config_ninja.settings

  1"""Read and deserialize configuration for the `config-ninja`_ agent.
  2
  3## Schema
  4
  5See `config_ninja.settings.schema` for the schema of the `config-ninja`_ settings file.
  6
  7.. _config-ninja: https://config-ninja.readthedocs.io/home.html
  8"""
  9
 10from __future__ import annotations
 11
 12import dataclasses
 13import logging
 14import typing
 15from pathlib import Path
 16
 17import jinja2
 18import pyspry
 19
 20from config_ninja.backend import DUMPERS, Backend, FormatT
 21from config_ninja.contrib import get_backend
 22from config_ninja.settings.schema import ConfigNinjaObject, Dest, DictConfigDefault, Source
 23
 24if typing.TYPE_CHECKING:  # pragma: no cover
 25    from config_ninja.hooks import Hook, HooksEngine
 26
 27__all__ = [
 28    'DEFAULT_LOGGING_CONFIG',
 29    'DEFAULT_PATHS',
 30    'PREFIX',
 31    'DestSpec',
 32    'ObjectSpec',
 33    'SourceSpec',
 34    'load',
 35    'resolve_path',
 36]
 37
 38logger = logging.getLogger(__name__)
 39
 40DEFAULT_PATHS = [
 41    Path.cwd() / 'config-ninja-settings.yaml',
 42    Path.home() / 'config-ninja-settings.yaml',
 43    Path('/etc/config-ninja/settings.yaml'),
 44]
 45"""Check each of these locations for `config-ninja`_'s settings file.
 46
 47The following locations are checked (ordered by priority):
 48
 491. `./config-ninja-settings.yaml`
 502. `~/config-ninja-settings.yaml`
 513. `/etc/config-ninja/settings.yaml`
 52
 53.. _config-ninja: https://config-ninja.readthedocs.io/home.html
 54"""
 55
 56
 57DEFAULT_LOGGING_CONFIG: DictConfigDefault = {
 58    'version': 1,
 59    'formatters': {
 60        'simple': {
 61            'datefmt': logging.Formatter.default_time_format,
 62            'format': '%(message)s',
 63            'style': '%',
 64            'validate': False,
 65        },
 66    },
 67    'filters': {},
 68    'handlers': {
 69        'rich': {  # type: ignore[typeddict-item,unused-ignore]  # needed for Python <3.11
 70            'class': 'rich.logging.RichHandler',
 71            'formatter': 'simple',
 72            'rich_tracebacks': True,
 73        },
 74    },
 75    'loggers': {},
 76    'root': {  # type: ignore[typeddict-item,unused-ignore]  # needed for Python <3.11
 77        'handlers': ['rich'],
 78        'level': logging.INFO,
 79        'propagate': False,
 80    },
 81    'disable_existing_loggers': True,
 82    'incremental': False,
 83}
 84"""Default logging configuration passed to `logging.config.dictConfig()`."""
 85
 86PREFIX = 'CONFIG_NINJA'
 87"""Each of `config-ninja`_'s settings must be prefixed with this string.
 88
 89.. _config-ninja: https://config-ninja.readthedocs.io/home.html
 90"""
 91
 92
 93@dataclasses.dataclass
 94class Config:
 95    """Wrap the `pyspry.Settings` object with additional configuration for the `HooksEngine`."""
 96
 97    settings: pyspry.Settings
 98    """The settings for the `config-ninja` agent."""
 99
