Session

`Session(username: str, passwd: str, cache: sqlite_cache.SqliteCache | None = None, user_agent: str | None = None, dev_mode: bool = False, bucket: AbstractBucket | None = None)`

A comprehensive API client for interacting with the Metron Comics Database.

The Session class provides a complete interface for accessing comic book data including creators, characters, publishers, series, issues, teams, arcs, and more. It handles authentication, rate limiting, caching, and response validation automatically.

The class implements automatic rate limiting to respect API quotas:

20 requests per minute
5,000 requests per day

Important: When rate limits are exceeded, a RateLimitError is raised immediately without making the API request. Applications must catch and handle this exception appropriately (see examples below).

Features:

Automatic authentication with username/password
Built-in rate limiting with clear error messages
Optional SQLite caching for improved performance
Comprehensive error handling and validation
Support for both read and write operations (write operations require admin permissions)
Automatic pagination handling for large result sets
Image upload support for certain endpoints
Development mode for testing against a local instances of Metron.

PARAMETER	DESCRIPTION
`username`	Username for Metron API authentication. TYPE: `str`
`passwd`	Password for Metron API authentication. TYPE: `str`
`cache`	Optional SqliteCache instance for caching responses to improve performance. TYPE: `SqliteCache \| None` DEFAULT: `None`
`user_agent`	Optional custom user agent string to append to the default user agent. TYPE: `str \| None` DEFAULT: `None`
`dev_mode`	If True, connects to local development instance at 127.0.0.1:8000 instead of production. TYPE: `bool` DEFAULT: `False`

ATTRIBUTE	DESCRIPTION
`username`	The username used for API authentication. TYPE: `str`
`passwd`	The password used for API authentication. TYPE: `str`
`header`	HTTP headers sent with each request, including User-Agent. TYPE: `dict`
`api_url`	The base URL for API requests (production or development). TYPE: `str`
`cache`	The cache instance if provided. TYPE: `SqliteCache \| None`

Examples:

Basic usage:

Python Console Session

>>> session = Session("username", "password")
>>> issue = session.issue(1)
>>> print(issue)

With caching:

Python Console Session

>>> from mokkari.sqlite_cache import SqliteCache
>>> cache = SqliteCache("cache.db")
>>> session = Session("username", "password", cache=cache)

Development mode:

Python Console Session

>>> session = Session("username", "password", dev_mode=True)

Handling rate limits - simple retry:

Python Console Session

>>> import time
>>> from mokkari.exceptions import RateLimitError
>>> session = Session("username", "password")
>>> try:
...     issue = session.issue(1)
... except RateLimitError as e:
...     print(f"Rate limited: {e}")
...     print(f"Waiting {format_time(e.retry_after)}...")
...     time.sleep(e.retry_after)
...     issue = session.issue(1)  # Retry after waiting

Handling minute vs daily rate limits:

Python Console Session

>>> import time
>>> from mokkari.exceptions import RateLimitError
>>> session = Session("username", "password")
>>> def fetch_with_rate_limit_handling(issue_id):
...     while True:
...         try:
...             return session.issue(issue_id)
...         except RateLimitError as e:
...             if "per minute" in str(e):
...                 # Minute limit - automatically wait and retry
...                 print(f"{e}")
...                 print(f"Waiting {format_time(e.retry_after)}...")
...                 time.sleep(e.retry_after)
...                 continue
...             elif "per day" in str(e):
...                 # Daily limit - ask user whether to wait or quit
...                 response = input(f"Wait {format_time(e.retry_after)}? (y/n): ")
...                 if response.lower() == 'y':
...                     time.sleep(e.retry_after)
...                     continue
...                 else:
...                     raise
...             else:
...                 raise
>>> issue = fetch_with_rate_limit_handling(1)

Redis-backed rate limiting (shared across multiple workers or processes):

Python Console Session

>>> from pyrate_limiter import RedisBucket
>>> import redis
>>> pool = redis.ConnectionPool.from_url("redis://localhost:6379")
>>> bucket = RedisBucket.init(DEFAULT_RATES, redis.Redis(connection_pool=pool), "mokkari")
>>> session = Session("username", "password", bucket=bucket)

In-memory bucket (useful for testing or single-process use without a database):

Python Console Session

>>> from pyrate_limiter import InMemoryBucket
>>> session = Session("username", "password", bucket=InMemoryBucket(DEFAULT_RATES))

