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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mokkari-4.5.0.tar.gz.
File metadata
- Download URL: mokkari-4.5.0.tar.gz
- Upload date:
- Size: 80.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
093afd0c31d3d4341bc5a52c2ad57fb26838a9bef6b026818c832937aecba90e
|
|
| MD5 |
049c234c157cc880dec8640d1993c653
|
|
| BLAKE2b-256 |
c0d2e82a8e98bc3fbbb9372abb3109f908081eee3cdaf72c633647b6bd0e1d7d
|
File details
Details for the file mokkari-4.5.0-py3-none-any.whl.
File metadata
- Download URL: mokkari-4.5.0-py3-none-any.whl
- Upload date:
- Size: 60.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a9a3cacf3e0742e904c0ed9ad624b9301abacee3c2f50ec5d3538dc1a96cd8fe
|
|
| MD5 |
6642e89cfee66de73b0036013f6cc72d
|
|
| BLAKE2b-256 |
6edbdf071cba51706db3507e0e98011b26ee71f324f76d06d0481fed725e4ea5
|
