Services

Service modules implement business logic for each API endpoint.

Base Services

Abstract base classes for Numista services.

class numistalib.services.base.service.BaseService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: ABC

Abstract base service class for all Numista services.

Enforces strict patterns for: - Client injection via duck-typing - Converting raw data to typed models - Centralized HTTP error handling - Consistent caching and logging

All concrete services must implement model conversion logic.

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize base service with HTTP client.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client conforming to the sync or async protocol

property copyright_text: str

Get the copyright text for logging and display.

Returns:: Service copyright text
Return type:: str

handle_cli_error(err: Exception, context: str, command: str) → NoReturn[source]

Handle CLI errors with consistent logging and user-friendly display.

Logs full traceback to module logger for debugging, displays friendly error message to user via Rich error console, then exits with code 1.

Parameters:

err (Exception) – The exception that occurred
context (str) – Human-readable context (e.g., “listing catalogues”, “fetching issuer details”)
command (str) – Command name for log correlation (e.g., “cat-list”, “isr-get”)

Examples

>>> try:
...     results = service.list_catalogues()
... except (RuntimeError, OSError, ValueError) as e:
...     service._handle_cli_error(e, "listing catalogues", "cat-list")

property last_cache_indicator: str

Get the cache indicator for the last response.

Returns:: Cache hit (💾) or cache miss (🌐) indicator
Return type:: str

property title_text: str

Get the title text for logging and display.

Returns:: Service title text
Return type:: str

abstractmethod to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[Any][source]

Convert raw API items to typed domain models.

Parameters:

items (list[Mapping[str, Any]]) – Raw items from API response
**kwargs (Any) – Service-specific conversion context (e.g., parent IDs)

Returns:

List of typed domain models

Return type:

list[Any]

class numistalib.services.base.service.EntityService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: BaseService

Base for single-entity endpoints.

Used for endpoints like: - /users/{user_id} → {“user”: {…}} - /types/{type_id} → {…}

Subclasses implement to_models() for single-item conversion.

to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[Any][source]

Convert single entity (wrapped in list for interface consistency).

Parameters:

items (list[Mapping[str, Any]]) – Single-item list containing entity data
**kwargs (Any) – Conversion context

Returns:

Single-item list with converted entity

Return type:

list[Any]

class numistalib.services.base.service.NestedResourceService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: BaseService

Base for endpoints with path parameters creating nested resources.

Used for endpoints like: - /types/{type_id}/issues → {“issues”: […]} - /types/{type_id}/issues/{issue_id}/prices → {“prices”: […]}

Subclasses must: 1. Define CLASS_ITEMS_KEY 2. Implement to_models() with required context parameters

CLASS_ITEMS_KEY: str = 'items'

class numistalib.services.base.service.SimpleListService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: BaseService

Base for endpoints returning a simple list of items in a single key.

Used for endpoints like: - /catalogues → {“catalogues”: […]} - /mints → {“mints”: […]}

Subclasses must: 1. Define CLASS_ITEMS_KEY (e.g., “catalogues”) 2. Implement to_models() to convert raw items

CLASS_ITEMS_KEY: str = 'items'

Types Service

Type service implementation.

class numistalib.services.types.service.SearchParams(query: str | None = None, issuer: str | None = None, year: int | None = None, category: str | None = None, lang: str = 'en', page: int = 1, count: int = 100)[source]

Bases: object

Search parameters for type catalogue queries.

category: str | None = None

count: int = 100

has_search_criteria() → bool[source]

Check if at least one search criterion is provided.

Returns:: True if any search criteria specified
Return type:: bool

issuer: str | None = None

lang: str = 'en'

page: int = 1

query: str | None = None

to_dict() → dict[str, Any][source]

Convert to API parameter dictionary.

Returns:: Parameters dictionary for HTTP request
Return type:: dict[str, Any]

year: int | None = None

class numistalib.services.types.service.TypeBasicService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: TypeBasicServiceBase

Type search service returning TypeBasic models.

async paginated_search(params: SearchParams) → AsyncGenerator[TypeBasic][source]

Search the type catalogue and yield results lazily across paginated responses.

