1# Licensed under the LGPL: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html
2# For details: https://github.com/pylint-dev/astroid/blob/main/LICENSE
3# Copyright (c) https://github.com/pylint-dev/astroid/blob/main/CONTRIBUTORS.txt
4
5"""
6Astroid hook for the dataclasses library.
7
8Support built-in dataclasses, pydantic.dataclasses, and marshmallow_dataclass-annotated
9dataclasses. References:
10- https://docs.python.org/3/library/dataclasses.html
11- https://pydantic-docs.helpmanual.io/usage/dataclasses/
12- https://lovasoa.github.io/marshmallow_dataclass/
13"""
14
15from __future__ import annotations
16
17from collections.abc import Iterator
18from typing import Literal
19
20from astroid import bases, context, nodes
21from astroid.brain.helpers import is_class_var
22from astroid.builder import parse
23from astroid.const import PY313_PLUS
24from astroid.exceptions import (
25 AstroidSyntaxError,
26 InferenceError,
27 MroError,
28 UseInferenceDefault,
29)
30from astroid.inference_tip import inference_tip
31from astroid.manager import AstroidManager
32from astroid.protocols import infer_instance_from_annotation
33from astroid.typing import InferenceResult
34from astroid.util import Uninferable, UninferableBase, safe_infer
35
36_FieldDefaultReturn = (
37 None
38 | tuple[Literal["default"], nodes.NodeNG]
39 | tuple[Literal["default_factory"], nodes.Call]
40)
41
42DATACLASSES_DECORATORS = frozenset(("dataclass",))
43FIELD_NAME = "field"
44DATACLASS_MODULES = frozenset(
45 ("dataclasses", "marshmallow_dataclass", "pydantic.dataclasses")
46)
47DEFAULT_FACTORY = "_HAS_DEFAULT_FACTORY" # based on typing.py
48
49
50def is_decorated_with_dataclass(
51 node: nodes.ClassDef, decorator_names: frozenset[str] = DATACLASSES_DECORATORS
52) -> bool:
53 """Return True if a decorated node has a `dataclass` decorator applied."""
54 if not (isinstance(node, nodes.ClassDef) and node.decorators):
55 return False
56
57 return any(
58 _looks_like_dataclass_decorator(decorator_attribute, decorator_names)
59 for decorator_attribute in node.decorators.nodes
60 )
61
62
63def dataclass_transform(node: nodes.ClassDef) -> nodes.ClassDef | None:
64 """Rewrite a dataclass to be easily understood by pylint."""
65 node.is_dataclass = True
66
67 for assign_node in _get_dataclass_attributes(node):
68 name = assign_node.target.name
69
70 rhs_node = nodes.Unknown(
71 lineno=assign_node.lineno,
72 col_offset=assign_node.col_offset,
73 parent=assign_node,
74 )
75 rhs_node = AstroidManager().visit_transforms(rhs_node)
76 node.instance_attrs[name] = [rhs_node]
77
78 if not _check_generate_dataclass_init(node):
79 return None
80
81 kw_only_decorated = False
82 if node.decorators.nodes:
83 for decorator in node.decorators.nodes:
84 if not isinstance(decorator, nodes.Call):
85 kw_only_decorated = False
86 break
87 for keyword in decorator.keywords:
88 if keyword.arg == "kw_only":
89 kw_only_decorated = keyword.value.bool_value() is True
90
91 init_str = _generate_dataclass_init(
92 node,
93 list(_get_dataclass_attributes(node, init=True)),
94 kw_only_decorated,
95 )
96
97 try:
98 init_node = parse(init_str)["__init__"]
99 except AstroidSyntaxError:
100 pass
101 else:
102 init_node.parent = node
103 init_node.lineno, init_node.col_offset = None, None
104 node.locals["__init__"] = [init_node]
105
106 root = node.root()
107 if DEFAULT_FACTORY in init_str and DEFAULT_FACTORY not in root.locals:
108 new_assign = parse(f"{DEFAULT_FACTORY} = object()").body[0]
109 new_assign.parent = root
110 root.locals[DEFAULT_FACTORY] = [new_assign.targets[0]]
111 return node
112
113
114def _get_dataclass_attributes(
115 node: nodes.ClassDef, init: bool = False
116) -> Iterator[nodes.AnnAssign]:
117 """Yield the AnnAssign nodes of dataclass attributes for the node.
118
119 If init is True, also include InitVars.
120 """
121 for assign_node in node.body:
122 if not (
123 isinstance(assign_node, nodes.AnnAssign)
124 and isinstance(assign_node.target, nodes.AssignName)
125 ):
126 continue
127
128 # Annotation is never None
129 if is_class_var(assign_node.annotation): # type: ignore[arg-type]
130 continue
131
132 if _is_keyword_only_sentinel(assign_node.annotation):
133 continue
134
135 # Annotation is never None
136 if not init and _is_init_var(assign_node.annotation): # type: ignore[arg-type]
137 continue
138
139 yield assign_node
140
141
142def _check_generate_dataclass_init(node: nodes.ClassDef) -> bool:
143 """Return True if we should generate an __init__ method for node.
144
145 This is True when:
146 - node doesn't define its own __init__ method
147 - the dataclass decorator was called *without* the keyword argument init=False
148 """
149 if "__init__" in node.locals:
150 return False
151
152 found = None
153
154 for decorator_attribute in node.decorators.nodes:
155 if not isinstance(decorator_attribute, nodes.Call):
156 continue
157
158 if _looks_like_dataclass_decorator(decorator_attribute):
159 found = decorator_attribute
160
161 if found is None:
162 return True
163
164 # Check for keyword arguments of the form init=False
165 return not any(
166 keyword.arg == "init"
167 and keyword.value.bool_value() is False # type: ignore[union-attr] # value is never None
168 for keyword in found.keywords
169 )
170
171
172def _find_arguments_from_base_classes(
173 node: nodes.ClassDef,
174) -> tuple[
175 dict[str, tuple[str | None, str | None]], dict[str, tuple[str | None, str | None]]
176]:
177 """Iterate through all bases and get their typing and defaults."""
178 pos_only_store: dict[str, tuple[str | None, str | None]] = {}
179 kw_only_store: dict[str, tuple[str | None, str | None]] = {}
180 # See TODO down below
181 # all_have_defaults = True
182
183 try:
184 mro = node.mro()
185 except MroError:
186 return pos_only_store, kw_only_store
187
188 for base in reversed(mro):
189 if not base.is_dataclass:
190 continue
191 try:
192 base_init = base.locals["__init__"][0]
193 except KeyError:
194 continue
195
196 # A base can bind "__init__" to something that is not a function, for
197 # example by annotating it as a field: "__init__: int". There are no
198 # arguments to inherit from such a base.
199 if not isinstance(base_init, nodes.FunctionDef):
200 continue
201
202 pos_only, kw_only = base_init.args._get_arguments_data()
203 for posarg, data in pos_only.items():
204 # if data[1] is None:
205 # if all_have_defaults and pos_only_store:
206 # # TODO: This should return an Uninferable as this would raise
207 # # a TypeError at runtime. However, transforms can't return
208 # # Uninferables currently.
209 # pass
210 # all_have_defaults = False
211 pos_only_store[posarg] = data
212
213 for kwarg, data in kw_only.items():
214 kw_only_store[kwarg] = data
215 return pos_only_store, kw_only_store
216
217
218def _parse_arguments_into_strings(
219 pos_only_store: dict[str, tuple[str | None, str | None]],
220 kw_only_store: dict[str, tuple[str | None, str | None]],
221) -> tuple[str, str]:
222 """Parse positional and keyword arguments into strings for an __init__ method."""
223 pos_only, kw_only = "", ""
224 for pos_arg, data in pos_only_store.items():
225 pos_only += pos_arg
226 if data[0]:
227 pos_only += ": " + data[0]
228 if data[1]:
229 pos_only += " = " + data[1]
230 pos_only += ", "
231 for kw_arg, data in kw_only_store.items():
232 kw_only += kw_arg
233 if data[0]:
234 kw_only += ": " + data[0]
235 if data[1]:
236 kw_only += " = " + data[1]
237 kw_only += ", "
238
239 return pos_only, kw_only
240
241
242def _get_previous_field_default(node: nodes.ClassDef, name: str) -> nodes.NodeNG | None:
243 """Get the default value of a previously defined field."""
244 try:
245 mro = node.mro()
246 except MroError:
247 return None
248
249 for base in reversed(mro):
250 if not base.is_dataclass:
251 continue
252 if name in base.locals:
253 for assign in base.locals[name]:
254 if (
255 isinstance(assign.parent, nodes.AnnAssign)
256 and assign.parent.value
257 and isinstance(assign.parent.value, nodes.Call)
258 and _looks_like_dataclass_field_call(assign.parent.value)
259 ):
260 default = _get_field_default(assign.parent.value)
261 if default:
262 return default[1]
263 return None
264
265
266def _generate_dataclass_init(
267 node: nodes.ClassDef, assigns: list[nodes.AnnAssign], kw_only_decorated: bool
268) -> str:
269 """Return an init method for a dataclass given the targets."""
270 # pylint: disable = too-many-locals, too-many-branches, too-many-statements
271
272 params: list[str] = []
273 kw_only_params: list[str] = []
274 assignments: list[str] = []
275
276 prev_pos_only_store, prev_kw_only_store = _find_arguments_from_base_classes(node)
277
278 for assign in assigns:
279 name, annotation, value = assign.target.name, assign.annotation, assign.value
280
281 # Check whether this assign is overriden by a property assignment
282 property_node: nodes.FunctionDef | None = None
283 for additional_assign in node.locals[name]:
284 if not isinstance(additional_assign, nodes.FunctionDef):
285 continue
286 if not additional_assign.decorators:
287 continue
288 if "builtins.property" in additional_assign.decoratornames():
289 property_node = additional_assign
290 break
291
292 is_field = isinstance(value, nodes.Call) and _looks_like_dataclass_field_call(
293 value, check_scope=False
294 )
295
296 if is_field:
297 # Skip any fields that have `init=False`
298 if any(
299 keyword.arg == "init" and (keyword.value.bool_value() is False)
300 for keyword in value.keywords # type: ignore[union-attr] # value is never None
301 ):
302 # Also remove the name from the previous arguments to be inserted later
303 prev_pos_only_store.pop(name, None)
304 prev_kw_only_store.pop(name, None)
305 continue
306
307 if _is_init_var(annotation): # type: ignore[arg-type] # annotation is never None
308 init_var = True
309 if isinstance(annotation, nodes.Subscript):
310 annotation = annotation.slice
311 else:
312 # Cannot determine type annotation for parameter from InitVar
313 annotation = None
314 assignment_str = ""
315 else:
316 init_var = False
317 assignment_str = f"self.{name} = {name}"
318
319 ann_str, default_str = None, None
320 if annotation is not None:
321 ann_str = annotation.as_string()
322
323 if value:
324 if is_field:
325 result = _get_field_default(value) # type: ignore[arg-type]
326 if result:
327 default_type, default_node = result
328 if default_type == "default":
329 default_str = default_node.as_string()
330 elif default_type == "default_factory":
331 default_str = DEFAULT_FACTORY
332 assignment_str = (
333 f"self.{name} = {default_node.as_string()} "
334 f"if {name} is {DEFAULT_FACTORY} else {name}"
335 )
336 else:
337 default_str = value.as_string()
338 elif property_node:
339 # We set the result of the property call as default
340 # This hides the fact that this would normally be a 'property object'
341 # But we can't represent those as string
342 try:
343 # Call str to make sure also Uninferable gets stringified
344 default_str = str(
345 next(property_node.infer_call_result(None)).as_string()
346 )
347 except (InferenceError, StopIteration):
348 pass
349 else:
350 # Even with `init=False` the default value still can be propogated to
351 # later assignments. Creating weird signatures like:
352 # (self, a: str = 1) -> None
353 previous_default = _get_previous_field_default(node, name)
354 if previous_default:
355 default_str = previous_default.as_string()
356
357 # Construct the param string to add to the init if necessary
358 param_str = name
359 if ann_str is not None:
360 param_str += f": {ann_str}"
361 if default_str is not None:
362 param_str += f" = {default_str}"
363
364 # If the field is a kw_only field, we need to add it to the kw_only_params
365 # This overwrites whether or not the class is kw_only decorated
366 if is_field:
367 kw_only = [k for k in value.keywords if k.arg == "kw_only"] # type: ignore[union-attr]
368 if kw_only:
369 if kw_only[0].value.bool_value() is True:
370 kw_only_params.append(param_str)
371 else:
372 params.append(param_str)
373 continue
374 # If kw_only decorated, we need to add all parameters to the kw_only_params
375 if kw_only_decorated:
376 if name in prev_kw_only_store:
377 prev_kw_only_store[name] = (ann_str, default_str)
378 else:
379 kw_only_params.append(param_str)
380 else:
381 # If the name was previously seen, overwrite that data
382 # pylint: disable-next=else-if-used
383 if name in prev_pos_only_store:
384 prev_pos_only_store[name] = (ann_str, default_str)
385 elif name in prev_kw_only_store:
386 params = [name, *params]
387 prev_kw_only_store.pop(name)
388 else:
389 params.append(param_str)
390
391 if not init_var:
392 assignments.append(assignment_str)
393
394 prev_pos_only, prev_kw_only = _parse_arguments_into_strings(
395 prev_pos_only_store, prev_kw_only_store
396 )
397
398 # Construct the new init method parameter string
399 # First we do the positional only parameters, making sure to add the
400 # self parameter and the comma to allow adding keyword only parameters
401 params_string = "" if "self" in prev_pos_only else "self, "
402 params_string += prev_pos_only + ", ".join(params)
403 if not params_string.endswith(", "):
404 params_string += ", "
405
406 # Then we add the keyword only parameters
407 if prev_kw_only or kw_only_params:
408 params_string += "*, "
409 params_string += f"{prev_kw_only}{', '.join(kw_only_params)}"
410
411 assignments_string = "\n ".join(assignments) if assignments else "pass"
412 return f"def __init__({params_string}) -> None:\n {assignments_string}"
413
414
415def infer_dataclass_attribute(
416 node: nodes.Unknown, ctx: context.InferenceContext | None = None
417) -> Iterator[InferenceResult]:
418 """Inference tip for an Unknown node that was dynamically generated to
419 represent a dataclass attribute.
420
421 In the case that a default value is provided, that is inferred first.
422 Then, an Instance of the annotated class is yielded.
423 """
424 assign = node.parent
425 if not isinstance(assign, nodes.AnnAssign):
426 yield Uninferable
427 return
428
429 annotation, value = assign.annotation, assign.value
430 if value is not None:
431 yield from value.infer(context=ctx)
432 if annotation is not None:
433 yield from infer_instance_from_annotation(annotation, ctx=ctx)
434 else:
435 yield Uninferable
436
437
438def infer_dataclass_field_call(
439 node: nodes.Call, ctx: context.InferenceContext | None = None
440) -> Iterator[InferenceResult]:
441 """Inference tip for dataclass field calls."""
442 if not isinstance(node.parent, (nodes.AnnAssign, nodes.Assign)):
443 raise UseInferenceDefault
444 result = _get_field_default(node)
445 if not result:
446 yield Uninferable
447 else:
448 default_type, default = result
449 if default_type == "default":
450 yield from default.infer(context=ctx)
451 else:
452 new_call = parse(default.as_string()).body[0].value
453 new_call.parent = node.parent
454 yield from new_call.infer(context=ctx)
455
456
457def _looks_like_dataclass_decorator(
458 node: nodes.NodeNG, decorator_names: frozenset[str] = DATACLASSES_DECORATORS
459) -> bool:
460 """Return True if node looks like a dataclass decorator.
461
462 Uses inference to lookup the value of the node, and if that fails,
463 matches against specific names.
464 """
465 if isinstance(node, nodes.Call): # decorator with arguments
466 node = node.func
467 try:
468 inferred = next(node.infer())
469 except (InferenceError, StopIteration):
470 inferred = Uninferable
471
472 if isinstance(inferred, UninferableBase):
473 if isinstance(node, nodes.Name):
474 return node.name in decorator_names
475 if isinstance(node, nodes.Attribute):
476 return node.attrname in decorator_names
477
478 return False
479
480 return (
481 isinstance(inferred, nodes.FunctionDef)
482 and inferred.name in decorator_names
483 and inferred.root().name in DATACLASS_MODULES
484 )
485
486
487def _looks_like_dataclass_attribute(node: nodes.Unknown) -> bool:
488 """Return True if node was dynamically generated as the child of an AnnAssign
489 statement.
490 """
491 parent = node.parent
492 if not parent:
493 return False
494
495 scope = parent.scope()
496 return (
497 isinstance(parent, nodes.AnnAssign)
498 and isinstance(scope, nodes.ClassDef)
499 and is_decorated_with_dataclass(scope)
500 )
501
502
503def _looks_like_dataclass_field_call(
504 node: nodes.Call, check_scope: bool = True
505) -> bool:
506 """Return True if node is calling dataclasses field or Field
507 from an AnnAssign statement directly in the body of a ClassDef.
508
509 If check_scope is False, skips checking the statement and body.
510 """
511 if check_scope:
512 stmt = node.statement()
513 scope = stmt.scope()
514 if not (
515 isinstance(stmt, nodes.AnnAssign)
516 and stmt.value is not None
517 and isinstance(scope, nodes.ClassDef)
518 and is_decorated_with_dataclass(scope)
519 ):
520 return False
521
522 try:
523 inferred = next(node.func.infer())
524 except (InferenceError, StopIteration):
525 return False
526
527 if not isinstance(inferred, nodes.FunctionDef):
528 return False
529
530 return inferred.name == FIELD_NAME and inferred.root().name in DATACLASS_MODULES
531
532
533def _looks_like_dataclasses(node: nodes.Module) -> bool:
534 return node.qname() == "dataclasses"
535
536
537def _looks_like_dataclasses_replace(node: nodes.Call) -> bool:
538 """Return True if node calls dataclasses.replace.
539
540 Matches both ``dataclasses.replace(...)`` and the bare-name form
541 ``from dataclasses import replace; replace(...)``.
542 """
543 func: nodes.NodeNG = node.func
544 if isinstance(func, nodes.Attribute) and func.attrname == "replace":
545 target = safe_infer(func.expr)
546 if isinstance(target, nodes.Module):
547 return _looks_like_dataclasses(target)
548 elif isinstance(func, nodes.Name) and func.name == "replace":
549 target = safe_infer(func)
550 if isinstance(target, nodes.FunctionDef):
551 return target.root().name == "dataclasses"
552 return False
553
554
555def infer_dataclasses_replace(
556 node: nodes.Call, ctx: context.InferenceContext | None = None
557) -> Iterator[InferenceResult]:
558 """Infer ``dataclasses.replace(obj, ...)`` as an instance of obj's type.
559
560 Bypasses the stdlib body of ``replace()`` / ``_replace()``, which trips
561 over subscripted generic bases in the metaclass-resolution chain.
562 """
563 if not node.args:
564 raise UseInferenceDefault
565 inferred_obj = safe_infer(node.args[0], context=ctx)
566 if isinstance(inferred_obj, UninferableBase) or inferred_obj is None:
567 yield Uninferable
568 return
569 if isinstance(inferred_obj, bases.Instance):
570 yield inferred_obj._proxied.instantiate_class()
571 return
572 if isinstance(inferred_obj, nodes.ClassDef):
573 # replace() must be called on a dataclass instance; passing the class
574 # itself raises TypeError at runtime, so there is nothing to infer.
575 yield Uninferable
576 return
577 raise UseInferenceDefault
578
579
580def _resolve_private_replace_to_public(node: nodes.Module) -> None:
581 """In python/cpython@6f3c138, a _replace() method was extracted from
582 replace(), and this indirection made replace() uninferable."""
583 if "_replace" in node.locals:
584 node.locals["replace"] = node.locals["_replace"]
585
586
587def _get_field_default(field_call: nodes.Call) -> _FieldDefaultReturn:
588 """Return a the default value of a field call, and the corresponding keyword
589 argument name.
590
591 field(default=...) results in the ... node
592 field(default_factory=...) results in a Call node with func ... and no arguments
593
594 If neither or both arguments are present, return ("", None) instead,
595 indicating that there is not a valid default value.
596 """
597 default, default_factory = None, None
598 for keyword in field_call.keywords:
599 if keyword.arg == "default":
600 default = keyword.value
601 elif keyword.arg == "default_factory":
602 default_factory = keyword.value
603
604 if default is not None and default_factory is None:
605 return "default", default
606
607 if default is None and default_factory is not None:
608 new_call = nodes.Call(
609 lineno=field_call.lineno,
610 col_offset=field_call.col_offset,
611 parent=field_call.parent,
612 end_lineno=field_call.end_lineno,
613 end_col_offset=field_call.end_col_offset,
614 )
615 new_call.postinit(func=default_factory, args=[], keywords=[])
616 return "default_factory", new_call
617
618 return None
619
620
621def _is_keyword_only_sentinel(node: nodes.NodeNG) -> bool:
622 """Return True if node is the KW_ONLY sentinel."""
623 inferred = safe_infer(node)
624 if not isinstance(inferred, bases.Instance):
625 return False
626 if inferred.qname() == "dataclasses._KW_ONLY_TYPE":
627 return True
628 if inferred.qname() != "builtins.sentinel":
629 return False
630 if isinstance(node, nodes.Name):
631 _, assignments = node.lookup(node.name)
632 return any(
633 isinstance(assignment, nodes.ImportFrom)
634 and assignment.modname == "dataclasses"
635 and any(imported == "KW_ONLY" for imported, _ in assignment.names)
636 for assignment in assignments
637 )
638 if isinstance(node, nodes.Attribute) and node.attrname == "KW_ONLY":
639 inferred_expr = safe_infer(node.expr)
640 return (
641 isinstance(inferred_expr, nodes.Module)
642 and inferred_expr.qname() == "dataclasses"
643 )
644 return False
645
646
647def _is_init_var(node: nodes.NodeNG) -> bool:
648 """Return True if node is an InitVar, with or without subscripting."""
649 try:
650 inferred = next(node.infer())
651 except (InferenceError, StopIteration):
652 return False
653
654 return getattr(inferred, "name", "") == "InitVar"
655
656
657def register(manager: AstroidManager) -> None:
658 if PY313_PLUS:
659 manager.register_transform(
660 nodes.Module,
661 _resolve_private_replace_to_public,
662 _looks_like_dataclasses,
663 )
664
665 manager.register_transform(
666 nodes.ClassDef, dataclass_transform, is_decorated_with_dataclass
667 )
668
669 manager.register_transform(
670 nodes.Call,
671 inference_tip(infer_dataclass_field_call, raise_on_overwrite=True),
672 _looks_like_dataclass_field_call,
673 )
674
675 manager.register_transform(
676 nodes.Unknown,
677 inference_tip(infer_dataclass_attribute, raise_on_overwrite=True),
678 _looks_like_dataclass_attribute,
679 )
680
681 manager.register_transform(
682 nodes.Call,
683 inference_tip(infer_dataclasses_replace, raise_on_overwrite=True),
684 _looks_like_dataclasses_replace,
685 )