catapa-python 0.1.0a1
Python client library for Catapa API
License: MIT
Requires Python: >=3.11
Keywords: catapa, api, client, hr, payroll

# CATAPA Python Client

A comprehensive Python client library for the CATAPA API with ergonomic wrapper and automatic OAuth2 authentication handling.

## Features

- 🔐 **Automatic OAuth2 Authentication** - Client credentials flow with automatic token refresh
- 🚀 **Ergonomic API** - Simple, intuitive interface for all Catapa APIs
- 📝 **Full Type Support** - Complete type hints with generated models
- 📦 **Direct Imports** - `from catapa_client import EmployeeApi`
- 🎯 **No Wrapping Required** - Reuses generated API classes without modification

## Installation

```bash
# Install from local directory
pip install -e /path/to/catapa-python
```

When installed, two packages are available:

- `catapa_client`: The wrapper with authentication logic
- `openapi_client`: The raw generated code

## Quick Start

```python
from catapa_client import Catapa, EmployeeApi

# 1. Initialize the client
client = Catapa(
    tenant='your-tenant',
    client_id='your-client-id',
    client_secret='your-client-secret'
)

# 2. Create API instances and use them
employee_api = EmployeeApi(client)
employees = employee_api.list_all_employees(page=0, size=10)

print(f"Found {len(employees.content)} employees")
```

## Advanced Usage

### Direct API Access

You can import any generated API or model class directly from the top-level package:

```python
from catapa_client import Catapa, OrganizationApi, SalaryPaymentApi

client = Catapa(...)
org_api = OrganizationApi(client)
company = org_api.get_company()
```

### Authentication

The client automatically handles OAuth2 authentication. It requests a token using `Basic base64(client_id:client_secret)` authentication and manages token refresh automatically.

## Architecture

1. **`catapa_python/catapa_client/`** - Main package

   - **`wrapper.py`** - Main `Catapa` wrapper class
   - **`auth/`** - Authentication logic

2. **`catapa_python/generated/`** - Auto-generated OpenAPI client code
   - `openapi_client` package lives here
   - Managed by `regenerate-client.sh`

## Development

The wrapper is designed to be regeneration-safe. When you regenerate the OpenAPI client:

1. The `catapa_python/generated/` directory gets updated (by `regenerate-client.sh`)
2. The wrapper files in `catapa_python/catapa_client/` remain unchanged
3. All APIs are immediately available through `catapa_client`

## Testing

To run the unit tests, first ensure you have installed the development dependencies:

```bash
pip install -e ".[dev]"
```

Then run the tests using the Makefile:

```bash
make test
```

Or run directly with pytest:

```bash
pytest tests/unit/ --ignore=tests/integration --cov=catapa_python --cov-report=html
```

## Make Commands

The project includes a Makefile with convenient commands for common development tasks:

```bash
# Create and activate virtual environment (interactive shell)
make venv

# Install the package (creates venv if needed)
make install

# Regenerate Python client from OpenAPI spec, Run this command before running the tests and examples
make regenerate-client

# Run unit tests
make test

# Run example script
make run-example
```

**Note:** All commands automatically create a virtual environment if it doesn't exist. The `venv` command opens an interactive shell with the environment activated, while other commands run within the activated environment automatically.