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

pip install ScoloConfig

Quick start

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

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.

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:

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.

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

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.