Metadata-Version: 2.4
Name: zoho-people-sdk
Version: 0.1.0
Summary: Python SDK for the Zoho People API (attendance, timesheet, leave, employees)
Author-email: madyel83 <madyel83@github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/madyel83/zoho-people-sdk
Project-URL: Repository, https://github.com/madyel83/zoho-people-sdk
Project-URL: Issues, https://github.com/madyel83/zoho-people-sdk/issues
Project-URL: Changelog, https://github.com/madyel83/zoho-people-sdk/blob/main/CHANGELOG.md
Keywords: zoho,people,hr,attendance,timesheet,api,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: termcolor>=2.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo>=2024.1; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Requires-Dist: sphinx-intl>=2.1; extra == "docs"
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == "browser"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Dynamic: license-file

# zoho-people-sdk

[![CI](https://github.com/madyel83/zoho-people-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/madyel/zoho_sdk/actions)
[![Docs](https://readthedocs.org/projects/zoho-sdk-people/badge/?version=latest)](https://zoho-sdk-people.readthedocs.io/en/latest/)
[![PyPI](https://img.shields.io/pypi/v/zoho-people-sdk)](https://pypi.org/project/zoho-people-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/zoho-people-sdk)](https://pypi.org/project/zoho-people-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Python SDK for the **Zoho People REST API**.

Covers attendance, timesheet, leave management, and employee records — with automatic OAuth token refresh, typed exceptions, and full type hints.

📚 **Full documentation:** [zoho-sdk-people.readthedocs.io](https://zoho-sdk-people.readthedocs.io/en/latest/)

---

## Features

- **Attendance** — check-in / check-out, bulk import, user reports, shift configuration
- **Timesheet** — create, submit, approve time logs and timesheet periods
- **Leave** — apply, approve, cancel leave requests; leave balance report
- **Employees** — list, search by email / ID, create and update records
- **OAuth 2.0** — automatic token refresh, `from_env()` helper, multi data-centre support
- **Typed exceptions** — `ZohoPeopleAuthError`, `ZohoPeoplePermissionError`, `ZohoPeopleRateLimitError`, …
- **PEP 561** — fully typed, `py.typed` marker included

---

## Installation

```bash
pip install zoho-people-sdk
```

With browser fallback for attendance (when API permissions are unavailable):

```bash
pip install "zoho-people-sdk[browser]"
playwright install chromium
```

---

## Quick Start

```python
from zoho_people import ZohoPeopleAuth, ZohoPeopleClient

# Load credentials from environment variables:
# ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REFRESH_TOKEN, ZOHO_DATA_CENTRE
auth   = ZohoPeopleAuth.from_env()
client = ZohoPeopleClient(auth=auth)

# Employees
employees = client.employee.list()

# Add a time log
client.timesheet.add_timelog(
    user="mario.rossi@company.com",
    work_date="2026-04-25",
    hours="08:00",
    job_name="My Project",
)

# Pending leave requests
pending = client.leave.get_pending(
    from_date="01-Apr-2026",
    to_date="30-Apr-2026",
)

# Monthly attendance report
report = client.attendance.get_user_report(
    start_date="01/04/2026",
    end_date="30/04/2026",
    date_format="dd/MM/yyyy",
)
```

---

## Environment Variables

Copy `.env.example` to `.env`:

```env
ZOHO_CLIENT_ID=1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ZOHO_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ZOHO_DATA_CENTRE=US          # US | EU | IN | AU | JP
ZOHO_REFRESH_TOKEN=1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ZOHO_USER_EMAIL=you@company.com
```

Required OAuth scopes:

```
ZOHOPEOPLE.forms.ALL,ZOHOPEOPLE.attendance.ALL,ZOHOPEOPLE.timetracker.ALL,ZOHOPEOPLE.leave.ALL
```

---

## Error Handling

```python
from zoho_people.exceptions import (
    ZohoPeopleAuthError,
    ZohoPeoplePermissionError,
    ZohoPeopleRateLimitError,
    ZohoPeopleNotFoundError,
    ZohoPeopleValidationError,
    ZohoPeopleError,
)

try:
    client.timesheet.add_timelog(...)
except ZohoPeoplePermissionError:
    print("Missing role permission in Zoho People settings")
except ZohoPeopleAuthError:
    print("Invalid or expired OAuth token")
except ZohoPeopleRateLimitError:
    print("Rate limit hit — SDK will auto-retry")
except ZohoPeopleError as e:
    print(f"API error {e.status_code}: {e.message}")
```

---

## Data Centres

| Region    | Code | Accounts URL                  |
|-----------|------|-------------------------------|
| US        | `US` | `accounts.zoho.com`           |
| Europe    | `EU` | `accounts.zoho.eu`            |
| India     | `IN` | `accounts.zoho.in`            |
| Australia | `AU` | `accounts.zoho.com.au`        |
| Japan     | `JP` | `accounts.zoho.jp`            |

---

## Documentation

Full documentation at **[zoho-sdk-people.readthedocs.io](https://zoho-sdk-people.readthedocs.io/en/latest/)** in English and Italian:

- [Getting Started](https://zoho-sdk-people.readthedocs.io/en/latest/getting-started/installation.html)
- [User Guide](https://zoho-sdk-people.readthedocs.io/en/latest/guide/attendance.html)
- [API Reference](https://zoho-sdk-people.readthedocs.io/en/latest/api/client.html)

---

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Install dev dependencies: `pip install -e ".[dev]"`
4. Run tests: `pytest`
5. Lint: `ruff check src/`
6. Open a pull request

---

## License

[MIT](LICENSE) © 2026 madyel83