RAISES	DESCRIPTION
`ApiError`	For general API errors, authentication failures, or network issues.
`RateLimitError`	When API rate limits are exceeded (both local tracking and server-side).
`CacheError`	For cache-related errors.
`ValidationError`	For invalid response data that doesn't match expected schemas.

Initialize a Session object with authentication and configuration.

Sets up the session with proper authentication headers, API endpoint URL, and optional caching. The user agent is automatically constructed to include the library version and system information.

PARAMETER	DESCRIPTION
`username`	Username for Metron API authentication. TYPE: `str`
`passwd`	Password for Metron API authentication. TYPE: `str`
`cache`	Optional SqliteCache instance for response caching. TYPE: `SqliteCache \| None` DEFAULT: `None`
`user_agent`	Optional custom user agent string to prepend to the default. TYPE: `str \| None` DEFAULT: `None`
`dev_mode`	If True, use local development server instead of production. TYPE: `bool` DEFAULT: `False`
`bucket`	Optional pyrate_limiter bucket for rate limiting. If not provided, a default SQLite-backed bucket is created and shared across sessions. Pass a custom bucket to share rate limit state across workers (e.g., using a Redis or database-backed bucket). TYPE: `AbstractBucket \| None` DEFAULT: `None`

Functions

`arc(_id: int, if_modified_since: datetime | None = None) -> Arc | None`

Retrieve detailed information about a story arc by ID.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the arc. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Arc \| None`	An Arc object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the arc is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`arc_issues_list(_id: int) -> list[BaseIssue]`

Retrieve a list of issues that are part of a specific story arc.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the arc. TYPE: `int`

RETURNS	DESCRIPTION
`list[BaseIssue]`	list[BaseIssue]: A list of BaseIssue objects.

`arc_patch(_id: int, data: ArcPost) -> Arc`

Update an existing story arc in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the arc to update. TYPE: `int`
`data`	ArcPost object containing the updated arc information. TYPE: `ArcPost`

RETURNS	DESCRIPTION
`Arc`	The updated Arc object. TYPE: `Arc`

RAISES	DESCRIPTION
`ApiError`	If update fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`arc_post(data: ArcPost) -> Arc`

Create a new story arc in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	ArcPost object containing the arc information to create. TYPE: `ArcPost`

RETURNS	DESCRIPTION
`Arc`	The newly created Arc object. TYPE: `Arc`

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`arcs_list(params: dict[str, str | int] | None = None) -> list[BaseResource]`

Retrieve a list of story arcs with optional filtering.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. Common parameters include 'name', 'modified_gt', 'modified_lt'. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BaseResource]`	list[BaseResource]: A list of BaseResource objects representing arcs.

`character(_id: int, if_modified_since: datetime | None = None) -> Character | None`

Retrieve detailed information about a character by ID.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the character. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Character \| None`	A Character object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the character is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> character = session.character(1)
>>> print(character.name)

`character_issues_list(_id: int) -> list[BaseIssue]`

Retrieve a list of issues featuring a specific character.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the character. TYPE: `int`

RETURNS	DESCRIPTION
`list[BaseIssue]`	list[BaseIssue]: A list of BaseIssue objects.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> issues = session.character_issues_list(1)
>>> print(f"Character appears in {len(issues)} issues")

`character_patch(_id: int, data: CharacterPost) -> CharacterPostResponse`

Update an existing character in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the character to update. TYPE: `int`
`data`	CharacterPost object containing the updated character information. TYPE: `CharacterPost`

RETURNS	DESCRIPTION
`CharacterPostResponse`	The updated character response. TYPE: `CharacterPostResponse`

RAISES	DESCRIPTION
`ApiError`	If update fails or if user lacks permissions.

`character_post(data: CharacterPost) -> CharacterPostResponse`

Create a new character in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	CharacterPost object containing the character information to create. TYPE: `CharacterPost`

RETURNS	DESCRIPTION
`CharacterPostResponse`	The newly created character response. TYPE: `CharacterPostResponse`

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.

`characters_list(params: dict[str, str | int] | None = None) -> list[BaseResource]`

Retrieve a list of characters with optional filtering.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. Common parameters include 'name', 'modified_gt', 'modified_lt'. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BaseResource]`	list[BaseResource]: A list of BaseResource objects representing characters.

`collection(_id: int, if_modified_since: datetime | None = None) -> CollectionRead | None`

