erdify 1.3.0__tar.gz → 1.4.1__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.3.0 → erdify-1.4.1}/PKG-INFO +1 -1
- {erdify-1.3.0 → erdify-1.4.1}/pyproject.toml +1 -1
- {erdify-1.3.0 → erdify-1.4.1}/pyproject.toml.orig +1 -1
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/config.py +6 -1
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/generator.py +184 -50
- erdify-1.4.1/src/erdify/parser/aliases.py +388 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/annotations.py +100 -2
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/common.py +17 -5
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/core.py +25 -5
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/annotated.py +115 -33
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/base.py +8 -1
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/django.py +1 -1
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/sqlalchemy.py +1 -0
- {erdify-1.3.0 → erdify-1.4.1}/LICENSE +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/README.md +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/__init__.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/__main__.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/cli.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/inject.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/__init__.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/__init__.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/keyless.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/discovery.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/inheritance.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/py.typed +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/pyproject.py +0 -0
- {erdify-1.3.0 → erdify-1.4.1}/src/erdify/sql_parser.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: erdify
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.4.1
|
|
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,7 +1,7 @@
|
|
|
1
1
|
"""Data classes for erdify."""
|
|
2
2
|
|
|
3
3
|
from dataclasses import dataclass, field
|
|
4
|
-
from typing import List, Tuple
|
|
4
|
+
from typing import Dict, List, Tuple
|
|
5
5
|
|
|
6
6
|
|
|
7
7
|
@dataclass
|
|
@@ -67,6 +67,10 @@ class EntityInfo:
|
|
|
67
67
|
reference is optional (e.g. ``user: User | None``); drawn as
|
|
68
68
|
zero-or-one on the target side. Foreign-key columns carry their own
|
|
69
69
|
``FieldInfo.is_nullable`` instead.
|
|
70
|
+
inverse_relationships: Relationship attribute -> the attribute of the
|
|
71
|
+
other side's relationship it pairs with, when the source names it
|
|
72
|
+
(SQLAlchemy / SQLModel ``back_populates=``). Both sides are then
|
|
73
|
+
drawn as one edge.
|
|
70
74
|
"""
|
|
71
75
|
|
|
72
76
|
name: str
|
|
@@ -79,6 +83,7 @@ class EntityInfo:
|
|
|
79
83
|
base_classes: List[str] = field(default_factory=list)
|
|
80
84
|
source: str = "sqlmodel"
|
|
81
85
|
nullable_relationships: List[str] = field(default_factory=list)
|
|
86
|
+
inverse_relationships: Dict[str, str] = field(default_factory=dict)
|
|
82
87
|
|
|
83
88
|
|
|
84
89
|
def is_structural_link_table(fields: List[FieldInfo]) -> bool:
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
import html
|
|
4
4
|
import json
|
|
5
5
|
import re
|
|
6
|
-
from typing import Dict, List, Tuple
|
|
6
|
+
from typing import Dict, Iterable, List, Tuple
|
|
7
7
|
|
|
8
8
|
from .config import EntityInfo, EnumInfo, FieldInfo
|
|
9
9
|
|
|
@@ -186,18 +186,34 @@ class _ERGenerator:
|
|
|
186
186
|
"""
|
|
187
187
|
return re.sub(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])", "_", name).lower()
|
|
188
188
|
|
|
189
|
+
#: Crow's-foot end at the target for what a relationship declares about
|
|
190
|
+
#: it: (kind, nullable) -> token, written on the target's side.
|
|
191
|
+
_TARGET_END = {
|
|
192
|
+
("one", False): "||",
|
|
193
|
+
("one", True): "o|",
|
|
194
|
+
("many", False): "o{",
|
|
195
|
+
("one_to_one", False): "||",
|
|
196
|
+
("many_to_many", False): "o{",
|
|
197
|
+
}
|
|
198
|
+
#: The source end when only one side is declared: kind -> token.
|
|
199
|
+
_DEFAULT_SOURCE_END = {"one": "}o", "many": "||", "one_to_one": "||", "many_to_many": "}o"}
|
|
200
|
+
|
|
189
201
|
@staticmethod
|
|
190
|
-
def
|
|
191
|
-
"""The
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
if
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
202
|
+
def _mirror(token: str) -> str:
|
|
203
|
+
"""The same end written on the other side of ``--`` (``o{`` -> ``}o``)."""
|
|
204
|
+
return token[::-1].replace("{", "}")
|
|
205
|
+
|
|
206
|
+
def _end(self, entity: EntityInfo, kind: str, attr: str) -> str:
|
|
207
|
+
"""The target end of ``entity.attr``; only a ``one`` reference can be optional."""
|
|
208
|
+
if kind not in self._DEFAULT_SOURCE_END:
|
|
209
|
+
kind = "one"
|
|
210
|
+
nullable = kind == "one" and attr in entity.nullable_relationships # #223
|
|
211
|
+
return self._TARGET_END[(kind, nullable)]
|
|
212
|
+
|
|
213
|
+
def _declared_line(self, entity: EntityInfo, target: str, rel_type: str, attr: str) -> str:
|
|
214
|
+
"""The edge for one declared relationship of ``entity``, other side undeclared."""
|
|
215
|
+
source = self._DEFAULT_SOURCE_END.get(rel_type, self._DEFAULT_SOURCE_END["one"])
|
|
216
|
+
return f'{entity.name} {source}--{self._end(entity, rel_type, attr)} {target} : "{attr}"'
|
|
201
217
|
|
|
202
218
|
def _declared_relationship_lines(
|
|
203
219
|
self, fk_pairs: "set[frozenset[str]]", link_pairs: "set[frozenset[str]]"
|
|
@@ -210,18 +226,12 @@ class _ERGenerator:
|
|
|
210
226
|
foreign-key column, so only a link table suppresses it: e.g. a Django
|
|
211
227
|
``ManyToManyField`` to the parent of a multi-table child (#233).
|
|
212
228
|
|
|
213
|
-
Every declared attribute gets its own edge (#230), except the
|
|
214
|
-
|
|
215
|
-
``Post.user``)
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
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.
|
|
229
|
+
Every declared attribute gets its own edge (#230), except that the two
|
|
230
|
+
sides of a bidirectional relationship (e.g. ``User.posts`` and
|
|
231
|
+
``Post.user``) describe one edge (:meth:`_pair_sides`). That edge is
|
|
232
|
+
drawn from the side whose entity name sorts first, so it does not
|
|
233
|
+
depend on file order, and each end shows what its own side declares
|
|
234
|
+
(#239): ``list[B]`` on ``A`` and ``list[A]`` on ``B`` give ``}o--o{``.
|
|
225
235
|
"""
|
|
226
236
|
connected = fk_pairs | link_pairs
|
|
227
237
|
rels = [
|
|
@@ -232,34 +242,156 @@ class _ERGenerator:
|
|
|
232
242
|
and frozenset((entity.name, target))
|
|
233
243
|
not in (link_pairs if rel_type == "many_to_many" else connected)
|
|
234
244
|
]
|
|
235
|
-
|
|
245
|
+
by_pair: Dict[frozenset[str], List[int]] = {}
|
|
236
246
|
for i, (entity, target, _, _) in enumerate(rels):
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
247
|
+
by_pair.setdefault(frozenset((entity.name, target)), []).append(i)
|
|
248
|
+
partner: Dict[int, int] = {}
|
|
249
|
+
for indices in by_pair.values():
|
|
250
|
+
partner.update(self._pair_sides(rels, indices))
|
|
251
|
+
folded = set(partner.values())
|
|
252
|
+
lines: List[str] = []
|
|
253
|
+
for i, (entity, target, rel_type, attr) in enumerate(rels):
|
|
254
|
+
if i in folded:
|
|
242
255
|
continue
|
|
243
|
-
if
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
256
|
+
if i in partner:
|
|
257
|
+
lines.append(self._merged_line(rels[i], rels[partner[i]]))
|
|
258
|
+
else:
|
|
259
|
+
lines.append(self._declared_line(entity, target, rel_type, attr))
|
|
260
|
+
return lines
|
|
261
|
+
|
|
262
|
+
def _pair_sides(
|
|
263
|
+
self, rels: "List[Tuple[EntityInfo, str, str, str]]", indices: List[int]
|
|
264
|
+
) -> Dict[int, int]:
|
|
265
|
+
"""Pair the relationships between one pair of entities: kept index -> folded index.
|
|
266
|
+
|
|
267
|
+
1. **Explicit** (#240): a side naming its inverse (``back_populates=``)
|
|
268
|
+
pairs with that attribute of the other side, mutual declarations
|
|
269
|
+
first. One naming an attribute the other side does not declare is
|
|
270
|
+
guessed like the rest.
|
|
271
|
+
2. **Guessed**: each relationship of the first side (the entity whose
|
|
272
|
+
name sorts first) folds at most one relationship declared back
|
|
273
|
+
from the other side, best candidates first: the inverse
|
|
274
|
+
cardinality (``many`` for ``one`` and vice versa) with attributes
|
|
275
|
+
named after the class they point at on both sides (``Post.user`` /
|
|
276
|
+
``User.posts``), then on one side, then any inverse cardinality,
|
|
277
|
+
then (not for a self-reference) anything left.
|
|
278
|
+
|
|
279
|
+
Equal candidates are tried in declaration order within each entity, the
|
|
280
|
+
first side before the other, so the file (entity) order never changes
|
|
281
|
+
the result. The kept side is the first side's relationship; for a
|
|
282
|
+
self-reference, the attribute whose name sorts first. A self-reference
|
|
283
|
+
only folds an N:1 / 1:N inverse (``parent`` / ``children``): two
|
|
284
|
+
references of the same cardinality
|
|
285
|
+
(``friends`` / ``blocked``, both M:N) stay two edges.
|
|
286
|
+
"""
|
|
287
|
+
|
|
288
|
+
def attr(i: int) -> str:
|
|
289
|
+
return rels[i][3]
|
|
290
|
+
|
|
291
|
+
def inverse_of(i: int) -> str | None:
|
|
292
|
+
return rels[i][0].inverse_relationships.get(attr(i))
|
|
293
|
+
|
|
294
|
+
def by_attr(idx: Iterable[int]) -> List[int]:
|
|
295
|
+
return sorted(idx, key=attr)
|
|
296
|
+
|
|
297
|
+
names = sorted({rels[i][0].name for i in indices} | {rels[i][1] for i in indices})
|
|
298
|
+
first = names[0]
|
|
299
|
+
self_ref = len(names) == 1
|
|
300
|
+
side_a = {i for i in indices if rels[i][0].name == first}
|
|
301
|
+
side_b = side_a if self_ref else set(indices) - side_a
|
|
302
|
+
pairs: Dict[int, int] = {}
|
|
303
|
+
used: set[int] = set()
|
|
304
|
+
|
|
305
|
+
def other_side(i: int) -> "set[int]":
|
|
306
|
+
return side_b if i in side_a else side_a
|
|
307
|
+
|
|
308
|
+
def pair(i: int, j: int) -> None:
|
|
309
|
+
if self_ref:
|
|
310
|
+
keep, fold = by_attr((i, j))
|
|
311
|
+
else:
|
|
312
|
+
keep, fold = (i, j) if i in side_a else (j, i)
|
|
313
|
+
pairs[keep] = fold
|
|
314
|
+
used.update((i, j))
|
|
315
|
+
|
|
316
|
+
# 1. Explicit: mutual back_populates first, then one-sided ones.
|
|
317
|
+
for mutual in (True, False):
|
|
318
|
+
for i in [*sorted(side_a), *sorted(side_b - side_a)]:
|
|
319
|
+
inverse = inverse_of(i)
|
|
320
|
+
if i in used or inverse is None:
|
|
321
|
+
continue
|
|
322
|
+
j = next(
|
|
323
|
+
(
|
|
324
|
+
j
|
|
325
|
+
for j in sorted(other_side(i))
|
|
326
|
+
if j != i
|
|
327
|
+
and j not in used
|
|
328
|
+
and attr(j) == inverse
|
|
329
|
+
and (inverse_of(j) == attr(i) if mutual else inverse_of(j) is None)
|
|
330
|
+
),
|
|
331
|
+
None,
|
|
332
|
+
)
|
|
333
|
+
if j is not None:
|
|
334
|
+
pair(i, j)
|
|
335
|
+
|
|
336
|
+
# 2. Guessed: everything not paired whose inverse (if named) does not exist.
|
|
337
|
+
def guessable(i: int) -> bool:
|
|
338
|
+
inverse = inverse_of(i)
|
|
339
|
+
return i not in used and (
|
|
340
|
+
inverse is None or not any(attr(j) == inverse for j in other_side(i))
|
|
341
|
+
)
|
|
342
|
+
|
|
343
|
+
plural_names = {name: self._class_attr_names(name) for name in names}
|
|
344
|
+
|
|
345
|
+
def exact(i: int, j: int) -> bool:
|
|
346
|
+
return rels[j][2] == self._INVERSE_KIND[rels[i][2]]
|
|
347
|
+
|
|
348
|
+
def named(i: int, j: int) -> int:
|
|
349
|
+
entity_i, target_i, _, attr_i = rels[i]
|
|
350
|
+
return int(attr_i in plural_names[target_i]) + int(
|
|
351
|
+
attr(j) in plural_names[entity_i.name]
|
|
352
|
+
)
|
|
353
|
+
|
|
354
|
+
tiers = [
|
|
355
|
+
lambda i, j: exact(i, j) and named(i, j) == 2,
|
|
356
|
+
lambda i, j: exact(i, j) and named(i, j) == 1,
|
|
357
|
+
exact,
|
|
262
358
|
]
|
|
359
|
+
if not self_ref:
|
|
360
|
+
tiers.append(lambda i, j: True)
|
|
361
|
+
free_a = [i for i in sorted(side_a) if guessable(i)]
|
|
362
|
+
free_b = [j for j in sorted(side_b) if guessable(j)]
|
|
363
|
+
for fits in tiers:
|
|
364
|
+
for i in free_a:
|
|
365
|
+
if i in used:
|
|
366
|
+
continue
|
|
367
|
+
if self_ref and self._INVERSE_KIND[rels[i][2]] == rels[i][2]:
|
|
368
|
+
continue # two M:N / 1:1 self-references are two relationships
|
|
369
|
+
j = next((j for j in free_b if j not in used and j != i and fits(i, j)), None)
|
|
370
|
+
if j is not None:
|
|
371
|
+
pair(i, j)
|
|
372
|
+
return pairs
|
|
373
|
+
|
|
374
|
+
def _class_attr_names(self, name: str) -> "set[str]":
|
|
375
|
+
"""Attribute names that refer to class ``name``: ``user``, ``users``, ``categories``."""
|
|
376
|
+
snake = self._snake_case(name)
|
|
377
|
+
names = {snake, snake + "s"}
|
|
378
|
+
if snake.endswith("y") and snake[-2:-1] not in ("a", "e", "i", "o", "u", ""):
|
|
379
|
+
names.add(snake[:-1] + "ies")
|
|
380
|
+
elif snake.endswith(("s", "x", "z", "ch", "sh")):
|
|
381
|
+
names.add(snake + "es")
|
|
382
|
+
return names
|
|
383
|
+
|
|
384
|
+
def _merged_line(
|
|
385
|
+
self,
|
|
386
|
+
kept: "Tuple[EntityInfo, str, str, str]",
|
|
387
|
+
folded: "Tuple[EntityInfo, str, str, str]",
|
|
388
|
+
) -> str:
|
|
389
|
+
"""One edge for both sides of a relationship; each end from its own side (#239)."""
|
|
390
|
+
entity, target, kind, attr = kept
|
|
391
|
+
other, _, other_kind, other_attr = folded
|
|
392
|
+
left = self._mirror(self._end(other, other_kind, other_attr))
|
|
393
|
+
right = self._end(entity, kind, attr)
|
|
394
|
+
return f'{entity.name} {left}--{right} {target} : "{attr}"'
|
|
263
395
|
|
|
264
396
|
def _relationship_lines(self) -> List[str]:
|
|
265
397
|
"""Resolve every relationship line, de-duplicated and ordered.
|
|
@@ -587,7 +719,8 @@ def generate_json(
|
|
|
587
719
|
|
|
588
720
|
Shape: ``{schema_version, title, entities: [{name, table_name, source, is_link_table,
|
|
589
721
|
fields: [{name, type, primary_key, foreign_key, nullable, foreign_table,
|
|
590
|
-
index, unique, default}], relationships: [{target, type, attribute, nullable
|
|
722
|
+
index, unique, default}], relationships: [{target, type, attribute, nullable,
|
|
723
|
+
inverse}]}],
|
|
591
724
|
enums:
|
|
592
725
|
[{name, values}]}``. Downstream tools can consume this without re-parsing.
|
|
593
726
|
``schema_version`` is :data:`JSON_SCHEMA_VERSION`; consumers should ignore
|
|
@@ -635,6 +768,7 @@ def generate_json(
|
|
|
635
768
|
"type": rel_type,
|
|
636
769
|
"attribute": attr,
|
|
637
770
|
"nullable": rel_type == "one" and attr in entity.nullable_relationships,
|
|
771
|
+
"inverse": entity.inverse_relationships.get(attr),
|
|
638
772
|
}
|
|
639
773
|
for target, rel_type, attr in entity.relationships
|
|
640
774
|
]
|
|
@@ -0,0 +1,388 @@
|
|
|
1
|
+
"""Column type aliases, resolved per module like Python names (#241, #249, #250).
|
|
2
|
+
|
|
3
|
+
SQLAlchemy's ``intpk = Annotated[int, mapped_column(primary_key=True)]``
|
|
4
|
+
lets ``id: Mapped[intpk]`` declare a primary key. Which object ``intpk``
|
|
5
|
+
names depends on the module and on where the class is defined in it, so it
|
|
6
|
+
is resolved like Python resolves the name when the class body runs:
|
|
7
|
+
|
|
8
|
+
- the module's last module-level binding of the name *before the class*
|
|
9
|
+
counts: an alias (``X = Annotated[...]``, ``X = other_alias``), an import,
|
|
10
|
+
a star import, or anything else (a function, a class, ``X = int``);
|
|
11
|
+
- an import is followed into the scanned file it names; a star import
|
|
12
|
+
provides the names that module exports (``__all__``, else its public names);
|
|
13
|
+
- an alias built on another one (``Annotated[intpk, ...]``) resolves that one
|
|
14
|
+
where the alias is defined;
|
|
15
|
+
- a name the module does not bind at all (e.g. imported under
|
|
16
|
+
``TYPE_CHECKING``) falls back to an alias of that name defined identically
|
|
17
|
+
wherever it is defined, unless a model class has that name.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
import ast
|
|
21
|
+
from bisect import bisect_left
|
|
22
|
+
from pathlib import Path
|
|
23
|
+
from types import MappingProxyType
|
|
24
|
+
from typing import Dict, Iterable, List, Mapping, NamedTuple, Set, Tuple
|
|
25
|
+
|
|
26
|
+
from .annotations import defines_column_alias, expand_aliases, parse_quoted
|
|
27
|
+
|
|
28
|
+
#: A name looked up at a line of a file (``None``: the whole module).
|
|
29
|
+
_Lookup = Tuple[Path, str, "int | None"]
|
|
30
|
+
|
|
31
|
+
#: ``_find_module`` result for an absolute import several scanned files match.
|
|
32
|
+
_AMBIGUOUS = Path("<ambiguous>")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class _Binding(NamedTuple):
|
|
36
|
+
"""One module-level binding of a name."""
|
|
37
|
+
|
|
38
|
+
#: ``"alias"`` (a possible alias value), ``"import"`` or ``"other"``.
|
|
39
|
+
kind: str
|
|
40
|
+
#: Line of the statement; a class only sees bindings before its own line.
|
|
41
|
+
line: int
|
|
42
|
+
#: The assigned value (``"alias"``).
|
|
43
|
+
value: ast.expr | None = None
|
|
44
|
+
#: The imported module as written, ``None`` for ``from . import x`` (``"import"``).
|
|
45
|
+
module: str | None = None
|
|
46
|
+
#: Leading dots of a relative import (``"import"``).
|
|
47
|
+
level: int = 0
|
|
48
|
+
#: The name imported from that module (``"import"``).
|
|
49
|
+
original: str = ""
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class AliasResolver:
|
|
53
|
+
"""Resolves column type aliases per scanned module.
|
|
54
|
+
|
|
55
|
+
Args:
|
|
56
|
+
trees: Each scanned file's syntax tree.
|
|
57
|
+
classes: Names of the parsed model classes; the by-name fallback never
|
|
58
|
+
turns one into an alias.
|
|
59
|
+
"""
|
|
60
|
+
|
|
61
|
+
def __init__(self, trees: Mapping[Path, ast.Module], classes: Iterable[str]):
|
|
62
|
+
self._trees = trees
|
|
63
|
+
self._classes = set(classes)
|
|
64
|
+
self._events: Dict[Path, List[Tuple[str, _Binding]]] = {}
|
|
65
|
+
#: Per file, each name's bindings in statement order (star imports expanded).
|
|
66
|
+
self._histories: Dict[Path, Dict[str, List[_Binding]]] = {}
|
|
67
|
+
#: Per file, names with a binding that may be an alias.
|
|
68
|
+
self._candidates: Dict[Path, List[str]] = {}
|
|
69
|
+
self._scoping: Set[Path] = set()
|
|
70
|
+
#: Star-import cut-offs so far; a history built across one is not cached.
|
|
71
|
+
self._star_cycles = 0
|
|
72
|
+
self._resolved_paths: Dict[Path, Path] = {}
|
|
73
|
+
self._modules: Dict[Tuple[Path, str | None, int], Path | None] = {}
|
|
74
|
+
self._resolved: Dict[Tuple[Path, str, int | None], ast.expr | None] = {}
|
|
75
|
+
#: Cycle cut-offs so far; a result computed across one is not cached.
|
|
76
|
+
self._cycles = 0
|
|
77
|
+
self._views: Dict[Tuple[Path, int | None], Mapping[str, ast.expr]] = {}
|
|
78
|
+
self._fallback: Dict[str, ast.expr] | None = None
|
|
79
|
+
self._suffixes: Dict[Tuple[str, ...], List[Path]] | None = None
|
|
80
|
+
|
|
81
|
+
def aliases_for(self, file: Path | None, line: int | None = None) -> Mapping[str, ast.expr]:
|
|
82
|
+
"""Alias name -> fully expanded ``Annotated[...]``, as seen at ``line`` of ``file``."""
|
|
83
|
+
if file is None or file not in self._trees:
|
|
84
|
+
return MappingProxyType(dict(self._fallback_aliases()))
|
|
85
|
+
key = (file, line)
|
|
86
|
+
view = self._views.get(key)
|
|
87
|
+
if view is not None:
|
|
88
|
+
return view
|
|
89
|
+
result: Dict[str, ast.expr] = {}
|
|
90
|
+
for name in self._candidate_names(file):
|
|
91
|
+
value = self._resolve(file, name, line, ())
|
|
92
|
+
if value is not None:
|
|
93
|
+
result[name] = value
|
|
94
|
+
for name, value in self._fallback_aliases().items():
|
|
95
|
+
# A name bound before the class (also via `*`) never falls back.
|
|
96
|
+
if name not in result and self._binding_at(file, name, line) is None:
|
|
97
|
+
result[name] = value
|
|
98
|
+
view = MappingProxyType(result)
|
|
99
|
+
self._views[key] = view
|
|
100
|
+
return view
|
|
101
|
+
|
|
102
|
+
# -- module scope ----------------------------------------------------------
|
|
103
|
+
|
|
104
|
+
def _module_events(self, file: Path) -> List[Tuple[str, _Binding]]:
|
|
105
|
+
"""``(name, binding)`` per module-level binding, in statement order.
|
|
106
|
+
|
|
107
|
+
A star import is recorded as name ``"*"`` and expanded by ``_scope``.
|
|
108
|
+
"""
|
|
109
|
+
events = self._events.get(file)
|
|
110
|
+
if events is not None:
|
|
111
|
+
return events
|
|
112
|
+
events = []
|
|
113
|
+
for node in self._trees[file].body:
|
|
114
|
+
line = node.lineno
|
|
115
|
+
if isinstance(node, ast.Assign):
|
|
116
|
+
if len(node.targets) == 1 and isinstance(node.targets[0], ast.Name):
|
|
117
|
+
events.append((node.targets[0].id, self._assigned(node.value, line)))
|
|
118
|
+
else: # chained or unpacking: whatever it binds is not an alias
|
|
119
|
+
events.extend(
|
|
120
|
+
(sub.id, _Binding("other", line))
|
|
121
|
+
for target in node.targets
|
|
122
|
+
for sub in ast.walk(target)
|
|
123
|
+
if isinstance(sub, ast.Name) and isinstance(sub.ctx, ast.Store)
|
|
124
|
+
)
|
|
125
|
+
elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
|
|
126
|
+
if node.value is not None: # a bare `x: int` binds nothing
|
|
127
|
+
events.append((node.target.id, self._assigned(node.value, line)))
|
|
128
|
+
elif isinstance(node, ast.ImportFrom):
|
|
129
|
+
for alias in node.names:
|
|
130
|
+
binding = _Binding(
|
|
131
|
+
"import", line, module=node.module, level=node.level, original=alias.name
|
|
132
|
+
)
|
|
133
|
+
events.append(
|
|
134
|
+
("*" if alias.name == "*" else alias.asname or alias.name, binding)
|
|
135
|
+
)
|
|
136
|
+
elif isinstance(node, ast.Import):
|
|
137
|
+
for alias in node.names:
|
|
138
|
+
name = alias.asname or alias.name.split(".")[0]
|
|
139
|
+
events.append((name, _Binding("other", line)))
|
|
140
|
+
elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
|
|
141
|
+
events.append((node.name, _Binding("other", line)))
|
|
142
|
+
elif type(node).__name__ == "TypeAlias":
|
|
143
|
+
# PEP 695 `type X = ...`: SQLAlchemy takes no mapped_column() from it.
|
|
144
|
+
alias_name = getattr(node, "name", None)
|
|
145
|
+
if isinstance(alias_name, ast.Name):
|
|
146
|
+
events.append((alias_name.id, _Binding("other", line)))
|
|
147
|
+
self._events[file] = events
|
|
148
|
+
return events
|
|
149
|
+
|
|
150
|
+
@staticmethod
|
|
151
|
+
def _assigned(value: ast.expr, line: int) -> _Binding:
|
|
152
|
+
"""``X = Annotated[...]`` or ``X = other_alias`` may be an alias; anything else is not."""
|
|
153
|
+
if isinstance(value, (ast.Subscript, ast.Name)):
|
|
154
|
+
return _Binding("alias", line, value=value)
|
|
155
|
+
return _Binding("other", line)
|
|
156
|
+
|
|
157
|
+
def _history(self, file: Path) -> Dict[str, List[_Binding]]:
|
|
158
|
+
"""Each name's module-level bindings in statement order, star imports expanded.
|
|
159
|
+
|
|
160
|
+
Not cached while a circular star import cut it short, so the cut-off
|
|
161
|
+
never becomes a permanently missing binding.
|
|
162
|
+
"""
|
|
163
|
+
cached = self._histories.get(file)
|
|
164
|
+
if cached is not None:
|
|
165
|
+
return cached
|
|
166
|
+
history: Dict[str, List[_Binding]] = {}
|
|
167
|
+
cycles = self._star_cycles
|
|
168
|
+
self._scoping.add(file)
|
|
169
|
+
try:
|
|
170
|
+
for name, binding in self._module_events(file):
|
|
171
|
+
if name != "*":
|
|
172
|
+
history.setdefault(name, []).append(binding)
|
|
173
|
+
continue
|
|
174
|
+
target = self._find_module(file, binding.module, binding.level)
|
|
175
|
+
if target is None or target is _AMBIGUOUS:
|
|
176
|
+
continue
|
|
177
|
+
if target in self._scoping:
|
|
178
|
+
self._star_cycles += 1
|
|
179
|
+
continue
|
|
180
|
+
for exported in self._exports(target):
|
|
181
|
+
history.setdefault(exported, []).append(binding._replace(original=exported))
|
|
182
|
+
finally:
|
|
183
|
+
self._scoping.discard(file)
|
|
184
|
+
if self._star_cycles == cycles:
|
|
185
|
+
self._histories[file] = history
|
|
186
|
+
return history
|
|
187
|
+
|
|
188
|
+
def _candidate_names(self, file: Path) -> List[str]:
|
|
189
|
+
"""Names with a binding in ``file`` that may be an alias (few, usually)."""
|
|
190
|
+
cached = self._candidates.get(file)
|
|
191
|
+
if cached is not None:
|
|
192
|
+
return cached
|
|
193
|
+
names = [
|
|
194
|
+
name
|
|
195
|
+
for name, bindings in self._history(file).items()
|
|
196
|
+
if any(b.kind != "other" for b in bindings)
|
|
197
|
+
]
|
|
198
|
+
if file in self._histories: # only once the history itself is final
|
|
199
|
+
self._candidates[file] = names
|
|
200
|
+
return names
|
|
201
|
+
|
|
202
|
+
def _binding_at(self, file: Path, name: str, line: int | None) -> _Binding | None:
|
|
203
|
+
"""The last module-level binding of ``name`` before ``line`` (any, if None)."""
|
|
204
|
+
bindings = self._history(file).get(name)
|
|
205
|
+
if not bindings:
|
|
206
|
+
return None
|
|
207
|
+
if line is None:
|
|
208
|
+
return bindings[-1]
|
|
209
|
+
index = bisect_left([b.line for b in bindings], line)
|
|
210
|
+
return bindings[index - 1] if index else None
|
|
211
|
+
|
|
212
|
+
def _exports(self, file: Path) -> List[str]:
|
|
213
|
+
"""What ``from <file> import *`` binds: the last literal ``__all__``, else public names."""
|
|
214
|
+
exports: List[str] | None = None
|
|
215
|
+
for node in self._trees[file].body:
|
|
216
|
+
targets = (
|
|
217
|
+
node.targets
|
|
218
|
+
if isinstance(node, ast.Assign)
|
|
219
|
+
else [node.target]
|
|
220
|
+
if isinstance(node, ast.AnnAssign)
|
|
221
|
+
else []
|
|
222
|
+
)
|
|
223
|
+
if any(isinstance(t, ast.Name) and t.id == "__all__" for t in targets):
|
|
224
|
+
value = node.value if isinstance(node, (ast.Assign, ast.AnnAssign)) else None
|
|
225
|
+
if value is None: # `__all__: list[str]` alone binds nothing
|
|
226
|
+
continue
|
|
227
|
+
exports = (
|
|
228
|
+
[
|
|
229
|
+
elt.value
|
|
230
|
+
for elt in value.elts
|
|
231
|
+
if isinstance(elt, ast.Constant) and isinstance(elt.value, str)
|
|
232
|
+
]
|
|
233
|
+
if isinstance(value, (ast.List, ast.Tuple))
|
|
234
|
+
else None # not a literal: unknown, fall back to public names
|
|
235
|
+
)
|
|
236
|
+
if exports is not None:
|
|
237
|
+
return exports
|
|
238
|
+
return [name for name in self._history(file) if not name.startswith("_")]
|
|
239
|
+
|
|
240
|
+
# -- resolution ----------------------------------------------------------------
|
|
241
|
+
|
|
242
|
+
def _resolve(
|
|
243
|
+
self, file: Path, name: str, line: int | None, stack: Tuple[_Lookup, ...]
|
|
244
|
+
) -> ast.expr | None:
|
|
245
|
+
"""The expanded column alias ``name`` refers to at ``line`` of ``file``, or None.
|
|
246
|
+
|
|
247
|
+
The stack holds ``(file, name, line)``, so ``intpk = Annotated[intpk, ...]``
|
|
248
|
+
can refer to the earlier ``intpk`` while a real cycle (mutual imports)
|
|
249
|
+
still stops.
|
|
250
|
+
"""
|
|
251
|
+
key = (file, name, line)
|
|
252
|
+
if key in self._resolved:
|
|
253
|
+
return self._resolved[key]
|
|
254
|
+
if key in stack:
|
|
255
|
+
self._cycles += 1 # results computed under this cut-off depend on the stack
|
|
256
|
+
return None
|
|
257
|
+
cycles = self._cycles
|
|
258
|
+
result = None
|
|
259
|
+
binding = self._binding_at(file, name, line)
|
|
260
|
+
if binding is not None:
|
|
261
|
+
result = self._resolve_binding(file, binding, stack + (key,))
|
|
262
|
+
if self._cycles == cycles:
|
|
263
|
+
self._resolved[key] = result
|
|
264
|
+
return result
|
|
265
|
+
|
|
266
|
+
def _resolve_binding(
|
|
267
|
+
self, file: Path, binding: _Binding, stack: Tuple[_Lookup, ...]
|
|
268
|
+
) -> ast.expr | None:
|
|
269
|
+
if binding.kind == "import":
|
|
270
|
+
target = self._find_module(file, binding.module, binding.level)
|
|
271
|
+
if target is _AMBIGUOUS: # several scanned modules match: by name
|
|
272
|
+
return self._fallback_aliases().get(binding.original)
|
|
273
|
+
if target is None: # not a scanned module (stdlib, third party)
|
|
274
|
+
return None
|
|
275
|
+
return self._resolve(target, binding.original, None, stack)
|
|
276
|
+
if binding.kind != "alias" or binding.value is None:
|
|
277
|
+
return None
|
|
278
|
+
# Names inside the alias resolve where, and when, it is defined (#249),
|
|
279
|
+
# also inside a quoted base (`Annotated["intpk", ...]`).
|
|
280
|
+
local: Dict[str, ast.expr] = {}
|
|
281
|
+
for name in self._referenced_names(binding.value):
|
|
282
|
+
if name not in local:
|
|
283
|
+
inner = self._resolve(file, name, binding.line, stack)
|
|
284
|
+
if inner is not None:
|
|
285
|
+
local[name] = inner
|
|
286
|
+
expanded = expand_aliases(binding.value, local)
|
|
287
|
+
return expanded if defines_column_alias(expanded) else None
|
|
288
|
+
|
|
289
|
+
@classmethod
|
|
290
|
+
def _referenced_names(cls, node: ast.expr) -> List[str]:
|
|
291
|
+
"""Names ``node`` mentions, also inside quoted type expressions."""
|
|
292
|
+
names: List[str] = []
|
|
293
|
+
for sub in ast.walk(node):
|
|
294
|
+
if isinstance(sub, ast.Name):
|
|
295
|
+
names.append(sub.id)
|
|
296
|
+
elif isinstance(sub, ast.Constant) and isinstance(sub.value, str):
|
|
297
|
+
parsed = parse_quoted(sub)
|
|
298
|
+
if parsed is not None:
|
|
299
|
+
names.extend(cls._referenced_names(parsed))
|
|
300
|
+
return names
|
|
301
|
+
|
|
302
|
+
def _find_module(self, file: Path, module: str | None, level: int) -> Path | None:
|
|
303
|
+
"""The scanned file an import refers to, ``_AMBIGUOUS``, or None (not scanned)."""
|
|
304
|
+
key = (file, module, level)
|
|
305
|
+
if key in self._modules:
|
|
306
|
+
return self._modules[key]
|
|
307
|
+
parts = module.split(".") if module else []
|
|
308
|
+
found: Path | None = None
|
|
309
|
+
if level:
|
|
310
|
+
base = file.parent
|
|
311
|
+
for _ in range(level - 1):
|
|
312
|
+
base = base.parent
|
|
313
|
+
if parts:
|
|
314
|
+
stem = base.joinpath(*parts)
|
|
315
|
+
# A package wins over a module file of the same name, as in Python.
|
|
316
|
+
candidates = [stem / "__init__.py", stem.parent / f"{stem.name}.py"]
|
|
317
|
+
else: # `from . import x`: the package itself
|
|
318
|
+
candidates = [base / "__init__.py"]
|
|
319
|
+
found = next((c for c in candidates if c in self._trees), None)
|
|
320
|
+
elif parts:
|
|
321
|
+
# Only a module whose import root contains the importing file can be
|
|
322
|
+
# what it imports: a scanned `pkg/uuid.py` is not `import uuid`.
|
|
323
|
+
matches = [
|
|
324
|
+
m
|
|
325
|
+
for m in self._suffix_index().get(tuple(parts), [])
|
|
326
|
+
if self._root_contains(m, len(parts), file)
|
|
327
|
+
]
|
|
328
|
+
packages = {m.parent for m in matches if m.name == "__init__.py"}
|
|
329
|
+
# `coltypes.py` beside a `coltypes/` package is shadowed by it.
|
|
330
|
+
matches = [
|
|
331
|
+
m for m in matches if m.name == "__init__.py" or m.with_suffix("") not in packages
|
|
332
|
+
]
|
|
333
|
+
found = matches[0] if len(matches) == 1 else (_AMBIGUOUS if matches else None)
|
|
334
|
+
self._modules[key] = found
|
|
335
|
+
return found
|
|
336
|
+
|
|
337
|
+
def _suffix_index(self) -> Dict[Tuple[str, ...], List[Path]]:
|
|
338
|
+
"""Dotted-module suffix -> scanned files, e.g. ``("app", "models")``."""
|
|
339
|
+
if self._suffixes is None:
|
|
340
|
+
index: Dict[Tuple[str, ...], List[Path]] = {}
|
|
341
|
+
for path in self._trees:
|
|
342
|
+
dotted = self._dotted(path)
|
|
343
|
+
for size in range(1, len(dotted) + 1):
|
|
344
|
+
index.setdefault(tuple(dotted[-size:]), []).append(path)
|
|
345
|
+
self._suffixes = index
|
|
346
|
+
return self._suffixes
|
|
347
|
+
|
|
348
|
+
def _absolute(self, path: Path) -> Path:
|
|
349
|
+
"""``path`` resolved, so a relative scan root (``erdify .``) keeps its packages."""
|
|
350
|
+
resolved = self._resolved_paths.get(path)
|
|
351
|
+
if resolved is None:
|
|
352
|
+
resolved = self._resolved_paths[path] = path.resolve()
|
|
353
|
+
return resolved
|
|
354
|
+
|
|
355
|
+
def _dotted(self, path: Path) -> Tuple[str, ...]:
|
|
356
|
+
"""The module path parts of a scanned file (``app/models.py`` -> app, models)."""
|
|
357
|
+
absolute = self._absolute(path)
|
|
358
|
+
return (
|
|
359
|
+
absolute.parent.parts
|
|
360
|
+
if absolute.name == "__init__.py"
|
|
361
|
+
else absolute.with_suffix("").parts
|
|
362
|
+
)
|
|
363
|
+
|
|
364
|
+
def _root_contains(self, module_file: Path, depth: int, importer: Path) -> bool:
|
|
365
|
+
"""Whether ``importer`` lies under the root ``module_file`` is imported from."""
|
|
366
|
+
dotted = self._dotted(module_file)
|
|
367
|
+
root = dotted[: len(dotted) - depth]
|
|
368
|
+
return self._absolute(importer).parts[: len(root)] == root
|
|
369
|
+
|
|
370
|
+
def _fallback_aliases(self) -> Dict[str, ast.expr]:
|
|
371
|
+
"""Aliases by name, for names a module does not bind (defined identically everywhere)."""
|
|
372
|
+
if self._fallback is not None:
|
|
373
|
+
return self._fallback
|
|
374
|
+
self._fallback = {} # guards re-entry from an ambiguous import while computing
|
|
375
|
+
found: Dict[str, List[ast.expr]] = {}
|
|
376
|
+
for file in self._trees:
|
|
377
|
+
for name, bindings in self._history(file).items():
|
|
378
|
+
if bindings[-1].kind == "alias" and name not in self._classes:
|
|
379
|
+
value = self._resolve(file, name, None, ())
|
|
380
|
+
if value is not None:
|
|
381
|
+
found.setdefault(name, []).append(value)
|
|
382
|
+
self._fallback = {
|
|
383
|
+
name: values[0]
|
|
384
|
+
for name, values in found.items()
|
|
385
|
+
if len({ast.dump(v) for v in values}) == 1
|
|
386
|
+
}
|
|
387
|
+
self._resolved.clear() # may hold results computed without the fallback
|
|
388
|
+
return self._fallback
|
|
@@ -5,7 +5,7 @@ nullability (#236), and call / wrapper recognition.
|
|
|
5
5
|
"""
|
|
6
6
|
|
|
7
7
|
import ast
|
|
8
|
-
from typing import Callable, List, NamedTuple, Tuple, TypeGuard
|
|
8
|
+
from typing import Callable, List, Mapping, NamedTuple, Tuple, TypeGuard
|
|
9
9
|
|
|
10
10
|
from .common import _Rel
|
|
11
11
|
|
|
@@ -152,6 +152,104 @@ def column_type(node: ast.expr) -> Tuple[str, bool]:
|
|
|
152
152
|
return ast.unparse(node), False
|
|
153
153
|
|
|
154
154
|
|
|
155
|
+
def expand_aliases(node: ast.expr, aliases: Mapping[str, ast.expr]) -> ast.expr:
|
|
156
|
+
"""``node`` with each column type alias replaced by its definition (#241).
|
|
157
|
+
|
|
158
|
+
``id: Mapped[intpk]`` with ``intpk = Annotated[int, mapped_column(...)]``
|
|
159
|
+
reads as ``Mapped[Annotated[int, mapped_column(...)]]``, also when quoted
|
|
160
|
+
(``Mapped["intpk"]``). Only type positions are expanded: ``Annotated``
|
|
161
|
+
metadata, ``Literal`` values and call arguments (``ForeignKey("user.id")``)
|
|
162
|
+
are left alone, and so is a subscripted (generic) alias such as
|
|
163
|
+
``Pk[int]``. Each value in ``aliases`` must already be resolved where
|
|
164
|
+
it is defined: it is inserted as is, never expanded again with the
|
|
165
|
+
names of the place that uses it. ``node`` itself is never modified.
|
|
166
|
+
"""
|
|
167
|
+
if not aliases or not _mentions_alias(node, aliases):
|
|
168
|
+
return node
|
|
169
|
+
if isinstance(node, ast.Name):
|
|
170
|
+
return aliases.get(node.id, node)
|
|
171
|
+
if isinstance(node, ast.Constant):
|
|
172
|
+
parsed = parse_quoted(node)
|
|
173
|
+
if parsed is None:
|
|
174
|
+
return node
|
|
175
|
+
expanded = expand_aliases(parsed, aliases)
|
|
176
|
+
return expanded if expanded is not parsed else node
|
|
177
|
+
if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
|
|
178
|
+
return ast.BinOp(
|
|
179
|
+
left=expand_aliases(node.left, aliases),
|
|
180
|
+
op=node.op,
|
|
181
|
+
right=expand_aliases(node.right, aliases),
|
|
182
|
+
)
|
|
183
|
+
if isinstance(node, ast.Subscript):
|
|
184
|
+
name, args = subscript_parts(node)
|
|
185
|
+
if (
|
|
186
|
+
not args
|
|
187
|
+
or name == "Literal"
|
|
188
|
+
or (isinstance(node.value, ast.Name) and node.value.id in aliases)
|
|
189
|
+
):
|
|
190
|
+
return node
|
|
191
|
+
# Annotated: only the type is a type position, not the metadata.
|
|
192
|
+
parts: List[ast.expr] = [expand_aliases(args[0], aliases)] + (
|
|
193
|
+
args[1:] if name == "Annotated" else [expand_aliases(a, aliases) for a in args[1:]]
|
|
194
|
+
)
|
|
195
|
+
slice_: ast.expr = (
|
|
196
|
+
ast.Tuple(elts=parts, ctx=ast.Load()) if isinstance(node.slice, ast.Tuple) else parts[0]
|
|
197
|
+
)
|
|
198
|
+
return ast.Subscript(value=node.value, slice=slice_, ctx=node.ctx)
|
|
199
|
+
return node
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def _mentions_alias(node: ast.expr, aliases: Mapping[str, ast.expr]) -> bool:
|
|
203
|
+
"""Whether an alias name, or any string (a possible quoted alias), occurs in ``node``."""
|
|
204
|
+
return any(
|
|
205
|
+
(isinstance(sub, ast.Name) and sub.id in aliases)
|
|
206
|
+
or (isinstance(sub, ast.Constant) and isinstance(sub.value, str))
|
|
207
|
+
for sub in ast.walk(node)
|
|
208
|
+
)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def defines_column_alias(value: ast.expr) -> bool:
|
|
212
|
+
"""``Annotated[X, ..., mapped_column(...), ...]``: an alias carrying column settings.
|
|
213
|
+
|
|
214
|
+
Other ``Annotated`` aliases (e.g. Pydantic's ``PositiveInt = Annotated[int,
|
|
215
|
+
Gt(0)]``) keep their name as the displayed type.
|
|
216
|
+
"""
|
|
217
|
+
if not isinstance(value, ast.Subscript) or subscript_parts(value)[0] != "Annotated":
|
|
218
|
+
return False
|
|
219
|
+
# column_metadata flattens nested Annotated, as typing does.
|
|
220
|
+
return any(is_call_to(arg, "mapped_column") for arg in column_metadata(value))
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def column_metadata(node: ast.expr) -> List[ast.expr]:
|
|
224
|
+
"""The ``Annotated`` metadata that applies to a column, innermost first (#241).
|
|
225
|
+
|
|
226
|
+
Follows the same wrappers as :func:`column_type`: ``Mapped`` and its
|
|
227
|
+
variants, type qualifiers, quotes, and an optional type (``Optional[X]``,
|
|
228
|
+
``X | None``), but not a union of several types.
|
|
229
|
+
"""
|
|
230
|
+
if isinstance(node, ast.Constant):
|
|
231
|
+
parsed = parse_quoted(node)
|
|
232
|
+
return column_metadata(parsed) if parsed is not None else []
|
|
233
|
+
if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
|
|
234
|
+
rest = [option for option in union_operands(node) if not is_none(option)]
|
|
235
|
+
return column_metadata(rest[0]) if len(rest) == 1 else []
|
|
236
|
+
if not isinstance(node, ast.Subscript):
|
|
237
|
+
return []
|
|
238
|
+
name, args = subscript_parts(node)
|
|
239
|
+
if not args:
|
|
240
|
+
return []
|
|
241
|
+
if name == "Annotated":
|
|
242
|
+
return [*column_metadata(args[0]), *args[1:]]
|
|
243
|
+
if name in TRANSPARENT_WRAPPERS | MANY_WRAPPERS | QUALIFIERS:
|
|
244
|
+
return column_metadata(args[0])
|
|
245
|
+
if name == "Optional" and len(args) == 1:
|
|
246
|
+
return column_metadata(args[0])
|
|
247
|
+
if name == "Union":
|
|
248
|
+
rest = [option for option in args if not is_none(option)]
|
|
249
|
+
return column_metadata(rest[0]) if len(rest) == 1 else []
|
|
250
|
+
return []
|
|
251
|
+
|
|
252
|
+
|
|
155
253
|
def literal_admits_none(args: List[ast.expr]) -> bool:
|
|
156
254
|
"""``Literal[..., None]``, also nested (``Literal[Literal[None], "a"]``).
|
|
157
255
|
|
|
@@ -267,4 +365,4 @@ def is_mapped_annotation(annotation: ast.expr) -> bool:
|
|
|
267
365
|
|
|
268
366
|
def as_rel(ref: _AnnotationRef, attr: str) -> _Rel:
|
|
269
367
|
"""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)
|
|
368
|
+
return _Rel(ref.target, "many" if ref.many else "one", attr, ref.nullable and not ref.many)
|
|
@@ -2,16 +2,28 @@
|
|
|
2
2
|
|
|
3
3
|
import ast
|
|
4
4
|
import re
|
|
5
|
-
from typing import Dict, List, Tuple, TypeVar
|
|
5
|
+
from typing import Dict, List, NamedTuple, Tuple, TypeVar
|
|
6
6
|
|
|
7
7
|
from ..config import FieldInfo
|
|
8
8
|
|
|
9
9
|
_V = TypeVar("_V")
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
11
|
+
|
|
12
|
+
class _Rel(NamedTuple):
|
|
13
|
+
"""A relationship while parsing.
|
|
14
|
+
|
|
15
|
+
The public ``EntityInfo.relationships`` keeps ``(target, kind, attr)``;
|
|
16
|
+
``nullable`` goes to ``EntityInfo.nullable_relationships`` and
|
|
17
|
+
``inverse`` to ``EntityInfo.inverse_relationships``.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
target: str
|
|
21
|
+
kind: str
|
|
22
|
+
attr: str
|
|
23
|
+
nullable: bool
|
|
24
|
+
#: The other side's attribute, when named explicitly (``back_populates=``).
|
|
25
|
+
inverse: str | None = None
|
|
26
|
+
|
|
15
27
|
|
|
16
28
|
# A class body's (fields, relationships, declared attribute names).
|
|
17
29
|
_ClassMembers = Tuple[Dict[str, FieldInfo], Dict[str, _Rel], List[str]]
|
|
@@ -5,9 +5,10 @@ import sys
|
|
|
5
5
|
from dataclasses import dataclass
|
|
6
6
|
from fnmatch import fnmatchcase
|
|
7
7
|
from pathlib import Path
|
|
8
|
-
from typing import Dict, List, Tuple
|
|
8
|
+
from typing import Callable, Dict, List, Mapping, Tuple
|
|
9
9
|
|
|
10
10
|
from ..config import EntityInfo, EnumInfo, is_structural_link_table
|
|
11
|
+
from .aliases import AliasResolver
|
|
11
12
|
from .common import is_enum_class, to_snake_case
|
|
12
13
|
from .dialects import ParseContext
|
|
13
14
|
from .discovery import discover_model_files
|
|
@@ -110,6 +111,8 @@ class ASTDatabaseParser:
|
|
|
110
111
|
self._enums: Dict[str, EnumInfo] = {}
|
|
111
112
|
self._all_classes: Dict[str, ast.ClassDef] = {} # Store all class definitions
|
|
112
113
|
self._file_trees: Dict[Path, ast.Module] = {}
|
|
114
|
+
#: The file each class definition (by ``id`` of its node) was read from.
|
|
115
|
+
self._class_files: Dict[int, Path] = {}
|
|
113
116
|
#: Classes and dialects (with their caches); renewed for each parse run.
|
|
114
117
|
self._ctx = self._new_context()
|
|
115
118
|
|
|
@@ -138,6 +141,7 @@ class ASTDatabaseParser:
|
|
|
138
141
|
for node in ast.walk(tree):
|
|
139
142
|
if isinstance(node, ast.ClassDef):
|
|
140
143
|
self._all_classes[node.name] = node
|
|
144
|
+
self._class_files[id(node)] = model_file
|
|
141
145
|
except Exception as e:
|
|
142
146
|
print(f"Error parsing {model_file}: {e}", file=sys.stderr)
|
|
143
147
|
self._parse_errors.append((model_file, str(e)))
|
|
@@ -217,6 +221,11 @@ class ASTDatabaseParser:
|
|
|
217
221
|
entity.nullable_relationships = [
|
|
218
222
|
attr for attr in entity.nullable_relationships if attr in kept
|
|
219
223
|
]
|
|
224
|
+
entity.inverse_relationships = {
|
|
225
|
+
attr: inverse
|
|
226
|
+
for attr, inverse in entity.inverse_relationships.items()
|
|
227
|
+
if attr in kept
|
|
228
|
+
}
|
|
220
229
|
|
|
221
230
|
def _parse_enum_class(self, class_node: ast.ClassDef) -> None:
|
|
222
231
|
"""Parse an enum class and extract its values."""
|
|
@@ -237,8 +246,19 @@ class ASTDatabaseParser:
|
|
|
237
246
|
infer_keys=self.infer_keys,
|
|
238
247
|
django_raw_types=self.django_raw_types,
|
|
239
248
|
base_classes=self.base_classes,
|
|
249
|
+
aliases_for=self._alias_lookup(),
|
|
240
250
|
)
|
|
241
251
|
|
|
252
|
+
def _alias_lookup(self) -> "Callable[[ast.ClassDef], Mapping[str, ast.expr]]":
|
|
253
|
+
"""Class -> the column type aliases visible where it is defined (#249, #250)."""
|
|
254
|
+
resolver = AliasResolver(self._file_trees, self._all_classes)
|
|
255
|
+
class_files = self._class_files
|
|
256
|
+
|
|
257
|
+
def aliases_for(class_node: ast.ClassDef) -> Mapping[str, ast.expr]:
|
|
258
|
+
return resolver.aliases_for(class_files.get(id(class_node)), class_node.lineno)
|
|
259
|
+
|
|
260
|
+
return aliases_for
|
|
261
|
+
|
|
242
262
|
def _classify_source(self, class_node: ast.ClassDef) -> str | None:
|
|
243
263
|
"""Classify which model framework a class belongs to (:meth:`ParseContext.classify`).
|
|
244
264
|
|
|
@@ -269,10 +289,10 @@ class ASTDatabaseParser:
|
|
|
269
289
|
fields_dict, relationships_dict = dialect.collect(class_node)
|
|
270
290
|
|
|
271
291
|
entity.fields = list(fields_dict.values())
|
|
272
|
-
|
|
273
|
-
entity.
|
|
274
|
-
|
|
275
|
-
|
|
292
|
+
rels = list(relationships_dict.values())
|
|
293
|
+
entity.relationships = [(r.target, r.kind, r.attr) for r in rels]
|
|
294
|
+
entity.nullable_relationships = [r.attr for r in rels if r.nullable]
|
|
295
|
+
entity.inverse_relationships = {r.attr: r.inverse for r in rels if r.inverse}
|
|
276
296
|
|
|
277
297
|
dialect.finish(entity, class_node)
|
|
278
298
|
|
|
@@ -7,10 +7,17 @@ and in which of these member kinds they accept.
|
|
|
7
7
|
"""
|
|
8
8
|
|
|
9
9
|
import ast
|
|
10
|
-
from typing import Dict, Tuple
|
|
10
|
+
from typing import Dict, List, Tuple
|
|
11
11
|
|
|
12
12
|
from ...config import FieldInfo
|
|
13
|
-
from ..annotations import
|
|
13
|
+
from ..annotations import (
|
|
14
|
+
annotation_reference,
|
|
15
|
+
as_rel,
|
|
16
|
+
column_metadata,
|
|
17
|
+
column_type,
|
|
18
|
+
expand_aliases,
|
|
19
|
+
is_call_to,
|
|
20
|
+
)
|
|
14
21
|
from ..common import _Rel
|
|
15
22
|
from .base import Dialect
|
|
16
23
|
|
|
@@ -33,6 +40,8 @@ class AnnotatedDialect(Dialect):
|
|
|
33
40
|
for node in class_node.body:
|
|
34
41
|
if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
|
|
35
42
|
field_name = node.target.id
|
|
43
|
+
if self.reads_annotated_columns:
|
|
44
|
+
node = self._with_aliases_expanded(node, class_node)
|
|
36
45
|
|
|
37
46
|
# Skip special attributes
|
|
38
47
|
if field_name.startswith("_"):
|
|
@@ -65,6 +74,29 @@ class AnnotatedDialect(Dialect):
|
|
|
65
74
|
|
|
66
75
|
return fields, relationships
|
|
67
76
|
|
|
77
|
+
@staticmethod
|
|
78
|
+
def _declares_default(value: ast.expr | None) -> bool:
|
|
79
|
+
"""Whether the assigned value sets a default, even one that cannot be shown."""
|
|
80
|
+
if value is None:
|
|
81
|
+
return False
|
|
82
|
+
if not is_call_to(value, "mapped_column"):
|
|
83
|
+
return True # `x: Mapped[str] = "a"` (MappedAsDataclass)
|
|
84
|
+
return any(
|
|
85
|
+
kw.arg in ("default", "default_factory", "insert_default") for kw in value.keywords
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
def _with_aliases_expanded(
|
|
89
|
+
self, node: ast.AnnAssign, class_node: ast.ClassDef
|
|
90
|
+
) -> ast.AnnAssign:
|
|
91
|
+
"""``node`` with column type aliases expanded, as seen where its class is defined."""
|
|
92
|
+
annotation = expand_aliases(node.annotation, self.ctx.aliases_for(class_node))
|
|
93
|
+
if annotation is node.annotation:
|
|
94
|
+
return node
|
|
95
|
+
expanded = ast.AnnAssign(
|
|
96
|
+
target=node.target, annotation=annotation, value=node.value, simple=node.simple
|
|
97
|
+
)
|
|
98
|
+
return ast.copy_location(expanded, node)
|
|
99
|
+
|
|
68
100
|
def _parse_field(self, node: ast.AnnAssign) -> FieldInfo | None:
|
|
69
101
|
"""Parse a field from an annotated assignment."""
|
|
70
102
|
if not isinstance(node.target, ast.Name):
|
|
@@ -73,42 +105,59 @@ class AnnotatedDialect(Dialect):
|
|
|
73
105
|
field_name = node.target.id
|
|
74
106
|
type_str, is_nullable = column_type(node.annotation)
|
|
75
107
|
|
|
76
|
-
#
|
|
108
|
+
# As in SQLAlchemy, the first mapped_column() in the Annotated metadata
|
|
109
|
+
# (#241) is merged with the assigned Field() (SQLModel) / mapped_column()
|
|
110
|
+
# (SQLAlchemy), bare or qualified (e.g. orm.mapped_column): what the
|
|
111
|
+
# assigned call sets wins, except that primary_key=True from either
|
|
112
|
+
# sticks. SQLModel ignores Field() keys in Annotated metadata.
|
|
113
|
+
metadata_calls = (
|
|
114
|
+
[
|
|
115
|
+
call
|
|
116
|
+
for call in column_metadata(node.annotation)
|
|
117
|
+
if is_call_to(call, "mapped_column")
|
|
118
|
+
][:1]
|
|
119
|
+
if self.reads_annotated_columns
|
|
120
|
+
else []
|
|
121
|
+
)
|
|
122
|
+
calls: List[ast.Call] = list(metadata_calls)
|
|
123
|
+
if node.value is not None and (
|
|
124
|
+
is_call_to(node.value, "Field") or is_call_to(node.value, "mapped_column")
|
|
125
|
+
):
|
|
126
|
+
calls.append(node.value)
|
|
127
|
+
|
|
77
128
|
is_primary_key = False
|
|
78
129
|
is_foreign_key = False
|
|
79
130
|
foreign_table = None
|
|
80
131
|
index = False
|
|
81
132
|
is_unique = False
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
is_primary_key = bool(keyword.value.value)
|
|
90
|
-
elif keyword.arg == "foreign_key" and isinstance(keyword.value, ast.Constant):
|
|
91
|
-
is_foreign_key = True
|
|
92
|
-
foreign_table = str(keyword.value.value)
|
|
93
|
-
elif keyword.arg == "index" and isinstance(keyword.value, ast.Constant):
|
|
94
|
-
index = bool(keyword.value.value)
|
|
95
|
-
elif keyword.arg == "unique" and isinstance(keyword.value, ast.Constant):
|
|
96
|
-
is_unique = bool(keyword.value.value)
|
|
97
|
-
elif (
|
|
98
|
-
keyword.arg == "nullable"
|
|
99
|
-
and isinstance(keyword.value, ast.Constant)
|
|
100
|
-
and isinstance(keyword.value.value, bool)
|
|
101
|
-
):
|
|
102
|
-
# An explicit nullable=True/False is what the database gets
|
|
103
|
-
# and overrides the annotation; nullable=None means
|
|
104
|
-
# "unspecified", so the annotation still decides.
|
|
105
|
-
is_nullable = keyword.value.value
|
|
106
|
-
|
|
107
|
-
# SQLAlchemy: ForeignKey("table.col") passed to mapped_column()
|
|
108
|
-
fk_target = extract_foreign_key_arg(node.value)
|
|
109
|
-
if fk_target is not None:
|
|
133
|
+
for call in calls:
|
|
134
|
+
for keyword in call.keywords:
|
|
135
|
+
if isinstance(keyword.value, ast.Constant) and keyword.value.value is None:
|
|
136
|
+
continue # `index=None` etc. means "unspecified" in SQLAlchemy
|
|
137
|
+
if keyword.arg == "primary_key" and isinstance(keyword.value, ast.Constant):
|
|
138
|
+
is_primary_key = is_primary_key or bool(keyword.value.value)
|
|
139
|
+
elif keyword.arg == "foreign_key" and isinstance(keyword.value, ast.Constant):
|
|
110
140
|
is_foreign_key = True
|
|
111
|
-
foreign_table =
|
|
141
|
+
foreign_table = str(keyword.value.value)
|
|
142
|
+
elif keyword.arg == "index" and isinstance(keyword.value, ast.Constant):
|
|
143
|
+
index = bool(keyword.value.value)
|
|
144
|
+
elif keyword.arg == "unique" and isinstance(keyword.value, ast.Constant):
|
|
145
|
+
is_unique = bool(keyword.value.value)
|
|
146
|
+
elif (
|
|
147
|
+
keyword.arg == "nullable"
|
|
148
|
+
and isinstance(keyword.value, ast.Constant)
|
|
149
|
+
and isinstance(keyword.value.value, bool)
|
|
150
|
+
):
|
|
151
|
+
# An explicit nullable=True/False is what the database gets
|
|
152
|
+
# and overrides the annotation; nullable=None means
|
|
153
|
+
# "unspecified", so the annotation still decides.
|
|
154
|
+
is_nullable = keyword.value.value
|
|
155
|
+
|
|
156
|
+
# SQLAlchemy: ForeignKey("table.col") passed to mapped_column()
|
|
157
|
+
fk_target = extract_foreign_key_arg(call)
|
|
158
|
+
if fk_target is not None:
|
|
159
|
+
is_foreign_key = True
|
|
160
|
+
foreign_table = fk_target
|
|
112
161
|
|
|
113
162
|
# Optional name-based key inference for keyless sources (Pydantic/dataclass).
|
|
114
163
|
# Never overrides explicitly declared keys above.
|
|
@@ -121,6 +170,12 @@ class AnnotatedDialect(Dialect):
|
|
|
121
170
|
|
|
122
171
|
# Extract default value
|
|
123
172
|
default_value = self._extract_default_value(node)
|
|
173
|
+
for call in metadata_calls: # only when nothing assigned declares a default
|
|
174
|
+
if self._declares_default(node.value):
|
|
175
|
+
break
|
|
176
|
+
default_value = self._extract_default_value(
|
|
177
|
+
ast.AnnAssign(target=node.target, annotation=node.annotation, value=call, simple=1)
|
|
178
|
+
)
|
|
124
179
|
|
|
125
180
|
# A primary key is never NULL in the database. SQLModel's idiomatic
|
|
126
181
|
# `id: int | None = Field(default=None, primary_key=True)` only means
|
|
@@ -205,7 +260,34 @@ class AnnotatedDialect(Dialect):
|
|
|
205
260
|
ref = annotation_reference(node.annotation)
|
|
206
261
|
if ref is None: # names no single class (e.g. Mapped[A | B]): nothing to draw
|
|
207
262
|
return None
|
|
208
|
-
|
|
263
|
+
rel = as_rel(ref, node.target.id)
|
|
264
|
+
# back_populates= names the other side's attribute, so the two sides
|
|
265
|
+
# can be paired exactly (#240). backref= creates that side implicitly,
|
|
266
|
+
# so there is no second declaration to pair with.
|
|
267
|
+
if isinstance(node.value, ast.Call):
|
|
268
|
+
inverse = self._back_populates(node.value)
|
|
269
|
+
if inverse is not None:
|
|
270
|
+
rel = rel._replace(inverse=inverse)
|
|
271
|
+
return rel
|
|
272
|
+
|
|
273
|
+
@staticmethod
|
|
274
|
+
def _back_populates(call: ast.Call) -> str | None:
|
|
275
|
+
"""``back_populates="x"``, also SQLModel's ``sa_relationship_kwargs={...}`` form."""
|
|
276
|
+
for kw in call.keywords:
|
|
277
|
+
value = kw.value
|
|
278
|
+
if kw.arg == "back_populates":
|
|
279
|
+
if isinstance(value, ast.Constant) and isinstance(value.value, str):
|
|
280
|
+
return value.value
|
|
281
|
+
elif kw.arg == "sa_relationship_kwargs" and isinstance(value, ast.Dict):
|
|
282
|
+
for key, item in zip(value.keys, value.values):
|
|
283
|
+
if (
|
|
284
|
+
isinstance(key, ast.Constant)
|
|
285
|
+
and key.value == "back_populates"
|
|
286
|
+
and isinstance(item, ast.Constant)
|
|
287
|
+
and isinstance(item.value, str)
|
|
288
|
+
):
|
|
289
|
+
return item.value
|
|
290
|
+
return None
|
|
209
291
|
|
|
210
292
|
def _parse_model_reference(self, node: ast.AnnAssign) -> _Rel | None:
|
|
211
293
|
"""Treat a field typed as another known model as a relationship.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
import ast
|
|
4
4
|
from dataclasses import dataclass, field
|
|
5
|
-
from typing import ClassVar, Dict, Iterable, List, Set, Tuple
|
|
5
|
+
from typing import Callable, ClassVar, Dict, Iterable, List, Mapping, Set, Tuple
|
|
6
6
|
|
|
7
7
|
from ...config import EntityInfo, FieldInfo
|
|
8
8
|
from ..annotations import is_call_to
|
|
@@ -21,6 +21,9 @@ class ParseContext:
|
|
|
21
21
|
base_classes: Extra base-class names treated as Pydantic models.
|
|
22
22
|
dialects: One instance of every dialect, in ``MODEL_SOURCES`` order;
|
|
23
23
|
created on first use.
|
|
24
|
+
aliases_for: Column type aliases visible where a class is defined
|
|
25
|
+
(``intpk = Annotated[int, mapped_column(primary_key=True)]``,
|
|
26
|
+
#241, #249, #250).
|
|
24
27
|
"""
|
|
25
28
|
|
|
26
29
|
classes: ClassIndex = field(default_factory=lambda: ClassIndex({}))
|
|
@@ -28,6 +31,7 @@ class ParseContext:
|
|
|
28
31
|
django_raw_types: bool = False
|
|
29
32
|
base_classes: Set[str] = field(default_factory=set)
|
|
30
33
|
dialects: List["Dialect"] = field(default_factory=list)
|
|
34
|
+
aliases_for: Callable[[ast.ClassDef], Mapping[str, ast.expr]] = lambda _class_node: {}
|
|
31
35
|
|
|
32
36
|
def all_dialects(self) -> List["Dialect"]:
|
|
33
37
|
"""Every dialect, in classification order, bound to this context."""
|
|
@@ -73,6 +77,9 @@ class Dialect:
|
|
|
73
77
|
#: typed as another model is a relationship, and an optional primary key
|
|
74
78
|
#: really is optional.
|
|
75
79
|
keyless: ClassVar[bool] = False
|
|
80
|
+
#: Reads SQLAlchemy column settings from ``Annotated`` metadata and column
|
|
81
|
+
#: type aliases (#241); only SQLAlchemy itself does.
|
|
82
|
+
reads_annotated_columns: ClassVar[bool] = False
|
|
76
83
|
|
|
77
84
|
def __init__(self, ctx: ParseContext):
|
|
78
85
|
self.ctx = ctx
|
|
@@ -728,7 +728,7 @@ class DjangoDialect(Dialect):
|
|
|
728
728
|
return None
|
|
729
729
|
if any(keyword.arg == "through" for keyword in call.keywords):
|
|
730
730
|
return None
|
|
731
|
-
return (target, "many_to_many", name, False)
|
|
731
|
+
return _Rel(target, "many_to_many", name, False)
|
|
732
732
|
|
|
733
733
|
def _resolve_django_relationship_target(self, call: ast.Call, current_class: str) -> str | None:
|
|
734
734
|
"""Resolve a relationship field's target from its first positional or ``to=`` arg.
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|