Collection Management

Manager

Card collection management module.

This module provides functionality for managing a local collection of Netrunner cards, including tracking owned cards, packs, and missing cards.

Classes:

CollectionManager: Main class for managing card collections. CardRequirement: Represents a card requirement from a decklist. CollectionError: Custom exception for collection errors.

Protocols:

APIClient: Protocol for API client dependency injection.

class simulchip.collection.manager.CollectionData

Bases: TypedDict

Type definition for collection file structure.

This represents the structure of the collection TOML file.

packs

List of pack codes that are fully owned.

owned_packs

List of pack codes that are owned (new format).

cards

Dictionary mapping card codes to quantities owned.

missing

Dictionary mapping card codes to quantities marked as missing.

packs: List[str]

owned_packs: List[str]

cards: Dict[str, int]

missing: Dict[str, int]

class simulchip.collection.manager.PackSummary

Bases: TypedDict

Type definition for pack summary statistics.

owned

Number of unique cards owned from this pack.

total

Total number of unique cards in this pack.

owned: int

total: int

exception simulchip.collection.manager.CollectionError

Bases: Exception

Custom exception for collection-related errors.

message

Error message describing what went wrong.

file_path

Path to the collection file if applicable.

message: str

file_path: Optional[Path] = None

__init__(message, file_path=None)

Parameters:

• message (str)

• file_path (Path | None)

Return type:

None

class simulchip.collection.manager.CardRequirement

Bases: object

Represents a card requirement from a decklist.

This class tracks how many copies of a card are required by a decklist and how many are available in the collection.

code

Card code (e.g., “01001”).

required

Number of copies required by the decklist.

owned

Number of copies owned in the collection.

missing

Number of additional copies needed.

Properties:

is_satisfied: True if owned >= required.

Examples

>>> req = CardRequirement("01001", required=3, owned=2, missing=1)
>>> req.is_satisfied
False

code: str

required: int

owned: int

missing: int

property is_satisfied: bool

Check if requirement is fully satisfied.

__init__(code, required, owned, missing)

Parameters:

• code (str)

• required (int)

• owned (int)

• missing (int)

Return type:

None

class simulchip.collection.manager.APIClient

Bases: Protocol

Protocol for API client interface.

get_all_cards()

Get all cards from the API.

Return type:

Dict[str, CardData]

get_pack_by_code(pack_code)

Get pack data by code.

Return type:

Optional[PackData]

Parameters:

pack_code (str)

__init__(*args, **kwargs)

class simulchip.collection.manager.CollectionManager

Bases: object

Manages local card collection data with validation and functional patterns.

collection_file: Optional[Path] = None

api: Optional[APIClient] = None

owned_packs: Set[str]

card_diffs: Dict[str, int]

collection: Dict[str, int]

missing_cards: Dict[str, int]

__post_init__()

Initialize and load collection after dataclass initialization.

Return type:

None

load_collection()

Load collection from file with validation.

Raises:

CollectionError – If file format is unsupported or data is invalid

Return type:

None

save_collection()

Save collection to file with atomic write.

Raises:

CollectionError – If save fails

Return type:

None

modify_card_count(card_code, delta, target)

Modify card count with validation (functional helper).

Parameters:

• card_code (str) – Card code to modify

• delta (int) – Change in count (positive or negative)

• target (Dict[str, int]) – Target dictionary to modify

Raises:

ValueError – If card_code is invalid

Return type:

None

add_card(card_code, count=1)

Add cards to collection.

Return type:

None

Parameters:

• card_code (str)

• count (int)

remove_card(card_code, count=1)

Remove cards from collection.

Return type:

None

Parameters:

• card_code (str)

• count (int)

add_missing_card(card_code, count=1)

Mark cards as missing/lost.

Return type:

None

Parameters:

• card_code (str)

• count (int)

remove_missing_card(card_code, count=1)

Mark missing cards as found.

Return type:

None

Parameters:

• card_code (str)

• count (int)

get_card_count(card_code)

Get effective card count (owned minus missing).

Return type:

int

Parameters:

card_code (str)

has_card(card_code, count=1)

Check if collection has enough copies of a card.

Return type:

bool

Parameters:

• card_code (str)

• count (int)

analyze_decklist(decklist)

Analyze decklist requirements against collection.