Parameters:: params (SearchParams) – Search parameters (query, issuer, year, category)
Yields:: TypeBasic – Individual type models from paginated responses

search_types(params: SearchParams) → list[TypeBasic][source]

Search the type catalogue with the given parameters.

Parameters:: params (SearchParams) – Search parameters (query, issuer, year, category, page)
Returns:: List of matching basic type models
Return type:: list[TypeBasic]

async search_types_async(params: SearchParams) → list[TypeBasic][source]

Search the type catalogue asynchronously with the given parameters.

Parameters:: params (SearchParams) – Search parameters (query, issuer, year, category, page)
Returns:: List of matching basic type models
Return type:: list[TypeBasic]

async search_types_paginated(query: str | None = None, issuer: str | None = None, year: int | None = None, category: str | None = None, limit: int = 50, lang: str = 'en') → AsyncGenerator[TypeBasic][source]

Search the type catalogue and yield results lazily.

Parameters:

query (str | None) – Full-text search query
issuer (str | None) – Issuer code to filter by
year (int | None) – Year to filter by
category (str | None) – Category to filter by (coin, banknote, exonumia)
limit (int) – Maximum results per page (default 50)
lang (str) – Language code (default ‘en’)

Yields:

TypeBasic – Individual type models

to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[TypeBasic][source]

Convert raw type data to TypeBasic models.

Parameters:

items (list[Mapping[str, Any]]) – Raw type data from API
**kwargs (Any) – Unused context parameters

Returns:

Validated TypeBasic models

Return type:

list[TypeBasic]

class numistalib.services.types.service.TypeFullService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: TypeFullServiceBase

Type detail service returning TypeFull models.

add_type(type_data: dict[str, object], lang: str | None = None) → TypeFull[source]

Create a new type in the catalogue.

Parameters:

type_data (dict[str, object]) – Type data to create
lang (str | None) – Optional language code

Returns:

The created type with assigned ID

Return type:

TypeFull

async add_type_async(type_data: dict[str, object], lang: str | None = None) → TypeFull[source]

Create a new type in the catalogue asynchronously.

Parameters:

type_data (dict[str, object]) – Type data to create
lang (str | None) – Optional language code

Returns:

The created type with assigned ID

Return type:

TypeFull

get_type(type_id: int, *, lang: str | None = None) → TypeFull[source]

Get detailed information for a single type by ID.

Parameters:

type_id (int) – The Numista type ID
lang (str | None) – Optional language code

Returns:

Detailed type information

Return type:

TypeFull

async get_type_async(type_id: int, *, lang: str | None = None) → TypeFull[source]

Get detailed information for a single type asynchronously.

Parameters:

type_id (int) – The Numista type ID
lang (str | None) – Optional language code

Returns:

Detailed type information

Return type:

TypeFull

to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[TypeFull][source]

Convert raw type data to TypeFull models.

Parameters:

items (list[Mapping[str, Any]]) – Raw type data from API
**kwargs (Any) – Unused context parameters

Returns:

Validated TypeFull models

Return type:

list[TypeFull]

class numistalib.services.types.service.TypePagedResponse(*, types: list[dict[str, Any]], next_url: str | None = None)[source]

Bases: BaseModel

Pagination response wrapper for types search.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

next_url: str | None

types: list[dict[str, Any]]

class numistalib.services.types.service.TypeService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: TypeFullService, TypeBasicService, TypeServiceBase

Composite type service combining search (basic) and detail (full).

Note: mypy reports to_models conflict between TypeBasicService (returns list[TypeBasic]) and TypeFullService (returns list[TypeFull]). This is inherent to composite service design; each parent class uses its own to_models internally. Python MRO resolves correctly at runtime.

Catalogues Service

Catalogue service implementation.

class numistalib.services.catalogues.service.CatalogueService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: CatalogueServiceBase

Unified catalogue service supporting both sync and async clients.

CLASS_ITEMS_KEY: str = 'catalogues'

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize catalogue service.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client instance (sync or async)

get_catalogues() → list[Catalogue][source]

Get list of all reference catalogues.

Supports both sync and async clients via duck-typing.

Returns:: All available catalogues
Return type:: list[Catalogue]
Raises:: httpx.HTTPStatusError – If API returns error

