config_ninja.settings.schema

  1"""Define the schema of `config-ninja`_'s settings file.
  2
  3The `typing.TypedDict` classes in this module describe the structure of the `config-ninja` settings file:
  4
  5```yaml
  6CONFIG_NINJA_OBJECTS:
  7```
  8```yaml
  9    example-1:
 10      dest:
 11        format: templates/settings-subset.toml.j2
 12        path: /tmp/config-ninja/local/subset.toml
 13
 14      source:
 15        backend: local
 16        format: yaml
 17
 18        new:
 19          kwargs:
 20            path: config-ninja-settings.yaml
 21```
 22
 23This YAML file would be parsed into a dictionary of the following structure:
 24
 25- `CONFIG_NINJA_OBJECTS:`
 26  - `example-1:`  (`ConfigNinjaObject`)
 27    - `dest:`  (`Dest`)
 28      - `...`
 29    - `source:`  (`Source`)
 30      - `...`
 31
 32.. _config-ninja: https://config-ninja.readthedocs.io/home.html
 33"""
 34
 35from __future__ import annotations
 36
 37import logging
 38import typing
 39from typing import Literal, TypedDict
 40
 41from config_ninja.backend import FormatT
 42
 43try:
 44    from typing import NotRequired, TypeAlias  # type: ignore[attr-defined,unused-ignore]  # for older Python versions
 45except ImportError:  # pragma: no cover
 46    from typing_extensions import NotRequired, TypeAlias
 47
 48
 49__all__ = ['ConfigNinjaObject', 'Dest', 'DictConfig', 'DictConfigDefault', 'Init', 'New', 'PathStr', 'Source']
 50
 51logger = logging.getLogger(__name__)
 52
 53
 54FilterId: TypeAlias = str
 55FormatterId: TypeAlias = str
 56HandlerId: TypeAlias = str
 57LoggerName: TypeAlias = str
 58
 59
 60class Formatter(TypedDict):
 61    """Structure of the `logging.Formatter` parameters in `DictConfig`."""
 62
 63    datefmt: str
 64    format: str
 65    style: Literal['%', '{', '$']
 66    validate: bool
 67
 68
 69class Filter(TypedDict):
 70    """Structure of the `logging.Filter` parameters in `DictConfig`."""
 71
 72    name: LoggerName
 73
 74
 75Handler = TypedDict(
 76    'Handler',
 77    {
 78        'class': str,
 79        'filters': NotRequired[typing.List[FilterId]],
 80        'formatter': FormatterId,
 81        'level': NotRequired[typing.Union[str, int]],
 82        'rich_tracebacks': NotRequired[bool],
 83    },
 84)
 85"""Structure of the `logging.Formatter` parameters in `DictConfig`."""
 86
 87
 88class Logger(TypedDict):
 89    """Structure of the `logging.Logger` parameters in `DictConfig`."""
 90
 91    filters: NotRequired[list[FilterId]]
 92    handlers: list[HandlerId]
 93    level: NotRequired[str | int]
 94    propagate: NotRequired[bool]
 95
 96
 97class DictConfig(TypedDict):
 98    """Type annotations for the `logging configuration dictionary schema`_.
 99
100    .. _logging configuration dictionary schema: https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
101    """
102
103    disable_existing_loggers: NotRequired[bool]
104    filters: NotRequired[dict[FilterId, Filter]]
105    formatters: NotRequired[dict[FormatterId, Formatter]]
106    handlers: NotRequired[dict[HandlerId, Handler]]
107    incremental: NotRequired[bool]
108    loggers: NotRequired[dict[LoggerName, Logger]]
109    root: NotRequired[Logger]
110    version: NotRequired[Literal[1]]
111
112
113class DictConfigDefault(TypedDict):
114    """Type annotations for the `logging configuration dictionary schema`_.
115
116    .. _logging configuration dictionary schema: https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
117    """
118
119    disable_existing_loggers: bool
120    filters: dict[FilterId, Filter]
121    formatters: dict[FormatterId, Formatter]
122    handlers: dict[HandlerId, Handler]
123    incremental: bool
124    loggers: dict[LoggerName, Logger]
125    root: Logger
126    version: Literal[1]
127
128
129class Init(TypedDict):
130    """Initialization parameters for the backend class.
131
132    ```yaml
133    CONFIG_NINJA_OBJECTS:
134      example-1:
135        source:
136    ```
137    ```yaml
138          init:
139            kwargs:
140              path: config-ninja-settings.yaml
141    ```
142    """
143
144    kwargs: dict[str, str]
145    """Pass these values as arguments to the `config_ninja.backend.Backend`'s `__init__()` method."""
146
147
148class New(TypedDict):
149    """Initialization parameters for the backend class.
150
151    ```yaml
152    CONFIG_NINJA_OBJECTS:
153      example-1:
154        source:
155    ```
156    ```yaml
157          new:
158            kwargs:
159              path: config-ninja-settings.yaml
160    ```
161    """
162
163    kwargs: dict[str, str]
164    """Pass these values as arguments to the `config_ninja.backend.Backend.new()` on creation."""
165
166
167class Source(TypedDict):
168    """Describe the source of configuration data written to a `Dest`.
169
170    The parameters `Source.init` and `Source.new` are mutually exclusive.
171
172    ```yaml
173    CONFIG_NINJA_OBJECTS:
174      example-1:
175    ```
176    ```yaml
177        source:
178          backend: local
179          format: yaml
180
181          new:
182            kwargs:
183              path: config-ninja-settings.yaml
184    ```
185    """
186
187    backend: Literal['local', 'appconfig']
188    """The module in `config_ninja.contrib` implementing the `config_ninja.backend.Backend` class."""
189
190    format: FormatT
191    """Deserialize the source data from this format.
192
193    Defaults to `'raw'`.
194    """
195
196    init: Init
197    """Pass these parameters to the `config_ninja.backend.Backend`'s `__init__()` method.
198
199    These are typically unique identifiers; friendly names can be passed to the
200    `config_ninja.backend.Backend.new()` method (via `Source.new`) instead.
201    """
202
203    new: New
204    """Pass these parameters to the backend class's `config_ninja.backend.Backend.new()` method.
205
206    If this property is defined, the `Source.init` property is ignored.
207    """
208
209
210PathStr: TypeAlias = str
211"""A string representing a file path."""
212
213
214class Dest(TypedDict):
215    """Destination metadata for the object's output file.
216
217    ```yaml
218    CONFIG_NINJA_OBJECTS:
219      example-1:
220    ```
221    ```yaml
222        dest:
223          # you can specify the path to a Jinja2 template:
224          format: templates/settings-subset.toml.j2
225          path: /tmp/config-ninja/local/subset.toml
226    ```
227    """
228
229    format: FormatT | PathStr
230    """Set the output serialization format of the destination file.
231
232    If given the path to a file, interpret the file as a Jinja2 template and render it with the
233    source data.
234    """
235
236    path: str
237    """Write the configuration file to this path"""
238
239
240class ConfigNinjaObject(TypedDict):
241    """Specify metadata to manage a system configuration file.
242
243    ```yaml
244    CONFIG_NINJA_OBJECTS:
245    ```
246    ```yaml
247        example-1:
248          dest:
249            format: templates/settings-subset.toml.j2
250            path: /tmp/config-ninja/local/subset.toml
251
252          source:
253            backend: local
254            format: yaml
255
256            new:
257              kwargs:
258                path: config-ninja-settings.yaml
259    ```
260    """
261
262    dest: Dest
263    """Metadata for the object's output file."""
264
265    hooks: NotRequired[list[str]]
266    """The names of the `poethepoet` tasks to run as callback hooks; not always defined."""
267
268    source: Source
269    """Configuration data for the object's `config_ninja.backend.Backend` data source."""
270
271
272logger.debug('successfully imported %s', __name__)