SwgohComlinkAsync API¶

SwgohComlinkAsync provides the same API as SwgohComlink with async/await support. All public methods have identical signatures — just add await to each call.

Quick Start¶

from swgoh_comlink import SwgohComlinkAsync

async with SwgohComlinkAsync() as comlink:
    player = await comlink.get_player(allycode=245866537)
    guild = await comlink.get_guild(guild_id=player["guildId"])

Without a context manager, call aclose() when done:

comlink = SwgohComlinkAsync()
try:
    player = await comlink.get_player(allycode=245866537)
finally:
    await comlink.aclose()

Connecting to Comlink¶

SwgohComlinkAsync takes the same constructor arguments as the synchronous client: url or host/port to choose the service, and access_key/ secret_key (or the ACCESS_KEY/SECRET_KEY environment variables) for HMAC signing. See Connecting to Comlink.

async with SwgohComlinkAsync(host="192.168.1.10", port=3000) as comlink:
    ...

Handling Errors¶

Failed calls raise the same typed HTTP errors as the synchronous client.

Retries and Pacing¶

The retry argument takes the same RetryPolicy as the synchronous client. Waits use asyncio.sleep, so they do not block the event loop. Pacing and the hold after a rate refusal apply across concurrent tasks on one client, and the tasks start in the order they asked. A task cancelled while it waits gives its slot back, so cancelling a batch does not delay the calls that follow it:

import asyncio

from swgoh_comlink import RetryPolicy, SwgohComlinkAsync

async with SwgohComlinkAsync(retry=RetryPolicy(min_interval=0.4)) as comlink:
    players = await asyncio.gather(*(comlink.get_player(allycode=code) for code in allycodes))

Stat Calculation¶

For local stat calculation in async code, use StatCalcAsync which fetches game data without blocking the event loop:

from swgoh_comlink import StatCalcAsync, SwgohComlinkAsync

async with SwgohComlinkAsync() as comlink:
    calc = await StatCalcAsync.create()
    player = await comlink.get_player(allycode=245866537)
    calc.calc_roster_stats(player["rosterUnit"])

See the StatCalc API for full details.

API Reference¶

`SwgohComlinkAsync` ¶

Bases: SwgohComlinkBase

Asynchronous interface for the swgoh-comlink service.

Instances of this class are used to query the Star Wars Galaxy of Heroes game servers for exposed endpoints via the swgoh-comlink proxy library running on the same host.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL where swgoh-comlink is running. Defaults to 'http://localhost:3000'	required
`access_key`	`str`	The HMAC public key. Default to None which indicates HMAC is not used.	required
`secret_key`	`str`	The HMAC private key. Default to None which indicates HMAC is not used.	required
`stats_url`	`str`	The url of the swgoh-stats service (if used), such as 'http://localhost:3223'	required
`host`	`str`	IP address or DNS name of server where the swgoh-comlink service is running	required
`port`	`int`	TCP port number where the swgoh-comlink service is running [Default: 3000]	required
`stats_port`	`int`	TCP port number of where the comlink-stats service is running [Default: 3223]	required
`verify_ssl`	`bool`	Whether to verify TLS certificates. [Default: True]	required
`version_cache_ttl`	`float`	Seconds to cache the game/localization versions fetched from /metadata. 0 disables caching; `math.inf` caches for the client lifetime. [Default: 3600]	required
`retry`	`RetryPolicy \| None`	Keyword-only. Retry rate refusals and HTTP 503 responses, and optionally space calls to the same endpoint, as described by a :class:`~swgoh_comlink.retry.RetryPolicy`. [Default: None, one attempt per call and no waiting]	required

Notes

If the 'host' and 'port' parameters are provided, the 'url' and 'stats_url' parameters are ignored.

Examples:

Basic usage::

async with SwgohComlinkAsync() as comlink:
    player = await comlink.get_player(allycode=123456789)

`aclose()` `async` ¶

Close the underlying async HTTP client connections.

`get_unit_stats(request_payload, flags=None, language=None)` `async` ¶

Calculate unit stats using the swgoh-stats service interface to swgoh-comlink.

Parameters:

Name	Type	Description	Default
`request_payload`	`dict[str, Any] \| list[Any]`	Dictionary or list of dictionaries containing units for which to calculate stats.	required
`flags`	`list[str] \| None`	List of strings specifying which flags to include in the request URI.	`None`
`language`	`str \| None`	String indicating the desired localized language. Default "eng_us".	`None`

Returns:

Type	Description
`list[Any] \| dict[str, Any]`	Input object with the calculated stats for the specified units included.

`get_enums(refresh=False)` `async` ¶

Get an object containing the game data enums.

Unlike most endpoints, /enums uses a GET request.

