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.
- confidantic/__init__.py +20 -0
- confidantic/_config/__init__.py +13 -0
- confidantic/_config/_cli.py +192 -0
- confidantic/_config/_docstring_backend.py +132 -0
- confidantic/_config/_docstrings.py +283 -0
- confidantic/_config/_factory_build.py +260 -0
- confidantic/_config/_factory_resolution.py +344 -0
- confidantic/_config/_formats.py +108 -0
- confidantic/_config/_info.py +162 -0
- confidantic/_config/_nested.py +269 -0
- confidantic/_config/_options.py +145 -0
- confidantic/_config/_settings.py +629 -0
- confidantic/_config/base.py +1056 -0
- confidantic/_config/factory.py +382 -0
- confidantic/annotations.py +301 -0
- confidantic/configurable.py +301 -0
- confidantic/context.py +145 -0
- confidantic/logging.py +182 -0
- confidantic/paths.py +213 -0
- confidantic/py.typed +0 -0
- confidantic/types.py +53 -0
- confidantic/utils.py +222 -0
- confidantic-0.1.0.dist-info/METADATA +290 -0
- confidantic-0.1.0.dist-info/RECORD +26 -0
- confidantic-0.1.0.dist-info/WHEEL +4 -0
- confidantic-0.1.0.dist-info/licenses/LICENSE +21 -0
confidantic/__init__.py
ADDED
|
@@ -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
|