Metadata-Version: 2.4
Name: tldr-common
Version: 2.0.3
Summary: Shared utilities and models for TL;DR.tv platform
Author: TL;DR.tv Team
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx
Requires-Dist: boto3
Requires-Dist: psycopg>=3
Requires-Dist: pydantic[email]
Requires-Dist: pydantic-settings
Requires-Dist: python-dotenv
Requires-Dist: uvicorn
Requires-Dist: websockets
Requires-Dist: fastapi
Requires-Dist: aio-pika
Requires-Dist: colorlog
Requires-Dist: logfire[aiohttp,fastapi,httpx,psycopg,psycopg2,system-metrics]
Requires-Dist: faststream
Requires-Dist: tomlkit
Requires-Dist: uvloop
Requires-Dist: aws-encryption-sdk>=4.0.3
Requires-Dist: cachetools
Requires-Dist: pkce
Requires-Dist: redis[hiredis]>=5.0.0
Requires-Dist: cryptography>=46.0.5

# Common Module

Shared utilities and models for the TL;DR.tv platform.

## Structure

```
common/
├── src/common/
│   ├── core/          # Core functionality (config, exceptions, dependencies)
│   ├── dao/           # Data Access Objects
│   ├── database/      # Database connectivity
│   ├── logging/       # Logging configuration
│   ├── message/       # Message queue models
│   ├── models/        # Domain models
│   ├── platform/      # Platform-specific APIs (Twitch, Kick)
│   └── utils/         # Utility functions
└── tests/
    ├── unit/          # Unit tests
    └── integration/   # Integration tests
```

## Installation

The common module is part of the uv workspace and is automatically available to other services.

For development:
```bash
uv pip install -e common
```

## Usage

### Data Access Objects (DAOs)

```python
from common.dao import UserDAO, StreamDAO, ClipDAO
from common.database import Db, DBConfig

# Initialize database
db = Db(DBConfig())

# Create DAOs
user_dao = UserDAO(db)
stream_dao = StreamDAO(db)
clip_dao = ClipDAO(db)
```

### Platform APIs

```python
from common.platform.twitch import TwitchApi, TwitchApiConfig
from common.platform.kick import KickApi, KickApiConfig

# Initialize APIs
twitch_api = TwitchApi(config=TwitchApiConfig())
kick_api = KickApi(config=KickApiConfig())
```

### Message Models

```python
from common.message import StreamOnlineMessage, StreamOfflineMessage

# Create messages for RabbitMQ
message = StreamOnlineMessage(
    stream_id="12345",
    user_id=67890,
    platform="twitch",
    started_at=datetime.now()
)
```

### Exception Handling

```python
from common.core.exceptions import (
    DatabaseError,
    TwitchError,
    KickError,
    ValidationError,
    RateLimitError
)

try:
    # Database operation
    user = await user_dao.get_user_by_id(user_id)
except DatabaseError as e:
    logger.error(f"Database error: {e}")
```

## Testing

Run all tests:
```bash
uv run pytest common/tests/
```

Run unit tests only:
```bash
uv run pytest common/tests/unit/
```

Run integration tests:
```bash
uv run pytest common/tests/integration/
```

## Type Checking

The module includes type information (py.typed). Run type checking with:
```bash
uv run ty check common/
```
