erdify 1.2.0__tar.gz → 1.3.0__tar.gz

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.
Files changed (27) hide show
  1. {erdify-1.2.0 → erdify-1.3.0}/PKG-INFO +1 -1
  2. {erdify-1.2.0 → erdify-1.3.0}/pyproject.toml +1 -1
  3. {erdify-1.2.0 → erdify-1.3.0}/pyproject.toml.orig +1 -1
  4. {erdify-1.2.0 → erdify-1.3.0}/src/erdify/cli.py +1 -1
  5. {erdify-1.2.0 → erdify-1.3.0}/src/erdify/generator.py +109 -33
  6. erdify-1.3.0/src/erdify/parser/__init__.py +26 -0
  7. erdify-1.3.0/src/erdify/parser/annotations.py +270 -0
  8. erdify-1.3.0/src/erdify/parser/common.py +36 -0
  9. erdify-1.3.0/src/erdify/parser/core.py +454 -0
  10. erdify-1.3.0/src/erdify/parser/dialects/__init__.py +22 -0
  11. erdify-1.3.0/src/erdify/parser/dialects/annotated.py +245 -0
  12. erdify-1.3.0/src/erdify/parser/dialects/base.py +362 -0
  13. erdify-1.3.0/src/erdify/parser/dialects/django.py +776 -0
  14. erdify-1.3.0/src/erdify/parser/dialects/keyless.py +201 -0
  15. erdify-1.3.0/src/erdify/parser/dialects/sqlalchemy.py +147 -0
  16. erdify-1.3.0/src/erdify/parser/discovery.py +180 -0
  17. erdify-1.3.0/src/erdify/parser/inheritance.py +177 -0
  18. {erdify-1.2.0 → erdify-1.3.0}/src/erdify/sql_parser.py +2 -1
  19. erdify-1.2.0/src/erdify/parser.py +0 -2025
  20. {erdify-1.2.0 → erdify-1.3.0}/LICENSE +0 -0
  21. {erdify-1.2.0 → erdify-1.3.0}/README.md +0 -0
  22. {erdify-1.2.0 → erdify-1.3.0}/src/erdify/__init__.py +0 -0
  23. {erdify-1.2.0 → erdify-1.3.0}/src/erdify/__main__.py +0 -0
  24. {erdify-1.2.0 → erdify-1.3.0}/src/erdify/config.py +0 -0
  25. {erdify-1.2.0 → erdify-1.3.0}/src/erdify/inject.py +0 -0
  26. {erdify-1.2.0 → erdify-1.3.0}/src/erdify/py.typed +0 -0
  27. {erdify-1.2.0 → erdify-1.3.0}/src/erdify/pyproject.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: erdify
3
- Version: 1.2.0
3
+ Version: 1.3.0
4
4
  Summary: A zero-dependency ERD generator for your Python models — pure AST, no database required.
5
5
  Keywords: sqlmodel,sqlalchemy,django,pydantic,dataclass,erd,plantuml,diagram,database,erdify,sql,ddl
6
6
  Author: devsuit GmbH, Fabian Clemenz
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "erdify"
3
- version = "1.2.0"
3
+ version = "1.3.0"
4
4
  description = "A zero-dependency ERD generator for your Python models — pure AST, no database required."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "erdify"
3
- version = "1.2.0"
3
+ version = "1.3.0"
4
4
  description = "A zero-dependency ERD generator for your Python models — pure AST, no database required."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -144,7 +144,7 @@ def build_parser() -> argparse.ArgumentParser:
144
144
  parser.add_argument(
145
145
  "--no-relationships",
146
146
  action="store_true",
147
- help="Skip relationship lines in output",
147
+ help="Draw no relationship lines (edges) in any format, foreign-key edges included",
148
148
  )
