# transpara-py-sdk

Transpara Python SDK - shared utilities for authentication, logging, tracing, and common infrastructure across Transpara services.

## Installation

```bash
pip install transpara-sdk
```

## Modules

### Authentication

| Module | Use Case | Docs |
|--------|----------|------|
| [TAuthTokenVerification](docs/tauth_token_verification.md) | Validate user bearer tokens at API endpoints, RBAC role checking | [docs/tauth_token_verification.md](docs/tauth_token_verification.md) |
| [TAuthManager](docs/tauth_manager.md) | Machine-to-machine (service account) authentication with background token refresh | [docs/tauth_manager.md](docs/tauth_manager.md) |

**Which one do I need?**

- Your API **receives** bearer tokens from users/clients -> [TAuthTokenVerification](docs/tauth_token_verification.md)
- Your service **calls** other services with a service account -> [TAuthManager](docs/tauth_manager.md)
- Your API calls another API **on behalf of a user** -> [TAuthTokenVerification.get_forwarding_header()](docs/tauth_token_verification.md#api-to-api-token-forwarding)

### Logging and Tracing

| Module | Description | Docs |
|--------|-------------|------|
| `transpara.tlogging` | Custom log levels, colored output, function logging decorators | [docs/logging_and_tracing.md](docs/logging_and_tracing.md) |
| `transpara.tracing` | OpenTelemetry distributed tracing with decorators | [docs/logging_and_tracing.md](docs/logging_and_tracing.md) |

### Internal Utilities

| Module | Description |
|--------|-------------|
| `transpara.internal.settings` | Pydantic-based configuration management for Transpara services |
| `transpara.internal.output_tstore` | InfluxDB/tStore output handler with async batching |
| `transpara.internal.utils` | URL joining and other small helpers |

## Upgrading

If upgrading from a version prior to **0.14.0**, there are breaking changes:

```
transpara_logging  ->  tlogging
transpara.middlewares  ->  transpara.tlogging
log_middleware  ->  logd
```
