Mokkari

A python wrapper for the Metron Comic Book Database API.

Installation

pip install mokkari

Authentication

Mokkari supports two authentication methods:

import mokkari

# Token authentication (generate a token from your metron.cloud account page)
m = mokkari.api(api_token="your-api-token")

# Username/password (Basic Auth)
m = mokkari.api(username, password)

Example Usage

import mokkari

# Your own config file to keep your credentials secret
from config import username, password

m = mokkari.api(username, password)

# Get all Marvel comics for the week of 2021-06-07
this_week = m.issues_list(
    {
        "store_date_range_after": "2021-06-07",
        "store_date_range_before": "2021-06-13",
        "publisher_name": "marvel",
    }
)

# Print the results
for i in this_week:
    print(f"{i.id} {i.issue_name}")

    # Retrieve the detail for an individual issue
    asm_68 = m.issue(31660)

# Print the issue Description
print(asm_68.desc)

Rate Limiting

The API has a fixed limit of 20 requests per minute, plus a daily limit that starts at 5,000 requests and is raised for OpenCollective donors (up to 25,000/day). Because the daily limit varies per user, mokkari doesn't hardcode it — it reads the X-RateLimit-* headers Metron returns with every response and pre-empts a request once those headers show a window is exhausted, avoiding an HTTP call that would fail anyway. When a rate limit is exceeded, a RateLimitError is raised.

The most recently observed state is available via session.rate_limit_status:

status = m.rate_limit_status
print(f"Sustained remaining: {status.sustained.remaining}/{status.sustained.limit}")

Handling Rate Limits

The RateLimitError includes a retry_after attribute that tells you exactly how many seconds to wait before making another request:

import mokkari
from mokkari.exceptions import RateLimitError
import time

m = mokkari.api(username, password)

try:
    issue = m.issue(31660)
except RateLimitError as e:
    # Display user-friendly message
    print(f"Rate limited: {e}")

    # Programmatically wait for the exact time needed
    print(f"Waiting {e.retry_after} seconds...")
    time.sleep(e.retry_after)

    # Retry the request
    issue = m.issue(31660)

Thread Safety

A Session can be shared across threads, but the rate-limit check above is advisory rather than a hard gate: it only blocks once the last known response headers show a window is exhausted, and that check isn't synchronized with sending the request. Concurrent threads can therefore each pass the check and send their requests before either response updates rate_limit_status, letting a burst of threads momentarily exceed the per-minute limit (Metron's server-side limit still applies and will reject the excess requests).

If you're calling a shared Session from multiple threads, cap your own concurrency instead of relying on Session to do it for you, e.g. keep a ThreadPoolExecutor at or below the burst limit:

from concurrent.futures import ThreadPoolExecutor

m = mokkari.api(username, password)

# Keep worker count at or below the burst limit (20/min) to avoid racing
# past the local rate-limit check.
with ThreadPoolExecutor(max_workers=20) as executor:
    issues = list(executor.map(m.issue, issue_ids))

Documentation

Read the project documentation

Bugs/Requests

Please use the GitHub issue tracker to submit bugs or request features.

Metadata

Release files for mokkari 4.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mokkari 4.7.1
File	Size	Uploaded
mokkari-4.7.1.tar.gz	81.6 kB	Sep 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mokkari 4.7.1
File	Interpreter	ABI	Platform	Reset
mokkari-4.7.1-py3-none-any.whl 60.7 kB Sep 14, 2026	Python 3	none	any	Details

Total release size: 142.4 kB

Release files / mokkari-4.7.1.tar.gz

Download URL	mokkari-4.7.1.tar.gz
Size	81.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`a722025d6b31080207f2a3a068530af4f6551f17dd12ee3a34312c4e16374756`
BLAKE2b-256 checksum How to use checksums	`9b9a1a237892a496356105c4e7b53b164856801304b057c7057768d3267d05b4`
Upload date	Sep 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / mokkari-4.7.1-py3-none-any.whl

Download URL	mokkari-4.7.1-py3-none-any.whl
Size	60.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`65cab05e8c45f6666a4ee3e7c2a97f22b0568a560054a223df4b55432d2366e9`
BLAKE2b-256 checksum How to use checksums	`43261922ecc5dbc191b44c8eb424336e1c66969e2b8fe895a14c38adf01fa990`
Upload date	Sep 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`