Metadata-Version: 2.4
Name: zohopy
Version: 0.2.0
Summary: Modern, async-ready Python client for Zoho APIs (Books, Inventory, and more)
Project-URL: Homepage, https://github.com/talas9/zohopy
Project-URL: Documentation, https://talas9.github.io/zohopy
Project-URL: Repository, https://github.com/talas9/zohopy
Project-URL: Issues, https://github.com/talas9/zohopy/issues
Project-URL: Changelog, https://github.com/talas9/zohopy/blob/main/CHANGELOG.md
Author: talas9
License: MIT
License-File: LICENSE
Keywords: accounting,api,async,sdk,zoho,zoho-books,zoho-inventory
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic-settings<3,>=2.13
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: structlog>=25.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=9.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Description-Content-Type: text/markdown

# ZohoPy

[![CI](https://github.com/talas9/zohopy/actions/workflows/ci.yml/badge.svg)](https://github.com/talas9/zohopy/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/zohopy)](https://pypi.org/project/zohopy/)
[![Python](https://img.shields.io/pypi/pyversions/zohopy)](https://pypi.org/project/zohopy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Modern, async-ready Python client for Zoho APIs — **complete Zoho Books v3 coverage**.

## Highlights

- **716 API methods** (358 sync + 358 async) across 57 resource types) across 43 resource types
- **CLI** — `zohopy` command with `--json` on every command
- **Multi-currency** + exchange rates on all transactions
- **Landed cost** support on bills
- **10+ typed exceptions** mapped from Zoho error codes
- **Structured logging** (JSON/console via structlog)
- **Docker ready** — Dockerfile + docker-compose
- **OAuth setup wizard** — `python -m zohopy` or `zohopy setup`

## Install

```bash
pip install zohopy
```

## Quick Start

```bash
# Setup (interactive — generates .env)
zohopy setup

# CLI
zohopy contacts list --json
zohopy invoices create '{"customer_id":"...","line_items":[{"item_id":"...","quantity":1}]}' --json
zohopy raw get /books/v3/items --json
```

```python
# Python SDK
from zohopy import ZohoConfig, SyncZohoClient
from zohopy.products.books import ZohoBooks

with SyncZohoClient(ZohoConfig()) as client:
    books = ZohoBooks(client)
    books.contacts.list()
    books.invoices.create({"customer_id": "...", "line_items": [...]})
    books.invoices.mark_sent("invoice_id")
```

## Products

| Product | Status | Coverage |
|---------|--------|----------|
| **Zoho Books** | ✅ v3 | 57 resources, 358 methods |
| Zoho Inventory | 🔜 Coming soon | — |
| Zoho CRM | 🔜 Coming soon | — |
| Zoho Payroll | 🔜 Planned | — |
| Zoho People | 🔜 Planned | — |

## Documentation

| Document | Description |
|----------|-------------|
| **[AGENT.md](AGENT.md)** | Agent/LLM reference — CLI commands, SDK quick ref, error codes |
| **[docs/api.md](docs/api.md)** | Full API reference — all 43 resources and their methods |
| **[docs/errors.md](docs/errors.md)** | Error handling guide — exception hierarchy + Zoho error codes |
| **[docs/setup.md](docs/setup.md)** | Setup guide — OAuth flows, .env, Docker, programmatic config |
| **[CHANGELOG.md](CHANGELOG.md)** | Release history |

## Contributing

```bash
git clone https://github.com/talas9/zohopy.git && cd zohopy
pip install -e ".[dev]"
pytest && ruff check src/ && mypy src/
```

Branch strategy: `dev` → PR → `main`. Tags trigger PyPI release.

## License

[MIT](LICENSE)