Retrieve detailed information about a collection item by ID.

Note: This endpoint requires authentication. Users can only access their own collection items.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the collection item. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`CollectionRead \| None`	A CollectionRead object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the collection item is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> collection_item = session.collection(1)
>>> print(f"Issue: {collection_item.issue.series.name} #{collection_item.issue.number}")

`collection_missing_issues(series_id: int) -> list[MissingIssue]`

Retrieve a list of missing issues for a specific series.

Returns issues from a series that are not in the authenticated user's collection.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`series_id`	The unique identifier for the series. TYPE: `int`

RETURNS	DESCRIPTION
`list[MissingIssue]`	list[MissingIssue]: A list of MissingIssue objects representing issues not in the user's collection.

RAISES	DESCRIPTION
`ApiError`	If the series is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> missing = session.collection_missing_issues(1)
>>> print(f"Missing {len(missing)} issues from this series")

`collection_missing_series() -> list[MissingSeries]`

Retrieve a list of series where the user has some issues but is missing others.

Returns series where the authenticated user owns at least one issue but not all issues in the series.

Note: This endpoint requires authentication.

RETURNS	DESCRIPTION
`list[MissingSeries]`	list[MissingSeries]: A list of MissingSeries objects representing series with incomplete collections.

RAISES	DESCRIPTION
`ApiError`	If there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> incomplete_series = session.collection_missing_series()
>>> for series in incomplete_series:
...     print(f"Series: {series.name} ({series.year_began})")

`collection_scrobble(data: ScrobbleRequest) -> ScrobbleResponse`

Mark an issue as read (scrobble).

This endpoint marks an issue as read and optionally provides a rating. If the issue is not already in the user's collection, it will be automatically added with default values.

Note: This endpoint requires authentication. Users can only scrobble issues to their own collection.

PARAMETER	DESCRIPTION
`data`	ScrobbleRequest object containing the issue_id and optional date_read and rating. TYPE: `ScrobbleRequest`

RETURNS	DESCRIPTION
`ScrobbleResponse`	A ScrobbleResponse object containing the updated collection item information and a 'created' flag indicating whether a new collection item was created. TYPE: `ScrobbleResponse`

RAISES	DESCRIPTION
`ApiError`	If the issue is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> from datetime import datetime
>>> scrobble_data = ScrobbleRequest(
...     issue_id=1,
...     date_read=datetime.now(),
...     rating=5
... )
>>> result = session.collection_scrobble(scrobble_data)
>>> print(f"Issue marked as read: {result.issue.series.name} #{result.issue.number}")
>>> print(f"New item created: {result.created}")

Mark as read without rating:

Python Console Session

>>> scrobble_data = ScrobbleRequest(issue_id=1)
>>> result = session.collection_scrobble(scrobble_data)

`collection_stats() -> CollectionStats`

Retrieve statistics about the authenticated user's collection.

Returns comprehensive statistics including total items, total value, read/unread counts, and breakdowns by format.

Note: This endpoint requires authentication.

RETURNS	DESCRIPTION
`CollectionStats`	A CollectionStats object containing collection statistics. TYPE: `CollectionStats`

RAISES	DESCRIPTION
`ApiError`	If there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> stats = session.collection_stats()
>>> print(f"Total items: {stats.total_items}")
>>> print(f"Total value: {stats.total_value}")
>>> print(f"Read: {stats.read_count}, Unread: {stats.unread_count}")

`collections_list(params: dict[str, str | int] | None = None) -> list[CollectionList]`

Retrieve a list of collection items with optional filtering.

Note: This endpoint requires authentication. Users can only access their own collection items.

PARAMETER DESCRIPTION

params

Optional dictionary of query parameters for filtering results. Common parameters include: - 'book_format': Filter by format (PRINT, DIGITAL, BOTH) - 'grade': Filter by comic book grade (CGC scale) - 'grading_company': Filter by grading company (CGC, CBCS, PGX) - 'is_read': Filter by read status (boolean) - 'issue__series': Filter by series ID - 'modified_gt': Filter by modification date (greater than) - 'purchase_date': Filter by purchase date - 'rating': Filter by star rating (1-5)

TYPE: dict[str, str | int] | None DEFAULT: None

RETURNS	DESCRIPTION
`list[CollectionList]`	list[CollectionList]: A list of CollectionList objects representing collection items.

