ScoloConfig 0.1.0__tar.gz

scoloconfig-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 G3tFun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scoloconfig-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+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.

scoloconfig-0.1.0/README.md

@@ -0,0 +1,94 @@
+# 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.

scoloconfig-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ScoloConfig"
+version = "0.1.0"
+description = "Safe typed configuration for Python bots and services."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "pydantic-settings>=2.4,<3",
+  "ScoloLogger>=0.1,<0.2",
+]
+license = "MIT"
+authors = [{ name = "G3tFun" }]
+keywords = ["configuration", "settings", "dotenv", "secrets", "pydantic", "telegram-bot"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8.0", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://github.com/G3tFun/ScoloConfig"
+Repository = "https://github.com/G3tFun/ScoloConfig"
+Documentation = "https://github.com/G3tFun/ScoloConfig#readme"
+Issues = "https://github.com/G3tFun/ScoloConfig/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scoloconfig = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501", "UP037", "SIM108"]

scoloconfig-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scoloconfig-0.1.0/src/ScoloConfig.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+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.

scoloconfig-0.1.0/src/ScoloConfig.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/ScoloConfig.egg-info/PKG-INFO
+src/ScoloConfig.egg-info/SOURCES.txt
+src/ScoloConfig.egg-info/dependency_links.txt
+src/ScoloConfig.egg-info/requires.txt
+src/ScoloConfig.egg-info/top_level.txt
+src/scoloconfig/__init__.py
+src/scoloconfig/core.py
+src/scoloconfig/py.typed
+tests/test_scoloconfig.py

scoloconfig-0.1.0/src/ScoloConfig.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scoloconfig-0.1.0/src/ScoloConfig.egg-info/requires.txt

@@ -0,0 +1,7 @@
+pydantic-settings<3,>=2.4
+ScoloLogger<0.2,>=0.1
+
+[dev]
+build>=1.2
+pytest>=8.0
+ruff>=0.6

scoloconfig-0.1.0/src/ScoloConfig.egg-info/top_level.txt

@@ -0,0 +1 @@
+scoloconfig

scoloconfig-0.1.0/src/scoloconfig/__init__.py

@@ -0,0 +1,23 @@
+"""ScoloConfig: safe typed configuration for Python bots and services."""
+
+from .core import (
+    REDACTED,
+    ConfigIssue,
+    ConfigurationError,
+    ScoloSettings,
+    SettingsConfig,
+    SourceReport,
+    env,
+)
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'REDACTED',
+    'ConfigIssue',
+    'ConfigurationError',
+    'ScoloSettings',
+    'SettingsConfig',
+    'SourceReport',
+    'env',
+]

scoloconfig-0.1.0/src/scoloconfig/core.py

