Package Reference

This section provides a description of all the classes you will encounter while using pyscx.

Note

“Our task is to invent. Yours is to use.” © Oidaho

Warning

Before you dive into the documentation, we strongly recommend reviewing the Usage Examples section. By looking at the practical use of pyscx, it will be easier to navigate the Package Reference.

API

The core and fundamental entity in pyscx is the API class. This class provides access to the STALCRAFT:X API with automatic handling of different types of authorization tokens.

The API class offers a convenient interface for calling API methods, somewhat resembling a builder pattern, although it is not strictly an implementation of it.

class pyscx.api.API(tokens: Token | Collection[Token], server: Server)

Bases: object

API Object Class for interacting with the STALCRAFT: X API.

This class provides an interface to communicate with the STALCRAFT: X API. It allows you to manage tokens and send HTTP requests to various API endpoints using the appropriate method groups.

__getattribute__(name: str) → Any

Intercepts attribute access and returns the appropriate method group for API interaction.

This method is triggered whenever an attribute is accessed on the API object. If the requested attribute is not found on the object itself, the method dynamically creates and returns an instance of MethodsGroupFabric, which is responsible for generating method groups for API endpoints.

Parameters:

name (str) – The name of the attribute being accessed.

Returns:

An instance of the appropriate method group factory, allowing access to various API endpoints.

Return type:

MethodsGroupFabric

__init__(tokens: Token | Collection[Token], server: Server) → None

Initializes the API object with the provided tokens and server.

Parameters:

  • tokens (Token | Collection[Token]) – A single token or a collection of tokens to be used for authentication.

  • server (Server) – The server instance representing the target API server.

get_token(type: TokenType) → str

Retrieves a token of the specified type from the stored tokens.

Parameters:

type (TokenType) – The type of the token to retrieve.

Returns:

The token value corresponding to the specified type.

Return type:

str

Raises:

MissingTokenError – If no token of the specified type is found.

In this class, the query-building function is handled by the API.__getattribute__() method. If an attribute is accessed that doesn’t exist in the class, the API.__getattribute__() method interprets this as an attempt to access a specific API methods group (MethodsGroup). In this case, the attribute name will correspond to the name of the API method group.

Token

The Token class serves as an interface for conveniently passing access tokens to the API class. It allows you to define standard access tokens for the API class in a clean, concise, and understandable manner, which will be automatically used by the class when calling API methods.

class pyscx.token.Token(value: str, type: TokenType)

Bases: object

API access token class.

This class provides an interface for passing a token to the API object. Each token consists of a value (the actual token string) and its type (which specifies the token’s purpose).

__init__(value: str, type: TokenType) → None

Initializes a token object with the specified value and type.

Parameters:

  • value (str) – The value of the token.

  • type (TokenType) – The type of the token, defined in the TokenType Enum.

To definitively specify the type of the token being used, the TokenType class is provided, which inherits from Enum.

class pyscx.token.TokenType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

A list of supported token types for authentication.

APPLICATION = 'application'
USER = 'user'

API Objects

For your convenience and ease of working with the data you will receive from the STALCRAFT:X API, models have been implemented to wrap raw data into Python objects.

These models are implemented using the Pydantic library. Therefore, hey inherit all the functionality offered by the BaseModel class from Pydantic. The APIObject class is created based on the BaseModel, and all other representations inherit from it.

class pyscx.objects.APIObject

Bases: BaseModel

An API object that provides data in a convenient form.

This class extends from Pydantic’s BaseModel and is designed to represent API responses in a structured and convenient format. When data is returned from the STALCRAFT: X API, the data is automatically wrapped in this class for easy access.

The class supports Pydantic’s data validation and serialization, making it easier to handle API responses and convert them into Python objects.

raw() → dict[str, Any]

Raw representation of the object as it was obtained from the STALCRAFT: X API.

Returns:

A dictionary containing the raw data of the object as it was received from the API.

Return type:

dict[str, Any]

Note

The documentation for the raw() function states that it returns the data in its original form. This means that the case of the keys in the data dictionary and the value formats will be restored to their original, and any fields with the value None will be removed.

All API objects can be divided into specific groups, which reflect the general association of models with a particular method or set of API methods.

Regions

class pyscx.objects.Region(*, id: str, name: str)

Bases: APIObject

Representation of data about the region where the game servers are located.

id

A unique identifier for the region.

Type:

str

name

The name of the region.

Type:

str

Emissions

class pyscx.objects.Emission(*, currentStart: datetime, previousStart: datetime, previousEnd: datetime)

Bases: APIObject

Representation of emissions data in the game.

current_start

The moment when the current emission iteration began.

Type:

datetime

previous_start

The moment when the previous emission iteration began.

Type:

