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.
Files changed (27) hide show
  1. {erdify-1.3.0 → erdify-1.4.1}/PKG-INFO +1 -1
  2. {erdify-1.3.0 → erdify-1.4.1}/pyproject.toml +1 -1
  3. {erdify-1.3.0 → erdify-1.4.1}/pyproject.toml.orig +1 -1
  4. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/config.py +6 -1
  5. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/generator.py +184 -50
  6. erdify-1.4.1/src/erdify/parser/aliases.py +388 -0
  7. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/annotations.py +100 -2
  8. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/common.py +17 -5
  9. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/core.py +25 -5
  10. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/annotated.py +115 -33
  11. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/base.py +8 -1
  12. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/django.py +1 -1
  13. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/sqlalchemy.py +1 -0
  14. {erdify-1.3.0 → erdify-1.4.1}/LICENSE +0 -0
  15. {erdify-1.3.0 → erdify-1.4.1}/README.md +0 -0
  16. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/__init__.py +0 -0
  17. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/__main__.py +0 -0
  18. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/cli.py +0 -0
  19. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/inject.py +0 -0
  20. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/__init__.py +0 -0
  21. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/__init__.py +0 -0
  22. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/dialects/keyless.py +0 -0
  23. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/discovery.py +0 -0
  24. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/parser/inheritance.py +0 -0
  25. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/py.typed +0 -0
  26. {erdify-1.3.0 → erdify-1.4.1}/src/erdify/pyproject.py +0 -0
  27. {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.0
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,6 +1,6 @@
1
1
  [project]
2
2
  name = "erdify"
3
- version = "1.3.0"
3
+ version = "1.4.1"
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.3.0"
3
+ version = "1.4.1"
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,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 _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"
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 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.
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
- by_direction: Dict[Tuple[str, str], List[int]] = {}
245
+ by_pair: Dict[frozenset[str], List[int]] = {}
236
246
  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:
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 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
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
- # 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]
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
- entity.relationships = [(t, kind, attr) for t, kind, attr, _ in relationships_dict.values()]
273
- entity.nullable_relationships = [
274
- attr for _, _, attr, nullable in relationships_dict.values() if nullable
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 annotation_reference, as_rel, column_type, is_call_to
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
- # Parse Field() / mapped_column() parameters
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
- if node.value and isinstance(node.value, ast.Call):
84
- # Field() (SQLModel) / mapped_column() (SQLAlchemy), bare or qualified
85
- # (e.g. orm.mapped_column).
86
- if is_call_to(node.value, "Field") or is_call_to(node.value, "mapped_column"):
87
- for keyword in node.value.keywords:
88
- if keyword.arg == "primary_key" and isinstance(keyword.value, ast.Constant):
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 = fk_target
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
- return as_rel(ref, node.target.id)
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.
@@ -30,6 +30,7 @@ class SQLAlchemyDialect(AnnotatedDialect):
30
30
  """
31
31
 
32
32
  kind = "sqlalchemy"
33
+ reads_annotated_columns = True
33
34
 
34
35
  def detect(self, class_node: ast.ClassDef) -> bool:
35
36
  return has_tablename(class_node) and has_mapped_field(class_node)
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