149
149
  parser.add_argument(
150
150
  "--format",
@@ -23,16 +23,27 @@ class _ERGenerator:
23
23
  the relationship logic and only differ in entity/enum block formatting.
24
24
  """
25
25
 
26
+ #: The cardinality a relationship's inverse side declares: a 1:N collection
27
+ #: (``many``) is mirrored by an N:1 reference (``one``), and so on.
28
+ _INVERSE_KIND = {
29
+ "one": "many",
30
+ "many": "one",
31
+ "one_to_one": "one_to_one",
32
+ "many_to_many": "many_to_many",
33
+ }
34
+
26
35
  def __init__(
27
36
  self,
28
37
  entities: Dict[str, EntityInfo],
29
38
  enums: Dict[str, EnumInfo] | None = None,
30
39
  *,
31
40
  title: str = "Database ERD",
41
+ include_relationships: bool = True,
32
42
  ):
33
43
  self.entities = entities
34
44
  self.enums = enums or {}
35
45
  self.title = title
46
+ self.include_relationships = include_relationships
36
47
 
37
48
  def _get_used_enums(self) -> "set[str]":
38
49
  """Get set of enum names used by entity fields."""
@@ -166,31 +177,89 @@ class _ERGenerator:
166
177
 
167
178
  return lines
168
179
 
169
- def _generate_relationship_list_lines(
170
- self, entity: EntityInfo
171
- ) -> "List[Tuple[str, frozenset[str]]]":
172
- """Generate lines from an entity's declared relationships.
180
+ @staticmethod
181
+ def _snake_case(name: str) -> str:
182
+ """``OrderItem`` -> ``order_item``, ``HTTPRequest`` -> ``http_request``.
183
+
184
+ The usual attribute name for a reference to a class; an acronym stays
185
+ one word.
186
+ """
187
+ return re.sub(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])", "_", name).lower()
173
188
 
174
- Returns (line, pair) tuples where pair is the frozenset of the two
175
- connected entity names, so callers can skip already-connected pairs.
189
+ @staticmethod
190
+ def _declared_line(entity: EntityInfo, target: str, rel_type: str, attr: str) -> str:
191
+ """The edge for one declared relationship of ``entity``."""
192
+ if rel_type == "many":
193
+ return f'{entity.name} ||--o{{ {target} : "{attr}"'
194
+ if rel_type == "one_to_one":
195
+ return f'{entity.name} ||--|| {target} : "{attr}"'
196
+ if rel_type == "many_to_many":
197
+ return f'{entity.name} }}o--o{{ {target} : "{attr}"'
198
+ if attr in entity.nullable_relationships: # optional "one" (#223)
199
+ return f'{entity.name} }}o--o| {target} : "{attr}"'
200
+ return f'{entity.name} }}o--|| {target} : "{attr}"' # "one"
201
+
202
+ def _declared_relationship_lines(
203
+ self, fk_pairs: "set[frozenset[str]]", link_pairs: "set[frozenset[str]]"
204
+ ) -> List[str]:
205
+ """Edges for declared relationships between pairs no column already connects.
206
+
207
+ A pair joined by a foreign-key column (``fk_pairs``) or a link table
208
+ (``link_pairs``) already has its edge, which an ORM relationship such
209
+ as ``relationship()`` merely mirrors. A many-to-many never mirrors a
210
+ foreign-key column, so only a link table suppresses it: e.g. a Django
211
+ ``ManyToManyField`` to the parent of a multi-table child (#233).
212
+
213
+ Every declared attribute gets its own edge (#230), except the inverse
214
+ side of a bidirectional relationship (e.g. ``User.posts`` and
215
+ ``Post.user``), which describes the same edge and is collapsed into the
216
+ side declared first. The IR does not record ``back_populates``, so each
217
+ edge of the first side absorbs at most one relationship declared back
218
+ from the other side: the first one with the inverse cardinality
219
+ (``many`` for ``one`` and vice versa), preferring an attribute named
220
+ after the class it points at (``Post.user`` for ``User``), else the
221
+ first one left. A self-reference has no "other side", so there only an
222
+ N:1 / 1:N inverse (``parent`` / ``children``) is absorbed; two references
223
+ of the same cardinality (``friends`` / ``blocked``, both M:N) stay two
224
+ edges.
176
225
  """
177
- results: List[Tuple[str, frozenset[str]]] = []
178
- for target_name, rel_type, attr in entity.relationships:
179
- target = self.entities.get(target_name)
180
- if not target:
226
+ connected = fk_pairs | link_pairs
227
+ rels = [
228
+ (entity, target, rel_type, attr)
229
+ for entity in self.entities.values()
230
+ for target, rel_type, attr in entity.relationships
231
+ if target in self.entities
232
+ and frozenset((entity.name, target))
233
+ not in (link_pairs if rel_type == "many_to_many" else connected)
234
+ ]
235
+ by_direction: Dict[Tuple[str, str], List[int]] = {}
236
+ for i, (entity, target, _, _) in enumerate(rels):
237
+ by_direction.setdefault((entity.name, target), []).append(i)
238
+ first_side: Dict[frozenset[str], str] = {}
239
+ absorbed: set[int] = set()
240
+ for i, (entity, target, rel_type, _) in enumerate(rels):
241
+ if i in absorbed:
181
242
  continue