async get_catalogues_async() → list[Catalogue][source]

Get list of all reference catalogues (async).

Returns:: All available catalogues
Return type:: list[Catalogue]
Raises:: httpx.HTTPStatusError – If API returns error

to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[Catalogue][source]

Convert API response items to Catalogue models.

Parameters:

items (list[Mapping[str, Any]]) – Raw API response items
**kwargs (Any) – Unused (for interface consistency)

Returns:

Parsed catalogue models

Return type:

list[Catalogue]

numistalib.services.catalogues.service.CatalogueServiceAsync: alias of CatalogueService

Issuers Service

Issuer service implementation.

class numistalib.services.issuer.service.IssuerService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: IssuerServiceBase

Unified issuer service supporting both sync and async clients.

CLASS_ITEMS_KEY: str = 'issuers'

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize issuer service.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client instance (sync or async)

get_issuers(lang: str = 'en', count: int | None = None) → list[Issuer][source]

Get the list of issuers.

Supports both sync and async clients via duck-typing.

Parameters:

lang (str) – Language code (en, es, fr)
count (int | None) – Optional max results per page (API default is applied when None)

Returns:

List of issuers

Return type:

list[Issuer]

Raises:

httpx.HTTPStatusError – If API returns error

async get_issuers_async(lang: str = 'en', count: int | None = None) → list[Issuer][source]

Get the list of issuers (async).

Parameters:

lang (str) – Language code (en, es, fr)
count (int | None) – Optional max results per page (API default is applied when None)

Returns:

List of issuers

Return type:

list[Issuer]

Raises:

httpx.HTTPStatusError – If API returns error

async get_issuers_paginated(lang: str = 'en', limit: int = 50) → AsyncGenerator[Issuer][source]

Paginate through all issuers (alias for paginated_issuers).

Parameters:

lang (str) – Language code (en, es, fr)
limit (int) – Results per page (max 100)

Yields:

Issuer – Individual issuer records

async paginated_issuers(lang: str = 'en', limit: int = 50) → AsyncGenerator[Issuer][source]

Lazily iterate all issuers by following pagination links.

Parameters:

lang (str) – Language code (en, es, fr)
limit (int) – Results per page (max 100)

Yields:

Issuer – Individual issuer records

to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[Issuer][source]

Convert API response items to Issuer models.

Parameters:

items (list[Mapping[str, Any]]) – Raw API response items
**kwargs (Any) – Unused (for interface consistency)

Returns:

Parsed issuer models

Return type:

list[Issuer]

numistalib.services.issuer.service.IssuerServiceAsync: alias of IssuerService

Issues Service

Issue service implementation.

class numistalib.services.issues.service.IssueService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: IssueServiceBase

Unified issue service supporting both sync and async clients.

CLASS_ITEMS_KEY: str = 'issues'

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize issue service.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client instance (sync or async)

add_issue(type_id: int, issue_data: Mapping[str, Any], lang: str | None = None) → Issue[source]

Add a new issue to a type.

Parameters:

type_id (int) – Numista type ID
issue_data (Mapping[str, Any]) – Issue data payload
lang (str | None) – Language code

Returns:

Created issue

Return type:

Issue

Raises:

httpx.HTTPStatusError – If API returns error

async add_issue_async(type_id: int, issue_data: Mapping[str, Any], lang: str | None = None) → Issue[source]

Add a new issue to a type (async).

Parameters:

type_id (int) – Numista type ID
issue_data (Mapping[str, Any]) – Issue data payload
lang (str | None) – Language code

Returns:

Created issue

Return type:

Issue

Raises:

httpx.HTTPStatusError – If API returns error

get_issues(type_id: int, lang: str = 'en') → list[Issue][source]

Get all issues for a specific type (single call).

Supports both sync and async clients via duck-typing.

Parameters:

type_id (int) – Numista type ID
lang (str) – Language code

Returns:

List of issues

Return type:

list[Issue]

Raises:

httpx.HTTPStatusError – If API returns error

async get_issues_async(type_id: int, lang: str = 'en') → list[Issue][source]

Get all issues for a specific type (async).

Parameters:

