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
Metadata
1 maintainer
Release files for mokkari 4.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mokkari-4.7.0.tar.gz | 81.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mokkari-4.7.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 142.4 kB
Release files / mokkari-4.7.0.tar.gz
| Download URL | mokkari-4.7.0.tar.gz |
|---|---|
| Size | 81.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ca5179fce50637cb03ce29ae8637bd448b23c38ce3d93d6b04d369eb3dbc8c46
|
|
BLAKE2b-256 checksum How to use checksums |
8b8ddce71ebd41ac2ef8cc9462d2f52860d4db8161d5aee1b8e8738802021bbe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","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.0-py3-none-any.whl
| Download URL | mokkari-4.7.0-py3-none-any.whl |
|---|---|
| Size | 60.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
370a0a64535da5fce52d16acfd7b9c1cd8282290a30fde75e13fd65404183362
|
|
BLAKE2b-256 checksum How to use checksums |
80f73ac69304b674612711a400834cb5a380dc5e45bd0a5630cab7c5f92b5162
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","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}
|