182
- if rel_type == "many":
183
- line = f'{entity.name} ||--o{{ {target.name} : "{attr}"'
184
- elif rel_type == "one_to_one":
185
- line = f'{entity.name} ||--|| {target.name} : "{attr}"'
186
- elif rel_type == "many_to_many":
187
- line = f'{entity.name} }}o--o{{ {target.name} : "{attr}"'
188
- elif attr in entity.nullable_relationships: # optional "one" (#223)
189
- line = f'{entity.name} }}o--o| {target.name} : "{attr}"'
190
- else: # "one"
191
- line = f'{entity.name} }}o--|| {target.name} : "{attr}"'
192
- results.append((line, frozenset((entity.name, target.name))))
193
- return results
243
+ if first_side.setdefault(frozenset((entity.name, target)), entity.name) != entity.name:
244
+ continue # the other side's leftovers: drawn as they are
245
+ if target == entity.name and self._INVERSE_KIND[rel_type] == rel_type:
246
+ continue # two M:N / 1:1 self-references are two relationships
247
+ inverse = [
248
+ j
249
+ for j in by_direction.get((target, entity.name), ())
250
+ if j > i and j not in absorbed
251
+ ]
252
+ exact = [j for j in inverse if rels[j][2] == self._INVERSE_KIND[rel_type]]
253
+ named = [j for j in exact if rels[j][3] == self._snake_case(entity.name)]
254
+ if exact:
255
+ absorbed.add((named or exact)[0])
256
+ elif inverse and target != entity.name:
257
+ absorbed.add(inverse[0])
258
+ return [
259
+ self._declared_line(entity, target, rel_type, attr)
260
+ for i, (entity, target, rel_type, attr) in enumerate(rels)
261
+ if i not in absorbed
262
+ ]
194
263
 
195
264
  def _relationship_lines(self) -> List[str]:
196
265
  """Resolve every relationship line, de-duplicated and ordered.
@@ -198,7 +267,11 @@ class _ERGenerator:
198
267
  Order: direct foreign-key edges, then many-to-many through link tables,
199
268
  then declared relationships for pairs not already connected (so keyless
200
269
  models get edges without duplicating SQLModel/SQLAlchemy foreign keys).
270
+ Empty when the generator was built with ``include_relationships=False``
271
+ (``--no-relationships``, #232).
201
272
  """
273
+ if not self.include_relationships:
274
+ return []
202
275
  link_table_map = self._build_link_table_map()
203
276
  lines: List[str] = []
204
277
  seen: set[str] = set()
@@ -217,20 +290,17 @@ class _ERGenerator:
217
290
  lines.append(rel)
218
291
  seen.add(rel)
219
292
 
220
- connected_pairs = self._connected_pairs()
293
+ link_pairs: set[frozenset[str]] = set()
221
294
  for table_a, table_b in link_table_map:
222
295
  entity_a = self._entity_by_table(table_a)
223
296
  entity_b = self._entity_by_table(table_b)
224
297
  if entity_a and entity_b:
225
- connected_pairs.add(frozenset((entity_a.name, entity_b.name)))
298
+ link_pairs.add(frozenset((entity_a.name, entity_b.name)))
226
299
 
227
- for entity in self.entities.values():
228
- for rel, pair in self._generate_relationship_list_lines(entity):
229
- if pair in connected_pairs or rel in seen:
230
- continue
300
+ for rel in self._declared_relationship_lines(self._connected_pairs(), link_pairs):
301
+ if rel not in seen:
231
302
  lines.append(rel)
232
303
  seen.add(rel)
233
- connected_pairs.add(pair)
234
304
 
235
305
  return lines
236
306
 
@@ -244,6 +314,8 @@ class PlantUMLGenerator(_ERGenerator):
244
314
  entities: Entity name to EntityInfo, as returned by the parsers.
245
315
  enums: Optional enum name to EnumInfo.
246
316
  title: Diagram title.
