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