Metadata-Version: 2.4
Name: hetman-codetable
Version: 1.0.3
Summary: Hetman Codetable provides centralized, standardized response codes for APIs and applications. It ensures consistency by treating codes as a single source of truth.
Author-email: Hetman <degadupeko@my-relay.app>
Project-URL: Homepage, https://github.com/hetman-app/hetman-codetable
Project-URL: Documentation, https://github.com/hetman-app/hetman-codetable
Project-URL: Repository, https://github.com/hetman-app/hetman-codetable
Project-URL: Issues, https://github.com/hetman-app/hetman-codetable/issues
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hetman-kit-localize>=1.0.0
Dynamic: license-file

<img src="https://hetman.app/svg/logo/full-white-text.svg" alt="Hetman Logo" width="200" height="38" />

**Hetman Codetable** provides centralized, standardized response codes for APIs and applications. It ensures consistency by treating codes as a single source of truth.

## Installation

```bash
pip install hetman-codetable
```

## Why use this?

Managing response codes and messages across an application can become chaotic. **Hetman Codetable** allows you to:

1.  **Centralize** all your application codes and messages in one place.
2.  **Standardize** API responses with consistent error codes and messages.
3.  **Internationalize (i18n)** messages easily, switching languages dynamically.

## Usage Example

### Defining Codetables

You can organize your codes into multiple classes for better structure, even while sharing the same namespace.

```python
from codetable import Codetable, msg, i18n

# 1. Set the base locale (Critical for i18n)
i18n.set_base_locale("en")

class UserError(Codetable):
    NAMESPACE = "user"

    NOT_FOUND = msg("User not found.")

    ALREADY_EXISTS = i18n(
        en="User already exists.",
        pl="Użytkownik już istnieje.",
    )

class UserSuccess(Codetable):
    NAMESPACE = "user"

    CREATED = msg("User created successfully.")

    UPDATED = i18n(
        en="User updated successfully.",
        pl="Użytkownik został zaktualizowany pomyślnie.",
    )
```

### Accessing Codes

```python
# --- 1. Accessing Standard Codes ---
print(UserError.NOT_FOUND)
# Output: {'code': 'user.not_found', 'msg': 'User not found.'}

print(UserSuccess.CREATED)
# Output: {'code': 'user.created', 'msg': 'User created successfully.'}

# --- 2. Accessing i18n Codes (Default: English, i18n.set_base_locale("en")) ---
print(UserError.ALREADY_EXISTS)
# Output: {'code': 'user.already_exists', 'msg': 'User already exists.'}

# --- 3. Switching Locales (for all i18n codes) ---
i18n.set_locale("pl")

print(UserError.ALREADY_EXISTS)
# Output: {'code': 'user.already_exists', 'msg': 'Użytkownik już istnieje.'}

print(UserSuccess.UPDATED)
# Output: {'code': 'user.updated', 'msg': 'Użytkownik został zaktualizowany pomyślnie.'}
```

### Lazy Load

```python
i18n.set_locale("en")

error = UserError.lazy("ALREADY_EXISTS")

print(error())
# Output: {'code': 'user.already_exists', 'msg': 'User already exists.'}

success = UserSuccess.lazy("UPDATED")

print(success())
# Output: {'code': 'user.updated', 'msg': 'User updated successfully.'}
```

### Customizing Key Maps

You can custom output keys globally or per-table by modifying the `key_map`.

```python
# Change default keys globally
Codetable.key_map = {"code": "error_code", "value": "message"}

print(UserError.ALREADY_EXISTS)
# Output: {'error_code': 'user.already_exists', 'message': 'Użytkownik już istnieje.'}
```

## Core Features

- **Namespace Management**: Automatically prefixes codes with the table's namespace (e.g., `user.not_found`).
- **Strict Typing**: Built with Python type hints for excellent IDE support.
- **Dynamic Descriptor Protocol**: Codes know their own variable names and parent tables automatically.
- **Context-Aware I18n**: Uses `contextvars` to handle per-request locales safely in async environments.
