REST Client Interface

class auraxium.Client(loop=None, service_id='s:example', profiling=False, endpoints=None)

The main client used to interface with the PlanetSide 2 API.

This class handles access to the REST API at https://census.daybreakgames.com/.

To interface with the REST API, use the methods get(), find(), or one of the Client.get_by_*() helpers.

loop: asyncio.AbstractEventLoop

The asyncio event loop used by the client.

service_id: str

The service ID identifying your app to the API. You can use the default value of 's:example', but you will likely run into rate limits. You can sign up for your own service ID at http://census.daybreakgames.com/#devSignup.

session: aiohttp.ClientSession

The aiohttp.ClientSession used for REST API requests.

async count(type_: type[auraxium.base.Ps2Object], **kwargs) → int

Return the number of items matching the given terms.

Parameters:
Returns:

The number of entries entries.

async find(type_: type[auraxium.base.Ps2Object], results: int = 10, offset: int = 0, promote_exact: bool = False, check_case: bool = True, **kwargs) → list[auraxium.base.Ps2Object]

Return a list of entries matching the given terms.

This returns up to as many entries as indicated by the results argument. Note that it may be fewer.

Parameters:

  • type (type[auraxium.base.Ps2Object]) – The object type to search for.

  • results (int) – The maximum number of results.

  • offset (int) – The number of entries to skip. Useful for paginated views.

  • promote_exact (bool) – If enabled, exact matches to non-exact searches will always come first in the return list.

  • check_case (bool) – Whether to check case when comparing strings. Note that case-insensitive searches are much more expensive.

  • kwargs – Any number of filters to apply.

Returns:

A list of matching entries.

async get(type_: type[auraxium.base.Ps2Object], check_case: bool = True, **kwargs) → auraxium.base.Ps2Object | None

Return the first entry matching the given terms.

Like Client.find(), but will only return one item.

Parameters:

  • type (type[auraxium.base.Ps2Object]) – The object type to search for.

  • check_case (bool) – Whether to check case when comparing strings. Note that case-insensitive searches are much more expensive.

  • kwargs – Any number of filters to apply.

Returns:

The first matching entry, or None if not found.

async get_by_id(type_: type[auraxium.base.Ps2Object], id_: int) → auraxium.base.Ps2Object | None

Retrieve an object by its unique Census ID.

Like Client.get(), but checks the local cache before performing the query.

Parameters:
Returns:

The entry with the matching ID, or None if not found.

async get_by_name(type_: type[auraxium.base.Named], name: str, *, locale: str = 'en') → auraxium.base.Named | None

Retrieve an object by its unique name.

Depending on the type_ specified, this may retrieve a cached object, rather than querying the API.

Keep in mind that not all Named objects have a localised name; the locale argument has no effect in these cases.

This query is always case-insensitive.

Parameters:
Returns:

The entry with the matching name, or None if not found.

latency() → float

Return the average request latency for the client.

This averages up to the last 100 query times. Use the logging utility to gain more insight into which queries take the most time.

async close() → None

Shut down the client.

This will end the HTTP session used for requests to the REST API.

Call this to clean up before the client object is destroyed.

async request(query: auraxium.census.Query, verb: str = 'get') → auraxium.types.CensusData

Perform a REST API request.

This performs the query and performs error checking to ensure the query is valid.

Parameters:
Returns:

The API response payload received.

Object Model Bases

class auraxium.base.Ps2Object(data, client)

Common base class for all PS2 object representations.

This requires that subclasses overwrite the collection and id_field names, which are used to tie the class to its corresponding API counterpart.

collection: str

The API collection linked to this type.

id_field: str

The field name containing the unique ID for this type.

Note

This will generally match the <type>_id convention, but some collections like outfit_member or profile_2 use custom names. This attribute provides support for the latter.

classmethod count(client: auraxium.Client, **kwargs) → int

Return the number of items matching the given terms.

Parameters:

  • client (auraxium.Client) – The client through which to perform the request.

  • kwargs – Any number of query filters to apply.

Returns:

The number of entries entries.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.count() instead.

classmethod find(results: int = 10, *, offset: int = 0, promote_exact: bool = False, check_case: bool = True, client: auraxium.Client, **kwargs) → list[Ps2Object]