RAISES	DESCRIPTION
`ApiError`	If there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> collection = session.collections_list({"is_read": False})
>>> unread = [item for item in collection if not item.is_read]

`creator(_id: int, if_modified_since: datetime | None = None) -> Creator | None`

Retrieve detailed information about a creator by ID.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the creator. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. Typically you would pass a previously fetched creator's `modified` field. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Creator \| None`	A Creator object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the creator is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> creator = session.creator(1)
>>> print(creator.name)
>>> # Later, check if updated:
>>> updated = session.creator(1, if_modified_since=creator.modified)
>>> if updated is None:
...     print("Not modified")

`creator_patch(_id: int, data: CreatorPost) -> Creator`

Update an existing creator in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the creator to update. TYPE: `int`
`data`	CreatorPost object containing the updated creator information. TYPE: `CreatorPost`

RETURNS	DESCRIPTION
`Creator`	The updated Creator object. TYPE: `Creator`

RAISES	DESCRIPTION
`ApiError`	If update fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> creator_data = CreatorPost(name="Jane Doe", birth_date="1980-01-01")
>>> updated_creator = session.creator_patch(1, creator_data)

`creator_post(data: CreatorPost) -> Creator`

Create a new creator in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	CreatorPost object containing the creator information to create. TYPE: `CreatorPost`

RETURNS	DESCRIPTION
`Creator`	The newly created Creator object. TYPE: `Creator`

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> creator_data = CreatorPost(name="Jane Doe", birth_date="1980-01-01")
>>> new_creator = session.creator_post(creator_data)

`creators_list(params: dict[str, str | int] | None = None) -> list[BaseResource]`

Retrieve a list of creators with optional filtering.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. Common parameters include 'name', 'modified_gt', 'modified_lt'. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BaseResource]`	list[BaseResource]: A list of BaseResource objects representing creators.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> creators = session.creators_list({"name": "Stan Lee"})
>>> all_creators = session.creators_list()

`credits_post(data: list[CreditPost]) -> list[CreditPostResponse]`

Create new credits for issues in bulk.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	List of CreditPost objects containing credit information to create. TYPE: `list[CreditPost]`

RETURNS	DESCRIPTION
`list[CreditPostResponse]`	list[CreditPostResponse]: A list of newly created credit responses.

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> credits_ = [CreditPost(issue=1, creator=1, role=[1])]
>>> new_credits = session.credits_post(credits_)

`imprint(_id: int, if_modified_since: datetime | None = None) -> Imprint | None`

Retrieve detailed information about an imprint by ID.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the imprint. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Imprint \| None`	An Imprint object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the imprint is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`imprints_list(params: dict[str, str | int] | None = None) -> list[BaseResource]`

Retrieve a list of imprints with optional filtering.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. Common parameters include 'name', 'publisher', 'modified_gt', 'modified_lt'. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BaseResource]`	list[BaseResource]: A list of BaseResource objects representing imprints.

`issue(_id: int, if_modified_since: datetime | None = None) -> Issue | None`

Retrieve detailed information about an issue by ID.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the issue. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Issue \| None`	An Issue object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the issue is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> issue = session.issue(1)
>>> print(f"Issue #{issue.number} of {issue.series.name}")
>>> # Later, check if updated:
>>> updated = session.issue(1, if_modified_since=issue.modified)
>>> if updated is None:
...     print("Not modified")

`issue_patch(_id: int, data: IssuePost) -> IssuePostResponse`

Update an existing issue in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the issue to update. TYPE: `int`
`data`	IssuePost object containing the updated issue information. TYPE: `IssuePost`

RETURNS	DESCRIPTION
`IssuePostResponse`	The updated issue response. TYPE: `IssuePostResponse`

RAISES	DESCRIPTION
`ApiError`	If update fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`issue_post(data: IssuePost) -> IssuePostResponse`

Create a new issue in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	IssuePost object containing the issue information to create. TYPE: `IssuePost`

RETURNS	DESCRIPTION
`IssuePostResponse`	The newly created issue response. TYPE: `IssuePostResponse`

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`issues_list(params: dict[str, str | int] | None = None) -> list[BaseIssue]`

