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.
- {erdify-1.2.0 → erdify-1.3.0}/PKG-INFO +1 -1
- {erdify-1.2.0 → erdify-1.3.0}/pyproject.toml +1 -1
- {erdify-1.2.0 → erdify-1.3.0}/pyproject.toml.orig +1 -1
- {erdify-1.2.0 → erdify-1.3.0}/src/erdify/cli.py +1 -1
- {erdify-1.2.0 → erdify-1.3.0}/src/erdify/generator.py +109 -33
- erdify-1.3.0/src/erdify/parser/__init__.py +26 -0
- erdify-1.3.0/src/erdify/parser/annotations.py +270 -0
- erdify-1.3.0/src/erdify/parser/common.py +36 -0
- erdify-1.3.0/src/erdify/parser/core.py +454 -0
- erdify-1.3.0/src/erdify/parser/dialects/__init__.py +22 -0
- erdify-1.3.0/src/erdify/parser/dialects/annotated.py +245 -0
- erdify-1.3.0/src/erdify/parser/dialects/base.py +362 -0
- erdify-1.3.0/src/erdify/parser/dialects/django.py +776 -0
- erdify-1.3.0/src/erdify/parser/dialects/keyless.py +201 -0
- erdify-1.3.0/src/erdify/parser/dialects/sqlalchemy.py +147 -0
- erdify-1.3.0/src/erdify/parser/discovery.py +180 -0
- erdify-1.3.0/src/erdify/parser/inheritance.py +177 -0
- {erdify-1.2.0 → erdify-1.3.0}/src/erdify/sql_parser.py +2 -1
- erdify-1.2.0/src/erdify/parser.py +0 -2025
- {erdify-1.2.0 → erdify-1.3.0}/LICENSE +0 -0
- {erdify-1.2.0 → erdify-1.3.0}/README.md +0 -0
- {erdify-1.2.0 → erdify-1.3.0}/src/erdify/__init__.py +0 -0
- {erdify-1.2.0 → erdify-1.3.0}/src/erdify/__main__.py +0 -0
- {erdify-1.2.0 → erdify-1.3.0}/src/erdify/config.py +0 -0
- {erdify-1.2.0 → erdify-1.3.0}/src/erdify/inject.py +0 -0
- {erdify-1.2.0 → erdify-1.3.0}/src/erdify/py.typed +0 -0
- {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.
|
|
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
|
|
@@ -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="
|
|
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
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
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
|
-
|
|
175
|
-
|
|
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
|
-
|
|
178
|
-
|
|
179
|
-
target
|
|
180
|
-
|
|
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
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
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
|
-
|
|
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
|
-
|
|
298
|
+
link_pairs.add(frozenset((entity_a.name, entity_b.name)))
|
|
226
299
|
|
|
227
|
-
for
|
|
228
|
-
|
|
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
|
-
|
|
288
|
-
|
|
289
|
-
|
|
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()
|