Return a list of entries matching the given terms.

This returns up to as many entries as indicated by the results argument. Note that it may be fewer if not enough matches are found.

Parameters:

  • results (int) – The maximum number of results.

  • offset (int) – The number of entries to skip. Useful for paginated views.

  • promote_exact (bool) – If enabled, exact matches to non-exact searches will always come first in the return list.

  • check_case (bool) – Whether to check case when comparing strings. Note that case-insensitive searches are much more expensive.

  • client (auraxium.Client) – The client through which to perform the request.

  • kwargs – Any number of filters to apply.

Returns:

A list of matching entries.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.find() instead.

classmethod get(client: auraxium.Client, check_case: bool = True, **kwargs) → Ps2Object | None

Return the first entry matching the given terms.

Like Ps2Object.get(), but will only return one item.

Parameters:

  • client (auraxium.Client) – The client through which to perform the request.

  • check_case (bool) – Whether to check case when comparing strings. Note that case-insensitive searches are much more expensive.

Returns:

A matching entry, or None if not found.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.get() instead.

classmethod get_by_id(id_: int, *, client: auraxium.Client) → Ps2Object | None

Retrieve an object by its unique Census ID.

Parameters:

  • id_ (int) – The unique ID of the object.

  • client (auraxium.Client) – The client through which to perform the request.

Returns:

The entry with the matching ID, or None if not found.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.get() instead.

query() → auraxium.census.Query

Return a query from the current object.

This is a utility method targeted at advanced users and developers. It is generally not required for most use cases.

class auraxium.base.Cached(data, client)

Base class for cacheable data types.

This generates a cache for each subclass that allows the storage and retrieval of objects by ID. This cache may be customised using keyword arguments as part of the class definition.

This customisation is done via two parameters: the cache size and the TTU.

The cache size defines the maximum number of items the cache may bold before it will discard the least recently used item for every new item added.

The TTU (time-to-use) will independently discard items that are older than the given number of seconds to ensure data does not go too far out of date.

classmethod alter_cache(size: int, ttu: float | None = None) → None

Modify the class cache to use a new size and TTU.

This will update and clear the cache for the current class. This allows customisation of the class depending on your use-case.

Parameters:

  • size (int) – The new cache size.

  • ttu (float) – The new item TTU.

Raises:

ValueError – Raised if the size is less than 1.

classmethod get_by_id(id_: int, *, client: auraxium.Client) → Cached | None

Retrieve an object by by ID.

This query uses caches and might return an existing instance if the object has been recently retrieved.

Parameters:

  • id_ (int) – The unique id of the object.

  • client (auraxium.Client) – The client through which to perform the request.

Returns:

The object matching the given ID or None if no match was found.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.get() instead.

class auraxium.base.Named(*args, locale=None, **kwargs)

Mix-in class for named objects.

This extends the functionality provided by Cached to also cache objects retrieved via Named.get_by_name(). The cache will also store the locale used for the request.

classmethod get_by_name(name: str, *, locale: str = 'en', client: auraxium.Client) → Named | None

Retrieve an object by its unique name.

If the same query has been performed recently, it may be restored from cache instead.

This query is always case-insensitive.

Parameters:

  • name (str) – The name to search for.

  • locale (str) – The locale of the search key.

  • client (auraxium.Client) – The client through which to perform the request.

Returns:

The entry with the matching name, or None if not found.

Deprecated since version 0.2: Scheduled for removal in 0.4. Use auraxium.Client.get() instead.

Proxy Objects

class auraxium.InstanceProxy(type_, query, client, lifetime=60.0)

Proxy for a single result.

This object can be awaited to retrieve the actual data.

Use this if your joins return a single object.

async resolve() → auraxium.base.Ps2Object | None

Return the proxy object.

Returns:

The object, or None if no match was found.

class auraxium.SequenceProxy(type_, query, client, lifetime=60.0)

Proxy for lists of results.

This object supports asynchronous iteration (in which case all elements are returned in a single request prior to iteration).

Alternatively, you can await it to receive a list of elements.

Use this if your joins return a list of objects.

async flatten() → list[auraxium.base.Ps2Object]

Retrieve all elements in the response as a list.

Returns:

A list of instantiated objects.