317
+ include_relationships: Draw relationship lines (``False`` omits the
318
+ whole ``' Relationships`` section).
247
319
  """
248
320
 
249
321
  def generate(self) -> str:
@@ -284,11 +356,12 @@ class PlantUMLGenerator(_ERGenerator):
284
356
  lines.extend(self._generate_entity(entity))
285
357
  lines.append("")
286
358
 
287
- lines.append("' Relationships")
288
- lines.append("")
289
- lines.extend(self._relationship_lines())
359
+ if self.include_relationships:
360
+ lines.append("' Relationships")
361
+ lines.append("")
362
+ lines.extend(self._relationship_lines())
363
+ lines.append("")
290
364
 
291
- lines.append("")
292
365
  lines.append("@enduml")
293
366
 
294
367
  return "\n".join(lines)
@@ -358,6 +431,7 @@ class MermaidGenerator(_ERGenerator):
358
431
  entities: Entity name to EntityInfo, as returned by the parsers.
359
432
  enums: Optional enum name to EnumInfo.
360
433
  title: Accepted for a uniform API; Mermaid ``erDiagram`` has no title.
434
+ include_relationships: Draw relationship lines.
361
435
  """
362
436
 
363
437
  def generate(self) -> str:
@@ -465,6 +539,7 @@ def generate_plantuml(
465
539
  entities=entities,
466
540
  enums=enums if include_enums else None,
467
541
  title=title,
542
+ include_relationships=include_relationships,
468
543
  )
469
544
  return generator.generate()
470
545
 
@@ -494,6 +569,7 @@ def generate_mermaid(
494
569
  entities=entities,
495
570
  enums=enums if include_enums else None,
496
571
  title=title,
572
+ include_relationships=include_relationships,
497
573
  )
498
574
  return generator.generate()
499
575
 
@@ -0,0 +1,26 @@
1
+ """AST-based parser for SQLModel, SQLAlchemy, Django, Pydantic and dataclass models.
2
+
3
+ Re-exports what :mod:`erdify` and the CLI use. The stable public surface is
4
+ ``erdify.__all__``; this package and its submodules are internal and may
5
+ change in any release.
6
+ """
7
+
8
+ from .core import (
9
+ ASTDatabaseParser,
10
+ ModelParseError,
11
+ ScanReport,
12
+ parse_models_directory,
13
+ scan_report,
14
+ )
15
+ from .dialects import MODEL_SOURCES
16
+ from .discovery import DEFAULT_EXCLUDE_DIRS, _match_include, _translate_glob # noqa: F401
17
+
18
+ __all__ = [
19
+ "ASTDatabaseParser",
20
+ "DEFAULT_EXCLUDE_DIRS",
21
+ "MODEL_SOURCES",
22
+ "ModelParseError",
23
+ "ScanReport",
24
+ "parse_models_directory",
25
+ "scan_report",
26
+ ]
@@ -0,0 +1,270 @@
1
+ """Pure helpers that read type annotations from the syntax tree.
2
+
3
+ Shared by every dialect: model references (#229), column types and
4
+ nullability (#236), and call / wrapper recognition.
5
+ """
6
+
7
+ import ast
8
+ from typing import Callable, List, NamedTuple, Tuple, TypeGuard
9
+
10
+ from .common import _Rel
11
+
12
+
13
+ class _AnnotationRef(NamedTuple):
14
+ """A single model an annotation refers to (see :func:`annotation_reference`)."""
15
+
16
+ target: str
17
+ many: bool
18
+ nullable: bool
19
+ #: Named through a module (``schemas.User``); only trusted in relationship().
20
+ qualified: bool = False
21
+ #: The name as written (``a.User``); tells same-named classes apart in a union.
22
+ spelled: str = ""
23
+
24
+
25
+ #: Wrappers whose first argument is the annotated type itself (metadata ignored).
26
+ TRANSPARENT_WRAPPERS = frozenset({"Mapped", "Annotated"})
27
+ #: SQLAlchemy wrappers that only annotate collections: ``WriteOnlyMapped["X"]``.
28
+ MANY_WRAPPERS = frozenset({"WriteOnlyMapped", "DynamicMapped"})
29
+ #: SQLAlchemy 2.0 annotation wrappers that mark a mapped attribute.
30
+ MAPPED_WRAPPERS = frozenset({"Mapped"}) | MANY_WRAPPERS
31
+ #: Type qualifiers: they say how a field is declared, not what it holds, so a
32
+ #: column's type and nullability are those of the qualified type.
33
+ QUALIFIERS = frozenset({"Final", "InitVar", "Required", "NotRequired", "ReadOnly"})
34
+ #: Single-argument collections of a model: a "many" reference.
35
+ MANY_CONTAINERS = frozenset(
36
+ {
37
+ "list",
38
+ "List",
39
+ "set",
40
+ "Set",
41
+ "frozenset",
42
+ "FrozenSet",
43
+ "AbstractSet",
44
+ "MutableSet",
45
+ "Sequence",
46
+ "MutableSequence",
47
+ "Collection",
48
+ "Iterable",
49
+ "deque",
50
+ "Deque",
51
+ }
52
+ )
53
+ #: Mappings whose *value* is the model (e.g. SQLAlchemy keyed-dict collections).
54
+ MANY_MAPPINGS = frozenset({"dict", "Dict", "Mapping", "MutableMapping"})
55
+
56
+
57
+ def expr_name(node: ast.expr) -> str | None:
58
+ """The last name of ``X`` or ``mod.X``; None for anything else."""
59
+ if isinstance(node, ast.Name):
60
+ return node.id
61
+ if isinstance(node, ast.Attribute):
62
+ return node.attr
63
+ return None
64
+
65
+
66
+ def is_call_to(value: ast.expr, func_name: str) -> TypeGuard[ast.Call]:
67
+ """Check whether an expression is a call to ``func_name`` (Name or attribute)."""
68
+ if not isinstance(value, ast.Call):
69
+ return False
70
+ return expr_name(value.func) == func_name
71
+
72
+
73
+ def parse_quoted(node: ast.expr) -> ast.expr | None:
74
+ """The expression inside a quoted annotation (``"User | None"``).
75
+
76
+ None when ``node`` is not a string, or the string is not an expression.
77
+ """
78
+ if not (isinstance(node, ast.Constant) and isinstance(node.value, str)):
79
+ return None
80
+ try:
81
+ return ast.parse(node.value.strip(), mode="eval").body
82
+ except (SyntaxError, ValueError): # ValueError: NUL byte on Python 3.11
83
+ return None
84
+
85
+
86
+ def subscript_parts(node: ast.Subscript) -> Tuple[str | None, List[ast.expr]]:
87
+ """``X[a, b]`` / ``mod.X[a, b]`` -> ``("X", [a, b])``."""
88
+ args = node.slice.elts if isinstance(node.slice, ast.Tuple) else [node.slice]
89
+ return expr_name(node.value), args
90
+
91
+
92
+ def is_none(node: ast.expr) -> bool:
93
+ """``None``, ``NoneType`` (``types.NoneType``) or ``type(None)``.
94
+
95
+ Also when quoted or wrapped in ``Annotated``.
96
+ """
97
+ if (
98
+ isinstance(node, ast.Subscript)
99
+ and expr_name(node.value) == "Annotated"
100
+ and isinstance(node.slice, ast.Tuple)
101
+ and node.slice.elts
102
+ ):
103
+ return is_none(node.slice.elts[0])
104
+ if isinstance(node, ast.Constant):
105
+ if node.value is None:
106
+ return True
107
+ parsed = parse_quoted(node)
108
+ return parsed is not None and is_none(parsed)
109
+ if isinstance(node, ast.Call): # type(None)
110
+ return (
111
+ expr_name(node.func) == "type"
112
+ and len(node.args) == 1
113
+ and not node.keywords
114
+ and isinstance(node.args[0], ast.Constant)
115
+ and node.args[0].value is None
116
+ )
117
+ return expr_name(node) == "NoneType"
118
+
119
+
120
+ def column_type(node: ast.expr) -> Tuple[str, bool]:
121
+ """A column's displayed type and whether its annotation admits ``None``.
122
+
123
+ Walks the syntax tree like :func:`annotation_reference` (#236): the
124
+ ``Mapped`` family, ``Annotated`` and type qualifiers such as ``Final``
125
+ (bare or qualified) are unwrapped,
126
+ and ``X | None``, ``None | X``, ``Optional[X]`` and ``Union[X, None]``
127
+ all give ``X`` and nullable. A union of several other types keeps them,
128
+ minus ``None``, in its own spelling; any member that is itself optional
129
+ makes the column nullable. ``Literal[..., None]`` is nullable too. A
130
+ quoted annotation is read like the unquoted one. Matching on the tree
131
+ means a class merely *named* ``OptionalSettings`` or ``NoneableJSON``
132
+ is not nullable.
133
+ """
134
+ if is_none(node):
135
+ return "None", True
136
+ if isinstance(node, ast.Constant) and isinstance(node.value, str):
137
+ parsed = parse_quoted(node)
138
+ return column_type(parsed) if parsed is not None else (node.value, False)
139
+ if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
140
+ return column_union(union_operands(node), " | ".join)
141
+ if isinstance(node, ast.Subscript):
142
+ name, args = subscript_parts(node)
143
+ if args and name in TRANSPARENT_WRAPPERS | MANY_WRAPPERS | QUALIFIERS:
144
+ return column_type(args[0])
145
+ if name == "Optional" and len(args) == 1:
146
+ return column_type(args[0])[0], True
147
+ if name == "Union" and args:
148
+ prefix = ast.unparse(node.value)
149
+ return column_union(args, lambda parts: f"{prefix}[{', '.join(parts)}]")
150
+ if name == "Literal":
151
+ return ast.unparse(node), literal_admits_none(args)
152
+ return ast.unparse(node), False
153
+
154
+
155
+ def literal_admits_none(args: List[ast.expr]) -> bool:
156
+ """``Literal[..., None]``, also nested (``Literal[Literal[None], "a"]``).
157
+
158
+ The string ``"None"`` is a value, not ``None``.
159
+ """
160
+ for arg in args:
161
+ if isinstance(arg, ast.Constant) and arg.value is None:
162
+ return True
163
+ if isinstance(arg, ast.Subscript):
164
+ name, inner = subscript_parts(arg)
165
+ if name == "Literal" and literal_admits_none(inner):
166
+ return True
167
+ return False
168
+
169
+
170
+ def column_union(options: List[ast.expr], spell: Callable[[List[str]], str]) -> Tuple[str, bool]:
171
+ """A union column type without its ``None`` members; ``spell`` joins the rest.
172
+
173
+ Each remaining member is resolved like a column of its own, so wrappers
174
+ and quotes are dropped and a nested ``Optional`` still counts.
175
+ """
176
+ rest = [option for option in options if not is_none(option)]
177
+ if not rest: # `None | None`
178
+ return "None", True
179
+ members = [column_type(option) for option in rest]
180
+ nullable = len(rest) < len(options) or any(inner for _, inner in members)
181
+ if len(members) == 1:
182
+ return members[0][0], nullable
183
+ return spell([type_str for type_str, _ in members]), nullable
184
+
185
+
186
+ def annotation_reference(node: ast.expr, many: bool = False) -> _AnnotationRef | None:
187
+ """The single class an annotation refers to, with cardinality and optionality.
188
+
189
+ Walks the annotation's syntax tree, so every spelling of the same type
190
+ resolves alike (#229): ``X | None`` / ``None | X``, ``Optional[X]``,
191
+ ``Union[X, None]``, string forward references (also ``"None"``),
192
+ ``Mapped`` / ``Annotated`` wrappers, ``typing.``-qualified forms,
193
+ module-qualified classes (``schemas.User``, flagged ``qualified``),
194
+ and collections: ``list``, ``set``, ``Sequence`` and friends,
195
+ ``tuple[X, ...]``, a mapping's value type, and the collection-only
196
+ ``WriteOnlyMapped`` / ``DynamicMapped``. Returns None when the
197
+ annotation does not name exactly one class, such as
198
+ ``Union[User, int]`` or ``tuple[User, int]``.
199
+ """
200
+ if isinstance(node, ast.Constant):
201
+ parsed = parse_quoted(node)
202
+ return annotation_reference(parsed, many) if parsed is not None else None
203
+ if isinstance(node, ast.Name):
204
+ return _AnnotationRef(node.id, many, False, spelled=node.id)
205
+ if isinstance(node, ast.Attribute):
206
+ return _AnnotationRef(node.attr, many, False, qualified=True, spelled=ast.unparse(node))
207
+ if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
208
+ return union_reference(union_operands(node), many)
209
+ if not isinstance(node, ast.Subscript):
210
+ return None
211
+ name, args = subscript_parts(node)
212
+ if not args:
213
+ return None
214
+ if name in TRANSPARENT_WRAPPERS:
215
+ return annotation_reference(args[0], many)
216
+ if name in MANY_WRAPPERS:
217
+ return annotation_reference(args[0], True)
218
+ if name == "Optional" and len(args) == 1:
219
+ ref = annotation_reference(args[0], many)
220
+ return ref._replace(nullable=True) if ref else None
221
+ if name == "Union":
222
+ return union_reference(args, many)
223
+ if name in MANY_CONTAINERS and len(args) == 1:
224
+ return annotation_reference(args[0], True)
225
+ if name in ("tuple", "Tuple") and len(args) == 2:
226
+ ellipsis = args[1]
227
+ if isinstance(ellipsis, ast.Constant) and ellipsis.value is Ellipsis:
228
+ return annotation_reference(args[0], True)
229
+ if name in MANY_MAPPINGS and len(args) == 2:
230
+ return annotation_reference(args[1], True)
231
+ return None
232
+
233
+
234
+ def union_operands(node: ast.expr) -> List[ast.expr]:
235
+ """Flatten ``A | B | C`` into its operands."""
236
+ if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
237
+ return [*union_operands(node.left), *union_operands(node.right)]
238
+ return [node]
239
+
240
+
241
+ def union_reference(options: List[ast.expr], many: bool) -> _AnnotationRef | None:
242
+ """Resolve a union whose members all name the same class, plus optional ``None``.
243
+
244
+ Members are compared after resolving, so repeated or nested spellings
245
+ of one type (``Union[User, User, None]``, ``Union[User, Optional[User]]``)
246
+ resolve like ``Optional[User]``. Members naming different classes, or
247
+ the same class once as one and once as many, name no single class.
248
+ """
249
+ rest = [option for option in options if not is_none(option)]
250
+ refs = [annotation_reference(option, many) for option in rest]
251
+ if not refs or any(ref is None for ref in refs):
252
+ return None
253
+ resolved = [ref for ref in refs if ref is not None]
254
+ first = resolved[0]
255
+ # Compare the full spelling: `a.User` and `b.User` are different classes.
256
+ if any((ref.spelled, ref.many) != (first.spelled, first.many) for ref in resolved):
257
+ return None
258
+ nullable = len(rest) < len(options) or any(ref.nullable for ref in resolved)
259
+ qualified = any(ref.qualified for ref in resolved)
260
+ return first._replace(nullable=nullable, qualified=qualified)
261
+
262
+
263
+ def is_mapped_annotation(annotation: ast.expr) -> bool:
264
+ """``Mapped[...]`` (or ``WriteOnlyMapped`` / ``DynamicMapped``), bare or qualified."""
265
+ return isinstance(annotation, ast.Subscript) and expr_name(annotation.value) in MAPPED_WRAPPERS
266
+
267
+
268
+ def as_rel(ref: _AnnotationRef, attr: str) -> _Rel:
269
+ """A relationship tuple; only a ``one`` reference can be optional (#223)."""
270
+ return (ref.target, "many" if ref.many else "one", attr, ref.nullable and not ref.many)
@@ -0,0 +1,36 @@
1
+ """Types and small helpers shared by the parser modules."""
2
+
3
+ import ast
4
+ import re
5
+ from typing import Dict, List, Tuple, TypeVar
6
+
7
+ from ..config import FieldInfo
8
+
9
+ _V = TypeVar("_V")
10
+
11
+ # A relationship while parsing: (target, type, attribute, nullable). The
12
+ # public EntityInfo.relationships keeps (target, type, attribute); the flag
13
+ # goes to EntityInfo.nullable_relationships.
14
+ _Rel = Tuple[str, str, str, bool]
15
+
16
+ # A class body's (fields, relationships, declared attribute names).
17
+ _ClassMembers = Tuple[Dict[str, FieldInfo], Dict[str, _Rel], List[str]]
18
+
19
+ #: Enum base class names recognized by erdify (stdlib Enum + Django choices).
20
+ ENUM_BASES = frozenset({"Enum", "TextChoices", "IntegerChoices"})
21
+
22
+
23
+ def is_enum_class(class_node: ast.ClassDef) -> bool:
24
+ """Check if a class is an Enum or a Django TextChoices/IntegerChoices."""
25
+ for base in class_node.bases:
26
+ if isinstance(base, ast.Attribute) and base.attr in ENUM_BASES:
27
+ return True
28
+ if isinstance(base, ast.Name) and base.id in ENUM_BASES:
29
+ return True
30
+ return False
31
+
32
+
33
+ def to_snake_case(name: str) -> str:
34
+ """Convert CamelCase to snake_case."""
35
+ s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
36
+ return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()