Retrieve a list of issues with optional filtering.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. Common parameters include 'series', 'number', 'cover_date', 'modified_gt', 'modified_lt'. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BaseIssue]`	list[BaseIssue]: A list of BaseIssue objects representing issues.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> issues = session.issues_list({"series": 1})
>>> recent_issues = session.issues_list({"modified_gt": "2023-01-01"})

`publisher(_id: int, if_modified_since: datetime | None = None) -> Publisher | None`

Retrieve detailed information about a publisher by ID.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the publisher. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Publisher \| None`	A Publisher object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the publisher is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`publisher_patch(_id: int, data: PublisherPost) -> Publisher`

Update an existing publisher in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the publisher to update. TYPE: `int`
`data`	PublisherPost object containing the updated publisher information. TYPE: `PublisherPost`

RETURNS	DESCRIPTION
`Publisher`	The updated Publisher object. TYPE: `Publisher`

RAISES	DESCRIPTION
`ApiError`	If update fails or if user lacks permissions.

`publisher_post(data: PublisherPost) -> Publisher`

Create a new publisher in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	PublisherPost object containing the publisher information to create. TYPE: `PublisherPost`

RETURNS	DESCRIPTION
`Publisher`	The newly created Publisher object. TYPE: `Publisher`

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.

`publishers_list(params: dict[str, str | int] | None = None) -> list[BaseResource]`

Retrieve a list of publishers with optional filtering.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. Common parameters include 'name', 'modified_gt', 'modified_lt'. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BaseResource]`	list[BaseResource]: A list of BaseResource objects representing publishers.

`pull_list() -> PullListRead`

Retrieve the authenticated user's pull list.

Note: This endpoint requires authentication.

RETURNS	DESCRIPTION
`PullListRead`	A PullListRead object.

RAISES	DESCRIPTION
`ApiError`	If there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> pl = session.pull_list()
>>> print(f"Series: {pl.series_count}")

`pull_list_add_series(series_id: int) -> PullListSeries`

Add a series to the authenticated user's pull list.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`series_id`	The unique identifier of the series to add. TYPE: `int`

RETURNS	DESCRIPTION
`PullListSeries`	The pull list series entry. TYPE: `PullListSeries`

RAISES	DESCRIPTION
`ApiError`	If the series is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> entry = session.pull_list_add_series(42)
>>> print(entry.series.display_name)

`pull_list_issues(params: dict[str, str | int] | None = None) -> list[PullListIssue]`

Retrieve issues for series on the authenticated user's pull list.

Optionally filter by store date using store_date_after and store_date_before.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters. Supports: - store_date_after: Return issues with a store date on or after this date (YYYY-MM-DD). - store_date_before: Return issues with a store date on or before this date (YYYY-MM-DD). TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[PullListIssue]`	list[PullListIssue]: A list of PullListIssue objects.

RAISES	DESCRIPTION
`ApiError`	If there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> issues = session.pull_list_issues({"store_date_after": "2024-01-01"})
>>> for issue in issues:
...     print(f"{issue.series.name} #{issue.number}")

`pull_list_remove_series(series_pk: int) -> None`

Remove a series from the authenticated user's pull list.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`series_pk`	The unique identifier of the pull list series entry to remove. TYPE: `int`

RAISES	DESCRIPTION
`ApiError`	If the entry is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> session.pull_list_remove_series(1)

`pull_list_series(params: dict[str, str | int] | None = None) -> list[PullListSeries]`

Retrieve the series on the authenticated user's pull list.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[PullListSeries]`	list[PullListSeries]: A list of PullListSeries objects.

RAISES	DESCRIPTION
`ApiError`	If there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> series_list = session.pull_list_series()
>>> for entry in series_list:
...     print(entry.series.display_name)

`reading_list(_id: int, if_modified_since: datetime | None = None) -> ReadingListRead | None`

Retrieve detailed information about a reading list by ID.

Note: This endpoint requires authentication. Users can access: - Authenticated users: Public lists + own lists - Admin users: Public lists + own lists + Metron's lists

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the reading list. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`ReadingListRead \| None`	A ReadingListRead object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the reading list is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`reading_list_items(_id: int) -> list[ReadingListItem]`

Retrieve a paginated list of items for a specific reading list.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the reading list. TYPE: `int`

RETURNS	DESCRIPTION
`list[ReadingListItem]`	list[ReadingListItem]: A list of ReadingListItem objects representing items in the reading list.

RAISES	DESCRIPTION
`ApiError`	If the reading list is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`reading_lists_list(params: dict[str, str | int] | None = None) -> list[ReadingListList]`

Retrieve a list of reading lists with optional filtering.