Parameters:

decklist (Dict[str, int]) – Dictionary mapping card codes to required counts

Return type:

List[CardRequirement]

Returns:

List of card requirements with ownership status

get_missing_cards(decklist)

Get cards missing from collection for a decklist.

Return type:

Dict[str, int]

Parameters:

decklist (Dict[str, int])

get_owned_cards(decklist)

Get cards from decklist that are in collection.

Return type:

Dict[str, int]

Parameters:

decklist (Dict[str, int])

get_all_cards()

Get all effective card counts.

Return type:

Dict[str, int]

get_pack_summary(api_client)

Get collection summary by pack with functional approach.

Parameters:

api_client (APIClient) – NetrunnerDB API client

Return type:

Dict[str, PackSummary]

Returns:

Dictionary mapping pack codes to statistics

add_pack(pack_code)

Add all cards from a pack to collection.

Raises:

ValueError – If pack_code is invalid

Return type:

None

Parameters:

pack_code (str)

remove_pack(pack_code)

Remove all cards from a pack from collection.

Raises:

ValueError – If pack is not owned

Return type:

None

Parameters:

pack_code (str)

has_pack(pack_code)

Check if collection has a pack.

Return type:

bool

Parameters:

pack_code (str)

get_owned_packs()

Get sorted list of owned pack codes.

Return type:

List[str]

get_expected_card_count(card_code)

Get expected card count based on owned packs.

Return type:

int

Parameters:

card_code (str)

get_card_difference(card_code)

Get card difference from expected (positive = extra, negative = missing).

Return type:

int

Parameters:

card_code (str)

get_actual_card_count(card_code)

Get actual card count (expected + difference).

Return type:

int

Parameters:

card_code (str)

modify_card_difference(card_code, delta)

Modify card difference by delta amount.

Parameters:

• card_code (str) – Card code to modify

• delta (int) – Change in difference (positive or negative)

Return type:

None

set_card_difference(card_code, difference)

Set card difference directly.

Parameters:

• card_code (str) – Card code to modify

• difference (int) – New difference value (positive = extra, negative = missing)

Return type:

None

get_all_cards_with_differences()

Get all cards with their expected counts and differences.

Returns:

int, ‘difference’: int, ‘actual’: int}

Return type:

Dict mapping card codes to {‘expected’

get_statistics()

Calculate collection statistics.

Returns:

• owned_packs: Number of owned packs

• unique_cards: Number of unique cards owned

• total_cards: Total number of cards (counting duplicates)

• missing_cards: Total number of missing cards

Return type:

Dictionary with statistics

__init__(collection_file=None, api=None, owned_packs=<factory>, card_diffs=<factory>, collection=<factory>, missing_cards=<factory>)

Parameters:

• collection_file (Path | None)

• api (APIClient | None)

• owned_packs (Set[str])

• card_diffs (Dict[str, int])

• collection (Dict[str, int])

• missing_cards (Dict[str, int])

Return type:

None

Operations

Collection operations and utilities.

This module provides utility functions for collection management that are used by the CLI but should be in the library.

simulchip.collection.operations.get_reset_items(collection_path)

Get list of items that would be reset.

Parameters:

collection_path (Path) – Path to collection file

Return type:

List[str]

Returns:

List of description strings for items to be reset

simulchip.collection.operations.get_or_create_manager(collection_file, api, all_cards=False)

Get or create a collection manager with appropriate settings.

Parameters:

• collection_file (Optional[Path]) – Path to collection file (can be None)

• api (NetrunnerDBAPI) – NetrunnerDB API instance

• all_cards (bool) – If True, use empty collection (ignore existing collection)

Return type:

CollectionManager

Returns:

CollectionManager instance

simulchip.collection.operations.sort_cards_by_title(cards_dict)

Sort cards by title for consistent display.

Parameters:

cards_dict (Dict[str, Any]) – Dictionary of card code to card data

Return type:

List[Dict[str, Any]]

Returns:

List of card data sorted by title

simulchip.collection.operations.get_packs_by_release_date(api, newest_first=True)

Get packs sorted by release date.

Parameters:

• api (NetrunnerDBAPI) – NetrunnerDB API instance

• newest_first (bool) – If True, sort newest first

Return type:

List[PackData]

Returns:

List of pack data sorted by release date