Coverage for pydantic/_internal/_utils.py: 99.54%
151 statements
« prev ^ index » next coverage.py v7.5.3, created at 2024-06-21 17:00 +0000
1"""Bucket of reusable internal utilities.
3This should be reduced as much as possible with functions only used in one place, moved to that place.
4"""
6from __future__ import annotations as _annotations 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
8import dataclasses 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
9import keyword 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
10import typing 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
11import weakref 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
12from collections import OrderedDict, defaultdict, deque 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
13from copy import deepcopy 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
14from itertools import zip_longest 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
15from types import BuiltinFunctionType, CodeType, FunctionType, GeneratorType, LambdaType, ModuleType 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
16from typing import Any, Mapping, TypeVar 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
18from typing_extensions import TypeAlias, TypeGuard 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
20from . import _repr, _typing_extra 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
22if typing.TYPE_CHECKING: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
23 MappingIntStrAny: TypeAlias = 'typing.Mapping[int, Any] | typing.Mapping[str, Any]'
24 AbstractSetIntStr: TypeAlias = 'typing.AbstractSet[int] | typing.AbstractSet[str]'
25 from ..main import BaseModel
28# these are types that are returned unchanged by deepcopy
29IMMUTABLE_NON_COLLECTIONS_TYPES: set[type[Any]] = { 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
30 int,
31 float,
32 complex,
33 str,
34 bool,
35 bytes,
36 type,
37 _typing_extra.NoneType,
38 FunctionType,
39 BuiltinFunctionType,
40 LambdaType,
41 weakref.ref,
42 CodeType,
43 # note: including ModuleType will differ from behaviour of deepcopy by not producing error.
44 # It might be not a good idea in general, but considering that this function used only internally
45 # against default values of fields, this will allow to actually have a field with module as default value
46 ModuleType,
47 NotImplemented.__class__,
48 Ellipsis.__class__,
49}
51# these are types that if empty, might be copied with simple copy() instead of deepcopy()
52BUILTIN_COLLECTIONS: set[type[Any]] = { 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
53 list,
54 set,
55 tuple,
56 frozenset,
57 dict,
58 OrderedDict,
59 defaultdict,
60 deque,
61}
64def sequence_like(v: Any) -> bool: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
65 return isinstance(v, (list, tuple, set, frozenset, GeneratorType, deque)) 1mnabcdopqrstuvefghwxyzABijklCDEF
68def lenient_isinstance(o: Any, class_or_tuple: type[Any] | tuple[type[Any], ...] | None) -> bool: # pragma: no cover 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
69 try:
70 return isinstance(o, class_or_tuple) # type: ignore[arg-type]
71 except TypeError:
72 return False
75def lenient_issubclass(cls: Any, class_or_tuple: Any) -> bool: # pragma: no cover 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
76 try: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
77 return isinstance(cls, type) and issubclass(cls, class_or_tuple) 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
78 except TypeError: 1abcdefghijkl
79 if isinstance(cls, _typing_extra.WithArgsTypes): 1abcdefghijkl
80 return False 1abcdefghijkl
81 raise # pragma: no cover
84def is_model_class(cls: Any) -> TypeGuard[type[BaseModel]]: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
85 """Returns true if cls is a _proper_ subclass of BaseModel, and provides proper type-checking,
86 unlike raw calls to lenient_issubclass.
87 """
88 from ..main import BaseModel 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
90 return lenient_issubclass(cls, BaseModel) and cls is not BaseModel 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
93def is_valid_identifier(identifier: str) -> bool: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
94 """Checks that a string is a valid identifier and not a Python keyword.
95 :param identifier: The identifier to test.
96 :return: True if the identifier is valid.
97 """
98 return identifier.isidentifier() and not keyword.iskeyword(identifier) 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
101KeyType = TypeVar('KeyType') 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
104def deep_update(mapping: dict[KeyType, Any], *updating_mappings: dict[KeyType, Any]) -> dict[KeyType, Any]: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
105 updated_mapping = mapping.copy() 1mnabcdopqrstuvefghwxyzABijklCDEF
106 for updating_mapping in updating_mappings: 1mnabcdopqrstuvefghwxyzABijklCDEF
107 for k, v in updating_mapping.items(): 1mnabcdopqrstuvefghwxyzABijklCDEF
108 if k in updated_mapping and isinstance(updated_mapping[k], dict) and isinstance(v, dict): 1mnabcdopqrstuvefghwxyzABijklCDEF
109 updated_mapping[k] = deep_update(updated_mapping[k], v) 1mnabcdopqrstuvefghwxyzABijklCDEF
110 else:
111 updated_mapping[k] = v 1mnabcdopqrstuvefghwxyzABijklCDEF
112 return updated_mapping 1mnabcdopqrstuvefghwxyzABijklCDEF
115def update_not_none(mapping: dict[Any, Any], **update: Any) -> None: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
116 mapping.update({k: v for k, v in update.items() if v is not None}) 1mnabcdopqrstuvefghwxyzABijklCDEF
119T = TypeVar('T') 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
122def unique_list( 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
123 input_list: list[T] | tuple[T, ...],
124 *,
125 name_factory: typing.Callable[[T], str] = str,
126) -> list[T]:
127 """Make a list unique while maintaining order.
128 We update the list if another one with the same name is set
129 (e.g. model validator overridden in subclass).
130 """
131 result: list[T] = [] 1mnabcdopqrstuvefghwxyzABijklCDEF
132 result_names: list[str] = [] 1mnabcdopqrstuvefghwxyzABijklCDEF
133 for v in input_list: 1mnabcdopqrstuvefghwxyzABijklCDEF
134 v_name = name_factory(v) 1mnabcdopqrstuvefghwxyzABijklCDEF
135 if v_name not in result_names: 1mnabcdopqrstuvefghwxyzABijklCDEF
136 result_names.append(v_name) 1mnabcdopqrstuvefghwxyzABijklCDEF
137 result.append(v) 1mnabcdopqrstuvefghwxyzABijklCDEF
138 else:
139 result[result_names.index(v_name)] = v 1mnabcdopqrstuvefghwxyzABijklCDEF
141 return result 1mnabcdopqrstuvefghwxyzABijklCDEF
144class ValueItems(_repr.Representation): 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
145 """Class for more convenient calculation of excluded or included fields on values."""
147 __slots__ = ('_items', '_type') 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
149 def __init__(self, value: Any, items: AbstractSetIntStr | MappingIntStrAny) -> None: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
150 items = self._coerce_items(items) 1mnabcdopqrstuvefghwxyzABijklCDEF
152 if isinstance(value, (list, tuple)): 1mnabcdopqrstuvefghwxyzABijklCDEF
153 items = self._normalize_indexes(items, len(value)) # type: ignore 1mnabcdopqrstuvefghwxyzABijklCDEF
155 self._items: MappingIntStrAny = items # type: ignore 1mnabcdopqrstuvefghwxyzABijklCDEF
157 def is_excluded(self, item: Any) -> bool: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
158 """Check if item is fully excluded.
160 :param item: key or index of a value
161 """
162 return self.is_true(self._items.get(item)) 1mnabcdopqrstuvefghwxyzABijklCDEF
164 def is_included(self, item: Any) -> bool: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
165 """Check if value is contained in self._items.
167 :param item: key or index of value
168 """
169 return item in self._items 1mnabcdopqrstuvefghwxyzABijklCDEF
171 def for_element(self, e: int | str) -> AbstractSetIntStr | MappingIntStrAny | None: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
172 """:param e: key or index of element on value
173 :return: raw values for element if self._items is dict and contain needed element
174 """
175 item = self._items.get(e) # type: ignore 1mnabcdopqrstuvefghwxyzABijklCDEF
176 return item if not self.is_true(item) else None 1mnabcdopqrstuvefghwxyzABijklCDEF
178 def _normalize_indexes(self, items: MappingIntStrAny, v_length: int) -> dict[int | str, Any]: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
179 """:param items: dict or set of indexes which will be normalized
180 :param v_length: length of sequence indexes of which will be
182 >>> self._normalize_indexes({0: True, -2: True, -1: True}, 4)
183 {0: True, 2: True, 3: True}
184 >>> self._normalize_indexes({'__all__': True}, 4)
185 {0: True, 1: True, 2: True, 3: True}
186 """
187 normalized_items: dict[int | str, Any] = {} 1mnabcdopqrstuvefghwxyzABijklCDEF
188 all_items = None 1mnabcdopqrstuvefghwxyzABijklCDEF
189 for i, v in items.items(): 1mnabcdopqrstuvefghwxyzABijklCDEF
190 if not (isinstance(v, typing.Mapping) or isinstance(v, typing.AbstractSet) or self.is_true(v)): 1mnabcdopqrstuvefghwxyzABijklCDEF
191 raise TypeError(f'Unexpected type of exclude value for index "{i}" {v.__class__}') 1mnabcdopqrstuvefghwxyzABijklCDEF
192 if i == '__all__': 1mnabcdopqrstuvefghwxyzABijklCDEF
193 all_items = self._coerce_value(v) 1mnabcdopqrstuvefghwxyzABijklCDEF
194 continue 1mnabcdopqrstuvefghwxyzABijklCDEF
195 if not isinstance(i, int): 1mnabcdopqrstuvefghwxyzABijklCDEF
196 raise TypeError( 1mnabcdopqrstuvefghwxyzABijklCDEF
197 'Excluding fields from a sequence of sub-models or dicts must be performed index-wise: '
198 'expected integer keys or keyword "__all__"'
199 )
200 normalized_i = v_length + i if i < 0 else i 1mnabcdopqrstuvefghwxyzABijklCDEF
201 normalized_items[normalized_i] = self.merge(v, normalized_items.get(normalized_i)) 1mnabcdopqrstuvefghwxyzABijklCDEF
203 if not all_items: 1mnabcdopqrstuvefghwxyzABijklCDEF
204 return normalized_items 1mnabcdopqrstuvefghwxyzABijklCDEF
205 if self.is_true(all_items): 1mnabcdopqrstuvefghwxyzABijklCDEF
206 for i in range(v_length): 1mnabcdopqrstuvefghwxyzABijklCDEF
207 normalized_items.setdefault(i, ...) 1mnabcdopqrstuvefghwxyzABijklCDEF
208 return normalized_items 1mnabcdopqrstuvefghwxyzABijklCDEF
209 for i in range(v_length): 1mnabcdopqrstuvefghwxyzABijklCDEF
210 normalized_item = normalized_items.setdefault(i, {}) 1mnabcdopqrstuvefghwxyzABijklCDEF
211 if not self.is_true(normalized_item): 211 ↛ 209line 211 didn't jump to line 209, because the condition on line 211 was always true1mnabcdopqrstuvefghwxyzABijklCDEF
212 normalized_items[i] = self.merge(all_items, normalized_item) 1mnabcdopqrstuvefghwxyzABijklCDEF
213 return normalized_items 1mnabcdopqrstuvefghwxyzABijklCDEF
215 @classmethod 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
216 def merge(cls, base: Any, override: Any, intersect: bool = False) -> Any: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
217 """Merge a `base` item with an `override` item.
219 Both `base` and `override` are converted to dictionaries if possible.
220 Sets are converted to dictionaries with the sets entries as keys and
221 Ellipsis as values.
223 Each key-value pair existing in `base` is merged with `override`,
224 while the rest of the key-value pairs are updated recursively with this function.
226 Merging takes place based on the "union" of keys if `intersect` is
227 set to `False` (default) and on the intersection of keys if
228 `intersect` is set to `True`.
229 """
230 override = cls._coerce_value(override) 1mnabcdopqrstuvefghwxyzABijklCDEF
231 base = cls._coerce_value(base) 1mnabcdopqrstuvefghwxyzABijklCDEF
232 if override is None: 1mnabcdopqrstuvefghwxyzABijklCDEF
233 return base 1mnabcdopqrstuvefghwxyzABijklCDEF
234 if cls.is_true(base) or base is None: 1mnabcdopqrstuvefghwxyzABijklCDEF
235 return override 1mnabcdopqrstuvefghwxyzABijklCDEF
236 if cls.is_true(override): 1mnabcdopqrstuvefghwxyzABijklCDEF
237 return base if intersect else override 1mnabcdopqrstuvefghwxyzABijklCDEF
239 # intersection or union of keys while preserving ordering:
240 if intersect: 1mnabcdopqrstuvefghwxyzABijklCDEF
241 merge_keys = [k for k in base if k in override] + [k for k in override if k in base] 1mnabcdopqrstuvefghwxyzABijklCDEF
242 else:
243 merge_keys = list(base) + [k for k in override if k not in base] 1mnabcdopqrstuvefghwxyzABijklCDEF
245 merged: dict[int | str, Any] = {} 1mnabcdopqrstuvefghwxyzABijklCDEF
246 for k in merge_keys: 1mnabcdopqrstuvefghwxyzABijklCDEF
247 merged_item = cls.merge(base.get(k), override.get(k), intersect=intersect) 1mnabcdopqrstuvefghwxyzABijklCDEF
248 if merged_item is not None: 1mnabcdopqrstuvefghwxyzABijklCDEF
249 merged[k] = merged_item 1mnabcdopqrstuvefghwxyzABijklCDEF
251 return merged 1mnabcdopqrstuvefghwxyzABijklCDEF
253 @staticmethod 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
254 def _coerce_items(items: AbstractSetIntStr | MappingIntStrAny) -> MappingIntStrAny: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
255 if isinstance(items, typing.Mapping): 1mnabcdopqrstuvefghwxyzABijklCDEF
256 pass 1mnabcdopqrstuvefghwxyzABijklCDEF
257 elif isinstance(items, typing.AbstractSet): 1mnabcdopqrstuvefghwxyzABijklCDEF
258 items = dict.fromkeys(items, ...) # type: ignore 1mnabcdopqrstuvefghwxyzABijklCDEF
259 else:
260 class_name = getattr(items, '__class__', '???') 1mnabcdopqrstuvefghwxyzABijklCDEF
261 raise TypeError(f'Unexpected type of exclude value {class_name}') 1mnabcdopqrstuvefghwxyzABijklCDEF
262 return items # type: ignore 1mnabcdopqrstuvefghwxyzABijklCDEF
264 @classmethod 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
265 def _coerce_value(cls, value: Any) -> Any: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
266 if value is None or cls.is_true(value): 1mnabcdopqrstuvefghwxyzABijklCDEF
267 return value 1mnabcdopqrstuvefghwxyzABijklCDEF
268 return cls._coerce_items(value) 1mnabcdopqrstuvefghwxyzABijklCDEF
270 @staticmethod 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
271 def is_true(v: Any) -> bool: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
272 return v is True or v is ... 1mnabcdopqrstuvefghwxyzABijklCDEF
274 def __repr_args__(self) -> _repr.ReprArgs: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
275 return [(None, self._items)] 1mnabcdopqrstuvefghwxyzABijklCDEF
278if typing.TYPE_CHECKING: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
280 def ClassAttribute(name: str, value: T) -> T: ...
282else:
284 class ClassAttribute: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
285 """Hide class attribute from its instances."""
287 __slots__ = 'name', 'value' 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
289 def __init__(self, name: str, value: Any) -> None: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
290 self.name = name 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
291 self.value = value 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
293 def __get__(self, instance: Any, owner: type[Any]) -> None: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
294 if instance is None: 1mnabcdopqrstuvefghwxyzABijklCDEF
295 return self.value 1mnabcdopqrstuvefghwxyzABijklCDEF
296 raise AttributeError(f'{self.name!r} attribute of {owner.__name__!r} is class-only') 1mnabcdopqrstuvefghwxyzABijklCDEF
299Obj = TypeVar('Obj') 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
302def smart_deepcopy(obj: Obj) -> Obj: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
303 """Return type as is for immutable built-in types
304 Use obj.copy() for built-in empty collections
305 Use copy.deepcopy() for non-empty collections and unknown objects.
306 """
307 obj_type = obj.__class__ 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
308 if obj_type in IMMUTABLE_NON_COLLECTIONS_TYPES: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
309 return obj # fastest case: obj is immutable and not collection therefore will not be copied anyway 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
310 try: 1mnabcdopqrstuvefghwxyzABijklCDEF
311 if not obj and obj_type in BUILTIN_COLLECTIONS: 1mnabcdopqrstuvefghwxyzABijklCDEF
312 # faster way for empty collections, no need to copy its members
313 return obj if obj_type is tuple else obj.copy() # tuple doesn't have copy method # type: ignore 1mnabcdopqrstuvefghwxyzABijklCDEF
314 except (TypeError, ValueError, RuntimeError): 1mnabcdopqrstuvefghwxyzABijklCDEF
315 # do we really dare to catch ALL errors? Seems a bit risky
316 pass 1mnabcdopqrstuvefghwxyzABijklCDEF
318 return deepcopy(obj) # slowest way when we actually might need a deepcopy 1mnabcdopqrstuvefghwxyzABijklCDEF
321_SENTINEL = object() 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
324def all_identical(left: typing.Iterable[Any], right: typing.Iterable[Any]) -> bool: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
325 """Check that the items of `left` are the same objects as those in `right`.
327 >>> a, b = object(), object()
328 >>> all_identical([a, b, a], [a, b, a])
329 True
330 >>> all_identical([a, b, [a]], [a, b, [a]]) # new list object, while "equal" is not "identical"
331 False
332 """
333 for left_item, right_item in zip_longest(left, right, fillvalue=_SENTINEL): 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
334 if left_item is not right_item: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
335 return False 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
336 return True 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
339@dataclasses.dataclass(frozen=True) 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
340class SafeGetItemProxy: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
341 """Wrapper redirecting `__getitem__` to `get` with a sentinel value as default
343 This makes is safe to use in `operator.itemgetter` when some keys may be missing
344 """
346 # Define __slots__manually for performances
347 # @dataclasses.dataclass() only support slots=True in python>=3.10
348 __slots__ = ('wrapped',) 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
350 wrapped: Mapping[str, Any] 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
352 def __getitem__(self, key: str, /) -> Any: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
353 return self.wrapped.get(key, _SENTINEL) 1mnabcdopqrstuvefghwxyzABijklCDEF
355 # required to pass the object to operator.itemgetter() instances due to a quirk of typeshed
356 # https://github.com/python/mypy/issues/13713
357 # https://github.com/python/typeshed/pull/8785
358 # Since this is typing-only, hide it in a typing.TYPE_CHECKING block
359 if typing.TYPE_CHECKING: 1mnabcdopqrstuvefghwxyzGHIJKLMNOABijklCDEF
361 def __contains__(self, key: str, /) -> bool:
362 return self.wrapped.__contains__(key)