100    engine: HooksEngine | None = None
101    """If `poethepoet` is installed and configured, use this engine for callback hooks."""
102
103
104def load(path: Path) -> Config:
105    """Load the settings from the given path.
106
107    >>> conf = load('config-ninja-settings.yaml')
108    >>> conf.settings.__class__, conf.engine.__class__
109    (<class 'pyspry.base.Settings'>, <class 'config_ninja.hooks.HooksEngine'>)
110
111
112    `config_ninja.hooks.HooksEngine` is imported and loaded if the `poethepoet` extra is installed. When not
113        installed, the `ImportError` is handled, and `engine=None` is returned in place of
114        `config_ninja.hooks.HooksEngine`.
115
116    >>> seed_import_error()
117    >>> load('examples/hooks.yaml').engine is None
118    True
119
120    """
121    try:
122        from config_ninja.hooks import HooksEngine, exceptions
123    except ImportError as exc:
124        logger.debug('%s: %s', exc.name, exc.msg)
125        return Config(engine=None, settings=pyspry.Settings.load(path, PREFIX))
126
127    try:
128        engine = HooksEngine.load_file(path, DEFAULT_PATHS)
129    except exceptions.PoeException:
130        # this is expected if the file does not define any hooks
131        logger.debug('could not load `poethepoet` hooks from %s', path, exc_info=True)
132        engine = None
133    return Config(engine=engine, settings=pyspry.Settings.load(path, PREFIX))
134
135
136def resolve_path() -> Path:
137    """Return the first path in `DEFAULT_PATHS` that exists."""
138    for path in DEFAULT_PATHS:
139        if path.is_file():
140            return path
141
142    raise FileNotFoundError('Could not find config-ninja settings', DEFAULT_PATHS)
143
144
145@dataclasses.dataclass
146class DestSpec:
147    """Container for the destination spec parsed from `config-ninja`_'s own configuration file.
148
149    .. _config-ninja: https://config-ninja.readthedocs.io/home.html
150    """
151
152    format: FormatT | jinja2.Template
153    """Specify the format of the configuration file to write."""
154
155    path: Path
156    """Write the configuration file to this path."""
157
158    def __str__(self) -> str:
159        """Represent the destination spec as a string."""
160        if self.is_template:
161            assert isinstance(self.format, jinja2.Template)  # noqa: S101  # 👈 for static analysis
162            fmt = f'(template: {self.format.name})'
163        else:
164            fmt = f'(format: {self.format})'
165
166        return f'{fmt} -> {self.path}'
167
168    @classmethod
169    def from_primitives(cls, data: Dest) -> DestSpec:
170        """Create a `DestSpec` instance from a dictionary of primitive types."""
171        path = Path(data['path'])
172        if data['format'] in DUMPERS:
173            fmt: FormatT = data['format']  # type: ignore[assignment,unused-ignore]
174            return DestSpec(format=fmt, path=path)
175
176        template_path = Path(data['format'])
177
178        loader = jinja2.FileSystemLoader(template_path.parent)
179        env = jinja2.Environment(autoescape=jinja2.select_autoescape(default=True), loader=loader)
180
181        return DestSpec(path=path, format=env.get_template(template_path.name))
182
183    @property
184    def is_template(self) -> bool:
185        """Whether the destination uses a Jinja2 template."""
186        return isinstance(self.format, jinja2.Template)
187
188
189@dataclasses.dataclass
190class SourceSpec:
191    """The data source of a `config-ninja`_ object.
192
193    .. _config-ninja: https://config-ninja.readthedocs.io/home.html
194    """
195
196    backend: Backend
197    """Read configuration data from this backend (see `config_ninja.contrib` for supported backends)."""
198
199    format: FormatT = 'raw'
200    """Decode the source data from this format."""
201
202    @classmethod
203    def from_primitives(cls, data: Source) -> SourceSpec:
204        """Create a `SourceSpec` instance from a dictionary of primitive types.
205
206        If the given `Source` has a `Source.new` key, the appropriate `config_ninja.backend.Backend.new()` method is
207        invoked to create `SourceSpec.backend`. Otherwise, the `Source` must have a `Source.init` key for passing
208        arguments to the `config_ninja.backend.Backend`'s `__init__()` method.
209        """
210        backend_class = get_backend(data['backend'])
211        fmt = data.get('format', 'raw')
212        if new := data.get('new'):
213            backend = backend_class.new(**new['kwargs'])
214        else:
215            backend = backend_class(**data['init']['kwargs'])
216
217        return SourceSpec(backend=backend, format=fmt)
218
219
220@dataclasses.dataclass
221class ObjectSpec:
222    """Container for each object parsed from `config-ninja`_'s own configuration file.
223
224    .. _config-ninja: https://config-ninja.readthedocs.io/home.html
225    """
226
227    dest: DestSpec
228    """Destination metadata for the object's output file."""
229
230    hooks: tuple[Hook, ...]
231    """Zero or more `poethepoet` tasks to execute as callback hooks."""
232
233    source: SourceSpec
234    """Configuration for the object's `config_ninja.backend.Backend` data source."""
235
236    @staticmethod
237    def _load_hooks(data: ConfigNinjaObject, engine: HooksEngine | None) -> tuple[Hook, ...]:
238        hook_names: list[str] = data.get('hooks', [])  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
239        if hook_names and engine is None:
240            raise ValueError(f"'poethepoet' configuration must be defined for hooks in config to work: {data!r}")
241
242        return tuple(engine.get_hook(hook_name) for hook_name in hook_names)  # type: ignore[union-attr]
243
244    @classmethod
245    def from_primitives(cls, data: ConfigNinjaObject, engine: HooksEngine | None) -> ObjectSpec:
246        """Create an `ObjectSpec` instance from a dictionary of primitive types.
247
248        A `ValueError` is raised when hooks are referenced by the `ConfigNinjaObject` but the `HooksEngine` is not
249            provided:
250
251        >>> data = {
252        ...   'dest': {
253        ...     'path': '/dev/null',
254        ...     'format': 'yaml'
255        ...   },
256        ...   'source': {
257        ...     'backend': 'local',
258        ...     'init': {
259        ...       'kwargs': {
260        ...         'path': 'example.yaml'
261        ...       }
262        ...     }
263        ...   },
264        ...   'hooks': ['foo']
265        ... }
266
267        >>> ObjectSpec.from_primitives(data, None)
268        Traceback (most recent call last):
269        ...
270        ValueError: 'poethepoet' configuration must be defined for hooks in config to work: ...
271        """
272        return ObjectSpec(
273            dest=DestSpec.from_primitives(data['dest']),
274            hooks=cls._load_hooks(data, engine),
275            source=SourceSpec.from_primitives(data['source']),
276        )
277
278
279logger.debug('successfully imported %s', __name__)