🔎 Database

🔎 Database#

Lookup#

class DatabaseLookup(github=None, realm=None, threshold=0.2, stale_time=900, asset_ttl=86400, asset_capacity=128, sync_on_update=True)[source]#

Bases: object

Entity lookup and search interface for game database.

property state: CommitState#
async get_entity(entity_id, filename=IndexFile.LISTING, realm=None)[source]#

Retrieve entity data by ID.

Parameters:

  • entity_id (str) – Entity identifier.

  • filename (optional) – Index file name. Defaults to listing.json.

  • realm (optional) – Game version realm. Defaults to ru.

Return type:

Optional[dict[str, Any]]

Returns:

Entity json data or None.

async get_all(filename=IndexFile.LISTING, realm=None)[source]#

Retrieve all entities from index file.

Parameters:

  • filename (optional) – Index file name. Defaults to listing.json.

  • realm (optional) – Game version realm. Defaults to ru.

Returns:

entity}.

Return type:

Dictionary mapping entity IDs to their data {id

async search(query, filename=IndexFile.LISTING, realm=None, threshold=None)[source]#

Search entities by text query.

Parameters:

  • query (str) – Search text.

  • filename (optional) – Index file name. Defaults to listing.json.

  • realm (optional) – Game version realm. Defaults to ru.

  • threshold (optional) – Override similarity threshold (0.0-1.0). Defaults to 0.2.

Return type:

list[Lookup]

Returns:

List of search results sorted by relevance.

async find_one(query, filename=IndexFile.LISTING, realm=None, threshold=None)[source]#

Find single best match for text query.

Parameters:

  • query (str) – Search text.

  • filename (optional) – Index file name. Defaults to listing.json.

  • realm (optional) – Game version realm. Defaults to ru.

  • threshold (optional) – Override similarity threshold (0.0-1.0). Defaults to 0.2.

Return type:

Optional[Lookup]

Returns:

Best match result or None.

async item_info(path, upgrade_level=0, realm=None)[source]#

Retrieve item information.

Parameters:

  • path (str) – Item data path.

  • upgrade_level (optional) – Item upgrade level (0-15). Defaults to 0.

  • realm (optional) – Game version realm. Defaults to ru.

Return type:

Any

Returns:

Item json data.

async item_icon(path, realm=None)[source]#

Download item icon image.

Parameters:

  • path (str) – Icon file path.

  • realm (optional) – Game version realm. Defaults to ru.

Return type:

bytes

Returns:

Icon binary data.

async sync(force=False, realm=None)[source]#

Synchronize local database with remote.

Parameters:

  • force (optional) – Force sync regardless of commit state.

  • realm (optional) – Game version realm. Use value from ALL_REALMS_KEYWORDS (e.g. all) to sync all realms. Defaults to ru.

Return type:

bool

Returns:

True if sync was performed, False if already up-to-date.

Github#

class GitHubClient(*, token=None, owner='EXBO-Studio', repository='stalcraft-database', branch='main', timeout=300, headers=None)[source]#

Bases: APIClient

API Client for GitHub repository operations.

property has_token: bool#
async latest_commit()[source]#

Get latest commit hash.

Return type:

str

Returns:

Commit SHA hash.

async diff(base, head)[source]#

Compare commits or branches.

Parameters:

  • base (str) – Base commit or branch.

  • head (str) – Head commit or branch.

Return type:

dict[str, Any]

Returns:

Comparison data.

async contents(path='')[source]#

List repository contents at specified path.

Parameters:

path (optional) – Directory path. Defaults to repository root.

Returns:

Repository contents listing.

async rawfile(path, ref=None, output=None)[source]#

Download raw file from repository.

Parameters:

  • path (str) – File path within repository.

  • ref (optional) – Git reference. Defaults to configured branch.

  • output (optional) – Local filename for file streaming.

Returns:

File content bytes.

async archive(output=None)[source]#

Download repository as ZIP archive.

Parameters:

output (optional) – Local filename for file streaming.

Returns:

Archive content bytes.

State#

class CommitState(ttl, local='')[source]#

Bases: object

Commit state tracker with TTL cache for remote commit.

property remote: str#

Cached remote commit hash.

property uptodate: bool#

Local and remote commit equality.

property until: datetime | None#

Expiration time as datetime or None if infinite.

Contents