The response is cached on the instance as enums, with the game data version it was fetched under as enums_version. Later calls return the cached response while the game data version is unchanged and fetch it again once it changes. The version is read through the instance version cache (see version_cache_ttl), so a check usually makes no request. When the version cannot be determined, the enums are fetched and returned without being cached.

Parameters:

Name	Type	Description	Default
`refresh`	`bool`	When True, fetch the game data version and the enums again even if they are cached.	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the game data enums. A cached response is the same object as `enums`:
`dict[str, Any]`	copy it before changing it.

`get_events(enums=False)` `async` ¶

Get an object containing the events game data.

Parameters:

Name	Type	Description	Default
`enums`	`bool`	Boolean flag to indicate whether enum value should be converted in response. [Default is False]	`False`

Returns:

Type	Description
`dict[str, list[Any]]`	A single element dictionary containing a list of the events game data.

`get_game_data(version='', include_pve_units=True, request_segment=0, enums=False, items=None, device_platform='Android')` `async` ¶

Get game data.

Parameters:

Name	Type	Description	Default
`version`	`str`	string (found in metadata key value 'latestGamedataVersion')	`''`
`include_pve_units`	`bool`	boolean [Defaults to True]	`True`
`request_segment`	`int`	integer >=0 [Defaults to 0]	`0`
`enums`	`bool`	boolean [Defaults to False]	`False`
`items`	`str \| DataItems \| int \| None`	string [Defaults to None] bitwise value indicating the collections to retrieve from game. NOTE: this parameter is mutually exclusive with request_segment.	`None`
`device_platform`	`str`	string [Defaults to "Android"]	`'Android'`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the game data.

`get_localization(localization_id=None, locale=None, unzip=False, enums=False)` `async` ¶

Get localization data from game.

Parameters:

Name	Type	Description	Default
`localization_id`	`str \| None`	latestLocalizationBundleVersion found in game metadata.	`None`
`locale`	`str \| None`	string Specify only a specific locale to retrieve [for example "ENG_US"]	`None`
`unzip`	`bool`	boolean [Defaults to False]	`False`
`enums`	`bool`	boolean [Defaults to False]	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the localization data.

`get_game_metadata(client_specs=None, enums=False)` `async` ¶

Get the game metadata. Game metadata contains the current game and localization versions.

Parameters:

Name	Type	Description	Default
`client_specs`	`dict[str, Any] \| None`	Optional dictionary containing client specifications.	`None`
`enums`	`bool`	Boolean signifying whether enums in response should be translated to text. [Default: False]	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the game metadata.

`get_player(allycode=None, player_id=None, enums=False)` `async` ¶

Get player information from game. Either allycode or player_id must be provided.

Parameters:

Name	Type	Description	Default
`allycode`	`str \| int \| None`	integer or string representing player allycode	`None`
`player_id`	`str \| None`	string representing player game ID	`None`
`enums`	`bool`	boolean [Defaults to False]	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the player information.

`get_player_arena(allycode=None, player_id=None, player_details_only=False, enums=False)` `async` ¶

Get player arena information from game. Either allycode or player_id must be provided.

Parameters:

Name	Type	Description	Default
`allycode`	`str \| int \| None`	integer or string representing player allycode	`None`
`player_id`	`str \| None`	string representing player game ID	`None`
`player_details_only`	`bool`	filter results to only player details [Defaults to False]	`False`
`enums`	`bool`	boolean [Defaults to False]	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the player arena information.

`get_guild(guild_id, include_recent_guild_activity_info=False, enums=False)` `async` ¶

Get guild information for a specific Guild ID.

Parameters:

Name	Type	Description	Default
`guild_id`	`str`	String ID of guild to retrieve.	required
`include_recent_guild_activity_info`	`bool`	boolean [Default: False]	`False`
`enums`	`bool`	Should enums in response be translated to text. [Default: False]	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the guild information.

`get_guilds_by_name(name, start_index=0, count=10, enums=False)` `async` ¶

Search for guild by name and return match.

Parameters:

Name	Type	Description	Default
`name`	`str`	string for guild name search	required
`start_index`	`int`	integer for where in the result list to begin	`0`
`count`	`int`	integer for max matches to return [Default: 10]	`10`
`enums`	`bool`	Whether to translate enums in response to text [Default: False]	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the guild search results.

`get_guilds_by_criteria(search_criteria, start_index=0, count=10, enums=False)` `async` ¶

Search for guild by guild criteria and return matches.

Parameters:

Name	Type	Description	Default
`search_criteria`	`dict[str, Any]`	Dictionary of search criteria	required
`start_index`	`int`	integer for where in the result list to begin	`0`
`count`	`int`	integer for max matches to return	`10`
`enums`	`bool`	Whether to translate enum values to text [Default: False]	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the guild search results.

`get_leaderboard(leaderboard_type, *, league=None, division=None, event_instance_id=None, group_id=None, enums=False)` `async` ¶

Retrieve Grand Arena Championship leaderboard information.

