erdify 1.1.0__tar.gz → 1.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: erdify
3
- Version: 1.1.0
3
+ Version: 1.2.0
4
4
  Summary: A zero-dependency ERD generator for your Python models — pure AST, no database required.
5
5
  Keywords: sqlmodel,sqlalchemy,django,pydantic,dataclass,erd,plantuml,diagram,database,erdify,sql,ddl
6
6
  Author: devsuit GmbH, Fabian Clemenz
@@ -27,7 +27,12 @@ Project-URL: Issues, https://github.com/devsuit-berlin/erdify/issues
27
27
  Provides-Extra: sql
28
28
  Description-Content-Type: text/markdown
29
29
 
30
- # 🗃️ erdify
30
+ <p align="center">
31
+ <picture>
32
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/devsuit-berlin/erdify/main/docs/assets/erdify-wordmark-dark.svg">
33
+ <img alt="erdify" src="https://raw.githubusercontent.com/devsuit-berlin/erdify/main/docs/assets/erdify-wordmark-light.svg" width="420">
34
+ </picture>
35
+ </p>
31
36
 
32
37
  [![PyPI version](https://img.shields.io/pypi/v/erdify)](https://pypi.org/project/erdify/)
33
38
  [![Python versions](https://img.shields.io/pypi/pyversions/erdify)](https://pypi.org/project/erdify/)
@@ -1,4 +1,9 @@
1
- # 🗃️ erdify
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/devsuit-berlin/erdify/main/docs/assets/erdify-wordmark-dark.svg">
4
+ <img alt="erdify" src="https://raw.githubusercontent.com/devsuit-berlin/erdify/main/docs/assets/erdify-wordmark-light.svg" width="420">
5
+ </picture>
6
+ </p>
2
7
 
3
8
  [![PyPI version](https://img.shields.io/pypi/v/erdify)](https://pypi.org/project/erdify/)
4
9
  [![Python versions](https://img.shields.io/pypi/pyversions/erdify)](https://pypi.org/project/erdify/)
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "erdify"
3
- version = "1.1.0"
3
+ version = "1.2.0"
4
4
  description = "A zero-dependency ERD generator for your Python models — pure AST, no database required."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -70,7 +70,7 @@ dev = [
70
70
  docs = ["mkdocs-material[imaging]"]
71
71
 
72
72
  [build-system]
73
- requires = ["uv_build>=0.11.19,<0.13.0"]
73
+ requires = ["uv_build>=0.11.19,<0.14.0"]
74
74
  build-backend = "uv_build"
75
75
 
76
76
  [tool.ruff]
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "erdify"
3
- version = "1.1.0"
3
+ version = "1.2.0"
4
4
  description = "A zero-dependency ERD generator for your Python models — pure AST, no database required."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -56,7 +56,7 @@ Changelog = "https://github.com/devsuit-berlin/erdify/blob/main/CHANGELOG.md"
56
56
  Issues = "https://github.com/devsuit-berlin/erdify/issues"
57
57
 
58
58
  [build-system]
59
- requires = ["uv_build>=0.11.19,<0.13.0"]
59
+ requires = ["uv_build>=0.11.19,<0.14.0"]
60
60
  build-backend = "uv_build"
61
61
 
62
62
  [tool.ruff]
@@ -352,7 +352,7 @@ def main() -> int:
352
352
  target = output_path.with_suffix(ext) if output_path is not None else None
353
353
 
354
354
  if args.check and target is not None:
355
- existing = target.read_text() if target.exists() else None
355
+ existing = target.read_text(encoding="utf-8") if target.exists() else None
356
356
  if existing == rendered:
357
357
  print(f"{fmt} ERD is up to date: {target}", file=sys.stderr)
358
358
  else:
@@ -366,7 +366,7 @@ def main() -> int:
366
366
 
367
367
  if target is not None:
368
368
  target.parent.mkdir(parents=True, exist_ok=True)
369
- target.write_text(rendered)
369
+ target.write_text(rendered, encoding="utf-8")
370
370
  print(f"Generated {fmt} ERD: {target}", file=sys.stderr)
371
371
  elif inject_path is None:
372
372
  print(rendered)
@@ -383,7 +383,10 @@ def main() -> int:
383
383
  )
384
384
  region = render_region(rendered, fence=fmt)
385
385
  try:
386
- with inject_path.open(newline="") as f:
386
+ # Always UTF-8, never the locale encoding: under a C/POSIX locale a
387
+ # non-ASCII character anywhere in the file would otherwise crash or
388
+ # make --check report a fresh region as stale (#219).
389
+ with inject_path.open(encoding="utf-8", newline="") as f:
387
390
  existing_text = f.read()
388
391
  except FileNotFoundError:
389
392
  print(f"Error: --inject target not found: {inject_path}", file=sys.stderr)
@@ -401,7 +404,7 @@ def main() -> int:
401
404
  stale = True
402
405
  else:
403
406
  new_text = inject(existing_text, region)
404
- with inject_path.open("w", newline="") as f:
407
+ with inject_path.open("w", encoding="utf-8", newline="") as f:
405
408
  f.write(new_text)
406
409
  print(f"Injected {fmt} ERD into {inject_path}", file=sys.stderr)
407
410
  except MarkerError as e:
@@ -63,6 +63,10 @@ class EntityInfo:
63
63
  source: The model kind that produced the entity: one of ``MODEL_SOURCES``
64
64
  (``sqlmodel``, ``sqlalchemy``, ``django``, ``dataclass``,
65
65
  ``pydantic``) or ``sql`` for SQL DDL.
66
+ nullable_relationships: Attribute names of ``"one"`` relationships whose
67
+ reference is optional (e.g. ``user: User | None``); drawn as
68
+ zero-or-one on the target side. Foreign-key columns carry their own
69
+ ``FieldInfo.is_nullable`` instead.
66
70
  """
67
71
 
68
72
  name: str
@@ -74,6 +78,7 @@ class EntityInfo:
74
78
  is_link_table: bool = False
75
79
  base_classes: List[str] = field(default_factory=list)
76
80
  source: str = "sqlmodel"
81
+ nullable_relationships: List[str] = field(default_factory=list)
77
82
 
78
83
 
79
84
  def is_structural_link_table(fields: List[FieldInfo]) -> bool:
@@ -70,7 +70,7 @@ class _ERGenerator:
70
70
  return link_map
71
71
 
72
72
  @staticmethod
73
- def _fk_glyph(field: FieldInfo) -> str:
73
+ def _fk_glyph(field: FieldInfo, sole_pk: bool = False) -> str:
74
74
  """Crow's-foot glyph for a direct FK edge, written ``child ... parent``.
75
75
 
76
76
  Each end counts that entity per one instance of the other. The child
@@ -80,11 +80,17 @@ class _ERGenerator:
80
80
  forces a parent to have a child, so it is never a mandatory ``||``.
81
81
  The parent end (right) is how many parents a child has, governed by FK
82
82
  nullability: exactly one (``||``) when NOT NULL, zero-or-one (``o|``)
83
- when nullable. A unique FK is thus rendered 1:1 (``|o--||`` / ``|o--o|``).
83
+ when nullable (#216). A unique FK is thus rendered 1:1 (``|o--||`` /
84
+ ``|o--o|``), a non-unique one N:1 (``}o--||`` / ``}o--o|``).
85
+
86
+ ``sole_pk`` marks an FK that is the entity's *only* primary-key column
87
+ (the shared-primary-key 1:1): the key makes it unique by definition, so
88
+ it is drawn 1:1 too (#222). In a composite PK the FK alone is not
89
+ unique and stays N:1.
84
90
  """
85
- if not field.is_unique:
86
- return "}o--||"
87
- return "|o--o|" if field.is_nullable else "|o--||"
91
+ child = "|o" if field.is_unique or sole_pk else "}o"
92
+ parent = "o|" if field.is_nullable else "||"
93
+ return f"{child}--{parent}"
88
94
 
89
95
  def _entity_by_table(self, table_name: str) -> EntityInfo | None:
90
96
  """Find an entity by its table name."""
@@ -109,6 +115,7 @@ class _ERGenerator:
109
115
  ) -> List[str]:
110
116
  """Generate direct relationships (foreign keys without link tables)."""
111
117
  lines: List[str] = []
118
+ single_pk = sum(f.is_primary_key for f in entity.fields) == 1
112
119
  for field in entity.fields:
113
120
  if field.is_foreign_key and field.foreign_table:
114
121
  target_table = field.foreign_table.split(".")[0]
@@ -118,7 +125,7 @@ class _ERGenerator:
118
125
  target_entity = e
119
126
  break
120
127
  if target_entity:
121
- glyph = self._fk_glyph(field)
128
+ glyph = self._fk_glyph(field, sole_pk=single_pk and field.is_primary_key)
122
129
  lines.append(f'{entity.name} {glyph} {target_entity.name} : "{field.name}"')
123
130
  return lines
124
131
 
@@ -178,6 +185,8 @@ class _ERGenerator:
178
185
  line = f'{entity.name} ||--|| {target.name} : "{attr}"'
179
186
  elif rel_type == "many_to_many":
180
187
  line = f'{entity.name} }}o--o{{ {target.name} : "{attr}"'
188
+ elif attr in entity.nullable_relationships: # optional "one" (#223)
189
+ line = f'{entity.name} }}o--o| {target.name} : "{attr}"'
181
190
  else: # "one"
182
191
  line = f'{entity.name} }}o--|| {target.name} : "{attr}"'
183
192
  results.append((line, frozenset((entity.name, target.name))))
@@ -502,7 +511,8 @@ def generate_json(
502
511
 
503
512
  Shape: ``{schema_version, title, entities: [{name, table_name, source, is_link_table,
504
513
  fields: [{name, type, primary_key, foreign_key, nullable, foreign_table,
505
- index, unique, default}], relationships: [{target, type, attribute}]}], enums:
514
+ index, unique, default}], relationships: [{target, type, attribute, nullable}]}],
515
+ enums:
506
516
  [{name, values}]}``. Downstream tools can consume this without re-parsing.
507
517
  ``schema_version`` is :data:`JSON_SCHEMA_VERSION`; consumers should ignore
508
518
  keys they do not know. The full schema is documented in
@@ -544,7 +554,12 @@ def generate_json(
544
554
  ],
545
555
  "relationships": (
546
556
  [
547
- {"target": target, "type": rel_type, "attribute": attr}
557
+ {
558
+ "target": target,
559
+ "type": rel_type,
560
+ "attribute": attr,
561
+ "nullable": rel_type == "one" and attr in entity.nullable_relationships,
562
+ }
548
563
  for target, rel_type, attr in entity.relationships
549
564
  ]
550
565
  if include_relationships
@@ -4,10 +4,10 @@ import ast
4
4
  import os
5
5
  import re
6
6
  import sys
7
- from dataclasses import dataclass
7
+ from dataclasses import dataclass, replace
8
8
  from fnmatch import fnmatchcase
9
9
  from pathlib import Path
10
- from typing import Dict, List, Tuple, TypeGuard
10
+ from typing import Dict, List, Mapping, Tuple, TypeGuard, TypeVar
11
11
 
12
12
  from .config import EntityInfo, EnumInfo, FieldInfo, is_structural_link_table
13
13
 
@@ -37,6 +37,16 @@ DEFAULT_EXCLUDE_DIRS = frozenset(
37
37
  #: Django relationship field constructs (everything else ending in "Field" is a column).
38
38
  DJANGO_RELATIONSHIP_FIELDS = frozenset({"ForeignKey", "OneToOneField", "ManyToManyField"})
39
39
 
40
+ _V = TypeVar("_V")
41
+
42
+ # A relationship while parsing: (target, type, attribute, nullable). The
43
+ # public EntityInfo.relationships keeps (target, type, attribute); the flag
44
+ # goes to EntityInfo.nullable_relationships.
45
+ _Rel = Tuple[str, str, str, bool]
46
+
47
+ # A class body's (fields, relationships, declared attribute names).
48
+ _ClassMembers = Tuple[Dict[str, FieldInfo], Dict[str, _Rel], List[str]]
49
+
40
50
  #: Conservative Django field -> Python type map for readable, source-consistent
41
51
  #: output. Ambiguous/lossy fields (JSONField, FileField, ImageField, custom or
42
52
  #: third-party fields) are intentionally omitted so they fall back to the Django
@@ -215,6 +225,9 @@ class ASTDatabaseParser:
215
225
  self._entities: Dict[str, EntityInfo] = {}
216
226
  self._enums: Dict[str, EnumInfo] = {}
217
227
  self._all_classes: Dict[str, ast.ClassDef] = {} # Store all class definitions
228
+ self._mro_cache: Dict[str, List[str] | None] = {}
229
+ self._target_column_cache: Dict[Tuple[str, str | None], Tuple[str, str]] = {}
230
+ self._dataclass_cache: Dict[str, Tuple[Dict[str, FieldInfo], Dict[str, _Rel]]] = {}
218
231
  self._file_trees: Dict[Path, ast.Module] = {}
219
232
 
220
233
  def parse_all_models(self) -> Tuple[Dict[str, EntityInfo], Dict[str, EnumInfo]]:
@@ -233,7 +246,7 @@ class ASTDatabaseParser:
233
246
  # First pass: parse all files and collect class definitions
234
247
  for model_file in model_files:
235
248
  try:
236
- with open(model_file, "r") as f:
249
+ with open(model_file, encoding="utf-8") as f: # PEP 3120 default
237
250
  content = f.read()
238
251
  tree = ast.parse(content)
239
252
  self._file_trees[model_file] = tree
@@ -250,6 +263,9 @@ class ASTDatabaseParser:
250
263
  raise ModelParseError(self._parse_errors)
251
264
 
252
265
  # Second pass: process enum and model classes
266
+ self._mro_cache = {}
267
+ self._target_column_cache = {}
268
+ self._dataclass_cache = {}
253
269
  for class_node in self._all_classes.values():
254
270
  if self._is_enum_class(class_node):
255
271
  self._parse_enum_class(class_node)
@@ -382,6 +398,10 @@ class ASTDatabaseParser:
382
398
  entity.relationships = [
383
399
  rel for rel in entity.relationships if rel[0] not in excluded_names
384
400
  ]
401
+ kept = {attr for _, _, attr in entity.relationships}
402
+ entity.nullable_relationships = [
403
+ attr for attr in entity.nullable_relationships if attr in kept
404
+ ]
385
405
 
386
406
  #: Enum base class names recognized by erdify (stdlib Enum + Django choices).
387
407
  _ENUM_BASES = frozenset({"Enum", "TextChoices", "IntegerChoices"})
@@ -637,15 +657,30 @@ class ASTDatabaseParser:
637
657
 
638
658
  # Collect fields from this class and all base classes (recursively)
639
659
  fields_dict: Dict[str, FieldInfo] = {}
640
- relationships_dict: Dict[str, Tuple[str, str, str]] = {}
660
+ relationships_dict: Dict[str, _Rel] = {}
641
661
 
642
662
  # Recursively collect fields from all ancestors
643
- base_fields, base_rels = self._collect_fields_recursive(class_node, set(), source)
663
+ base_fields, base_rels = self._collect_fields(class_node, source)
644
664
  fields_dict.update(base_fields)
645
665
  relationships_dict.update(base_rels)
646
666
 
647
667
  entity.fields = list(fields_dict.values())
648
- entity.relationships = list(relationships_dict.values())
668
+ entity.relationships = [(t, kind, attr) for t, kind, attr, _ in relationships_dict.values()]
669
+ entity.nullable_relationships = [
670
+ attr for _, _, attr, nullable in relationships_dict.values() if nullable
671
+ ]
672
+
673
+ # Single-column UniqueConstraint / unique Index in __table_args__ (#218).
674
+ # Constraints name the *database* column, which mapped_column("col", ...)
675
+ # may set apart from the attribute name (#221).
676
+ # A string names the DB column; a bare reference names the attribute.
677
+ unique_cols, unique_refs = self._table_args_unique_columns(class_node)
678
+ db_names = self._db_column_names(class_node)
679
+ for f in entity.fields:
680
+ if f.is_primary_key:
681
+ continue
682
+ if db_names.get(f.name, f.name) in unique_cols or f.name in unique_refs:
683
+ f.is_unique = True
649
684
 
650
685
  # Django implicitly adds an `id` primary key (BigAutoField since Django 3.2)
651
686
  # when no field declares primary_key=True.
@@ -668,6 +703,133 @@ class ASTDatabaseParser:
668
703
 
669
704
  _is_structural_link_table = staticmethod(is_structural_link_table)
670
705
 
706
+ def _db_column_names(self, class_node: ast.ClassDef) -> Dict[str, str]:
707
+ """Map attribute name -> explicit DB column name for a class and its bases.
708
+
709
+ See :meth:`_explicit_column_name` for the recognized forms. A column
710
+ without an explicit name maps to itself, so a redeclaration without one
711
+ overrides an inherited name. Bases resolve in the same order as the
712
+ fields (:meth:`_merge_order`), so the name matches the winning column.
713
+ """
714
+ names: Dict[str, str] = {}
715
+ for class_name in self._merge_order(class_node):
716
+ for node in self._all_classes[class_name].body:
717
+ if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
718
+ db_name = self._explicit_column_name(node.value)
719
+ names[node.target.id] = db_name if db_name is not None else node.target.id
720
+ return names
721
+
722
+ @classmethod
723
+ def _explicit_column_name(cls, value: ast.expr | None) -> str | None:
724
+ """Return the name a string constraint uses for this column, if explicit.
725
+
726
+ Recognizes ``mapped_column("name", ...)`` / ``mapped_column(name="name")``,
727
+ and SQLModel's ``Field(sa_column=Column("name", ...))`` /
728
+ ``Field(sa_column_kwargs={"name": "name"})``. SQLAlchemy resolves a
729
+ constraint's string column through the column *key*, which defaults to
730
+ the name, so an explicit ``key=`` takes precedence.
731
+ """
732
+ if value is None:
733
+ return None
734
+ if cls._is_call_to(value, "mapped_column") or cls._is_call_to(value, "Column"):
735
+ for kw in value.keywords:
736
+ if (
737
+ kw.arg == "key"
738
+ and isinstance(kw.value, ast.Constant)
739
+ and isinstance(kw.value.value, str)
740
+ ):
741
+ return kw.value.value
742
+ if (
743
+ value.args
744
+ and isinstance(value.args[0], ast.Constant)
745
+ and isinstance(value.args[0].value, str)
746
+ ):
747
+ return value.args[0].value
748
+ for kw in value.keywords:
749
+ if (
750
+ kw.arg == "name"
751
+ and isinstance(kw.value, ast.Constant)
752
+ and isinstance(kw.value.value, str)
753
+ ):
754
+ return kw.value.value
755
+ return None
756
+ if cls._is_call_to(value, "Field"):
757
+ for kw in value.keywords:
758
+ if kw.arg == "sa_column":
759
+ return cls._explicit_column_name(kw.value)
760
+ if kw.arg == "sa_column_kwargs" and isinstance(kw.value, ast.Dict):
761
+ opts = {
762
+ key.value: val.value
763
+ for key, val in zip(kw.value.keys, kw.value.values)
764
+ if isinstance(key, ast.Constant)
765
+ and isinstance(val, ast.Constant)
766
+ and isinstance(val.value, str)
767
+ }
768
+ # As above: an explicit key wins over the name.
769
+ found = opts.get("key", opts.get("name"))
770
+ if isinstance(found, str):
771
+ return found
772
+ return None
773
+
774
+ @classmethod
775
+ def _table_args_unique_columns(cls, class_node: ast.ClassDef) -> Tuple[set[str], set[str]]:
776
+ """Columns made unique on their own by the class's ``__table_args__``.
777
+
778
+ Recognizes ``UniqueConstraint("col")`` and ``Index("name", "col",
779
+ unique=True)`` with exactly one column, in a tuple/list ``__table_args__``
780
+ (a trailing options dict is ignored). Composite constraints and partial
781
+ indexes (``*_where=``) do not make a column unique and are skipped.
782
+
783
+ Returns ``(db_columns, attribute_refs)``: a string names the *database*
784
+ column, while a bare reference (``UniqueConstraint(account_id)``) names
785
+ the attribute declared earlier in the class body.
786
+ """
787
+ value: ast.expr | None = None
788
+ for node in class_node.body:
789
+ if isinstance(node, ast.Assign):
790
+ if any(isinstance(t, ast.Name) and t.id == "__table_args__" for t in node.targets):
791
+ value = node.value
792
+ elif (
793
+ isinstance(node, ast.AnnAssign)
794
+ and isinstance(node.target, ast.Name)
795
+ and node.target.id == "__table_args__"
796
+ ):
797
+ value = node.value
798
+ columns: set[str] = set()
799
+ refs: set[str] = set()
800
+ if not isinstance(value, (ast.Tuple, ast.List)):
801
+ return columns, refs
802
+
803
+ for item in value.elts:
804
+ if cls._is_call_to(item, "UniqueConstraint"):
805
+ cols = item.args
806
+ elif cls._is_call_to(item, "Index"):
807
+ if not any(
808
+ kw.arg == "unique" and isinstance(kw.value, ast.Constant) and kw.value.value
809
+ for kw in item.keywords
810
+ ):
811
+ continue
812
+ # A partial index (postgresql_where=, sqlite_where=, ...) is only
813
+ # unique over a subset of rows, so it does not imply a 1:1. A
814
+ # literal `*_where=None` is "no predicate", i.e. not partial.
815
+ if any(
816
+ kw.arg
817
+ and kw.arg.endswith("_where")
818
+ and not (isinstance(kw.value, ast.Constant) and kw.value.value is None)
819
+ for kw in item.keywords
820
+ ):
821
+ continue
822
+ cols = item.args[1:] # first positional arg is the index name
823
+ else:
824
+ continue
825
+ if len(cols) == 1:
826
+ col = cols[0]
827
+ if isinstance(col, ast.Constant) and isinstance(col.value, str):
828
+ columns.add(col.value)
829
+ elif isinstance(col, ast.Name):
830
+ refs.add(col.id)
831
+ return columns, refs
832
+
671
833
  def _parse_core_association_tables(self) -> None:
672
834
  """Synthesize link entities from module-level Core ``Table(...)`` assignments.
673
835
 
@@ -768,45 +930,322 @@ class ASTDatabaseParser:
768
930
  isinstance(func, ast.Attribute) and func.attr == func_name
769
931
  )
770
932
 
771
- def _collect_fields_recursive(
772
- self, class_node: ast.ClassDef, visited: set[str], model_kind: str
773
- ) -> Tuple[Dict[str, FieldInfo], Dict[str, Tuple[str, str, str]]]:
774
- """Recursively collect fields from a class and all its ancestors."""
775
- fields_dict: Dict[str, FieldInfo] = {}
776
- relationships_dict: Dict[str, Tuple[str, str, str]] = {}
933
+ def _local_bases(self, class_node: ast.ClassDef) -> List[str]:
934
+ """Names of the direct bases that are classes parsed from the input."""
935
+ return [
936
+ base.id
937
+ for base in class_node.bases
938
+ if isinstance(base, ast.Name) and base.id in self._all_classes
939
+ ]
940
+
941
+ def _dfs_order(self, class_node: ast.ClassDef, visited: set[str]) -> List[str]:
942
+ """Classes in depth-first post-order: bases (left to right), then the class.
777
943
 
778
- # Avoid infinite recursion
944
+ Each class appears once. This is the order fields are listed in.
945
+ """
779
946
  if class_node.name in visited:
780
- return fields_dict, relationships_dict
947
+ return []
781
948
  visited.add(class_node.name)
949
+ order: List[str] = []
950
+ for base in self._local_bases(class_node):
951
+ order.extend(self._dfs_order(self._all_classes[base], visited))
952
+ order.append(class_node.name)
953
+ return order
954
+
955
+ def _mro(self, name: str, stack: Tuple[str, ...] = ()) -> List[str] | None:
956
+ """C3 linearization of a parsed class, like Python's ``__mro__``.
957
+
958
+ Bases outside the parsed files are ignored. Returns None when Python
959
+ would reject the hierarchy (no consistent order) or it is cyclic, e.g.
960
+ ``class User(User)`` extending a namesake.
961
+ """
962
+ if name in self._mro_cache:
963
+ return self._mro_cache[name]
964
+ if name in stack:
965
+ return None
966
+ bases = self._local_bases(self._all_classes[name])
967
+ seqs: List[List[str]] = []
968
+ for base in bases:
969
+ base_mro = self._mro(base, stack + (name,))
970
+ if base_mro is None:
971
+ self._mro_cache[name] = None
972
+ return None
973
+ seqs.append(base_mro)
974
+ seqs.append(list(bases))
975
+
976
+ result = [name]
977
+ seqs = [seq for seq in seqs if seq]
978
+ while seqs:
979
+ for seq in seqs:
980
+ head = seq[0]
981
+ if not any(head in other[1:] for other in seqs):
982
+ break
983
+ else:
984
+ self._mro_cache[name] = None
985
+ return None
986
+ result.append(head)
987
+ seqs = [[c for c in seq if c != head] for seq in seqs]
988
+ seqs = [seq for seq in seqs if seq]
989
+ self._mro_cache[name] = result
990
+ return result
991
+
992
+ def _merge_order(self, class_node: ast.ClassDef) -> List[str]:
993
+ """Classes to merge members from, where a later class overrides an earlier one.
994
+
995
+ This is the reversed MRO, so the class body wins over its bases and an
996
+ earlier base wins over a later one, as in Python (#228). Without a valid
997
+ MRO it falls back to :meth:`_dfs_order`.
998
+ """
999
+ mro = self._mro(class_node.name)
1000
+ if mro is None:
1001
+ return self._dfs_order(class_node, set())
1002
+ return mro[::-1]
782
1003
 
783
- # First, process all base classes recursively
784
- for base in class_node.bases:
785
- if isinstance(base, ast.Name):
786
- base_name = base.id
787
- if base_name in self._all_classes:
788
- base_fields, base_rels = self._collect_fields_recursive(
789
- self._all_classes[base_name], visited, model_kind
790
- )
791
- fields_dict.update(base_fields)
792
- relationships_dict.update(base_rels)
1004
+ def _collect_fields(
1005
+ self, class_node: ast.ClassDef, model_kind: str
1006
+ ) -> Tuple[Dict[str, FieldInfo], Dict[str, _Rel]]:
1007
+ """Collect the fields and relationships of a class and all its ancestors.
1008
+
1009
+ Which declaration of an attribute wins follows the MRO
1010
+ (:meth:`_merge_order`), or, for dataclasses, the dataclass field
1011
+ merge (:meth:`_dataclass_fields`). The order they are listed in is the
1012
+ one the pre-MRO merge produced (:meth:`_listing_order`), so resolving by
1013
+ MRO does not reorder the output.
1014
+ """
1015
+ dfs_order = self._dfs_order(class_node, set())
1016
+ merge_order = self._merge_order(class_node)
1017
+ members = {
1018
+ name: self._class_members(
1019
+ self._all_classes[name],
1020
+ model_kind,
1021
+ self._django_self_owner(name, merge_order) if model_kind == "django" else None,
1022
+ )
1023
+ for name in dfs_order
1024
+ }
1025
+ order_fields, order_rels = self._listing_order(class_node, set(), members, model_kind)
1026
+ if model_kind == "dataclass" and self._mro(class_node.name) is not None:
1027
+ fields, rels = self._dataclass_fields(class_node.name, members)
1028
+ else:
1029
+ fields, rels = self._merge_members(merge_order, members, model_kind)
1030
+ return self._reorder(fields, order_fields), self._reorder(rels, order_rels)
1031
+
1032
+ def _django_self_owner(self, name: str, merge_order: List[str]) -> str:
1033
+ """The model a Django ``"self"`` relation declared in class ``name`` points at.
1034
+
1035
+ A concrete model's own fields point at that model, also when a child
1036
+ inherits them (multi-table inheritance). An abstract base's or a plain
1037
+ mixin's fields are copied into the first concrete model that inherits
1038
+ it, so ``"self"`` points there (#226).
1039
+ """
1040
+ if self._is_concrete_django_model(name):
1041
+ return name
1042
+ for candidate in merge_order: # root first, so the nearest concrete heir wins
1043
+ if (
1044
+ candidate != name
1045
+ and self._is_concrete_django_model(candidate)
1046
+ and name in (self._mro(candidate) or ())
1047
+ ):
1048
+ return candidate
1049
+ return name
1050
+
1051
+ def _is_concrete_django_model(self, name: str) -> bool:
1052
+ """A Django model with its own table: a ``models.Model`` subclass, not abstract.
1053
+
1054
+ A plain mixin or an abstract base has no table, so a ``"self"``
1055
+ relation declared there belongs to the concrete model that copies it.
1056
+ """
1057
+ node = self._all_classes[name]
1058
+ return self._inherits_django_model(node) and not self._meta_flag(node, "abstract")
1059
+
1060
+ def _dataclass_fields(
1061
+ self, name: str, members: Dict[str, _ClassMembers]
1062
+ ) -> Tuple[Dict[str, FieldInfo], Dict[str, _Rel]]:
1063
+ """The members of a dataclass entity: ``dataclasses.fields()`` plus mixins.
1064
+
1065
+ First the stdlib result (:meth:`_effective_dataclass_fields`). Then
1066
+ annotations of undecorated mixins in the hierarchy, which the stdlib
1067
+ ignores but erdify has always shown, fill in only attributes no
1068
+ dataclass declares (the first such mixin in the MRO wins).
1069
+ """
1070
+ fields, rels = self._effective_dataclass_fields(name, members)
1071
+ # The cache is shared across entities, and _parse_table_class mutates
1072
+ # fields (e.g. is_unique), so each entity gets its own copies.
1073
+ fields, rels = {attr: replace(f) for attr, f in fields.items()}, dict(rels)
1074
+ for base in self._mro(name) or [name]:
1075
+ if self._is_dataclass(self._all_classes[base]):
1076
+ continue
1077
+ base_fields, base_rels, _ = members[base]
1078
+ for attr, field in base_fields.items():
1079
+ if attr not in fields and attr not in rels:
1080
+ fields[attr] = replace(field)
1081
+ for attr, rel in base_rels.items():
1082
+ if attr not in fields and attr not in rels:
1083
+ rels[attr] = rel
1084
+ return fields, rels
1085
+
1086
+ def _effective_dataclass_fields(
1087
+ self, name: str, members: Dict[str, _ClassMembers]
1088
+ ) -> Tuple[Dict[str, FieldInfo], Dict[str, _Rel]]:
1089
+ """A class's ``__dataclass_fields__``, as the stdlib computes it.
1090
+
1091
+ A decorated class merges each base's ``__dataclass_fields__`` in
1092
+ reversed MRO, then its own annotations. So in ``Child(Left, Middle)``
1093
+ an attribute ``Left`` merely inherits still overrides one ``Middle``
1094
+ redeclares. An undecorated class has no fields of its own: it exposes
1095
+ those of the first decorated class in its MRO. Cached per parse; a
1096
+ class's own members do not depend on the entity being built.
1097
+ """
1098
+ memo = self._dataclass_cache
1099
+ if name in memo:
1100
+ return memo[name]
1101
+ mro = self._mro(name) or [name]
1102
+ if not self._is_dataclass(self._all_classes[name]):
1103
+ owner = next((c for c in mro if self._is_dataclass(self._all_classes[c])), None)
1104
+ result = (
1105
+ self._effective_dataclass_fields(owner, members) if owner is not None else ({}, {})
1106
+ )
1107
+ memo[name] = result
1108
+ return result
1109
+ synthetic: Dict[str, _ClassMembers] = {}
1110
+ for base in mro[:0:-1]:
1111
+ base_fields, base_rels = self._effective_dataclass_fields(base, members)
1112
+ synthetic[base] = (base_fields, base_rels, [*base_fields, *base_rels])
1113
+ synthetic[name] = members[name]
1114
+ result = self._merge_members([*mro[:0:-1], name], synthetic, "dataclass")
1115
+ memo[name] = result
1116
+ return result
793
1117
 
794
- # Then add/override with current class fields
795
- class_fields, class_rels = self._extract_class_fields(class_node, model_kind)
796
- fields_dict.update(class_fields)
797
- relationships_dict.update(class_rels)
1118
+ @staticmethod
1119
+ def _drop_django_redeclared(
1120
+ fields: Dict[str, FieldInfo], rels: Dict[str, _Rel], attr: str
1121
+ ) -> None:
1122
+ """Drop whatever earlier classes stored for a redeclared Django attribute.
1123
+
1124
+ A Django attribute is stored under a key that depends on its kind
1125
+ (relationship ``owner`` vs. FK column ``owner_id``, #224), so all of
1126
+ them go.
1127
+ """
1128
+ rels.pop(attr, None)
1129
+ fields.pop(attr, None)
1130
+ inherited_fk = fields.get(f"{attr}_id")
1131
+ if inherited_fk is not None and inherited_fk.is_foreign_key:
1132
+ del fields[f"{attr}_id"]
798
1133
 
799
- return fields_dict, relationships_dict
1134
+ def _listing_order(
1135
+ self,
1136
+ class_node: ast.ClassDef,
1137
+ visited: set[str],
1138
+ members: Dict[str, _ClassMembers],
1139
+ model_kind: str,
1140
+ ) -> Tuple[Dict[str, FieldInfo], Dict[str, _Rel]]:
1141
+ """The keys, in listing order, of the recursive merge used before #228.
1142
+
1143
+ Each base's whole subtree is merged in (left to right, each class once),
1144
+ then the class body. Only a Django body's own redeclaration moves an
1145
+ inherited attribute to the body's position; a sibling base never
1146
+ displaces another sibling's attribute. Only the key order is used.
1147
+ """
1148
+ fields: Dict[str, FieldInfo] = {}
1149
+ rels: Dict[str, _Rel] = {}
1150
+ if class_node.name in visited:
1151
+ return fields, rels
1152
+ visited.add(class_node.name)
1153
+ for base in self._local_bases(class_node):
1154
+ base_fields, base_rels = self._listing_order(
1155
+ self._all_classes[base], visited, members, model_kind
1156
+ )
1157
+ fields.update(base_fields)
1158
+ rels.update(base_rels)
1159
+ class_fields, class_rels, declared = members[class_node.name]
1160
+ if model_kind == "django":
1161
+ for attr in declared:
1162
+ self._drop_django_redeclared(fields, rels, attr)
1163
+ fields.update(class_fields)
1164
+ rels.update(class_rels)
1165
+ return fields, rels
1166
+
1167
+ @staticmethod
1168
+ def _reorder(values: Dict[str, _V], order: Mapping[str, object]) -> Dict[str, _V]:
1169
+ """Return ``values`` with keys in ``order``'s key order, extra keys last."""
1170
+ result = {key: values[key] for key in order if key in values}
1171
+ result.update((key, value) for key, value in values.items() if key not in result)
1172
+ return result
1173
+
1174
+ def _class_members(
1175
+ self, class_node: ast.ClassDef, model_kind: str, concrete: str | None = None
1176
+ ) -> _ClassMembers:
1177
+ """A single class body's fields, relationships, and declared attribute names."""
1178
+ fields, rels = self._extract_class_fields(class_node, model_kind, concrete)
1179
+ if model_kind == "django":
1180
+ declared = self._django_declared_names(class_node)
1181
+ else:
1182
+ declared = [*fields, *rels]
1183
+ return fields, rels, declared
1184
+
1185
+ @staticmethod
1186
+ def _merge_members(
1187
+ order: List[str], members: Dict[str, _ClassMembers], model_kind: str
1188
+ ) -> Tuple[Dict[str, FieldInfo], Dict[str, _Rel]]:
1189
+ """Merge class members in ``order``; a later class overrides an earlier one.
1190
+
1191
+ A redeclared attribute replaces whatever an earlier class stored for it,
1192
+ even under another key or kind: a Django relationship ``owner`` vs. its
1193
+ FK column ``owner_id`` (#224), or a column vs. a model reference.
1194
+ """
1195
+ fields: Dict[str, FieldInfo] = {}
1196
+ rels: Dict[str, _Rel] = {}
1197
+ for class_name in order:
1198
+ class_fields, class_rels, declared = members[class_name]
1199
+ for attr in declared:
1200
+ if model_kind == "django":
1201
+ ASTDatabaseParser._drop_django_redeclared(fields, rels, attr)
1202
+ # Same key and kind: update() below replaces it in place.
1203
+ elif attr in class_fields:
1204
+ rels.pop(attr, None)
1205
+ else:
1206
+ fields.pop(attr, None)
1207
+ fields.update(class_fields)
1208
+ rels.update(class_rels)
1209
+ return fields, rels
1210
+
1211
+ def _django_declared_names(self, class_node: ast.ClassDef) -> List[str]:
1212
+ """Attribute names a Django model body declares or removes.
1213
+
1214
+ A model field declares its name. ``name = None`` removes a field
1215
+ inherited from an abstract base, as Django documents, so it also drops
1216
+ whatever the bases stored under that name.
1217
+ """
1218
+ return [
1219
+ *(name for name, _, _ in self._django_field_calls(class_node)),
1220
+ *self._django_removed_names(class_node),
1221
+ ]
1222
+
1223
+ @staticmethod
1224
+ def _django_removed_names(class_node: ast.ClassDef) -> List[str]:
1225
+ """Names a Django class body sets to ``None`` to remove an inherited field."""
1226
+ return [
1227
+ node.targets[0].id
1228
+ for node in class_node.body
1229
+ if isinstance(node, ast.Assign)
1230
+ and len(node.targets) == 1
1231
+ and isinstance(node.targets[0], ast.Name)
1232
+ and isinstance(node.value, ast.Constant)
1233
+ and node.value.value is None
1234
+ ]
800
1235
 
801
1236
  def _extract_class_fields(
802
- self, class_node: ast.ClassDef, model_kind: str
803
- ) -> Tuple[Dict[str, FieldInfo], Dict[str, Tuple[str, str, str]]]:
804
- """Extract fields and relationships from a class definition."""
1237
+ self, class_node: ast.ClassDef, model_kind: str, concrete: str | None = None
1238
+ ) -> Tuple[Dict[str, FieldInfo], Dict[str, _Rel]]:
1239
+ """Extract fields and relationships from a class definition.
1240
+
1241
+ ``concrete`` (Django only, default: the class itself) is the model a
1242
+ ``"self"`` relation in this body points at (:meth:`_django_self_owner`).
1243
+ """
805
1244
  if model_kind == "django":
806
- return self._extract_django_fields(class_node)
1245
+ return self._extract_django_fields(class_node, concrete or class_node.name)
807
1246
 
808
1247
  fields: Dict[str, FieldInfo] = {}
809
- relationships: Dict[str, Tuple[str, str, str]] = {}
1248
+ relationships: Dict[str, _Rel] = {}
810
1249
 
811
1250
  for node in class_node.body:
812
1251
  if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
@@ -846,17 +1285,44 @@ class ASTDatabaseParser:
846
1285
  return fields, relationships
847
1286
 
848
1287
  def _extract_django_fields(
849
- self, class_node: ast.ClassDef
850
- ) -> Tuple[Dict[str, FieldInfo], Dict[str, Tuple[str, str, str]]]:
1288
+ self, class_node: ast.ClassDef, concrete: str
1289
+ ) -> Tuple[Dict[str, FieldInfo], Dict[str, _Rel]]:
851
1290
  """Extract fields and relationships from a Django model.
852
1291
 
853
1292
  Django fields are plain assignments (``name = models.CharField(...)``),
854
- not annotated. Relationship fields (ForeignKey/OneToOneField/
855
- ManyToManyField) become relationships; every other ``*Field`` is a column.
1293
+ not annotated. ``ForeignKey`` / ``OneToOneField`` become ``<name>_id``
1294
+ foreign-key columns, ``ManyToManyField`` becomes a relationship, and
1295
+ every other ``*Field`` is a column. ``"self"`` names ``concrete``, the
1296
+ model being built, as in Django, where a relation to ``"self"`` in an
1297
+ abstract base points at each concrete subclass.
856
1298
  """
857
1299
  fields: Dict[str, FieldInfo] = {}
858
- relationships: Dict[str, Tuple[str, str, str]] = {}
1300
+ relationships: Dict[str, _Rel] = {}
1301
+
1302
+ for name, field_type, call in self._django_field_calls(class_node):
1303
+ if field_type in ("ForeignKey", "OneToOneField"):
1304
+ # Both are a real `<name>_id` column in the DB; model them as such
1305
+ # (like SQLAlchemy) so they render consistently across sources and
1306
+ # follow `null=` (#223). A OneToOneField is that column made unique,
1307
+ # or the PK itself with primary_key=True (shared primary key), in
1308
+ # which case Django adds no implicit `id` (#224).
1309
+ fk = self._parse_django_fk_column(
1310
+ name, call, concrete, one_to_one=field_type == "OneToOneField"
1311
+ )
1312
+ if fk:
1313
+ fields[fk.name] = fk
1314
+ elif field_type == "ManyToManyField":
1315
+ rel = self._parse_django_many_to_many(name, call, concrete)
1316
+ if rel:
1317
+ relationships[name] = rel
1318
+ else:
1319
+ fields[name] = self._parse_django_column(name, field_type, call)
859
1320
 
1321
+ return fields, relationships
1322
+
1323
+ def _django_field_calls(self, class_node: ast.ClassDef) -> List[Tuple[str, str, ast.Call]]:
1324
+ """``(attribute, field class name, call)`` for each model field in a Django class body."""
1325
+ calls: List[Tuple[str, str, ast.Call]] = []
860
1326
  for node in class_node.body:
861
1327
  if not isinstance(node, ast.Assign) or len(node.targets) != 1:
862
1328
  continue
@@ -865,48 +1331,145 @@ class ASTDatabaseParser:
865
1331
  continue
866
1332
  if not isinstance(node.value, ast.Call):
867
1333
  continue
868
-
869
1334
  field_type = self._django_field_type(node.value)
870
- if field_type is None:
871
- continue
1335
+ if field_type is not None:
1336
+ calls.append((target.id, field_type, node.value))
1337
+ return calls
872
1338
 
873
- name = target.id
874
- if field_type == "ForeignKey":
875
- # A ForeignKey is a real `<name>_id` column in the DB; model it as
876
- # such (like SQLAlchemy) so it renders consistently across sources.
877
- fk = self._parse_django_fk_column(name, node.value, class_node.name)
878
- if fk:
879
- fields[fk.name] = fk
880
- elif field_type in DJANGO_RELATIONSHIP_FIELDS:
881
- rel = self._parse_django_relationship(name, field_type, node.value, class_node.name)
882
- if rel:
883
- relationships[name] = rel
884
- else:
885
- fields[name] = self._parse_django_column(name, field_type, node.value)
886
-
887
- return fields, relationships
1339
+ @staticmethod
1340
+ def _has_true_kw(call: ast.Call, name: str) -> bool:
1341
+ """Whether ``call`` passes ``name=True`` as a literal keyword."""
1342
+ return any(
1343
+ kw.arg == name and isinstance(kw.value, ast.Constant) and kw.value.value is True
1344
+ for kw in call.keywords
1345
+ )
888
1346
 
889
1347
  def _parse_django_fk_column(
890
- self, name: str, call: ast.Call, current_class: str
1348
+ self, name: str, call: ast.Call, current_class: str, *, one_to_one: bool = False
891
1349
  ) -> FieldInfo | None:
892
- """Model a Django ``ForeignKey`` as the ``<name>_id`` column it creates in the DB."""
1350
+ """Model a ``ForeignKey`` / ``OneToOneField`` as the ``<name>_id`` column it creates.
1351
+
1352
+ A ``OneToOneField`` is a ``ForeignKey(unique=True)``.
1353
+ """
893
1354
  target = self._resolve_django_relationship_target(call, current_class)
894
1355
  if target is None:
895
1356
  return None
896
1357
 
897
1358
  is_nullable = False
1359
+ is_unique = one_to_one
1360
+ is_primary_key = False
898
1361
  for keyword in call.keywords:
899
- if keyword.arg == "null" and isinstance(keyword.value, ast.Constant):
1362
+ if not isinstance(keyword.value, ast.Constant):
1363
+ continue
1364
+ if keyword.arg == "null":
900
1365
  is_nullable = bool(keyword.value.value)
1366
+ elif keyword.arg == "unique" and not one_to_one:
1367
+ is_unique = bool(keyword.value.value)
1368
+ elif keyword.arg == "primary_key":
1369
+ is_primary_key = bool(keyword.value.value)
901
1370
 
1371
+ # ForeignKey(primary_key=True) makes `<name>_id` the table's primary key,
1372
+ # so Django adds no implicit `id` (#224). A PK is never NULL, and its
1373
+ # uniqueness is tracked by is_primary_key, not is_unique.
1374
+ to_field = self._django_to_field(call)
1375
+ column, type_str = self._django_target_column(target, to_field, ())
902
1376
  return FieldInfo(
903
1377
  name=f"{name}_id",
904
- type_str=self._django_display_type("BigAutoField"),
1378
+ type_str=type_str,
1379
+ is_primary_key=is_primary_key,
905
1380
  is_foreign_key=True,
906
- is_nullable=is_nullable,
907
- foreign_table=f"{self._django_target_table(target)}.id",
1381
+ is_nullable=is_nullable and not is_primary_key,
1382
+ is_unique=is_unique and not is_primary_key,
1383
+ foreign_table=f"{self._django_target_table(target)}.{column}",
908
1384
  )
909
1385
 
1386
+ @staticmethod
1387
+ def _django_to_field(call: ast.Call) -> str | None:
1388
+ """The literal ``to_field=`` of a Django relationship field, if any."""
1389
+ for kw in call.keywords:
1390
+ if (
1391
+ kw.arg == "to_field"
1392
+ and isinstance(kw.value, ast.Constant)
1393
+ and isinstance(kw.value.value, str)
1394
+ ):
1395
+ return kw.value.value
1396
+ return None
1397
+
1398
+ def _django_target_column(
1399
+ self, target: str, to_field: str | None, stack: Tuple[Tuple[str, str | None], ...]
1400
+ ) -> Tuple[str, str]:
1401
+ """Return the ``(column, type)`` a Django FK to ``target`` references (#226).
1402
+
1403
+ That is the ``to_field`` column if given, else the target's primary key,
1404
+ including one inherited from a base. A key that is itself a foreign key
1405
+ is its ``<name>_id`` column, typed like the column *it* references. An
1406
+ unknown target, field or cycle falls back to ``id`` / ``to_field`` with
1407
+ Django's default ``BigAutoField`` type. A cycle is a repeated
1408
+ ``(model, to_field)`` lookup, so following a key to another column of
1409
+ the same model still resolves.
1410
+ """
1411
+ key = (target, to_field)
1412
+ cached = self._target_column_cache.get(key)
1413
+ if cached is not None:
1414
+ return cached
1415
+ default = (to_field or "id", self._django_display_type("BigAutoField"))
1416
+ node = self._all_classes.get(target)
1417
+ if node is None or key in stack:
1418
+ return default
1419
+ result = self._resolve_django_target_column(target, node, to_field, stack, default)
1420
+ self._target_column_cache[key] = result
1421
+ return result
1422
+
1423
+ def _resolve_django_target_column(
1424
+ self,
1425
+ target: str,
1426
+ node: ast.ClassDef,
1427
+ to_field: str | None,
1428
+ stack: Tuple[Tuple[str, str | None], ...],
1429
+ default: Tuple[str, str],
1430
+ ) -> Tuple[str, str]:
1431
+ """Uncached body of :meth:`_django_target_column`."""
1432
+
1433
+ # The winning declaration of each attribute, resolved like the fields (#228).
1434
+ declared: Dict[str, Tuple[str, ast.Call, str]] = {}
1435
+ for class_name in self._merge_order(node):
1436
+ class_node = self._all_classes[class_name]
1437
+ for attr in self._django_removed_names(class_node):
1438
+ declared.pop(attr, None)
1439
+ for attr, field_type, call in self._django_field_calls(class_node):
1440
+ declared.pop(attr, None)
1441
+ declared[attr] = (field_type, call, class_name)
1442
+
1443
+ if to_field is not None:
1444
+ attr = to_field
1445
+ # Django also accepts a relation's attname (`account_id` for `account`).
1446
+ if attr not in declared and attr.endswith("_id"):
1447
+ relation = declared.get(attr[: -len("_id")])
1448
+ if relation is not None and relation[0] in ("ForeignKey", "OneToOneField"):
1449
+ attr = attr[: -len("_id")]
1450
+ if attr not in declared:
1451
+ return default
1452
+ else:
1453
+ pks = [
1454
+ a for a, (_, call, _) in declared.items() if self._has_true_kw(call, "primary_key")
1455
+ ]
1456
+ if not pks:
1457
+ return default
1458
+ attr = pks[-1]
1459
+
1460
+ field_type, call, declaring = declared[attr]
1461
+ if field_type in ("ForeignKey", "OneToOneField"):
1462
+ # "self" binds like on the entity side (#226).
1463
+ owner = self._django_self_owner(declaring, self._merge_order(node))
1464
+ ref = self._resolve_django_relationship_target(call, owner)
1465
+ if ref is None:
1466
+ return f"{attr}_id", default[1]
1467
+ _, ref_type = self._django_target_column(
1468
+ ref, self._django_to_field(call), stack + ((target, to_field),)
1469
+ )
1470
+ return f"{attr}_id", ref_type
1471
+ return attr, self._parse_django_column(attr, field_type, call).type_str
1472
+
910
1473
  def _django_target_table(self, class_name: str) -> str:
911
1474
  """Resolve a target class name to its table name (Meta.db_table or snake_case)."""
912
1475
  node = self._all_classes.get(class_name)
@@ -938,6 +1501,7 @@ class ASTDatabaseParser:
938
1501
  """Parse a Django column field (``models.CharField(...)``, etc.)."""
939
1502
  is_primary_key = False
940
1503
  is_nullable = False
1504
+ is_unique = False
941
1505
  default_value = None
942
1506
 
943
1507
  for keyword in call.keywords:
@@ -945,6 +1509,8 @@ class ASTDatabaseParser:
945
1509
  is_primary_key = bool(keyword.value.value)
946
1510
  elif keyword.arg == "null" and isinstance(keyword.value, ast.Constant):
947
1511
  is_nullable = bool(keyword.value.value)
1512
+ elif keyword.arg == "unique" and isinstance(keyword.value, ast.Constant):
1513
+ is_unique = bool(keyword.value.value)
948
1514
  elif keyword.arg == "default" and isinstance(keyword.value, ast.Constant):
949
1515
  default_value = repr(keyword.value.value)
950
1516
 
@@ -957,8 +1523,9 @@ class ASTDatabaseParser:
957
1523
  name=name,
958
1524
  type_str=type_str,
959
1525
  is_primary_key=is_primary_key,
960
- is_nullable=is_nullable,
1526
+ is_nullable=is_nullable and not is_primary_key,
961
1527
  default_value=default_value,
1528
+ is_unique=is_unique and not is_primary_key,
962
1529
  )
963
1530
 
964
1531
  def _django_choices_enum(self, call: ast.Call) -> str | None:
@@ -995,28 +1562,22 @@ class ASTDatabaseParser:
995
1562
  return field_type
996
1563
  return DJANGO_FIELD_TYPE_MAP.get(field_type, field_type)
997
1564
 
998
- def _parse_django_relationship(
999
- self, name: str, field_type: str, call: ast.Call, current_class: str
1000
- ) -> Tuple[str, str, str] | None:
1001
- """Parse a Django relationship field into a (target, rel_type, attr) tuple.
1565
+ def _parse_django_many_to_many(
1566
+ self, name: str, call: ast.Call, current_class: str
1567
+ ) -> _Rel | None:
1568
+ """Parse a Django ``ManyToManyField`` into a relationship tuple.
1002
1569
 
1003
- ``ManyToManyField(through=...)`` is skipped - that M:N is drawn through
1004
- the through-model's own foreign keys, exactly like SQLAlchemy ``secondary=``.
1570
+ ``ForeignKey`` / ``OneToOneField`` are FK columns instead (see
1571
+ :meth:`_parse_django_fk_column`). ``ManyToManyField(through=...)`` is
1572
+ skipped - that M:N is drawn through the through-model's own foreign
1573
+ keys, exactly like SQLAlchemy ``secondary=``.
1005
1574
  """
1006
1575
  target = self._resolve_django_relationship_target(call, current_class)
1007
1576
  if target is None:
1008
1577
  return None
1009
-
1010
- if field_type == "ManyToManyField":
1011
- if any(keyword.arg == "through" for keyword in call.keywords):
1012
- return None
1013
- rel_type = "many_to_many"
1014
- elif field_type == "OneToOneField":
1015
- rel_type = "one_to_one"
1016
- else: # ForeignKey
1017
- rel_type = "one"
1018
-
1019
- return (target, rel_type, name)
1578
+ if any(keyword.arg == "through" for keyword in call.keywords):
1579
+ return None
1580
+ return (target, "many_to_many", name, False)
1020
1581
 
1021
1582
  def _resolve_django_relationship_target(self, call: ast.Call, current_class: str) -> str | None:
1022
1583
  """Resolve a relationship field's target from its first positional or ``to=`` arg."""
@@ -1061,11 +1622,13 @@ class ASTDatabaseParser:
1061
1622
  is_foreign_key = False
1062
1623
  foreign_table = None
1063
1624
  index = False
1625
+ is_unique = False
1064
1626
 
1065
1627
  if node.value and isinstance(node.value, ast.Call):
1066
- if isinstance(node.value.func, ast.Name) and node.value.func.id in (
1067
- "Field", # SQLModel
1068
- "mapped_column", # SQLAlchemy
1628
+ # Field() (SQLModel) / mapped_column() (SQLAlchemy), bare or qualified
1629
+ # (e.g. orm.mapped_column).
1630
+ if self._is_call_to(node.value, "Field") or self._is_call_to(
1631
+ node.value, "mapped_column"
1069
1632
  ):
1070
1633
  for keyword in node.value.keywords:
1071
1634
  if keyword.arg == "primary_key" and isinstance(keyword.value, ast.Constant):
@@ -1075,6 +1638,17 @@ class ASTDatabaseParser:
1075
1638
  foreign_table = str(keyword.value.value)
1076
1639
  elif keyword.arg == "index" and isinstance(keyword.value, ast.Constant):
1077
1640
  index = bool(keyword.value.value)
1641
+ elif keyword.arg == "unique" and isinstance(keyword.value, ast.Constant):
1642
+ is_unique = bool(keyword.value.value)
1643
+ elif (
1644
+ keyword.arg == "nullable"
1645
+ and isinstance(keyword.value, ast.Constant)
1646
+ and isinstance(keyword.value.value, bool)
1647
+ ):
1648
+ # An explicit nullable=True/False is what the database gets
1649
+ # and overrides the annotation; nullable=None means
1650
+ # "unspecified", so the annotation still decides.
1651
+ is_nullable = keyword.value.value
1078
1652
 
1079
1653
  # SQLAlchemy: ForeignKey("table.col") passed to mapped_column()
1080
1654
  fk_target = self._extract_foreign_key_arg(node.value)
@@ -1094,6 +1668,17 @@ class ASTDatabaseParser:
1094
1668
  # Extract default value
1095
1669
  default_value = self._extract_default_value(node)
1096
1670
 
1671
+ # A primary key is never NULL in the database. SQLModel's idiomatic
1672
+ # `id: int | None = Field(default=None, primary_key=True)` only means
1673
+ # "unset until the database assigns it", so drop the Optional and the
1674
+ # `None` default rather than render the key as nullable (#217). Keyless
1675
+ # sources (Pydantic/dataclass) describe objects, not tables: an inferred
1676
+ # `id: int | None = None` there really is optional, so keep it.
1677
+ if is_primary_key and model_kind in ("sqlmodel", "sqlalchemy"):
1678
+ is_nullable = False
1679
+ if default_value == "None":
1680
+ default_value = None
1681
+
1097
1682
  # Clean up type string: drop the optional wrapper without mangling
1098
1683
  # generic args (e.g. list[str] must keep its closing bracket).
1099
1684
  type_str = type_str.replace(" | None", "").strip()
@@ -1109,6 +1694,8 @@ class ASTDatabaseParser:
1109
1694
  foreign_table=foreign_table,
1110
1695
  index=index,
1111
1696
  default_value=default_value,
1697
+ # is_unique is reserved for non-PK uniqueness (see FieldInfo).
1698
+ is_unique=is_unique and not is_primary_key,
1112
1699
  )
1113
1700
 
1114
1701
  @staticmethod
@@ -1121,9 +1708,7 @@ class ASTDatabaseParser:
1121
1708
  candidates = list(call.args) + [kw.value for kw in call.keywords]
1122
1709
  for arg in candidates:
1123
1710
  if (
1124
- isinstance(arg, ast.Call)
1125
- and isinstance(arg.func, ast.Name)
1126
- and arg.func.id == "ForeignKey"
1711
+ ASTDatabaseParser._is_call_to(arg, "ForeignKey") # also sa.ForeignKey
1127
1712
  and arg.args
1128
1713
  and isinstance(arg.args[0], ast.Constant)
1129
1714
  ):
@@ -1141,12 +1726,12 @@ class ASTDatabaseParser:
1141
1726
 
1142
1727
  # Field() / mapped_column() with default parameter
1143
1728
  if isinstance(node.value, ast.Call):
1144
- if isinstance(node.value.func, ast.Name) and node.value.func.id in (
1145
- "Field",
1146
- "mapped_column",
1147
- ):
1148
- # Check positional args first (Field(default_value, ...))
1149
- if node.value.args:
1729
+ is_field = self._is_call_to(node.value, "Field")
1730
+ if is_field or self._is_call_to(node.value, "mapped_column"):
1731
+ # Positional default: only SQLModel's Field(default, ...).
1732
+ # mapped_column()'s positional args are the column name, type
1733
+ # and ForeignKey, never a default (#221).
1734
+ if node.value.args and is_field:
1150
1735
  first_arg = node.value.args[0]
1151
1736
  if isinstance(first_arg, ast.Constant):
1152
1737
  return repr(first_arg.value)
@@ -1170,7 +1755,7 @@ class ASTDatabaseParser:
1170
1755
 
1171
1756
  return None
1172
1757
 
1173
- def _parse_relationship(self, node: ast.AnnAssign) -> Tuple[str, str, str] | None:
1758
+ def _parse_relationship(self, node: ast.AnnAssign) -> _Rel | None:
1174
1759
  """Parse a relationship from an annotated assignment.
1175
1760
 
1176
1761
  A relationship that declares ``link_model=`` (SQLModel) or ``secondary=``
@@ -1191,10 +1776,11 @@ class ASTDatabaseParser:
1191
1776
 
1192
1777
  rel_type = "many" if ("list[" in type_str or "List[" in type_str) else "one"
1193
1778
  target = self._clean_target(type_str)
1779
+ nullable = rel_type == "one" and self._is_optional_annotation(node.annotation)
1194
1780
 
1195
- return (target, rel_type, field_name)
1781
+ return (target, rel_type, field_name, nullable)
1196
1782
 
1197
- def _parse_model_reference(self, node: ast.AnnAssign) -> Tuple[str, str, str] | None:
1783
+ def _parse_model_reference(self, node: ast.AnnAssign) -> _Rel | None:
1198
1784
  """Treat a field typed as another known model as a relationship.
1199
1785
 
1200
1786
  Used for Pydantic/dataclass models, which express relationships as plain
@@ -1210,9 +1796,50 @@ class ASTDatabaseParser:
1210
1796
 
1211
1797
  target_class = self._all_classes.get(target)
1212
1798
  if target_class is not None and self._classify_source(target_class) is not None:
1213
- return (target, rel_type, node.target.id)
1799
+ # `user: User | None` is an optional reference (#223).
1800
+ nullable = rel_type == "one" and self._is_optional_annotation(node.annotation)
1801
+ return (target, rel_type, node.target.id, nullable)
1214
1802
  return None
1215
1803
 
1804
+ @classmethod
1805
+ def _is_optional_annotation(cls, node: ast.expr) -> bool:
1806
+ """Whether an annotation admits ``None`` at its top level.
1807
+
1808
+ Recognizes ``X | None`` (either side), ``Optional[X]``,
1809
+ ``Union[..., None]``, the same inside ``Mapped[...]``, and string
1810
+ (forward-reference) annotations. A name that merely contains
1811
+ "Optional" or "None" (``OptionalSettings``) is not optional.
1812
+ """
1813
+ if isinstance(node, ast.Constant):
1814
+ if node.value is None:
1815
+ return True
1816
+ if isinstance(node.value, str):
1817
+ try:
1818
+ parsed = ast.parse(node.value, mode="eval").body
1819
+ except SyntaxError:
1820
+ return False
1821
+ return cls._is_optional_annotation(parsed)
1822
+ return False
1823
+ if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
1824
+ return cls._is_optional_annotation(node.left) or cls._is_optional_annotation(node.right)
1825
+ if isinstance(node, ast.Subscript):
1826
+ func = node.value
1827
+ name = (
1828
+ func.id
1829
+ if isinstance(func, ast.Name)
1830
+ else func.attr
1831
+ if isinstance(func, ast.Attribute)
1832
+ else None
1833
+ )
1834
+ if name == "Optional":
1835
+ return True
1836
+ if name == "Mapped":
1837
+ return cls._is_optional_annotation(node.slice)
1838
+ if name == "Union":
1839
+ args = node.slice.elts if isinstance(node.slice, ast.Tuple) else [node.slice]
1840
+ return any(cls._is_optional_annotation(arg) for arg in args)
1841
+ return False
1842
+
1216
1843
  @staticmethod
1217
1844
  def _clean_target(type_str: str) -> str:
1218
1845
  """Reduce a (possibly wrapped) annotation to a bare target class name."""
@@ -114,7 +114,7 @@ class SqlSchemaParser:
114
114
  try:
115
115
  # Read inside the try: an unreadable or non-UTF-8 file is a parse
116
116
  # failure for this file only, like a syntax error.
117
- text = f.read_text()
117
+ text = f.read_text(encoding="utf-8")
118
118
  statements.extend(sqlglot.parse(text, dialect=self.dialect))
119
119
  except Exception as err:
120
120
  print(f"Error parsing {f}: {err}", file=sys.stderr)
@@ -201,7 +201,8 @@ class SqlSchemaParser:
201
201
  name=name,
202
202
  type_str=type_str,
203
203
  is_primary_key=is_pk,
204
- is_nullable=not not_null,
204
+ # A PRIMARY KEY column is implicitly NOT NULL (#217).
205
+ is_nullable=not not_null and not is_pk,
205
206
  default_value=default,
206
207
  is_unique=is_unique,
207
208
  )
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes