Repository navigation
zdc-google-api v1.0.0
First official production release of zdc-google-api — a clean, Pythonic wrapper for Google Gmail and Calendar APIs with automated OAuth credential handling.
Features
OAuth & Factory Architecture
- Zero-Boilerplate Authentication: Default scopes (
GMAIL_SCOPES,CALENDAR_SCOPES) are encapsulated inside factory helpers (get_message_handler(),get_calendar_handler(), etc.). - Desktop & Headless Support: Automated local redirect server for desktop apps, and console copy-paste flow (
headless=TrueorGOOGLE_API_HEADLESS=1) for Docker/SSH environments. - In-Memory Credentials:
get_credentials_notoken()for ephemeral sessions and CI environments. - Context Managers: Native
withstatement support on all handlers for deterministic socket and resource cleanup.
Gmail API (google_api.gmail)
MessageHandler:- Generator-based message iteration with automatic pagination (
iter_messages). - Search queries and sender filtering (
filterSenders). - Robust MIME decoding with HTML/plain-text fallbacks (
get_message_body). - Email sending and draft creation (
send_message,create_draft). - Batch modifications (
batch_modify,batch_delete) and trash management.
- Generator-based message iteration with automatic pagination (
LabelHandler: Complete label CRUD, visibility controls, and color management.
Google Calendar API (google_api.calendar)
EventHandler: Event creation (plan_event), multi-page event listing (iter_events), Dutch/ISO date and time conversions, and automated duplicate event cleanup.CalendarHandler: Primary and secondary calendar CRUD, calendar list entry management, and calendar ID resolution.
Developer Experience
- 100% Offline Test Suite: 76 unit tests covering all components with offline mocks.
- Full PEP 561 Typing: Ships with
py.typedfor IDE autocomplete and type checkers. - Modern Standards: Structured
src/layout configured with Hatchling and PEP 621pyproject.toml. - Automated CI: GitHub Actions matrix workflow testing Python 3.10–3.13.
Installation
To use this library in any Python project directly via Git:
pip install git+https://github.com/ZennDC/Google_API.git@v1.0.0