@@ -0,0 +1,209 @@
+"""Typed, safe configuration primitives built on pydantic-settings."""
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping, Sequence
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, SecretBytes, SecretStr, ValidationError
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from scolologger import get_logger
+
+_LOG = get_logger('scoloconfig')
+REDACTED = '***REDACTED***'
+_SENSITIVE_PARTS = ('token', 'secret', 'password', 'api_key', 'private_key', 'authorization', 'cookie')
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigIssue:
+    """A validation issue without the rejected input value."""
+
+    location: str
+    message: str
+    error_type: str
+
+
+class ConfigurationError(ValueError):
+    """Safe validation error that never includes a raw configuration value."""
+
+    def __init__(self, settings_name: str, issues: Sequence[ConfigIssue]) -> None:
+        self.settings_name = settings_name
+        self.issues = tuple(issues)
+        details = '; '.join(f'{issue.location}: {issue.message}' for issue in self.issues)
+        super().__init__(f'Invalid configuration for {settings_name}: {details}')
+
+
+@dataclass(frozen=True, slots=True)
+class SourceReport:
+    """Safe summary of available configuration sources and field classification."""
+
+    settings: str
+    sources: tuple[str, ...]
+    secret_fields: tuple[str, ...]
+    validated_fields: int
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def SettingsConfig(
+    *,
+    env_file: str | Path | Sequence[str | Path] | None = None,
+    env_prefix: str = '',
+    case_sensitive: bool = False,
+    env_nested_delimiter: str | None = '__',
+    extra: str = 'ignore',
+) -> SettingsConfigDict:
+    """Return a concise settings configuration accepted by ``ScoloSettings``.
+
+    Process environment always takes priority over the optional ``.env`` file.
+    The default nested delimiter maps ``DATABASE__HOST`` to ``database.host``.
+    """
+    return SettingsConfigDict(
+        env_file=env_file,
+        env_prefix=env_prefix,
+        case_sensitive=case_sensitive,
+        env_nested_delimiter=env_nested_delimiter,
+        extra=extra,
+    )
+
+
+def env(name: str, default: Any = ...) -> Any:
+    """Bind one field to an explicit environment variable name."""
+    if not isinstance(name, str) or not name:
+        raise ValueError('environment variable name must be a non-empty string')
+    if default is ...:
+        return Field(validation_alias=name)
+    return Field(default=default, validation_alias=name)
+
+
+def _is_sensitive_name(name: str) -> bool:
+    normalized = name.casefold().replace('-', '_')
+    return any(part in normalized for part in _SENSITIVE_PARTS)
+
+
+def _is_secret(value: Any) -> bool:
+    return isinstance(value, (SecretStr, SecretBytes))
+
+
+def _redact(value: Any, *, name: str = '') -> Any:
+    if _is_secret(value):
+        return REDACTED
+    if _is_sensitive_name(name):
+        return REDACTED
+    if isinstance(value, BaseModel):
+        return _redact(value.model_dump(mode='python'), name=name)
+    if isinstance(value, Mapping):
+        return {str(key): _redact(item, name=str(key)) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_redact(item, name=name) for item in value]
+    if isinstance(value, tuple):
+        return tuple(_redact(item, name=name) for item in value)
+    if isinstance(value, set):
+        return {_redact(item, name=name) for item in value}
+    if isinstance(value, bytes):
+        return REDACTED if _is_sensitive_name(name) else f'<bytes:{len(value)}>'
+    return value
+
+
+class ScoloSettings(BaseSettings):
+    """Base settings class with safe rendering, reports, and startup logging.
+
+    Subclasses declare ordinary Pydantic fields and set ``model_config`` with
+    :func:`SettingsConfig`. Call ``MySettings.load()`` at process startup to obtain
+    a safe validation error instead of an error that can display rejected secrets.
+    """
+
+    model_config = SettingsConfigDict(extra='ignore')
+
+    @classmethod
+    def load(cls, **overrides: Any) -> ScoloSettings:
+        """Load and validate settings while removing raw values from validation errors."""
+        try:
+            settings = cls(**overrides)
+        except ValidationError as error:
+            issues = tuple(
+                ConfigIssue(
+                    location='.'.join(str(part) for part in item['loc']),
+                    message=str(item['msg']),
+                    error_type=str(item['type']),
+                )
+                for item in error.errors(include_input=False)
+            )
+            _LOG.error('config.validation_failed', settings=cls.__name__, issue_count=len(issues))
+            raise ConfigurationError(cls.__name__, issues) from None
+        return settings
+
+    @classmethod
+    def _field_environment_names(cls, field_name: str) -> tuple[str, ...]:
+        field = cls.model_fields[field_name]
+        prefix = str(cls.model_config.get('env_prefix') or '')
+        case_sensitive = bool(cls.model_config.get('case_sensitive'))
+        alias = field.validation_alias or field.alias or field_name
+        names = (str(alias),) if field.validation_alias is not None else (f'{prefix}{alias}',)
+        return names if case_sensitive else tuple(name.upper() for name in names)
+
+    @classmethod
+    def _configured_env_files(cls) -> tuple[Path, ...]:
+        raw = cls.model_config.get('env_file')
+        if raw is None:
+            return ()
+        values = raw if isinstance(raw, Sequence) and not isinstance(raw, (str, bytes, Path)) else (raw,)
+        return tuple(Path(value) for value in values)
+
+    @classmethod
+    def _field_is_sensitive(cls, field_name: str, value: Any) -> bool:
+        return _is_sensitive_name(field_name) or _is_secret(value)
+
+    def redacted_dump(self, *, by_alias: bool = False, exclude_none: bool = False) -> dict[str, Any]:
+        """Return a JSON-compatible configuration mapping with sensitive values hidden."""
+        raw = self.model_dump(mode='python', by_alias=by_alias, exclude_none=exclude_none)
+        return {name: _redact(value, name=name) for name, value in raw.items()}
+
+    def redacted_json(self, *, by_alias: bool = False, exclude_none: bool = False) -> str:
+        """Serialise :meth:`redacted_dump` without exposing secret values."""
+        return json.dumps(
+            self.redacted_dump(by_alias=by_alias, exclude_none=exclude_none),
+            ensure_ascii=False,
+            separators=(',', ':'),
+            default=str,
+        )
+
+    def source_report(self) -> SourceReport:
+        """Describe available sources and sensitive field names without reading values."""
+        sources: list[str] = []
+        environment_names = {
+            name
+            for field_name in type(self).model_fields
+            for name in self._field_environment_names(field_name)
+        }
+        environment = os.environ if bool(self.model_config.get('case_sensitive')) else {
+            key.upper(): value for key, value in os.environ.items()
+        }
+        if any(name in environment for name in environment_names):
+            sources.append('environment')
+        if any(path.is_file() for path in self._configured_env_files()):
+            sources.append('dotenv')
+        if not sources:
+            sources.append('defaults-or-overrides')
+        secret_fields = tuple(
+            name for name in type(self).model_fields if self._field_is_sensitive(name, getattr(self, name))
+        )
+        return SourceReport(
+            settings=self.__class__.__name__,
+            sources=tuple(sources),
+            secret_fields=secret_fields,
+            validated_fields=len(type(self).model_fields),
+        )
+
+    def log_startup(self) -> SourceReport:
+        """Emit one safe structured startup event and return its report."""
+        report = self.source_report()
+        _LOG.info('config.loaded', **report.as_dict())
+        return report
+
+    def __repr_args__(self) -> Any:
+        return list(self.redacted_dump().items())