Note: This endpoint requires authentication. Users can access: - Authenticated users: Public lists + own lists - Admin users: Public lists + own lists + Metron's lists

PARAMETER DESCRIPTION

params

Optional dictionary of query parameters for filtering results. Common parameters include: - 'name': Filter by reading list name - 'user': Filter by user ID - 'username': Filter by username - 'is_private': Filter by privacy status (boolean) - 'attribution_source': Filter by attribution source (CBRO, CMRO, CBH, etc.) - 'modified_gt': Filter by modification date (greater than)

TYPE: dict[str, str | int] | None DEFAULT: None

RETURNS	DESCRIPTION
`list[ReadingListList]`	list[ReadingListList]: A list of ReadingListList objects representing reading lists.

RAISES	DESCRIPTION
`ApiError`	If there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`role_list(params: dict[str, str | int] | None = None) -> list[GenericItem]`

Retrieve a list of available creator roles.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[GenericItem]`	list[GenericItem]: A list of GenericItem objects representing creator roles (e.g., Writer, Artist, Colorist, etc.).

`series(_id: int, if_modified_since: datetime | None = None) -> Series | None`

Retrieve detailed information about a series by ID.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the series. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Series \| None`	A Series object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the series is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`series_issues_list(_id: int) -> list[BaseIssue]`

Retrieve a list of issues that are part of a specific series.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the series. TYPE: `int`

RETURNS	DESCRIPTION
`list[BaseIssue]`	list[BaseIssue]: A list of BaseIssue objects.

`series_list(params: dict[str, str | int] | None = None) -> list[BaseSeries]`

Retrieve a list of series with optional filtering.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. Common parameters include 'name', 'publisher', 'year_began', 'modified_gt', 'modified_lt'. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BaseSeries]`	list[BaseSeries]: A list of BaseSeries objects representing series.

`series_patch(_id: int, data: SeriesPost) -> SeriesPostResponse`

Update an existing series in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the series to update. TYPE: `int`
`data`	SeriesPost object containing the updated series information. TYPE: `SeriesPost`

RETURNS	DESCRIPTION
`SeriesPostResponse`	The updated series response. TYPE: `SeriesPostResponse`

RAISES	DESCRIPTION
`ApiError`	If update fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`series_post(data: SeriesPost) -> SeriesPostResponse`

Create a new series in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	SeriesPost object containing the series information to create. TYPE: `SeriesPost`

RETURNS	DESCRIPTION
`SeriesPostResponse`	The newly created series response. TYPE: `SeriesPostResponse`

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`series_type_list(params: dict[str, str | int] | None = None) -> list[GenericItem]`

Retrieve a list of available series types.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[GenericItem]`	list[GenericItem]: A list of GenericItem objects representing series types.

`team(_id: int, if_modified_since: datetime | None = None) -> Team | None`

Retrieve detailed information about a team by ID.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the team. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Team \| None`	A Team object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the team is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`team_issues_list(_id: int) -> list[BaseIssue]`

Retrieve a list of issues featuring a specific team.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the team. TYPE: `int`

RETURNS	DESCRIPTION
`list[BaseIssue]`	list[BaseIssue]: A list of BaseIssue objects.

`team_patch(_id: int, data: TeamPost) -> TeamPostResponse`

Update an existing team in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the team to update. TYPE: `int`
`data`	TeamPost object containing the updated team information. TYPE: `TeamPost`

RETURNS	DESCRIPTION
`TeamPostResponse`	The updated team response. TYPE: `TeamPostResponse`

RAISES	DESCRIPTION
`ApiError`	If update fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`team_post(data: TeamPost) -> TeamPostResponse`

Create a new team in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	TeamPost object containing the team information to create. TYPE: `TeamPost`

RETURNS	DESCRIPTION
`TeamPostResponse`	The newly created team response. TYPE: `TeamPostResponse`

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`teams_list(params: dict[str, str | int] | None = None) -> list[BaseResource]`

Retrieve a list of teams with optional filtering.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. Common parameters include 'name', 'modified_gt', 'modified_lt'. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BaseResource]`	list[BaseResource]: A list of BaseResource objects representing teams.

`universe(_id: int, if_modified_since: datetime | None = None) -> Universe | None`

