confidantic 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,20 @@
1
+ """Configuration and CLIs for Python projects based on Pydantic Settings."""
2
+
3
+ __all__ = (
4
+ "BaseConfig",
5
+ "ClassDefaultsSource",
6
+ "ConfigModelDict",
7
+ "Factory",
8
+ "__version__",
9
+ )
10
+
11
+ import importlib.metadata
12
+
13
+ from confidantic._config import (
14
+ BaseConfig,
15
+ ClassDefaultsSource,
16
+ ConfigModelDict,
17
+ Factory,
18
+ )
19
+
20
+ __version__ = importlib.metadata.version("confidantic")
@@ -0,0 +1,13 @@
1
+ """Configuration models and sources."""
2
+
3
+ __all__ = (
4
+ "BaseConfig",
5
+ "ClassDefaultsSource",
6
+ "ConfigModelDict",
7
+ "Factory",
8
+ )
9
+
10
+ from confidantic._config._options import ConfigModelDict
11
+ from confidantic._config._settings import ClassDefaultsSource
12
+ from confidantic._config.base import BaseConfig
13
+ from confidantic._config.factory import Factory
@@ -0,0 +1,192 @@
1
+ """CLI source selection and context-local suppression during resolution."""
2
+
3
+ from collections.abc import Generator, Mapping
4
+ from contextlib import contextmanager
5
+ from contextvars import ContextVar
6
+ from copy import copy
7
+ from inspect import signature
8
+ from types import GenericAlias
9
+ from typing import Any
10
+
11
+ from pydantic import BaseModel
12
+ from pydantic.fields import FieldInfo
13
+ from pydantic_settings import BaseSettings, CliSettingsSource, EnvSettingsSource
14
+
15
+ # Resolution may construct arbitrary settings inside a target constructor, so
16
+ # suppression must reach those calls without changing their public signatures.
17
+ _CLI_SUPPRESSED: ContextVar[bool] = ContextVar(
18
+ "confidantic_cli_suppressed", default=False
19
+ )
20
+
21
+
22
+ class _FactoryCliSettingsSource(CliSettingsSource[Any]):
23
+ """Expose nested CLI fields from concrete Factory instance defaults.
24
+
25
+ Parser-facing FieldInfo copies use the default's concrete factory type.
26
+ The original model's annotations and field metadata remain unchanged.
27
+ """
28
+
29
+ @staticmethod
30
+ def supports(model: type[BaseModel]) -> bool:
31
+ """Detect direct factory-annotated fields with concrete factory defaults.
32
+
33
+ Union members and default factories are not evaluated. This check
34
+ decides whether the root parser needs factory-specific field handling.
35
+ """
36
+ from confidantic._config.factory import Factory
37
+
38
+ return any(
39
+ isinstance(field.annotation, type)
40
+ and issubclass(field.annotation, Factory)
41
+ and isinstance(field.default, Factory)
42
+ for field in model.model_fields.values()
43
+ )
44
+
45
+ @staticmethod
46
+ def _import_annotation(target: type[Any]) -> Any:
47
+ """Represent CLI type choices as import strings constrained to the target."""
48
+ from confidantic.annotations import Import
49
+
50
+ return Import[GenericAlias(type, target)] # type: ignore[misc]
51
+
52
+ def _sort_arg_fields(self, model: type[BaseModel]) -> list[tuple[str, FieldInfo]]:
53
+ """Retain upstream field order while exposing concrete factory-default fields."""
54
+ from confidantic._config.factory import Factory
55
+
56
+ fields = super()._sort_arg_fields(model)
57
+ normalized: list[tuple[str, FieldInfo]] = []
58
+ for field_name, field_info in fields:
59
+ if (
60
+ isinstance(field_info.annotation, type)
61
+ and issubclass(field_info.annotation, Factory)
62
+ and isinstance(field_info.default, Factory)
63
+ ):
64
+ field_info = copy(field_info)
65
+ field_info.annotation = type(field_info.default)
66
+ normalized.append((field_name, field_info))
67
+ return normalized
68
+
69
+
70
+ class _FactoryCliHelpDisabledSettingsSource(_FactoryCliSettingsSource):
71
+ """Keep nested Factory options while omitting the generated help option."""
72
+
73
+ def _add_default_help(self) -> None:
74
+ pass
75
+
76
+
77
+ class _CliHelpDisabledSettingsSource(CliSettingsSource[Any]):
78
+ """Omit the generated help option without changing argument parsing."""
79
+
80
+ def _add_default_help(self) -> None:
81
+ pass
82
+
83
+
84
+ class _CliSettings:
85
+ """Prepare CLI and environment options for one class in the settings MRO.
86
+
87
+ The original env_prefix is retained separately from the normalized
88
+ environment options: None disables that class's ordinary environment source.
89
+ The source method preserves supplied parsers and returns None when upstream
90
+ should construct its normal parser. Suppression is a separate context-local
91
+ policy shared by all settings created during recursive resolution.
92
+
93
+ Parameters
94
+ ----------
95
+ model_type
96
+ Settings class whose parser and environment policy are being prepared.
97
+ options
98
+ Bound upstream source-builder arguments, including defaults. Non-None
99
+ per-call options override the corresponding model configuration values.
100
+ model_config
101
+ Effective configuration at this MRO level, including custom overrides.
102
+
103
+ Attributes
104
+ ----------
105
+ cli_options, env_options
106
+ Resolved keyword arguments supported by the installed source classes.
107
+ A configured environment null token also becomes the CLI null token.
108
+ env_prefix
109
+ Prefix before normalization; ``None`` disables the ordinary environment
110
+ source even though the parser-facing environment options use ``""``.
111
+ """
112
+
113
+ def __init__(
114
+ self,
115
+ model_type: type[BaseSettings],
116
+ options: Mapping[str, Any],
117
+ model_config: Mapping[str, Any],
118
+ ) -> None:
119
+ self.model_type = model_type
120
+ self.help_enabled = model_config.get("cli_help", True)
121
+ self.cli_options: dict[str, Any] = {}
122
+ self.env_options: dict[str, Any] = {}
123
+ for source_type, target in (
124
+ (CliSettingsSource, self.cli_options),
125
+ (EnvSettingsSource, self.env_options),
126
+ ):
127
+ for name in signature(source_type).parameters:
128
+ if f"_{name}" in options:
129
+ value = options[f"_{name}"]
130
+ target[name] = (
131
+ value if value is not None else model_config.get(name)
132
+ )
133
+ self.env_prefix: str | None = self.env_options["env_prefix"]
134
+ self.env_options["env_prefix"] = self.env_prefix or ""
135
+ if self.env_options["env_parse_none_str"] is not None:
136
+ self.cli_options["cli_parse_none_str"] = self.env_options[
137
+ "env_parse_none_str"
138
+ ]
139
+
140
+ def source(
141
+ self, supplied: CliSettingsSource[Any] | None
142
+ ) -> CliSettingsSource[Any] | None:
143
+ """Return a supplied/custom source, or defer normal construction upstream.
144
+
145
+ Parameters
146
+ ----------
147
+ supplied
148
+ Caller-provided source, returned unchanged without replacing its
149
+ parser or help policy.
150
+
151
+ Returns
152
+ -------
153
+ CliSettingsSource | None
154
+ Supplied source or a generated source for factory defaults or
155
+ disabled help. ``None`` leaves ordinary construction to upstream,
156
+ including when automatic parsing is disabled.
157
+ """
158
+ parse_args = self.cli_options["cli_parse_args"]
159
+ if supplied is not None or parse_args is None or parse_args is False:
160
+ return supplied
161
+ has_factory_fields = _FactoryCliSettingsSource.supports(self.model_type)
162
+ if not has_factory_fields and self.help_enabled:
163
+ return None
164
+ source_type = (
165
+ _FactoryCliSettingsSource
166
+ if self.help_enabled
167
+ else (
168
+ _FactoryCliHelpDisabledSettingsSource
169
+ if has_factory_fields
170
+ else _CliHelpDisabledSettingsSource
171
+ )
172
+ )
173
+ return source_type(
174
+ self.model_type,
175
+ **self.cli_options,
176
+ _env_settings_source=EnvSettingsSource(self.model_type, **self.env_options),
177
+ )
178
+
179
+ @staticmethod
180
+ def is_suppressed() -> bool:
181
+ """Whether the current resolution scope disables automatic CLI parsing."""
182
+ return _CLI_SUPPRESSED.get()
183
+
184
+ @staticmethod
185
+ @contextmanager
186
+ def suppress() -> Generator[None]:
187
+ """Disable CLI parsing for this scope and restore the enclosing policy."""
188
+ token = _CLI_SUPPRESSED.set(True)
189
+ try:
190
+ yield
191
+ finally:
192
+ _CLI_SUPPRESSED.reset(token)
@@ -0,0 +1,132 @@
1
+ """Optional composition and parsing for generated Attributes sections.
2
+
3
+ The layout scanner loads this module only for a validated insertion request.
4
+ Parser-specific objects stay here; callers exchange text and field descriptions.
5
+ """
6
+
7
+ import re
8
+ from collections.abc import Iterable, Mapping
9
+ from typing import Literal
10
+
11
+ from docstring_parser import (
12
+ Docstring,
13
+ DocstringParam,
14
+ DocstringStyle,
15
+ ParseError,
16
+ compose,
17
+ parse,
18
+ )
19
+ from docstring_parser.numpydoc import NumpydocParser, Section
20
+
21
+
22
+ class _LiteralNumpySection(Section):
23
+ """Treat a custom NumPy section as text rather than additional attributes."""
24
+
25
+ @property
26
+ def title_pattern(self) -> str:
27
+ """Match a literal heading and its underline without interpreting title regexes."""
28
+ # Custom titles may contain regex syntax, such as parentheses.
29
+ return rf"^({re.escape(self.title)})[ \t]*\n{'-' * len(self.title)}[ \t]*$"
30
+
31
+
32
+ class _AttributeDocstringBackend:
33
+ """Compose and parse one docstring style with class-qualified diagnostics.
34
+
35
+ Composition preserves field order and descriptions. Parsing returns field
36
+ names and whitespace-normalized descriptions for independent comparison by
37
+ the caller, validating the complete document rather than just its new section.
38
+
39
+ Parameters
40
+ ----------
41
+ style
42
+ Detected or explicitly selected convention used for both operations.
43
+ class_name
44
+ Configuration class name included in parser-error diagnostics.
45
+ """
46
+
47
+ def __init__(self, style: Literal["numpy", "google"], *, class_name: str) -> None:
48
+ self._style = style
49
+ self._class_name = class_name
50
+ self._parser_style = (
51
+ DocstringStyle.NUMPYDOC if style == "numpy" else DocstringStyle.GOOGLE
52
+ )
53
+
54
+ def compose(self, fields: Mapping[str, str | None]) -> str:
55
+ """Compose an Attributes section, retaining its heading when empty.
56
+
57
+ Parameters
58
+ ----------
59
+ fields
60
+ Field names and optional descriptions in output order. Types and
61
+ defaults are not added to the generated entries.
62
+
63
+ Returns
64
+ -------
65
+ str
66
+ Section text without leading or trailing newlines. Empty headings
67
+ are emitted here; the subsequent parse decides whether they are valid.
68
+ """
69
+ generated = Docstring(style=self._parser_style)
70
+ generated.meta = [
71
+ DocstringParam(
72
+ args=["attribute", name],
73
+ description=description,
74
+ arg_name=name,
75
+ type_name=None,
76
+ is_optional=None,
77
+ default=None,
78
+ )
79
+ for name, description in fields.items()
80
+ ]
81
+ fragment = compose(generated, style=self._parser_style, indent=" ").strip(
82
+ "\n"
83
+ )
84
+ # Composers omit empty sections; parsing decides whether they are valid.
85
+ return fragment or (
86
+ "Attributes\n----------" if self._style == "numpy" else "Attributes:"
87
+ )
88
+
89
+ def attributes(
90
+ self, text: str, *, custom_numpy_titles: Iterable[str]
91
+ ) -> list[tuple[str, str]]:
92
+ """Parse a complete docstring and return its normalized attribute entries.
93
+
94
+ Parameters
95
+ ----------
96
+ text
97
+ Completed docstring. Newlines are normalized only in the parser's view.
98
+ custom_numpy_titles
99
+ Detected NumPy headings to register as literal sections if unknown
100
+ to the parser, preventing their content from becoming attributes.
101
+ Ignored for Google-style parsing.
102
+
103
+ Returns
104
+ -------
105
+ list[tuple[str, str]]
106
+ Attribute names and whitespace-normalized descriptions in parse order.
107
+
108
+ Raises
109
+ ------
110
+ ValueError
111
+ If parsing fails, with the configuration class and style in the message.
112
+ """
113
+ try:
114
+ # Normalize only the parser's view, leaving the stored string intact.
115
+ normalized = text.replace("\r\n", "\n").replace("\r", "\n")
116
+ if self._style == "numpy":
117
+ parser = NumpydocParser()
118
+ for title in custom_numpy_titles:
119
+ if title not in parser.sections:
120
+ parser.add_section(_LiteralNumpySection(title, "custom"))
121
+ parsed = parser.parse(normalized)
122
+ else:
123
+ parsed = parse(normalized, style=self._parser_style)
124
+ except ParseError as error:
125
+ raise ValueError(
126
+ f"{self._class_name}: invalid generated {self._style} docstring: {error}"
127
+ ) from error
128
+ return [
129
+ (item.arg_name, " ".join((item.description or "").split()))
130
+ for item in parsed.params
131
+ if item.args[0] == "attribute"
132
+ ]
@@ -0,0 +1,283 @@
1
+ """Replace marked attribute sections without rewriting surrounding text.
2
+
3
+ A line-based scan locates sections and active markers while retaining their
4
+ original line indices. Only the replacement section is composed; the complete
5
+ result is then parsed to validate its meaning independently of the layout scan.
6
+ """
7
+
8
+ from dataclasses import dataclass
9
+ from typing import Literal
10
+
11
+ _Style = Literal["numpy", "google"]
12
+
13
+
14
+ @dataclass(frozen=True)
15
+ class _SectionSpan:
16
+ """Section boundaries as zero-based line indices, with an exclusive end.
17
+
18
+ Attributes
19
+ ----------
20
+ title, style
21
+ Heading text without its delimiter and the detected section convention.
22
+ header_start, body_start
23
+ First heading and content lines, respectively. NumPy headings occupy
24
+ two lines; Google headings occupy one.
25
+ end
26
+ First line outside the section, or the total line count at end of text.
27
+ """
28
+
29
+ title: str
30
+ style: _Style
31
+ header_start: int
32
+ body_start: int
33
+ end: int
34
+
35
+
36
+ def _scan_docstring(text: str) -> tuple[list[str], list[_SectionSpan], list[int]]:
37
+ """Locate section boundaries and standalone insertion markers.
38
+
39
+ Parameters
40
+ ----------
41
+ text
42
+ Original docstring, including its source indentation. Scanning ignores
43
+ doctests, fenced blocks, and indented literal content without altering
44
+ the stored text or its line numbering.
45
+
46
+ Returns
47
+ -------
48
+ lines : list[str]
49
+ Dedented scan view with tabs expanded and line endings removed. Its
50
+ indices remain aligned with the original text, including blank lines.
51
+ sections : list[_SectionSpan]
52
+ NumPy and Google sections in heading order, with exclusive end indices.
53
+ active_markers : list[int]
54
+ Marker line indices outside examples and literal content. These may
55
+ lie outside Attributes; the caller validates insertion requests.
56
+ """
57
+ # Keep line indices aligned with the original, unlike cleandoc(), which
58
+ # removes leading/trailing empty lines. Expand tabs only in the scan view.
59
+ lines = text.expandtabs().splitlines()
60
+ margin = min(
61
+ (len(line) - len(line.lstrip()) for line in lines[1:] if line.strip()),
62
+ default=0,
63
+ )
64
+ lines = [line.lstrip() if i == 0 else line[margin:] for i, line in enumerate(lines)]
65
+
66
+ # Collect headings and markers outside literal content. Literal blocks end
67
+ # at dedentation, fences at the next fence, and doctests at a blank line.
68
+ headings: list[tuple[str, _Style, int, int]] = []
69
+ markers: list[int] = []
70
+ literal_indent: int | None = None
71
+ fenced = False
72
+ doctest = False
73
+ for line_index, line in enumerate(lines):
74
+ stripped = line.strip()
75
+ if not stripped:
76
+ doctest = False
77
+ continue
78
+ indent = len(line) - len(line.lstrip())
79
+ if literal_indent is not None:
80
+ if indent > literal_indent:
81
+ continue
82
+ literal_indent = None
83
+ if stripped.startswith(("```", "~~~")):
84
+ fenced = not fenced
85
+ continue
86
+ if fenced:
87
+ continue
88
+ if stripped.startswith(">>>"):
89
+ doctest = True
90
+ if doctest:
91
+ continue
92
+ if stripped.endswith("::"):
93
+ literal_indent = indent
94
+ continue
95
+ if indent == 0:
96
+ if (
97
+ line_index + 1 < len(lines)
98
+ and len(lines[line_index + 1].rstrip()) >= 3
99
+ and set(lines[line_index + 1].rstrip()) == {"-"}
100
+ ):
101
+ headings.append((stripped, "numpy", line_index, line_index + 2))
102
+ elif stripped.endswith(":") and stripped not in {"@attrs:"}:
103
+ headings.append((stripped[:-1], "google", line_index, line_index + 1))
104
+ if stripped in {"@attrs", "@attrs:"}:
105
+ markers.append(line_index)
106
+
107
+ # NumPy sections end at the next NumPy heading. Google sections end at
108
+ # any heading or unindented content.
109
+ sections: list[_SectionSpan] = []
110
+ for heading_index, (title, style, header_start, body_start) in enumerate(headings):
111
+ end = next(
112
+ (
113
+ next_header_start
114
+ for _, next_style, next_header_start, _ in headings[heading_index + 1 :]
115
+ if style == "google" or next_style == "numpy"
116
+ ),
117
+ len(lines),
118
+ )
119
+ if style == "google":
120
+ end = next(
121
+ (
122
+ line_index
123
+ for line_index in range(body_start, end)
124
+ if lines[line_index] and not lines[line_index][0].isspace()
125
+ ),
126
+ end,
127
+ )
128
+ sections.append(_SectionSpan(title, style, header_start, body_start, end))
129
+
130
+ # Section context distinguishes insertion requests from example text and
131
+ # markers nested within an entry's description.
132
+ active_markers: list[int] = []
133
+ for marker_index in markers:
134
+ section = next(
135
+ (
136
+ candidate
137
+ for candidate in sections
138
+ if candidate.body_start <= marker_index < candidate.end
139
+ ),
140
+ None,
141
+ )
142
+ if section is not None:
143
+ if section.title.lower() in {"example", "examples"}:
144
+ continue
145
+ entry_indent = min(
146
+ (
147
+ len(line) - len(line.lstrip())
148
+ for line in lines[section.body_start : section.end]
149
+ if line.strip()
150
+ ),
151
+ default=0,
152
+ )
153
+ marker = lines[marker_index]
154
+ if len(marker) - len(marker.lstrip()) > entry_indent:
155
+ continue
156
+ active_markers.append(marker_index)
157
+ return lines, sections, active_markers
158
+
159
+
160
+ def replace_attributes(
161
+ text: str,
162
+ *,
163
+ fields: dict[str, str | None],
164
+ style: _Style | None,
165
+ class_name: str,
166
+ ) -> str:
167
+ """Replace a marked Attributes section with model field documentation.
168
+
169
+ Parameters
170
+ ----------
171
+ text : str
172
+ Original class docstring. A standalone ``@attrs`` marker requests
173
+ replacement of the entire Attributes section; Google sections also
174
+ accept ``@attrs:``. Markers in examples or literal content are ignored.
175
+ fields : dict[str, str | None]
176
+ Effective model field names and descriptions, in output order.
177
+ style : {"numpy", "google"} or None
178
+ Expected input format, or None to detect it from the Attributes
179
+ section. An explicit style validates the format without converting it.
180
+ class_name : str
181
+ Class name prefixed to validation error messages.
182
+
183
+ Returns
184
+ -------
185
+ str
186
+ Docstring with the generated section, preserving surrounding text and
187
+ using the original heading's indentation and LF/CRLF convention. Returns the
188
+ original text unchanged when no active marker is present.
189
+
190
+ Raises
191
+ ------
192
+ ImportError
193
+ If an active insertion request requires the missing ``docstrings`` extra.
194
+ ValueError
195
+ If the marked section is invalid, its style conflicts with the expected
196
+ format, or the completed docstring fails structural or parser validation.
197
+ Empty marked Google sections fail validation; NumPy permits them.
198
+ """
199
+ lines, sections, active_markers = _scan_docstring(text)
200
+ if not active_markers:
201
+ return text
202
+
203
+ def fail(reason: str) -> ValueError:
204
+ return ValueError(f"{class_name}: {reason}")
205
+
206
+ # Validate the insertion request before composing any replacement text.
207
+ attributes = [section for section in sections if section.title == "Attributes"]
208
+ if len(attributes) != 1:
209
+ raise fail("expected exactly one Attributes section")
210
+ section = attributes[0]
211
+ if (
212
+ len(active_markers) != 1
213
+ or not section.body_start <= active_markers[0] < section.end
214
+ ):
215
+ raise fail("expected one @attrs marker inside Attributes")
216
+ marker = lines[active_markers[0]]
217
+ if section.style == "numpy" and (
218
+ marker.rstrip() != "@attrs"
219
+ or lines[section.header_start + 1].rstrip() != "----------"
220
+ ):
221
+ raise fail("invalid NumPy @attrs marker")
222
+ if style is not None and style != section.style:
223
+ raise fail(f"Attributes section does not match docstring_style={style!r}")
224
+
225
+ # Unmarked text and malformed requests need no optional parser dependency.
226
+ try:
227
+ from confidantic._config._docstring_backend import _AttributeDocstringBackend
228
+ except ModuleNotFoundError as error:
229
+ if error.name != "docstring_parser":
230
+ raise
231
+ raise ImportError(
232
+ f"{class_name}: @attrs generation requires docstring-parser; "
233
+ "install confidantic[docstrings]"
234
+ ) from error
235
+
236
+ # Compose only the Attributes section so other sections keep their layout.
237
+ backend = _AttributeDocstringBackend(section.style, class_name=class_name)
238
+ fragment = backend.compose(fields)
239
+
240
+ # Splice original lines, leaving trailing blank lines outside the replaced
241
+ # span so their whitespace survives exactly.
242
+ original_lines = text.splitlines(keepends=True)
243
+ replacement_end = section.end
244
+ while (
245
+ replacement_end > section.body_start and not lines[replacement_end - 1].strip()
246
+ ):
247
+ replacement_end -= 1
248
+ header = original_lines[section.header_start]
249
+ prefix = header[: len(header) - len(header.lstrip(" \t"))]
250
+ newline = "\r\n" if header.endswith("\r\n") else "\n"
251
+ replacement = newline.join(
252
+ prefix + line if line else "" for line in fragment.splitlines()
253
+ )
254
+ if original_lines[replacement_end - 1].endswith(("\n", "\r")):
255
+ replacement += newline
256
+ candidate = (
257
+ "".join(original_lines[: section.header_start])
258
+ + replacement
259
+ + "".join(original_lines[replacement_end:])
260
+ )
261
+
262
+ # Check structure before parsing: parsers may collapse duplicate sections
263
+ # or accept leftover markers as attribute names.
264
+ _, result_sections, result_markers = _scan_docstring(candidate)
265
+ if sum(s.title == "Attributes" for s in result_sections) != 1:
266
+ raise fail("generated docstring must contain exactly one Attributes section")
267
+ if result_markers:
268
+ raise fail("generated docstring still contains an @attrs marker")
269
+ # Compare descriptions by content, ignoring wrapping and indentation
270
+ # introduced by composition and parsing. Keep field order significant.
271
+ actual = backend.attributes(
272
+ candidate,
273
+ custom_numpy_titles=(
274
+ section.title for section in result_sections if section.style == "numpy"
275
+ ),
276
+ )
277
+ expected = [
278
+ (name, " ".join((description or "").split()))
279
+ for name, description in fields.items()
280
+ ]
281
+ if actual != expected:
282
+ raise fail("generated Attributes do not match model fields")
283
+ return candidate