Coverage for src/dynapydantic/tracking_group.py: 100%
146 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-16 12:39 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-16 12:39 +0000
1"""Base class for dynamic pydantic models"""
3import contextlib
4import typing as ty
5import warnings
7import pydantic
8import pydantic.fields
9import pydantic_core
11from .exceptions import (
12 AmbiguousDiscriminatorValueError,
13 NoRegisteredTypesError,
14 RegistrationError,
15)
16from .union_mode import DiscriminatedConfig, UnionMode
18_ModelT = ty.TypeVar("_ModelT", bound=pydantic.BaseModel)
21def _inject_discriminator_field(
22 cls: type[pydantic.BaseModel],
23 disc_field: str,
24 value: str,
25) -> pydantic.fields.FieldInfo:
26 """Injects the discriminator field into the given model
28 Parameters
29 ----------
30 cls
31 The BaseModel subclass
32 disc_field
33 Name of the discriminator field
34 value
35 Value of the discriminator field
36 """
37 if hasattr(cls, disc_field):
38 msg = (
39 f'Cannot inject discriminator field "{disc_field}" into '
40 f"{cls.__name__}: an attribute with that name already exists. "
41 "Rename either the attribute or the discriminator_field to avoid "
42 "the conflict."
43 )
44 raise RegistrationError(msg)
46 cls.model_fields[disc_field] = pydantic.fields.FieldInfo(
47 default=value,
48 annotation=ty.Literal[value], # type: ignore[not-a-type]
49 frozen=True,
50 )
51 with contextlib.suppress(pydantic.errors.PydanticUndefinedAnnotation):
52 cls.model_rebuild(force=True)
53 return cls.model_fields[disc_field]
56class TrackingGroup(pydantic.BaseModel):
57 """Tracker for pydantic models"""
59 name: str = pydantic.Field(
60 description=(
61 "Name of the tracking group. This is for human display, so it "
62 "doesn't technically need to be globally unique, but it should be "
63 "meaningfully named, as it will be used in error messages."
64 ),
65 )
66 union_mode: UnionMode | None = pydantic.Field(
67 None,
68 description=(
69 "Union validation strategy. Pass a DiscriminatedConfig instance "
70 'or one of the plain strings "smart" or "left_to_right". You can '
71 "also just pass the fields for DiscriminatedConfig to this "
72 "model and they will be forwarded."
73 ),
74 )
75 discriminator_field: str | None = pydantic.Field(
76 None,
77 description=(
78 "Name of the discriminator field. NOTE: This field is "
79 "here as an alias for union_mode.discriminator_field. Passing "
80 "both a discriminator_field and a union_mode will result in an "
81 "error."
82 ),
83 )
84 discriminator_value_generator: ty.Callable[[type], str] | None = pydantic.Field(
85 None,
86 description=(
87 "A callable that produces default values for the discriminator field"
88 ),
89 )
90 plugin_entry_point: str | None = pydantic.Field(
91 None,
92 description=(
93 "If given, then plugins packages will be supported through this "
94 "Python entrypoint. The entrypoint can either be a function, "
95 "which will be called, or simply a module, which will be "
96 "imported. In either case, models found along the import path of "
97 "the entrypoint will be registered. If the entrypoint is a "
98 "function, additional models may be declared in the function."
99 ),
100 )
101 models: dict[str, type[pydantic.BaseModel]] = pydantic.Field(
102 {},
103 description="The tracked models",
104 )
106 _generation: int = pydantic.PrivateAttr(default=0)
107 _adapter: pydantic.TypeAdapter | None = pydantic.PrivateAttr(default=None)
108 _adapter_generation: int = pydantic.PrivateAttr(default=-1)
110 @pydantic.model_validator(mode="after")
111 def _ensure_union_mode(self) -> "TrackingGroup":
112 """There must be a union_mode
114 This validator works as a guard on _coerce_union_mode to make
115 """
116 if self.union_mode is None:
117 msg = (
118 "union_mode is required. This normally indicates that you "
119 "subclasses TrackingGroup and wrote an invalid validator, but "
120 "could also be a bug with dynapydantic, so please file a bug "
121 "report with a reproducer on how you got here if you suspect "
122 "a bug."
123 )
124 raise ValueError(msg)
126 # Ensure the top-level fields are in-sync
127 if isinstance(self.union_mode, DiscriminatedConfig):
128 self.discriminator_field = self.union_mode.discriminator_field
129 self.discriminator_value_generator = (
130 self.union_mode.discriminator_value_generator
131 )
132 else:
133 self.discriminator_field = None
134 self.discriminator_value_generator = None
136 return self
138 @pydantic.model_validator(mode="before")
139 @classmethod
140 def _coerce_union_mode(cls, data: ty.Any) -> ty.Any: # noqa: ANN401
141 """Coerce flat discriminator kwargs into a DiscriminatedConfig.
143 Allows callers to pass ``discriminator_field`` and
144 ``discriminator_value_generator`` at the top level and transparently
145 assembles a ``DiscriminatedConfig`` from them. This avoids an extra
146 import/nesting layer for the user.
147 """
148 if not isinstance(data, dict):
149 return data
151 disc_field = data.get("discriminator_field", None)
152 has_disc_field = disc_field is not None
153 union_mode = data.get("union_mode", None)
154 has_union_mode = union_mode is not None
156 # If the user passed us both a discriminator field and a union_mode,
157 # things must be perfectly consistent
158 if has_disc_field and has_union_mode:
159 consistent = (
160 isinstance(union_mode, DiscriminatedConfig)
161 and disc_field == union_mode.discriminator_field
162 and data.get("discriminator_value_generator")
163 is union_mode.discriminator_value_generator
164 ) or (
165 isinstance(union_mode, dict)
166 and disc_field == union_mode.get("discriminator_field")
167 and data.get("discriminator_value_generator")
168 is union_mode.get("discriminator_value_generator")
169 )
170 if not consistent:
171 msg = (
172 "Received both union_mode and discriminator_field; pass one "
173 "or the other."
174 )
175 raise ValueError(msg)
177 if has_disc_field and not has_union_mode:
178 # Forward arguments to DiscriminatedConfig
179 data["union_mode"] = {
180 "discriminator_field": disc_field,
181 "discriminator_value_generator": data.get(
182 "discriminator_value_generator",
183 ),
184 }
185 elif not has_disc_field and not has_union_mode:
186 msg = "Either union_mode or discriminator_field must be given"
187 raise ValueError(msg)
189 return data
191 @property
192 def _discriminated(self) -> DiscriminatedConfig | None:
193 """Return the DiscriminatedMode config, or None if not discriminated."""
194 return (
195 self.union_mode
196 if isinstance(self.union_mode, DiscriminatedConfig)
197 else None
198 )
200 def load_plugins(self) -> None:
201 """Load plugins to discover/register additional models"""
202 if self.plugin_entry_point is None:
203 return
205 from importlib.metadata import entry_points # noqa: PLC0415
207 for ep in entry_points().select(group=self.plugin_entry_point):
208 plugin = ep.load()
209 if callable(plugin):
210 plugin()
212 @ty.overload
213 def register(
214 self, value: str | None = None
215 ) -> ty.Callable[[type[_ModelT]], type[_ModelT]]: ...
217 @ty.overload
218 def register(self, value: type[_ModelT]) -> type[_ModelT]: ...
220 def register(
221 self,
222 value: str | type[_ModelT] | None = None,
223 ) -> ty.Callable[[type[_ModelT]], type[_ModelT]] | type[_ModelT]:
224 """Register a model into this group (decorator)
226 Parameters
227 ----------
228 value
229 Value for the discriminator field. If not given, then
230 discriminator_value_generator must be non-None or the
231 discriminator field must be declared by hand. Can also be the type
232 itself to register (if the ()'s are omitted from the decorator).
233 """
234 if isinstance(value, type):
235 self.register_model(value)
236 return value
238 def _wrapper(cls: type[_ModelT]) -> type[_ModelT]:
239 self.register_model(cls, value)
240 return cls
242 return _wrapper
244 def register_model(
245 self,
246 cls: type[pydantic.BaseModel],
247 discriminator_value: str | None = None,
248 ) -> None:
249 """Register the given model into this group
251 Parameters
252 ----------
253 cls
254 The model to register
255 discriminator_value
256 Value for the discriminator field. If not given, then
257 discriminator_value_generator must be non-None or the
258 discriminator field must be declared by hand.
259 """
260 if discriminator_value is not None and not isinstance(discriminator_value, str):
261 msg = (
262 "discriminator_value must be a str if given, was "
263 f"{type(discriminator_value).__name__}"
264 )
265 raise RegistrationError(msg)
267 if not isinstance(cls, type) or not issubclass(cls, pydantic.BaseModel):
268 msg = (
269 "only pydantic BaseModel subclasses can be registered in a "
270 f"TrackingGroup. Got {cls}, which was not."
271 )
272 raise RegistrationError(msg)
274 if (dm := self._discriminated) is not None:
275 disc = dm.discriminator_field
276 field = cls.model_fields.get(disc)
278 if field is None:
279 if discriminator_value is not None:
280 _inject_discriminator_field(cls, disc, discriminator_value)
281 elif dm.discriminator_value_generator is not None:
282 _inject_discriminator_field(
283 cls,
284 disc,
285 dm.discriminator_value_generator(cls),
286 )
287 else:
288 msg = (
289 f"unable to determine a discriminator value for "
290 f'{cls.__name__} in tracking group "{self.name}". '
291 "No value was passed, discriminator_value_generator "
292 f'was None and the "{disc}" field was not defined.'
293 )
294 raise RegistrationError(msg)
295 elif ty.get_origin(field.annotation) is not ty.Literal:
296 msg = (
297 f'the discriminator field "{disc}" already existed in '
298 f"{cls.__name__}, but its type annotation was "
299 f"{field.annotation}, not Literal."
300 )
301 raise RegistrationError(msg)
302 elif (
303 discriminator_value is not None and field.default != discriminator_value
304 ):
305 msg = (
306 f"the discriminator value for {cls.__name__} was "
307 f'ambiguous, the passed value was "{discriminator_value}" '
308 f' and "{field.default}" via the discriminator '
309 f"field ({disc})."
310 )
311 raise AmbiguousDiscriminatorValueError(msg)
313 self._register_with_discriminator_field(cls)
314 else:
315 if discriminator_value is not None:
316 warnings.warn(
317 f'A discriminator_value of "{discriminator_value}" was '
318 f"explicitly passed for {cls.__name__}, but "
319 f'union_mode="{self.union_mode}" does not use a '
320 "discriminator. The value will be ignored.",
321 stacklevel=2,
322 )
323 self._register_plain(cls)
325 def union(
326 self,
327 *,
328 plain: bool | None = None,
329 ) -> ty.Any: # noqa: ANN401
330 """Return the union of all registered models
332 Parameters
333 ----------
334 plain
335 If set to `True`, a plain union of all members will be returned.
336 Otherwise, the returned union will be annotated in accordance with
337 the union mode.
339 Returns
340 -------
341 Any
342 If there is 1 registered type, the type itself. If there is > 1, a
343 union of all registered types. This union may be annotated if
344 `plain` is not `True`.
346 Raises
347 ------
348 NoRegisteredTypesError
349 If no types have been registered yet.
350 """
351 n = len(self.models)
352 if n == 0:
353 msg = (
354 "Unable to produce a union from the tracking group "
355 f'"{self.name}", as no types have been registered yet.'
356 )
357 raise NoRegisteredTypesError(msg)
358 if n == 1:
359 return next(iter(self.models.values()))
361 union_mode = "smart" if plain else self.union_mode
363 if isinstance(union_mode, DiscriminatedConfig):
364 return ty.Annotated[
365 # This is significantly faster than |'ing into a UnionType
366 ty.Union[ # noqa: UP007
367 tuple( # type: ignore[not-a-type]
368 ty.Annotated[x, pydantic.Tag(v)] for v, x in self.models.items()
369 )
370 ],
371 pydantic.Field(discriminator=union_mode.discriminator_field),
372 ]
374 plain_union = ty.Union[ # noqa: UP007
375 tuple(self.models.values()) # type: ignore[not-a-type]
376 ]
377 if union_mode == "left_to_right":
378 return ty.Annotated[plain_union, pydantic.Field(union_mode="left_to_right")]
380 # "smart" mode is pydantic's default behavior on a plain union
381 return plain_union
383 @property
384 def generation(self) -> int:
385 """The generation of the tracking group.
387 This is a counter that increments every time a new registration occurs
388 """
389 return self._generation
391 @property
392 def type_adapter(self) -> pydantic.TypeAdapter:
393 """Get the pydantic TypeAdapter for the union of all group members"""
394 if self.generation != self._adapter_generation:
395 self._adapter = pydantic.TypeAdapter(self.union())
396 self._adapter_generation = self.generation
398 # casting because the if statement ensures it is non-None (because
399 # _adapter_generation starts at -1 and generation increments from 0.
400 return ty.cast("pydantic.TypeAdapter", self._adapter)
402 def _register_with_discriminator_field(self, cls: type[pydantic.BaseModel]) -> None:
403 """Register the model with the default of the discriminator field
405 Parameters
406 ----------
407 cls
408 The class to register, must have the disciminator field set with a
409 unique default value in the group.
410 """
411 disc = ty.cast("DiscriminatedConfig", self.union_mode).discriminator_field
412 value = cls.model_fields[disc].default
413 if value == pydantic_core.PydanticUndefined:
414 msg = (
415 f"{cls.__name__}.{disc} had no default value, it must "
416 "have one which is unique among all tracked models."
417 )
418 raise RegistrationError(msg)
419 if not isinstance(value, str):
420 msg = (
421 f"{cls.__name__}.{disc} had a default value of {value}, which "
422 f"was of type {type(value).__name__}, not str."
423 )
424 raise RegistrationError(msg)
426 self._do_register(value, cls)
428 def _register_plain(self, cls: type[pydantic.BaseModel]) -> None:
429 """Register the model keyed by its class name.
431 Used for smart / left_to_right modes where no discriminator field
432 is involved.
434 Parameters
435 ----------
436 cls
437 The model to register.
438 """
439 self._do_register(str(id(cls)), cls)
441 def _do_register(self, key: str, cls: type[pydantic.BaseModel]) -> None:
442 """Register the given model under the given key
444 Parameters
445 ----------
446 key
447 The key under which to register the model
448 cls
449 The model to register.
450 """
451 if (other := self.models.get(key)) is not None:
452 if other is not cls:
453 msg = (
454 f'Cannot register {cls.__name__} under the "{key}" '
455 f"identifier, which is already in use by {other.__name__}."
456 )
457 raise RegistrationError(msg)
458 else:
459 self._generation += 1
460 self.models[key] = cls