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

1"""Base class for dynamic pydantic models""" 

2 

3import contextlib 

4import typing as ty 

5import warnings 

6 

7import pydantic 

8import pydantic.fields 

9import pydantic_core 

10 

11from .exceptions import ( 

12 AmbiguousDiscriminatorValueError, 

13 NoRegisteredTypesError, 

14 RegistrationError, 

15) 

16from .union_mode import DiscriminatedConfig, UnionMode 

17 

18_ModelT = ty.TypeVar("_ModelT", bound=pydantic.BaseModel) 

19 

20 

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 

27 

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) 

45 

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] 

54 

55 

56class TrackingGroup(pydantic.BaseModel): 

57 """Tracker for pydantic models""" 

58 

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 ) 

105 

106 _generation: int = pydantic.PrivateAttr(default=0) 

107 _adapter: pydantic.TypeAdapter | None = pydantic.PrivateAttr(default=None) 

108 _adapter_generation: int = pydantic.PrivateAttr(default=-1) 

109 

110 @pydantic.model_validator(mode="after") 

111 def _ensure_union_mode(self) -> "TrackingGroup": 

112 """There must be a union_mode 

113 

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) 

125 

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 

135 

136 return self 

137 

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. 

142 

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 

150 

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 

155 

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) 

176 

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) 

188 

189 return data 

190 

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 ) 

199 

200 def load_plugins(self) -> None: 

201 """Load plugins to discover/register additional models""" 

202 if self.plugin_entry_point is None: 

203 return 

204 

205 from importlib.metadata import entry_points # noqa: PLC0415 

206 

207 for ep in entry_points().select(group=self.plugin_entry_point): 

208 plugin = ep.load() 

209 if callable(plugin): 

210 plugin() 

211 

212 @ty.overload 

213 def register( 

214 self, value: str | None = None 

215 ) -> ty.Callable[[type[_ModelT]], type[_ModelT]]: ... 

216 

217 @ty.overload 

218 def register(self, value: type[_ModelT]) -> type[_ModelT]: ... 

219 

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) 

225 

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 

237 

238 def _wrapper(cls: type[_ModelT]) -> type[_ModelT]: 

239 self.register_model(cls, value) 

240 return cls 

241 

242 return _wrapper 

243 

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 

250 

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) 

266 

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) 

273 

274 if (dm := self._discriminated) is not None: 

275 disc = dm.discriminator_field 

276 field = cls.model_fields.get(disc) 

277 

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) 

312 

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) 

324 

325 def union( 

326 self, 

327 *, 

328 plain: bool | None = None, 

329 ) -> ty.Any: # noqa: ANN401 

330 """Return the union of all registered models 

331 

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. 

338 

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`. 

345 

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())) 

360 

361 union_mode = "smart" if plain else self.union_mode 

362 

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 ] 

373 

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")] 

379 

380 # "smart" mode is pydantic's default behavior on a plain union 

381 return plain_union 

382 

383 @property 

384 def generation(self) -> int: 

385 """The generation of the tracking group. 

386 

387 This is a counter that increments every time a new registration occurs 

388 """ 

389 return self._generation 

390 

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 

397 

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) 

401 

402 def _register_with_discriminator_field(self, cls: type[pydantic.BaseModel]) -> None: 

403 """Register the model with the default of the discriminator field 

404 

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) 

425 

426 self._do_register(value, cls) 

427 

428 def _register_plain(self, cls: type[pydantic.BaseModel]) -> None: 

429 """Register the model keyed by its class name. 

430 

431 Used for smart / left_to_right modes where no discriminator field 

432 is involved. 

433 

434 Parameters 

435 ---------- 

436 cls 

437 The model to register. 

438 """ 

439 self._do_register(str(id(cls)), cls) 

440 

441 def _do_register(self, key: str, cls: type[pydantic.BaseModel]) -> None: 

442 """Register the given model under the given key 

443 

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