Retrieve detailed information about a universe by ID.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the universe. TYPE: `int`
`if_modified_since`	Optional datetime for conditional requests. When provided, the server may return 304 Not Modified and this method returns `None`. TYPE: `datetime \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Universe \| None`	A Universe object, or `None` if the resource has not been modified.

RAISES	DESCRIPTION
`ApiError`	If the universe is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`universe_patch(_id: int, data: UniversePost) -> UniversePostResponse`

Update an existing universe in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`_id`	The unique identifier for the universe to update. TYPE: `int`
`data`	UniversePost object containing the updated universe information. TYPE: `UniversePost`

RETURNS	DESCRIPTION
`UniversePostResponse`	The updated universe response. TYPE: `UniversePostResponse`

RAISES	DESCRIPTION
`ApiError`	If update fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`universe_post(data: UniversePost) -> UniversePostResponse`

Create a new universe in the database.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	UniversePost object containing the universe information to create. TYPE: `UniversePost`

RETURNS	DESCRIPTION
`UniversePostResponse`	The newly created universe response. TYPE: `UniversePostResponse`

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`universes_list(params: dict[str, str | int] | None = None) -> list[BaseResource]`

Retrieve a list of universes with optional filtering.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. Common parameters include 'name', 'modified_gt', 'modified_lt'. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BaseResource]`	list[BaseResource]: A list of BaseResource objects representing universes.

`variant_post(data: VariantPost) -> VariantPostResponse`

Create a new variant cover for an issue.

Note: This function requires Admin permissions at Metron.

PARAMETER	DESCRIPTION
`data`	VariantPost object containing the variant cover information to create. TYPE: `VariantPost`

RETURNS	DESCRIPTION
`VariantPostResponse`	The newly created variant cover response. TYPE: `VariantPostResponse`

RAISES	DESCRIPTION
`ApiError`	If creation fails or if user lacks permissions.
`RateLimitError`	If the Metron API rate limit has been exceeded.

`wish_list() -> WishList`

Retrieve the authenticated user's wish list.

Note: This endpoint requires authentication.

RETURNS	DESCRIPTION
`WishList`	A WishList object.

RAISES	DESCRIPTION
`ApiError`	If there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> wl = session.wish_list()
>>> print(f"Items: {wl.item_count}")

`wish_list_acquire_item(item_pk: int, data: AcquireWishListItem) -> None`

Mark a wish list item as acquired and create a collection item.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`item_pk`	The unique identifier of the wish list item to acquire. TYPE: `int`
`data`	AcquireWishListItem object with optional purchase details. TYPE: `AcquireWishListItem`

RAISES	DESCRIPTION
`ApiError`	If the item is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> from mokkari.schemas.wish_list import AcquireWishListItem
>>> session.wish_list_acquire_item(1, AcquireWishListItem(purchase_price="9.99"))

`wish_list_add_item(data: WishListAddItem) -> WishListItemRead`

Add an issue to the authenticated user's wish list.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`data`	WishListAddItem object containing the issue_id and optional fields. TYPE: `WishListAddItem`

RETURNS	DESCRIPTION
`WishListItemRead`	The newly created wish list item. TYPE: `WishListItemRead`

RAISES	DESCRIPTION
`ApiError`	If the issue is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> from mokkari.schemas.wish_list import WishListAddItem
>>> item = session.wish_list_add_item(WishListAddItem(issue_id=1, priority=2))
>>> print(f"Added: {item.issue.series.name} #{item.issue.number}")

`wish_list_items(params: dict[str, str | int] | None = None) -> list[WishListItemList]`

Retrieve wish list items for the authenticated user.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`params`	Optional dictionary of query parameters for filtering results. TYPE: `dict[str, str \| int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[WishListItemList]`	list[WishListItemList]: A list of WishListItemList objects.

RAISES	DESCRIPTION
`ApiError`	If there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> items = session.wish_list_items()
>>> for item in items:
...     print(f"{item.issue.series.name} #{item.issue.number} - {item.status}")

`wish_list_remove_item(item_pk: int) -> None`

Remove an item from the authenticated user's wish list.

Note: This endpoint requires authentication.

PARAMETER	DESCRIPTION
`item_pk`	The unique identifier of the wish list item to remove. TYPE: `int`

RAISES	DESCRIPTION
`ApiError`	If the item is not found or if there's an API error.
`RateLimitError`	If the Metron API rate limit has been exceeded.

Examples:

Python Console Session

>>> session = Session("username", "password")
>>> session.wish_list_remove_item(1)