Metadata-Version: 2.4
Name: ScoloConfig
Version: 0.1.0
Summary: Safe typed configuration for Python bots and services.
Author: G3tFun
License-Expression: MIT
Project-URL: Homepage, https://github.com/G3tFun/ScoloConfig
Project-URL: Repository, https://github.com/G3tFun/ScoloConfig
Project-URL: Documentation, https://github.com/G3tFun/ScoloConfig#readme
Project-URL: Issues, https://github.com/G3tFun/ScoloConfig/issues
Keywords: configuration,settings,dotenv,secrets,pydantic,telegram-bot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic-settings<3,>=2.4
Requires-Dist: ScoloLogger<0.2,>=0.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# ScoloConfig

ScoloConfig provides safe typed configuration for Python bots and services. It uses `pydantic-settings` for validation, reads process environment and optional `.env` files, masks secrets by default, and emits safe startup events through ScoloLogger.

## Installation

```bash
pip install ScoloConfig
```

## Quick start

```python
from pydantic import SecretStr
from scoloconfig import ScoloSettings, SettingsConfig

class AppConfig(ScoloSettings):
    model_config = SettingsConfig(
        env_file='.env',
        env_prefix='BOT_',
    )

    token: SecretStr
    debug: bool = False
    request_timeout: float = 35.0

config = AppConfig.load()
config.log_startup()

bot_token = config.token.get_secret_value()
```

With this model, `BOT_TOKEN`, `BOT_DEBUG`, and `BOT_REQUEST_TIMEOUT` are read from the process environment. Values in the process environment always override `.env`.

## `.env`

```dotenv
BOT_TOKEN=123456:replace-with-a-real-token-locally
BOT_DEBUG=false
BOT_REQUEST_TIMEOUT=35
```

Commit `.env.example`, not `.env`. Production deployments should inject settings through the process environment or a dedicated secret manager.

## Secret safety

Use `SecretStr` or `SecretBytes` for credentials. ScoloConfig also masks fields whose names include `token`, `secret`, `password`, `api_key`, `private_key`, `authorization`, or `cookie`.

```python
config.redacted_dump()
# {
#   'token': '***REDACTED***',
#   'debug': False,
#   'request_timeout': 35.0,
# }
```

Secrets are not included in `repr`, `redacted_json()`, `source_report()`, `log_startup()`, or safe validation errors. Reveal a secret only at the narrow point where a client requires it:

```python
token = config.token.get_secret_value()
```

## Explicit environment names

Use `env()` when a field should map to an exact environment variable instead of a prefix-derived name.

```python
from pydantic import SecretStr
from scoloconfig import ScoloSettings, env

class LegacyConfig(ScoloSettings):
    telegram_token: SecretStr = env('TELEGRAM_BOT_TOKEN')
    retries: int = env('RETRIES', default=3)
```

## Safe startup report

```python
from scolologger import configure

configure(level='INFO', json_output=True)
report = config.log_startup()
```

The report includes only the settings class name, source categories, secret field names, and number of validated fields. It never includes configuration values.

## Limits

ScoloConfig 0.1.0 supports process environment and `.env` files. It does not fetch remote secrets, watch files, mutate a running configuration object, or replace a dedicated secrets manager.

## License

MIT.