Parameters:

Name	Type	Description	Default
`leaderboard_type`	`int`	Type 4 for GAC brackets, Type 6 for global leaderboards.	required
`league`	`int \| str \| None`	Enum value or string name for league.	`None`
`division`	`int \| str \| None`	Enum value or string name for division.	`None`
`event_instance_id`	`str \| None`	Event+instance ID (for type 4).	`None`
`group_id`	`str \| None`	Group ID (for type 4).	`None`
`enums`	`bool`	Whether to translate enum values to text [Default: False]	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the leaderboard data.

`get_guild_leaderboard(leaderboard_id, count=200, enums=False)` `async` ¶

Fetches the guild leaderboard data for given leaderboard ID.

Parameters:

Name	Type	Description	Default
`leaderboard_id`	`list[dict[str, Any]]`	A list containing one leaderboard ID dictionary.	required
`count`	`int`	The number of leaderboard entries to retrieve. [Default: 200]	`200`
`enums`	`bool`	Whether or not to translate enum values. [Default: False]	`False`

Returns:

Type	Description
`dict[str, Any]`	A dictionary containing the guild leaderboard data.

`get_name_spaces(only_compatible=False, enums=False)` `async` ¶

Fetches namespaces based on the specified filter criteria.

`get_segmented_content(content_name_space='current', accept_language='ENG_US', enums=False)` `async` ¶

Retrieves segmented content from a specified namespace.

`get_latest_game_data_version(refresh=False)` `async` ¶

Get the latest game data and language bundle versions.

Results are served from the instance version cache (see version_cache_ttl).

Parameters:

Name	Type	Description	Default
`refresh`	`bool`	When True, bypass the cache and fetch fresh values from /metadata.	`False`

Returns:

Type	Description
`dict[str, Any]`	Dictionary with 'game' and 'language' version strings.

SwgohComlinkAsync API¶

Quick Start¶

Connecting to Comlink¶

Handling Errors¶

Retries and Pacing¶

Stat Calculation¶

API Reference¶

SwgohComlinkAsync ¶

aclose() async ¶

get_unit_stats(request_payload, flags=None, language=None) async ¶

get_enums(refresh=False) async ¶

get_events(enums=False) async ¶

get_game_data(version='', include_pve_units=True, request_segment=0, enums=False, items=None, device_platform='Android') async ¶

get_localization(localization_id=None, locale=None, unzip=False, enums=False) async ¶

get_game_metadata(client_specs=None, enums=False) async ¶

get_player(allycode=None, player_id=None, enums=False) async ¶

get_player_arena(allycode=None, player_id=None, player_details_only=False, enums=False) async ¶

get_guild(guild_id, include_recent_guild_activity_info=False, enums=False) async ¶

get_guilds_by_name(name, start_index=0, count=10, enums=False) async ¶

get_guilds_by_criteria(search_criteria, start_index=0, count=10, enums=False) async ¶

get_leaderboard(leaderboard_type, *, league=None, division=None, event_instance_id=None, group_id=None, enums=False) async ¶

get_guild_leaderboard(leaderboard_id, count=200, enums=False) async ¶

get_name_spaces(only_compatible=False, enums=False) async ¶

get_segmented_content(content_name_space='current', accept_language='ENG_US', enums=False) async ¶

get_latest_game_data_version(refresh=False) async ¶

`SwgohComlinkAsync` ¶

`aclose()` `async` ¶

`get_unit_stats(request_payload, flags=None, language=None)` `async` ¶

`get_enums(refresh=False)` `async` ¶

`get_events(enums=False)` `async` ¶

`get_game_data(version='', include_pve_units=True, request_segment=0, enums=False, items=None, device_platform='Android')` `async` ¶

`get_localization(localization_id=None, locale=None, unzip=False, enums=False)` `async` ¶

`get_game_metadata(client_specs=None, enums=False)` `async` ¶

`get_player(allycode=None, player_id=None, enums=False)` `async` ¶

`get_player_arena(allycode=None, player_id=None, player_details_only=False, enums=False)` `async` ¶

`get_guild(guild_id, include_recent_guild_activity_info=False, enums=False)` `async` ¶

`get_guilds_by_name(name, start_index=0, count=10, enums=False)` `async` ¶

`get_guilds_by_criteria(search_criteria, start_index=0, count=10, enums=False)` `async` ¶

`get_leaderboard(leaderboard_type, *, league=None, division=None, event_instance_id=None, group_id=None, enums=False)` `async` ¶

`get_guild_leaderboard(leaderboard_id, count=200, enums=False)` `async` ¶

`get_name_spaces(only_compatible=False, enums=False)` `async` ¶

`get_segmented_content(content_name_space='current', accept_language='ENG_US', enums=False)` `async` ¶

`get_latest_game_data_version(refresh=False)` `async` ¶