Skip to main content

amazing-marvin

Licence: MIT

Async Python client library for the Amazing Marvin API.

Async-first, fully typed, no global state, no blocking I/O. Suitable for any Python application — CLIs, web services, MCP servers, Home Assistant integrations, sync bridges, scheduled scripts.


Installation

pip install amazing-marvin

Requires Python 3.12+ and aiohttp>=3.9.


Quick Start

import asyncio
from amazing_marvin import MarvinClient

async def main():
    async with MarvinClient(api_token="your_token") as client:
        tasks = await client.get_today_items()
        for task in tasks:
            print(task.title, task.done)

asyncio.run(main())

When embedding inside a host that already manages an aiohttp.ClientSession (FastAPI, Home Assistant, an MCP server runtime), pass the existing session at construction so the client never owns or closes it:

client = MarvinClient(
    api_token=token,
    full_access_token=full_token,   # optional
    tz_offset=600,                  # AEST
    throttle=True,
    session=existing_session,       # borrowed; not closed by client
)
tasks = await client.get_today_items()
task = await client.mark_done(item_id)

Use Cases

The library is intentionally framework-agnostic. Common embeddings:

  • MCP servers — wrap each MarvinClient method as a tool; the typed dataclasses serialise cleanly to JSON.
  • Home Assistant integrations — use the borrowed-session pattern with async_get_clientsession(hass).
  • CLIs — pair with Typer or Click for terminal-driven task entry.
  • FastAPI / web dashboards — share the app's aiohttp session via lifespan.
  • Sync bridges — Notion, Todoist, Linear, calendar providers.
  • Scheduled scripts — cron, GitHub Actions, weekly reviews, exports.

Auth Setup

Amazing Marvin exposes two separate tokens, both found under Profile > Integrations > API in the Marvin app:

Token Constructor arg Required for
API Token api_token Read and write operations (most methods)
Full Access Token full_access_token Raw document access, reminders, admin ops

Methods that need a token you have not supplied will raise MarvinAuthError before making any HTTP request.


CouchDB Queries (optional)

If you run a local CouchDB replica of Marvin's database (Marvin's /pre?api page exposes your account's Cloudant credentials for pull replication), the client can query it directly — fast, searchable reads with no Marvin API rate limits:

async with MarvinClient(
    couch_url="http://couchdb:5984",
    couch_db="marvin",
    couch_user="marvin_sync",
    couch_password="...",
) as client:
    await client.ensure_couch_indexes()          # idempotent, run once
    tasks = await client.find_tasks(title_contains="invoice", done=False)
    today = await client.tasks_by_day("2026-07-07")
    overdue = await client.tasks_due_by("2026-07-07")

Helpers: find_tasks, tasks_by_day, tasks_due_by, planner_items, recurring_generators, categories_from_couch, plus raw couch_find for custom Mango selectors. Couch methods raise MarvinCouchError before any HTTP call when couch is unconfigured — HTTP-only users are unaffected.

find_tasks(title_contains=...) is a substring scan, not an indexed lookup: CouchDB narrows on db via the index, then regex-filters the remaining Task documents. It's bounded by limit (default 25) and fine for interactive search, but don't rely on it for large unbounded queries.

The replica is eventually consistent (replication lag of seconds). Treat it as read-only display state; never seed a write from it — fetch authoritative state with get_doc instead.


Rate Limits

The Amazing Marvin API enforces:

  • Burst: 1 request per 3 seconds
  • Daily cap: 1440 requests per calendar day (resets at midnight in your local timezone)

Pass throttle=True to have the client enforce these limits automatically using an internal asyncio lock. When the daily cap is hit, MarvinRateLimitError is raised with daily_cap_exceeded=True. When the server itself returns 429, MarvinRateLimitError is raised with the retry_after value from the response header (if present).


Timezone Handling

Marvin uses integer minutes east of UTC for timezone offsets. For example:

  • tz_offset=600 — AEST (UTC+10)
  • tz_offset=0 — UTC
  • tz_offset=-300 — EST (UTC-5)

Pass tz_offset at client construction for a default, or override it per-call on methods that accept tz_offset=. The offset affects which calendar day is considered "today" for scheduling and daily cap resets.


Licence

MIT — see LICENSE.

Metadata

Release files for amazing-marvin 0.2.0

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

Source distribution (sdist)

Source distribution for amazing-marvin 0.2.0
File Size Uploaded Provenance Actions
amazing_marvin-0.2.0.tar.gz 129.3 kB With provenance Details for amazing_marvin-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amazing-marvin 0.2.0
File Interpreter ABI Platform Actions
amazing_marvin-0.2.0-py3-none-any.whl Python 3 none any Details for amazing_marvin-0.2.0-py3-none-any.whl

Total release size: 147.8 kB

Release files / amazing_marvin-0.2.0.tar.gz

Download URL amazing_marvin-0.2.0.tar.gz
Size 129.3 kB
Tags Source
SHA-256 checksum
How to use checksums
c309dcdc0eb155fbfe54885282c2907da0757a35a1acb75b18a3a9207a4b8d53
BLAKE2b-256 checksum
How to use checksums
04660c13d3dc5a5bbd3f3e7d0e42bb21c69526db115f1509235925ee895b2655
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 7, 2026.

Transparency log

Release files / amazing_marvin-0.2.0-py3-none-any.whl

Download URL amazing_marvin-0.2.0-py3-none-any.whl
Size 18.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f24c4f41416edabc232532a14a97cb4b9fced5645448776df1ce13e0664c7541
BLAKE2b-256 checksum
How to use checksums
0357d2c8a3f6a24bd19a3a33eef1202b944c408daf491fa580f54dd5ccfdeda7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 7, 2026.

Transparency log

Security for amazing-marvin 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for amazing_marvin-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page