datetime

previous_end

The moment when the previous emission iteration ended.

Type:

datetime

Auction

class pyscx.objects.AuctionLot(*, itemId: str, amount: int, startPrice: int, currentPrice: int | None = None, buyoutPrice: int, startTime: datetime, endTime: datetime, additional: dict[str, Any])

Bases: APIObject

Representation of an active auction lot for an item.

item_id

Unique identifier of the in-game item.

Type:

str

amount

Number of items in the lot.

Type:

int

start_price

Starting price of the auction lot.

Type:

int

current_price

Current bid price for the auction lot. Defaults to None.

Type:

int, optional

buyout_price

Buyout price of the auction lot.

Type:

int

start_time

Datetime when the auction lot was created.

Type:

datetime

end_time

Datetime when the auction lot will close.

Type:

datetime

additional

Additional data about the lot, such as specific conditions or properties.

Type:

dict[str, Any]

class pyscx.objects.AuctionRedeemedLot(*, amount: int, price: int, time: datetime, additional: dict[str, Any])

Bases: APIObject

Representation of a purchased auction lot for an item.

amount

Number of items in the lot.

Type:

int

price

Final sale price of the lot.

Type:

int

time

Datetime when the lot was sold.

Type:

datetime

additional

Additional data about the lot, such as special conditions or properties.

Type:

dict[str, Any]

Clans

class pyscx.objects.Clan(*, id: str, name: str, tag: str, level: int, levelPoints: int, registrationTime: datetime, alliance: str, description: str, leader: str, memberCount: int)

Bases: APIObject

Representation of in-game unit (clan) data.

id

Unique unit identifier.

Type:

str

name

Unit name.

Type:

str

tag

Unit tag.

Type:

str

level

Current unit level.

Type:

int

level_points

Number of unit level points.

Type:

int

registration_time

Datetime when the unit was created.

Type:

datetime

alliance

Grouping to which the unit belongs.

Type:

str

description

Public unit description.

Type:

str

leader

In-game name of the unit leader.

Type:

str

member_count

Number of active members in the unit.

Type:

int

