Metadata-Version: 2.4
Name: corekat
Version: 0.3.0
Summary: Core utilities for Kat-based microservices
Author-email: velocikat <velocikat@lza.sh>
Requires-Python: >=3.12
Requires-Dist: aiofiles
Requires-Dist: aioshutil
Requires-Dist: asyncio
Requires-Dist: cachetools
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic
Requires-Dist: pydantic-settings
Requires-Dist: python-multipart
Requires-Dist: pyyaml
Requires-Dist: typing-extensions
Provides-Extra: all
Requires-Dist: rich; extra == 'all'
Requires-Dist: sentry-sdk; extra == 'all'
Requires-Dist: typer; extra == 'all'
Provides-Extra: cli
Requires-Dist: rich; extra == 'cli'
Requires-Dist: typer; extra == 'cli'
Provides-Extra: sentry
Requires-Dist: sentry-sdk; extra == 'sentry'
Description-Content-Type: text/markdown

<img width="1408" height="736" alt="corekat-light" src="https://github.com/user-attachments/assets/69aa23fe-3b76-48d9-bc01-36b99faa5266" />


`corekat` is a powerful, asynchronous Python toolkit providing shared utilities for Kat-based microservices. It offers robust configuration management, pluggable file download capabilities, foundational async client infrastructure, and standardized exception handling.

## Key Features

-   **Type-Safe Configuration**: Manage your application's settings with Pydantic V2, loading from YAML files and environment variables with a clear hierarchy.
-   **Exception Hierarchy**: Standardized exceptions with HTTP status mapping, structured error details, and automatic serialization.
-   **String & Dict Utilities**: Case conversion (`to_snake_case`, `to_pascal_case`, `to_kebab_case`) and dictionary flattening/unflattening for config transformations.
-   **Pluggable Download Client**: A fully asynchronous `DownloadClient` for handling files from HTTP, local storage, and S3 (via StashKat) through a pluggable "fetcher" protocol.
-   **Dependency Injection Pattern**: Encourages clean architecture by promoting dependency injection for configuration and clients, making your code more modular and easier to test.
-   **Async Context Managers**: All clients support `async with` for automatic resource cleanup.

## What's New in v3

### Exception Hierarchy

Standardized exception handling with automatic HTTP status mapping:

```python
from corekat.exceptions import NotFoundError, ValidationError

# Raise with structured details
raise NotFoundError(
    "User not found",
    details={"user_id": "123"}
)

# Automatic HTTP mapping in ServeKat
# → 404 response with {"code": "not_found", "message": "...", "details": {...}}
```

### String Utilities

Common string transformations for code generation and API design:

```python
from corekat import to_snake_case, to_pascal_case, to_kebab_case

to_snake_case("HelloWorld")    # "hello_world"
to_pascal_case("hello_world")  # "HelloWorld"
to_kebab_case("HelloWorld")    # "hello-world"
```

### Dict Utilities

Flatten and unflatten nested dictionaries for config processing:

```python
from corekat import flatten_dict, unflatten_dict

nested = {"app": {"db": {"host": "localhost"}}}
flat = flatten_dict(nested)
# {"app.db.host": "localhost"}

restored = unflatten_dict(flat)
# {"app": {"db": {"host": "localhost"}}}
```

## Installation

Install the library and its dependencies.

```bash
# Core library
uv pip install corekat

# For S3 support, install the stashkat plugin
uv pip install stashkat

# For development with all extras
uv pip install -e ".[dev,all]"
```

*(Requires Python >= 3.12)*

## Full Documentation

For detailed guides, tutorials, and the API reference, please visit the **[full documentation site](https://velocikat.github.io/corekat)**.

## Development

-   **Setup:** `uv sync --dev`
-   **Testing:** `make test`
-   **Linting & Formatting:** `make check` and `make fix`

## License

This project is licensed under the BSD 3-Clause License. See the [LICENSE](LICENSE) file for details.