scoloconfig-0.1.0/tests/test_scoloconfig.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+from pydantic import SecretStr
+
+from scoloconfig import ConfigurationError, ScoloSettings, SettingsConfig, env
+
+
+def test_environment_overrides_dotenv_and_values_are_typed(monkeypatch, tmp_path):
+    dotenv = tmp_path / '.env'
+    dotenv.write_text('BOT_TOKEN=dotenv-token\nBOT_DEBUG=false\nBOT_TIMEOUT=12.5\n', encoding='utf-8')
+    monkeypatch.setenv('BOT_TOKEN', 'environment-token')
+    monkeypatch.setenv('BOT_DEBUG', 'true')
+
+    class AppSettings(ScoloSettings):
+        model_config = SettingsConfig(env_file=dotenv, env_prefix='BOT_')
+
+        token: SecretStr
+        debug: bool = False
+        timeout: float = 5.0
+
+    settings = AppSettings.load()
+
+    assert settings.token.get_secret_value() == 'environment-token'
+    assert settings.debug is True
+    assert settings.timeout == 12.5
+    assert settings.source_report().sources == ('environment', 'dotenv')
+
+
+def test_secrets_are_never_present_in_repr_or_redacted_serialization(monkeypatch):
+    monkeypatch.setenv('APP_TOKEN', '123456:real-token')
+    monkeypatch.setenv('APP_API_KEY', 'real-api-key')
+
+    class AppSettings(ScoloSettings):
+        model_config = SettingsConfig(env_prefix='APP_')
+
+        token: SecretStr
+        api_key: str
+        plain: str = 'safe'
+
+    settings = AppSettings.load()
+    rendered = repr(settings)
+    redacted = settings.redacted_dump()
+
+    assert '123456:real-token' not in rendered
+    assert 'real-api-key' not in rendered
+    assert '123456:real-token' not in settings.redacted_json()
+    assert 'real-api-key' not in settings.redacted_json()
+    assert redacted == {'token': '***REDACTED***', 'api_key': '***REDACTED***', 'plain': 'safe'}
+    assert settings.source_report().secret_fields == ('token', 'api_key')
+
+
+def test_explicit_environment_alias_and_defaults(monkeypatch):
+    monkeypatch.setenv('TELEGRAM_BOT_TOKEN', 'token-from-explicit-name')
+
+    class AppSettings(ScoloSettings):
+        token: SecretStr = env('TELEGRAM_BOT_TOKEN')
+        retries: int = env('RETRIES', default=3)
+
+    settings = AppSettings.load()
+
+    assert settings.token.get_secret_value() == 'token-from-explicit-name'
+    assert settings.retries == 3
+    assert settings.source_report().sources == ('environment',)
+
+
+def test_safe_validation_error_excludes_rejected_secret(monkeypatch):
+    raw_secret = 'not-an-integer-and-must-not-leak'
+    monkeypatch.setenv('APP_PORT', raw_secret)
+
+    class AppSettings(ScoloSettings):
+        model_config = SettingsConfig(env_prefix='APP_')
+
+        port: int
+
+    with pytest.raises(ConfigurationError) as captured:
+        AppSettings.load()
+
+    error = captured.value
+    assert raw_secret not in str(error)
+    assert error.settings_name == 'AppSettings'
+    assert error.issues[0].location == 'port'
+    assert error.issues[0].error_type == 'int_parsing'
+
+
+def test_missing_required_setting_is_safe_and_env_is_not_mutated(monkeypatch):
+    monkeypatch.delenv('REQUIRED_TOKEN', raising=False)
+    before = dict(os.environ)
+
+    class AppSettings(ScoloSettings):
+        token: SecretStr = env('REQUIRED_TOKEN')
+
+    with pytest.raises(ConfigurationError) as captured:
+        AppSettings.load()
+
+    assert 'REQUIRED_TOKEN' in str(captured.value)
+    assert dict(os.environ) == before