type_id (int) – Numista type ID
lang (str) – Language code

Returns:

List of issues

Return type:

list[Issue]

Raises:

httpx.HTTPStatusError – If API returns error

async get_issues_paginated(type_id: int, lang: str = 'en', limit: int = 100) → AsyncGenerator[Issue][source]

Paginate through issues for a type (alias for paginated_issues).

Parameters:

type_id (int) – Numista type ID
lang (str) – Language code
limit (int) – Results per page (max 100)

Yields:

Issue – Individual issue records

async paginated_issues(type_id: int, lang: str = 'en', limit: int = 100) → AsyncGenerator[Issue][source]

Lazily iterate issues by following pagination links.

Parameters:

type_id (int) – Numista type ID
lang (str) – Language code
limit (int) – Results per page (max 100)

Yields:

Issue – Individual issue records

to_models(items: list[Mapping[str, Any]], type_id: int | None = None, **kwargs: Any) → list[Issue][source]

Convert API response items to Issue models.

Parameters:

items (list[Mapping[str, Any]]) – Raw API response items
type_id (int | None) – Numista type ID (required context)
**kwargs (Any) – Additional context

Returns:

Parsed issue models

Return type:

list[Issue]

numistalib.services.issues.service.IssueServiceAsync: alias of IssueService

Mints Service

Mint service implementation.

class numistalib.services.mints.service.MintService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: MintServiceBase

Unified mint service supporting both sync and async clients.

CLASS_ITEMS_KEY: str = 'mints'

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize mint service.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client instance (sync or async)

get_mint(mint_id: int, *, lang: str | None = None) → Mint[source]

Get details about a specific mint.

Parameters:: mint_id (int) – Numista mint ID
Returns:: Mint details
Return type:: Mint
Raises:: httpx.HTTPStatusError – If mint not found or API error

async get_mint_async(mint_id: int, *, lang: str | None = None) → Mint[source]

Get details about a specific mint (async).

Parameters:: mint_id (int) – Numista mint ID
Returns:: Mint details
Return type:: Mint
Raises:: httpx.HTTPStatusError – If mint not found or API error

get_mints(lang: str = 'en') → list[Mint][source]

Get list of all mints.

Supports both sync and async clients via duck-typing.

Parameters:: lang (str) – Language code (en, es, fr)
Returns:: List of all mints
Return type:: list[Mint]
Raises:: httpx.HTTPStatusError – If API returns error

async get_mints_async(lang: str = 'en') → list[Mint][source]

Get list of all mints (async).

Parameters:: lang (str) – Language code (en, es, fr)
Returns:: List of all mints
Return type:: list[Mint]
Raises:: httpx.HTTPStatusError – If API returns error

to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[Mint][source]

Convert API response items to Mint models.

Parameters:

items (list[Mapping[str, Any]]) – Raw API response items
**kwargs (Any) – Unused (for interface consistency)

Returns:

Parsed mint models

Return type:

list[Mint]

numistalib.services.mints.service.MintServiceAsync: alias of MintService

Collections Service

Collection service implementation.

class numistalib.services.collections.service.CollectionService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: CollectionServiceBase

Unified collection service supporting both sync and async clients.

Requires OAuth authentication with appropriate scopes.

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize collection service.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client instance (sync or async)

add_collected_item(user_id: int, item_data: dict[str, object]) → CollectedItem[source]

Add item to user’s collection.

Requires OAuth 2.0 authentication with ‘edit_collection’ scope.

Parameters:

user_id (int) – Numista user ID
item_data (dict) – Item data payload

Returns:

Created collected item

Return type:

CollectedItem

Raises:

httpx.HTTPStatusError – If API returns error

async add_collected_item_async(user_id: int, item_data: dict[str, object]) → CollectedItem[source]

Add item to user’s collection (async).

Requires OAuth 2.0 authentication with ‘edit_collection’ scope.

Parameters:

user_id (int) – Numista user ID
item_data (dict) – Item data payload

Returns:

Created collected item

Return type:

CollectedItem

Raises:

httpx.HTTPStatusError – If API returns error

delete_collected_item(user_id: int, item_id: int) → None[source]

Delete item from user’s collection.

