NetrunnerDB API Client

NetrunnerDB API client module.

This module provides a client for interacting with the NetrunnerDB API to fetch card data, pack information, and decklists.

Classes:: NetrunnerDBAPI: Main API client class. APIError: Custom exception for API-related errors.
TypeDict Classes:: CardData: Type definition for card data. PackData: Type definition for pack data. DecklistData: Type definition for decklist data.

class simulchip.api.netrunnerdb.CardData[source]

Bases: TypedDict

Type definition for card data from NetrunnerDB.

code: Unique card identifier (e.g., “01001”).

title: Card name.

type_code: Card type code (e.g., “agenda”, “asset”, “ice”).

faction_code: Faction code (e.g., “haas-bioroid”, “shaper”).

pack_code: Pack code where the card was released.

quantity: Number of copies in a pack.

deck_limit: Maximum copies allowed in a deck.

image_url: URL to the card image.

code: str

title: str

type_code: str

faction_code: str

pack_code: str

quantity: int

deck_limit: int

image_url: str

class simulchip.api.netrunnerdb.PackData[source]

Bases: TypedDict

Type definition for pack data from NetrunnerDB.

code: Unique pack identifier (e.g., “core”).

name: Full pack name.

position: Pack position in the cycle.

cycle_code: Cycle code this pack belongs to.

cycle: Full cycle name.

date_release: Release date in YYYY-MM-DD format.

code: str

name: str

position: int

cycle_code: str

cycle: str

date_release: str

class simulchip.api.netrunnerdb.DecklistData[source]

Bases: TypedDict

Type definition for decklist data from NetrunnerDB.

id: Unique decklist identifier.

name: Deck name.

description: Deck description (may include HTML).

cards: Dictionary mapping card codes to quantities.

id: str

name: str

description: str

cards: Dict[str, int]

exception simulchip.api.netrunnerdb.APIError[source]

Bases: Exception

Custom exception for API-related errors.

message: Error message describing what went wrong.

status_code: HTTP status code if applicable.

url: The URL that caused the error if applicable.

message: str

status_code: Optional[int] = None

url: Optional[str] = None

__init__(message, status_code=None, url=None)

Parameters:

message (str)
status_code (int | None)
url (str | None)

Return type:

None

class simulchip.api.netrunnerdb.NetrunnerDBAPI[source]

Bases: object

Client for interacting with NetrunnerDB API.

Provides methods to fetch card data, pack information, and decklists from NetrunnerDB. Implements rate limiting and caching to be respectful of the API.

BASE_URL: Base URL for the NetrunnerDB API.

DEFAULT_RATE_LIMIT: Default delay between API calls (0.5 seconds).

rate_limit_delay: Configured delay between API calls.

cache: Cache manager instance for storing API responses.

Examples

Basic usage:

api = NetrunnerDBAPI()
cards = api.get_all_cards()
decklist = api.get_decklist("12345")

BASE_URL: Final[str] = 'https://netrunnerdb.com/api/2.0/public'

DEFAULT_RATE_LIMIT: Final[float] = 0.5

__init__(rate_limit_delay=0.5, cache_dir=None)[source]

Initialize API client with validation.

Parameters:

rate_limit_delay (float) – Delay between API calls in seconds
cache_dir (Optional[Path]) – Directory for cache storage

Raises:

ValueError – If rate_limit_delay is negative

Return type:

None

get_all_cards()[source]

Fetch all cards from NetrunnerDB with smart caching.

Uses smart cache validation based on pack releases to minimize API calls.

Return type:: Dict[str, CardData]
Returns:: Dictionary mapping card codes to card data
Raises:: APIError – If API request fails

get_all_packs(skip_cache_check=False)[source]

Fetch all pack information with smart caching.

Parameters:: skip_cache_check (bool) – Skip cache validity check (used internally to avoid recursion)
Return type:: List[PackData]
Returns:: List of pack data
Raises:: APIError – If API request fails

check_cache_validity()[source]

Check if cache needs refresh by fetching pack data only.

This is a lightweight check that only fetches pack information to determine if there are new releases since the cache was last updated.

Return type:: bool
Returns:: True if cache is valid, False if it needs refresh

check_cache_validity_with_reason()[source]

Check if cache needs refresh and provide detailed reason.

Return type:: Dict[str, Any]
Returns:: Dictionary with ‘valid’ boolean, ‘reason’ string, and metadata

set_offline_mode(offline=True)[source]

Enable or disable offline mode.

In offline mode, the API will only use cached data and won’t make any network requests.

Parameters:: offline (bool) – True to enable offline mode, False to disable
Return type:: None

is_offline_mode()[source]

Check if offline mode is enabled.

Return type:: bool
Returns:: True if offline mode is enabled

get_packs_by_release_date(newest_first=True)[source]

Get all packs sorted by release date with enriched cycle names.

Parameters:: newest_first (bool) – If True, sort newest first. If False, sort oldest first.
Return type:: List[PackData]
Returns:: List of pack data sorted by release date
Raises:: APIError – If API request fails

get_card_by_code(code)[source]

Get a specific card by its code.

Parameters:: code (str) – Card code
Return type:: Optional[CardData]
Returns:: Card data or None if not found

get_all_printings(card_title)[source]

Get all printings of a card by its title.

Parameters:: card_title (str) – The card title to search for
Return type:: List[CardData]
Returns:: List of all printings of the card, sorted by release date (newest first)

get_cycle_name_mapping()[source]

Fetch cycle code to name mapping with caching.

Return type:: Dict[str, str]
Returns:: Dictionary mapping cycle codes to cycle names
Raises:: APIError – If API request fails

get_decklist(decklist_id)[source]

Fetch a specific decklist by ID with validation.

Parameters:

decklist_id (str) – NetrunnerDB decklist ID

Return type:

DecklistData

Returns:

Decklist data including cards

Raises:

ValueError – If decklist_id is invalid
APIError – If API request fails or decklist not found

get_pack_by_code(pack_code)[source]

Get a specific pack by its code using functional approach.

Parameters:: pack_code (str) – Pack code (e.g., “core”)
Return type:: Optional[PackData]
Returns:: Pack data or None if not found
Raises:: ValueError – If pack_code is invalid

get_cards_by_pack(pack_code)[source]

Get all cards from a specific pack.

Parameters:: pack_code (str) – Pack code to filter by
Return type:: List[CardData]
Returns:: List of cards in the pack
Raises:: ValueError – If pack_code is invalid

refresh_cache()[source]

Force refresh of all cached data.

Return type:: None