class pyscx.objects.ClanMemberRank(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

A list of ranks within a unit (clan).

COLONEL = 'COLONEL'
COMMONER = 'COMMONER'
LEADER = 'LEADER'
OFFICER = 'OFFICER'
RECRUIT = 'RECRUIT'
SERGEANT = 'SERGANT'
SOLDIER = 'SOLIDER'
class pyscx.objects.ClanMember(*, name: str, rank: ClanMemberRank, joinTime: datetime)

Bases: APIObject

Representation of data about a member of a unit (clan).

name

The in-game name of the member.

Type:

str

rank

The rank of the member within the unit, which is defined by the ClanMemberRank enum.

Type:

ClanMemberRank

join_time

The moment when the member joined the unit. This is the date and time of their joining.

Type:

datetime

Characters

class pyscx.objects.CharacterStatType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

A list of supported types for player statistic values.

DATE = 'DATE'
DECIMAL = 'DECIMAL'
DURATION = 'DURATION'
INTEGER = 'INTEGER'
class pyscx.objects.CharacterStat(*, id: str, type: CharacterStatType, value: dict[str, Any])

Bases: APIObject

Representation of data for a specific player statistic.

id

The unique identifier of the statistic. This could be the name or key of the statistic.

Type:

str

type

The type of the statistic value, which is defined by the CharacterStatType enum.

Type:

CharacterStatType

value

A dictionary that contains the actual values of the statistic.

Type:

dict[str, Any]

class pyscx.objects.CharacterMeta(*, id: str, name: str, creationTime: datetime)

Bases: APIObject

Representation of the primary data about a character.

id

The unique identifier of the character.

Type:

str

name

The in-game name of the character.

Type:

str

creation_time

The moment when the character was created.

Type:

datetime

class pyscx.objects.CharacterClan(*, info: Clan, member: ClanMember)

Bases: APIObject

Representation of the primary data about a character.

id

The unique identifier of the character.

Type:

str

name

The in-game name of the character.

Type:

str

creation_time

The moment when the character was created.

Type:

datetime

class pyscx.objects.CharacterInfo(*, information: CharacterMeta, clan: CharacterClan)

Bases: APIObject

Representation of data about a game character.

information

Primary information about the character, including the character’s unique ID, name, and creation time.

Type:

CharacterMeta

clan

Information about the character’s unit (clan), if the character is part of one. This includes details such as the clan’s name and rank.

Type:

CharacterClan

class pyscx.objects.FullCharacterInfo(*, uuid: str, username: str, status: str, alliance: str, lastLogin: datetime, displayedAchievements: list[str], clan: CharacterClan, stats: list[CharacterStat])

Bases: APIObject

Representation of complete information about a game character.

uuid

The unique universal identifier of the game character.

Type:

str

name

The name of the game character as it appears in the game.

Type:

str

status

The online status of the game character (e.g., “online”, “offline”).

Type:

str

alliance

The grouping or faction to which the game character belongs.

Type:

str

last_login

The last time the character logged into the game.

Type:

datetime

displayed_achievements

A list of identifiers for the achievements or statistics pinned to the character’s profile.

Type:

list[str]

clan

Information about the character’s unit (clan). This includes details such as the clan’s name, rank, and other related information.

Type:

CharacterClan

stats

A list of representations of the character’s statistics. Each statistic includes an ID, value, and other associated metadata.

Type:

list[CharacterStat]

API Methods

When you attempt to access the API class in an effort to call an API method, the code structure will likely look something like this:

api.clans("EU").get_all()

In this case, the following will happen:

  1. You will attempt to access the regions attribute.

  2. The __getattribute__() method will not find an attribute named regions and will return an instance of the method group factory class (MethodsGroupFabric).

  3. The __call__() method of the MethodsGroupFabric class will be invoked, after which an instance of the MethodsGroup class will be returned with the region pre-set.

  4. The get_all() method will be called on the instance of the MethodsGroup, which retrieves the list of all game regions.

class pyscx.methods.MethodsGroup(region: str | None, session: APISession, tokens: dict[TokenType, str])

Bases: object

A base class for managing method groupsrelated to specific API endpoints.

The MethodsGroup class is responsible for providing common functionality to interact with various API method groups (such as regions, emissions, etc.). It provides utilities to wrap data into model instances and manage tokens for API requests.

Naturally, this sequence of actions is a generalization. In practice, you will receive instances of classes that inherit from MethodsGroup. These instances will contain methods related to a specific group of the API.

Regions

class pyscx.methods.RegionsMethods(region: str | None, session: APISession, tokens: dict[TokenType, str])

Bases: MethodsGroup

get_all(**kwargs) → list[Region]

Retrieves all regions from the API.

Parameters:

**kwargs – Additional arguments that can be passed to modify the request.

Returns:

A list of Region objects representing all the regions returned by the API.

Return type:

list[Region]

Method get_all():

  • No region specification is required.

  • No token is required.

Emissions

class pyscx.methods.EmissionsMethods(region: str | None, session: APISession, tokens: dict[TokenType, str])

Bases: MethodsGroup

get_info(**kwargs) → Emission

Retrieves emission information for the specified region.

Parameters:

**kwargs – Additional arguments that can be passed to modify the request.

Returns:

An instance of the Emission model containing the emission data retrieved from the API.

Return type:

Emission

Raises:

MissingTokenError – If the required token is not provided or is missing from the _tokens attribute.

Method get_info():

  • A region must be specified.

  • A token of type TokenType.APPLICATION is required.

Friends

class pyscx.methods.FriendsMethods(region: str | None, session: APISession, tokens: dict[TokenType, str])

Bases: MethodsGroup

get_all(character_name: str, **kwargs) → list[str]

Retrieves a list of friends for the specified character in the current region.

Parameters:

  • character_name (str) – The name of the character whose friends list is to be fetched.

  • **kwargs – Additional arguments that can be passed to modify the request.

Returns:

A list of strings representing the names of the character’s friends.

Return type:

list[str]

Raises:

MissingTokenError – If the required token is not provided or is missing from the _tokens attribute.

Method get_all():

  • A region must be specified.

  • A token of type TokenType.USER is required.

  • kwargs:

    • tokken (TokenType) - Access token.

Auction

class pyscx.methods.AuctionMethods(region: str | None, session: APISession, tokens: dict[TokenType, str])

Bases: MethodsGroup

get_item_history(item_id: str, **kwargs) → list[AuctionRedeemedLot]

Retrieves the history of a specific item in the auction.

Parameters:

  • item_id (str) – The unique identifier of the item for which to fetch the history.

  • **kwargs – Additional arguments that can be passed to modify the request.

Returns:

A list of AuctionRedeemedLot objects representing the item’s price history.

Return type:

list[AuctionRedeemedLot]

Raises:

MissingTokenError – If the required token is not provided or is missing from the _tokens attribute.

get_item_lots(item_id: str, **kwargs) → list[AuctionLot]

Retrieves the auction lots for a specific item.

Parameters:

  • item_id (str) – The unique identifier of the item for which to fetch the auction lots.

  • **kwargs – Additional arguments that can be passed to modify the request.

Returns:

A list of AuctionLot objects representing the auction lots the item has been listed in.

Return type:

list[AuctionLot]

Raises:

MissingTokenError – If the required token is not provided or is missing from the _tokens attribute.

Method get_item_history():

  • A region must be specified.

  • A token of type TokenType.APPLICATION is required.

  • kwargs:

    • tokken (TokenType) - Access token.

    • additional (bool) - Whether to include additional information about lots: True or False. By default False.

    • limit (int) - Amount of prices to return, starting from offset, min 0, max 200, default 20.

    • offset (int) - Amount of prices in list to skip.

Method get_item_lots():

  • A region must be specified.

  • A token of type TokenType.APPLICATION is required.

  • kwargs:

    • tokken (TokenType) - Access token.

    • additional (bool) - Whether to include additional information about lots: True or False. By default False.

    • limit (int) - Amount of lots to return, starting from offset, min 0, max 200, default 20.

    • offset (int) - Amount of lots in list to skip.

    • order (str) - Either asc or desc.

    • sort (str) - Property to sort by, one of: time_created, time_left, current_price, buyout_price.

Clans

class pyscx.methods.ClansMethods(region: str | None, session: APISession, tokens: dict[TokenType, str])

Bases: MethodsGroup

get_all(**kwargs) → list[Clan]

Retrieves a list of all clans in the current region.

Parameters:

**kwargs – Additional arguments that can be passed to modify the request.

Returns:

A list of Clan objects representing all the clans in the region.

Return type:

list[Clan]

Raises:

MissingTokenError – If the required token is not provided or is missing from the _tokens attribute.

get_info(clan_id: str, **kwargs) → Clan

Retrieves information about a specific clan by its ID.

Parameters:

  • clan_id (str) – The unique identifier of the clan whose information is to be fetched.

  • **kwargs – Additional arguments that can be passed to modify the request.

Returns:

A Clan object containing detailed information about the specified clan.

Return type:

Clan

Raises:

MissingTokenError – If the required token is not provided or is missing from the _tokens attribute.

get_members(clan_id: str, **kwargs) → list[ClanMember]

Retrieves a list of members in a specific clan by its ID.

Parameters:

  • clan_id (str) – The unique identifier of the clan whose members are to be fetched.

  • **kwargs – Additional arguments that can be passed to modify the request.

Returns:

A list of ClanMember objects representing the members of the specified clan.

Return type:

list[ClanMember]

Raises:

MissingTokenError – If the required token is not provided or is missing from the _tokens attribute.

Method get_info():

  • A region must be specified.

  • A token of type TokenType.APPLICATION is required.

  • kwargs:

    • tokken (TokenType) - Access token.

Method get_members():

  • A region must be specified.

  • A token of type TokenType.USER is required.

  • kwargs:

    • tokken (TokenType) - Access token.

Method get_all():

  • A region must be specified.

  • A token of type TokenType.APPLICATION is required.

  • kwargs:

    • tokken (TokenType) - Access token.

    • limit (int) - Amount of lots to return, starting from offset, min 0, max 200, default 20.

    • offset (int) - Amount of lots in list to skip.

Characters

class pyscx.methods.CharactersMethods(region: str | None, session: APISession, tokens: dict[TokenType, str])

Bases: MethodsGroup

get_all(**kwargs) → list[CharacterInfo]

Retrieves a list of characters in the current region.

Parameters:

**kwargs – Additional arguments that can be passed to modify the request.

Returns:

A list of CharacterInfo objects containing information about the characters.

Return type:

list[CharacterInfo]

Raises:

MissingTokenError – If the required token is not provided or is missing from the _tokens attribute.

get_profile(character_name: str, **kwargs) → FullCharacterInfo

Retrieves the full profile of a specific character by name.

Parameters:

  • character_name (str) – The name of the character whose profile is to be fetched.

  • **kwargs – Additional arguments that can be passed to modify the request.

Returns:

A FullCharacterInfo object containing the full profile of the specified character.

Return type:

FullCharacterInfo

Raises:

MissingTokenError – If the required token is not provided or is missing from the _tokens attribute.

Method get_all():

  • A region must be specified.

  • A token of type TokenType.USER is required.

  • kwargs:

    • tokken (TokenType) - Access token.

Method get_profile():

  • A region must be specified.

  • A token of type TokenType.APPLICATION is required.

  • kwargs:

    • tokken (TokenType) - Access token.

Note

**kwargs allows you not only to pass query parameters in the request but also to override the access token. This is useful if, for example, you have multiple tokens of the ‘TokenType.USER’ type. You can override the token as follows:

api.clans("EU").get_all(token="other_user_token")

Warning

Don’t forget to check the documentation to find out:

  • Which token type is required for each request.

  • What query parameters can be passed in the request.

Items Database

Danger

The functionality related to this section is under development.

Async API

Danger

The functionality related to this section is under development.