Requires OAuth 2.0 authentication with ‘edit_collection’ scope.

Parameters:

user_id (int) – Numista user ID
item_id (int) – Collected item ID

Raises:

httpx.HTTPStatusError – If API returns error

async delete_collected_item_async(user_id: int, item_id: int) → None[source]

Delete item from user’s collection (async).

Requires OAuth 2.0 authentication with ‘edit_collection’ scope.

Parameters:

user_id (int) – Numista user ID
item_id (int) – Collected item ID

Raises:

httpx.HTTPStatusError – If API returns error

edit_collected_item(user_id: int, item_id: int, item_data: dict[str, object]) → CollectedItem[source]

Edit item in user’s collection.

Requires OAuth 2.0 authentication with ‘edit_collection’ scope.

Parameters:

user_id (int) – Numista user ID
item_id (int) – Collected item ID
item_data (dict) – Item data payload (all fields optional)

Returns:

Updated collected item

Return type:

CollectedItem

Raises:

httpx.HTTPStatusError – If API returns error

async edit_collected_item_async(user_id: int, item_id: int, item_data: dict[str, object]) → CollectedItem[source]

Edit item in user’s collection (async).

Requires OAuth 2.0 authentication with ‘edit_collection’ scope.

Parameters:

user_id (int) – Numista user ID
item_id (int) – Collected item ID
item_data (dict) – Item data payload (all fields optional)

Returns:

Updated collected item

Return type:

CollectedItem

Raises:

httpx.HTTPStatusError – If API returns error

get_collected_item(user_id: int, item_id: int) → CollectedItem[source]

Get details about a specific collected item.

Requires OAuth 2.0 authentication with ‘view_collection’ scope.

Parameters:

user_id (int) – Numista user ID
item_id (int) – Collected item ID

Returns:

Collected item details

Return type:

CollectedItem

Raises:

httpx.HTTPStatusError – If item not found, unauthorized, or API error

async get_collected_item_async(user_id: int, item_id: int) → CollectedItem[source]

Get details about a specific collected item (async).

Parameters:

user_id (int) – Numista user ID
item_id (int) – Collected item ID

Returns:

Collected item details

Return type:

CollectedItem

Raises:

httpx.HTTPStatusError – If item not found, unauthorized, or API error

get_collected_items(user_id: int, category: str | None = None, type_id: int | None = None, collection_id: int | None = None) → list[CollectedItem][source]

Get all items in a user’s collection.

Requires OAuth 2.0 authentication with ‘view_collection’ scope. Supports both sync and async clients via duck-typing.

Parameters:

user_id (int) – Numista user ID
category (str | None) – Filter by category (coin, banknote, exonumia)
type_id (int | None) – Filter by type ID
collection_id (int | None) – Filter by collection ID

Returns:

List of collected items

Return type:

list[CollectedItem]

Raises:

httpx.HTTPStatusError – If user not found, unauthorized, or API error

async get_collected_items_async(user_id: int, category: str | None = None, type_id: int | None = None, collection_id: int | None = None) → list[CollectedItem][source]

Get all items in a user’s collection (async).

Parameters:

user_id (int) – Numista user ID
category (str | None) – Filter by category (coin, banknote, exonumia)
type_id (int | None) – Filter by type ID
collection_id (int | None) – Filter by collection ID

Returns:

List of collected items

Return type:

list[CollectedItem]

Raises:

httpx.HTTPStatusError – If user not found, unauthorized, or API error

get_collections(user_id: int) → list[UserCollection][source]

Get all collections for a user.

Requires OAuth 2.0 authentication with ‘view_collection’ scope.

Parameters:: user_id (int) – Numista user ID
Returns:: List of user collections
Return type:: list[UserCollection]
Raises:: httpx.HTTPStatusError – If user not found, unauthorized, or API error

async get_collections_async(user_id: int) → list[UserCollection][source]

Get all collections for a user (async).

Parameters:: user_id (int) – Numista user ID
Returns:: List of user collections
Return type:: list[UserCollection]
Raises:: httpx.HTTPStatusError – If user not found, unauthorized, or API error

to_models(items: list[Mapping[str, Any]], user_id: int | None = None, **kwargs: Any) → list[CollectedItem][source]

