corekat 0.3.0

Core utilities for Kat-based microservices

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:

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:

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:

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.

# 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.

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 file for details.