Convert API response items to CollectedItem models.

Parameters:

items (list[Mapping[str, Any]]) – Raw API response items
user_id (int | None) – Associated user ID (not used, kept for interface compatibility)
**kwargs (Any) – Additional context

Returns:

Parsed collected item models

Return type:

list[CollectedItem]

Image Search Service

Image Search service implementation.

class numistalib.services.image_search.service.ImageSearchService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: ImageSearchServiceBase

Unified image search service supporting both sync and async clients.

This is a paid feature. See pricing page for details.

CLASS_ITEMS_KEY: str = 'types'

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize image search service.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client instance (sync or async)

search_by_image(images: list[dict[str, str]], category: str | None = None, lang: str = 'en', activate_experimental_features: bool = False) → list[TypeBasic][source]

Search catalogue by image(s).

This is a paid feature.

Supports both sync and async clients via duck-typing.

Parameters:

images (list[dict]) – List of image objects with ‘mime_type’ and ‘image_data’ keys. Max 2 images. Max size 1024x1024 px.
category (str | None) – Filter by category (coin, banknote, exonumia)
lang (str) – Language code
activate_experimental_features (bool) – Enable experimental features (beta, longer response time)

Returns:

List of matching types (up to 100)

Return type:

list[TypeBasic]

Raises:

httpx.HTTPStatusError – If API returns error
ValueError – If invalid image count or size

async search_by_image_async(images: list[dict[str, str]], category: str | None = None, lang: str = 'en', activate_experimental_features: bool = False) → list[TypeBasic][source]

Search catalogue by image(s) (async).

This is a paid feature.

Parameters:

images (list[dict]) – List of image objects with ‘mime_type’ and ‘image_data’ keys. Max 2 images. Max size 1024x1024 px.
category (str | None) – Filter by category (coin, banknote, exonumia)
lang (str) – Language code
activate_experimental_features (bool) – Enable experimental features (beta, longer response time)

Returns:

List of matching types (up to 100)

Return type:

list[TypeBasic]

Raises:

httpx.HTTPStatusError – If API returns error
ValueError – If invalid image count or size

to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[TypeBasic][source]

Convert API response items to TypeBasic models.

Parameters:

items (list[Mapping[str, Any]]) – Raw API response items
**kwargs (Any) – Unused (for interface consistency)

Returns:

List of type models

Return type:

list[TypeBasic]

numistalib.services.image_search.service.ImageSearchServiceAsync: alias of ImageSearchService

Literature Service

Literature service implementation.

class numistalib.services.literature.service.LiteratureService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: LiteratureServiceBase

Unified literature service supporting both sync and async clients.

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize literature service.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client instance (sync or async)

get_publication(publication_id: int) → Publication[source]

Get publication details by ID.

Parameters:: publication_id (int) – Numista publication ID
Returns:: Publication details
Return type:: Publication

Examples

>>> service = LiteratureService(client)
>>> pub = service.get_publication(123)
>>> print(pub.title)

async get_publication_async(publication_id: int) → Publication[source]

Get publication details by ID (async).

Parameters:: publication_id (int) – Numista publication ID
Returns:: Publication details
Return type:: Publication

Examples

>>> service = LiteratureService(async_client)
>>> pub = await service.get_publication_async(123)
>>> print(pub.title)

to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[Publication][source]

Convert API response items to Publication models.

Parameters:

items (list[Mapping[str, Any]]) – Raw API response items
**kwargs (Any) – Unused (for interface consistency)

Returns:

Parsed publication models

Return type:

list[Publication]

Prices Service

Price service implementation.

class numistalib.services.prices.service.PriceService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: PriceServiceBase

Unified price service supporting both sync and async clients.

CLASS_ITEMS_KEY: str = 'prices'

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize price service.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client instance (sync or async)

get_prices(type_id: int, issue_id: int, *, currency: str | None = None, lang: str | None = None) → list[Price][source]

Get price estimates for a specific issue.

Supports both sync and async clients via duck-typing.

Parameters:

type_id (int) – Numista type ID
issue_id (int) – Numista issue ID
currency (str | None) – Filter by currency code
lang (str | None) – Language code

Returns:

List of price estimates by grade

Return type:

list[Price]

Raises:

httpx.HTTPStatusError – If issue not found or API error

async get_prices_async(type_id: int, issue_id: int, *, currency: str | None = None, lang: str | None = None) → list[Price][source]

Get price estimates for a specific issue (async).

Parameters:

type_id (int) – Numista type ID
issue_id (int) – Numista issue ID
currency (str | None) – Filter by currency code
lang (str | None) – Language code

Returns:

List of price estimates by grade

Return type:

list[Price]

Raises:

httpx.HTTPStatusError – If issue not found or API error

to_models(items: list[Mapping[str, Any]], issue_id: int | None = None, **kwargs: Any) → list[Price][source]

Convert API response to Price models.

The API returns {currency: “EUR”, prices: [{grade: “f”, price: 180}]}, so we need to extract the top-level currency and merge it with each price.

Parameters:

items (list[Mapping[str, Any]]) – Raw API response items (single dict with currency and prices array)
issue_id (int | None) – Numista issue ID (required context)
**kwargs (Any) – Additional conversion context

Returns:

Parsed price models

Return type:

list[Price]

numistalib.services.prices.service.PriceServiceAsync: alias of PriceService

Users Service

User service implementation.

class numistalib.services.users.service.UserService(client: SyncClientProtocol | AsyncClientProtocol)[source]

Bases: UserServiceBase

Unified user service supporting both sync and async clients.

__init__(client: SyncClientProtocol | AsyncClientProtocol) → None[source]

Initialize user service.

Parameters:: client (SyncClientProtocol | AsyncClientProtocol) – HTTP client instance (sync or async)

get_collected_items(user_id: int, category: str | None = None, type_id: int | None = None, collection_id: int | None = None) → list[CollectedItem][source]

Get collected items for a user.

Parameters:

user_id (int) – Numista user ID
category (str | None) – Filter by category (coin, banknote, exonumia)
type_id (int | None) – Filter by type ID
collection_id (int | None) – Filter by collection ID

Returns:

List of collected items

Return type:

list[CollectedItem]

Raises:

httpx.HTTPStatusError – If user not found or API error

async get_collected_items_async(user_id: int, category: str | None = None, type_id: int | None = None, collection_id: int | None = None) → list[CollectedItem][source]

Get collected items for a user (async).

Parameters:

user_id (int) – Numista user ID
category (str | None) – Filter by category (coin, banknote, exonumia)
type_id (int | None) – Filter by type ID
collection_id (int | None) – Filter by collection ID

Returns:

List of collected items

Return type:

list[CollectedItem]

Raises:

httpx.HTTPStatusError – If user not found or API error

get_collections(user_id: int) → list[dict[str, Any]][source]

Get list of collections for a user.

Parameters:: user_id (int) – Numista user ID
Returns:: List of collection objects
Return type:: list[dict[str, Any]]
Raises:: httpx.HTTPStatusError – If user not found or API error

async get_collections_async(user_id: int) → list[dict[str, Any]][source]

Get list of collections for a user (async).

Parameters:: user_id (int) – Numista user ID
Returns:: List of collection objects
Return type:: list[dict[str, Any]]
Raises:: httpx.HTTPStatusError – If user not found or API error

get_user(user_id: int) → User[source]

Get details about a specific user.

Supports both sync and async clients via duck-typing.

Parameters:: user_id (int) – Numista user ID
Returns:: User profile details
Return type:: User
Raises:: httpx.HTTPStatusError – If user not found or API error

async get_user_async(user_id: int) → User[source]

Get details about a specific user (async).

Parameters:: user_id (int) – Numista user ID
Returns:: User profile details
Return type:: User
Raises:: httpx.HTTPStatusError – If user not found or API error

to_models(items: list[Mapping[str, Any]], **kwargs: Any) → list[User][source]

Convert API response items to User models.

Parameters:

items (list[Mapping[str, Any]]) – Raw API response items (single item)
**kwargs (Any) – Unused (for interface consistency)

Returns:

List with single User model

Return type:

list[User]

numistalib.services.users.service.UserServiceAsync: alias of UserService