erdify 1.5.0__tar.gz → 1.5.2__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 (29) hide show
  1. {erdify-1.5.0 → erdify-1.5.2}/PKG-INFO +1 -1
  2. {erdify-1.5.0 → erdify-1.5.2}/pyproject.toml +1 -1
  3. {erdify-1.5.0 → erdify-1.5.2}/pyproject.toml.orig +1 -1
  4. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/config.py +22 -2
  5. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/generator.py +220 -37
  6. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/core.py +3 -1
  7. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/dialects/annotated.py +2 -2
  8. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/dialects/base.py +12 -4
  9. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/dialects/django.py +306 -42
  10. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/dialects/sqlalchemy.py +2 -2
  11. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/inheritance.py +2 -1
  12. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/sql_parser.py +15 -13
  13. {erdify-1.5.0 → erdify-1.5.2}/LICENSE +0 -0
  14. {erdify-1.5.0 → erdify-1.5.2}/README.md +0 -0
  15. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/__init__.py +0 -0
  16. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/__main__.py +0 -0
  17. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/cli.py +0 -0
  18. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/inject.py +0 -0
  19. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/__init__.py +0 -0
  20. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/aliases.py +0 -0
  21. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/annotations.py +0 -0
  22. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/common.py +0 -0
  23. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/dialects/__init__.py +0 -0
  24. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/dialects/django_apps.py +0 -0
  25. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/dialects/django_contrib.py +0 -0
  26. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/dialects/keyless.py +0 -0
  27. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/parser/discovery.py +0 -0
  28. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/py.typed +0 -0
  29. {erdify-1.5.0 → erdify-1.5.2}/src/erdify/pyproject.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: erdify
3
- Version: 1.5.0
3
+ Version: 1.5.2
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.5.0"
3
+ version = "1.5.2"
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.5.0"
3
+ version = "1.5.2"
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"
@@ -18,8 +18,11 @@ class FieldInfo:
18
18
  foreign_table: Referenced ``"table.column"`` when ``is_foreign_key``.
19
19
  index: Column is indexed.
20
20
  default_value: Default value as source text, if any.
21
- is_unique: Non-primary-key unique constraint (implies a 1:1 relationship
22
- when the column is also a foreign key).
21
+ is_unique: Unique on its own (implies a 1:1 relationship when the
22
+ column is also a foreign key). Never set on a table's *sole*
23
+ primary-key column, which the key already makes unique; a member
24
+ of a composite primary key keeps its own uniqueness (#331), see
25
+ :func:`normalize_key_uniqueness`.
23
26
  """
24
27
 
25
28
  name: str
@@ -86,6 +89,23 @@ class EntityInfo:
86
89
  inverse_relationships: Dict[str, str] = field(default_factory=dict)
87
90
 
88
91
 
92
+ def normalize_key_uniqueness(fields: List[FieldInfo]) -> None:
93
+ """Clear ``is_unique`` on a sole primary-key column, where it is redundant.
94
+
95
+ A member of a composite primary key is not unique by the key, so its own
96
+ ``unique`` / single-column unique constraint stays (#331). Shared by every
97
+ parser backend, which keep ``is_unique`` as declared until this runs.
98
+ """
99
+ pks = [f for f in fields if f.is_primary_key]
100
+ if len(pks) == 1:
101
+ pks[0].is_unique = False
102
+
103
+
104
+ def is_sole_primary_key(field: FieldInfo, fields: List[FieldInfo]) -> bool:
105
+ """Whether ``field`` is the only primary-key column among ``fields``."""
106
+ return field.is_primary_key and sum(f.is_primary_key for f in fields) == 1
107
+
108
+
89
109
  def is_structural_link_table(fields: List[FieldInfo]) -> bool:
90
110
  """Return True if fields describe a join table: a composite primary key
91
111
  made up entirely of foreign keys, with no payload columns.
@@ -5,7 +5,7 @@ import json
5
5
  import re
6
6
  from typing import Dict, Iterable, List, Tuple
7
7
 
8
- from .config import EntityInfo, EnumInfo, FieldInfo
8
+ from .config import EntityInfo, EnumInfo, FieldInfo, is_sole_primary_key
9
9
 
10
10
  #: Pinned Mermaid CDN major version used by the HTML preview format.
11
11
  MERMAID_CDN = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"
@@ -44,6 +44,74 @@ class _ERGenerator:
44
44
  self.enums = enums or {}
45
45
  self.title = title
46
46
  self.include_relationships = include_relationships
47
+ self._ids: Dict[Tuple[str, str], str] | None = None
48
+
49
+ # -- Names in the diagram source (#288) ---------------------------------
50
+ #
51
+ # Entity and enum names come from the model source, and a SQL table can be
52
+ # called anything (``"Order Items"``). Each format turns a name into an
53
+ # identifier its grammar accepts (``_identifier``, made unique across
54
+ # entities and enums) and writes references to it (``_render_ref``) and
55
+ # quoted labels (``_label``) its own way. The IR and JSON keep real names.
56
+
57
+ def _identifier(self, name: str) -> str:
58
+ """The bare diagram identifier for an entity or enum ``name``."""
59
+ return name
60
+
61
+ def _render_ref(self, identifier: str) -> str:
62
+ """How a reference to ``identifier`` is written (e.g. quoted)."""
63
+ return identifier
64
+
65
+ def _label(self, text: str) -> str:
66
+ """A quoted relationship label."""
67
+ return f'"{text}"'
68
+
69
+ def _diagram_ids(self) -> Dict[Tuple[str, str], str]:
70
+ """``("entity" | "enum", name)`` -> unique diagram identifier.
71
+
72
+ A name the format accepts as it is keeps it; an encoded name that
73
+ collides with another one gets a ``_2``, ``_3``, ... suffix. Entities
74
+ are numbered before enums, each in diagram order. Keyed by
75
+ ``EntityInfo.name`` / ``EnumInfo.name`` (:meth:`_ref` resolves a dict
76
+ key first); built once per :meth:`generate` call.
77
+ """
78
+ if self._ids is None:
79
+ entity_names = [e.name for e in self.entities.values()]
80
+ enum_names = [self.enums[n].name for n in sorted(self._get_used_enums())]
81
+ keys = [("entity", name) for name in dict.fromkeys(entity_names)]
82
+ keys += [("enum", name) for name in dict.fromkeys(enum_names)]
83
+ encoded = {key: self._identifier(key[1]) for key in keys}
84
+ ids: Dict[Tuple[str, str], str] = {}
85
+ taken: set[str] = set()
86
+ for key in keys:
87
+ if encoded[key] == key[1] and key[1] not in taken:
88
+ ids[key] = key[1]
89
+ taken.add(key[1])
90
+ for key in keys:
91
+ if key in ids:
92
+ continue
93
+ candidate, n = encoded[key], 2
94
+ while candidate in taken:
95
+ candidate, n = f"{encoded[key]}_{n}", n + 1
96
+ ids[key] = candidate
97
+ taken.add(candidate)
98
+ self._ids = ids
99
+ return self._ids
100
+
101
+ def _ref(self, entity_name: str, kind: str = "entity") -> str:
102
+ """The diagram reference to an entity (or enum) called ``entity_name``.
103
+
104
+ ``entity_name`` may also be a key of ``entities`` / ``enums`` (a
105
+ relationship target), which a caller's dict may hold apart from the name.
106
+ """
107
+ index = self.entities if kind == "entity" else self.enums
108
+ if entity_name in index:
109
+ entity_name = index[entity_name].name
110
+ return self._render_ref(self._diagram_ids()[(kind, entity_name)])
111
+
112
+ def _edge(self, left: str, glyph: str, right: str, label: str) -> str:
113
+ """One relationship line between the entities ``left`` and ``right``."""
114
+ return f"{self._ref(left)} {glyph} {self._ref(right)} : {self._label(label)}"
47
115
 
48
116
  def _get_used_enums(self) -> "set[str]":
49
117
  """Get set of enum names used by entity fields."""
@@ -97,7 +165,7 @@ class _ERGenerator:
97
165
  ``sole_pk`` marks an FK that is the entity's *only* primary-key column
98
166
  (the shared-primary-key 1:1): the key makes it unique by definition, so
99
167
  it is drawn 1:1 too (#222). In a composite PK the FK alone is not
100
- unique and stays N:1.
168
+ unique and stays N:1, unless it is unique on its own (#331).
101
169
  """
102
170
  child = "|o" if field.is_unique or sole_pk else "}o"
103
171
  parent = "o|" if field.is_nullable else "||"
@@ -137,16 +205,18 @@ class _ERGenerator:
137
205
  break
138
206
  if target_entity:
139
207
  glyph = self._fk_glyph(field, sole_pk=single_pk and field.is_primary_key)
140
- lines.append(f'{entity.name} {glyph} {target_entity.name} : "{field.name}"')
208
+ lines.append(self._edge(entity.name, glyph, target_entity.name, field.name))
141
209
  return lines
142
210
 
143
211
  def _generate_link_table_relationships(self, link_entity: EntityInfo) -> List[str]:
144
212
  """Generate relationships through a link table.
145
213
 
146
214
  A binary association table (two FKs) is drawn as the classic M:N
147
- pass-through path. A ternary or higher-order one (three or more FKs)
148
- has no single binary cardinality, so it is drawn as a star: one edge
149
- from each parent to the link entity (#118).
215
+ pass-through path; a member that is unique on its own (#331) caps its
216
+ side at one link row (``||--o|`` / ``|o--||``). A ternary or
217
+ higher-order one (three or more FKs) has no single binary cardinality,
218
+ so it is drawn as a star: one edge from each parent to the link
219
+ entity (#118).
150
220
  """
151
221
  lines: List[str] = []
152
222
  fk_fields = [f for f in link_entity.fields if f.is_foreign_key]
@@ -165,15 +235,21 @@ class _ERGenerator:
165
235
  # Arity is decided by the number of FK columns, not by how many targets
166
236
  # resolved: a ternary table with one unresolved FK must still be drawn
167
237
  # as a (partial) star, never mistaken for a binary M:N (#118).
238
+ # A member that is unique on its own (#331) gives each parent at most
239
+ # one link row.
240
+ unique = {f.name for f in fk_fields if f.is_unique}
168
241
  if len(fk_fields) == 2:
169
242
  if len(entities_to_link) == 2:
170
243
  entity1, fk1_name = entities_to_link[0]
171
244
  entity2, fk2_name = entities_to_link[1]
172
- lines.append(f'{entity1.name} ||--o{{ {link_entity.name} : "{fk1_name}"')
173
- lines.append(f'{link_entity.name} }}o--|| {entity2.name} : "{fk2_name}"')
245
+ many1 = "o|" if fk1_name in unique else "o{"
246
+ many2 = "|o" if fk2_name in unique else "}o"
247
+ lines.append(self._edge(entity1.name, f"||--{many1}", link_entity.name, fk1_name))
248
+ lines.append(self._edge(link_entity.name, f"{many2}--||", entity2.name, fk2_name))
174
249
  else: # three or more FK columns -> star of edges from each parent
175
250
  for parent, fk_name in entities_to_link:
176
- lines.append(f'{parent.name} ||--o{{ {link_entity.name} : "{fk_name}"')
251
+ many = "o|" if fk_name in unique else "o{"
252
+ lines.append(self._edge(parent.name, f"||--{many}", link_entity.name, fk_name))
177
253
 
178
254
  return lines
179
255
 
@@ -213,7 +289,8 @@ class _ERGenerator:
213
289
  def _declared_line(self, entity: EntityInfo, target: str, rel_type: str, attr: str) -> str:
214
290
  """The edge for one declared relationship of ``entity``, other side undeclared."""
215
291
  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}"'
292
+ glyph = f"{source}--{self._end(entity, rel_type, attr)}"
293
+ return self._edge(entity.name, glyph, target, attr)
217
294
 
218
295
  def _declared_relationship_lines(
219
296
  self, fk_pairs: "set[frozenset[str]]", link_pairs: "set[frozenset[str]]"
@@ -391,7 +468,7 @@ class _ERGenerator:
391
468
  other, _, other_kind, other_attr = folded
392
469
  left = self._mirror(self._end(other, other_kind, other_attr))
393
470
  right = self._end(entity, kind, attr)
394
- return f'{entity.name} {left}--{right} {target} : "{attr}"'
471
+ return self._edge(entity.name, f"{left}--{right}", target, attr)
395
472
 
396
473
  def _relationship_lines(self) -> List[str]:
397
474
  """Resolve every relationship line, de-duplicated and ordered.
@@ -450,12 +527,30 @@ class PlantUMLGenerator(_ERGenerator):
450
527
  whole ``' Relationships`` section).
451
528
  """
452
529
 
530
+ def _identifier(self, name: str) -> str:
531
+ """One word: other characters become ``_`` (``Order Items`` -> ``Order_Items``)."""
532
+ return re.sub(r"\W+", "_", name) or "_"
533
+
534
+ @staticmethod
535
+ def _text(text: str) -> str:
536
+ """Text on one line: ``"`` and ``<`` (markup) as ``&#34;`` / ``&#60;``.
537
+
538
+ A control character (line break) becomes a space.
539
+ """
540
+ text = re.sub(r"[\x00-\x1f\x7f]", " ", text)
541
+ return text.replace('"', "&#34;").replace("<", "&#60;")
542
+
543
+ def _label(self, text: str) -> str:
544
+ """A quoted relationship label."""
545
+ return f'"{self._text(text)}"'
546
+
453
547
  def generate(self) -> str:
454
548
  """Render the diagram.
455
549
 
456
550
  Returns:
457
551
  PlantUML source, from ``@startuml`` to ``@enduml``.
458
552
  """
553
+ self._ids = None # the entities may have changed since the last call
459
554
  lines = [
460
555
  f"@startuml {self.title}",
461
556
  '!define Table(name,desc) class name as "desc" << (T,#FFAAAA) >>',
@@ -501,16 +596,15 @@ class PlantUMLGenerator(_ERGenerator):
501
596
  def _generate_entity(self, entity: EntityInfo) -> List[str]:
502
597
  """Generate PlantUML entity definition."""
503
598
  lines = []
599
+ head = f'entity "{self._text(entity.table_name)}" as {self._ref(entity.name)}'
504
600
  if entity.is_link_table:
505
- lines.append(
506
- f'entity "{entity.table_name}" as {entity.name} << (L, #AAFFAA) link >> {{'
507
- )
601
+ lines.append(f"{head} << (L, #AAFFAA) link >> {{")
508
602
  else:
509
- lines.append(f'entity "{entity.table_name}" as {entity.name} {{')
603
+ lines.append(f"{head} {{")
510
604
 
511
605
  if entity.fields:
512
606
  for field in entity.fields:
513
- lines.append(f" {self._format_field(field)}")
607
+ lines.append(f" {self._format_field(field, entity.fields)}")
514
608
  else:
515
609
  lines.append(" ' (no fields)")
516
610
 
@@ -519,14 +613,16 @@ class PlantUMLGenerator(_ERGenerator):
519
613
 
520
614
  def _generate_enum(self, enum_info: EnumInfo) -> List[str]:
521
615
  """Generate PlantUML enum definition."""
522
- lines = [f"enum {enum_info.name} << (E,#FFCC00) >> {{"]
616
+ alias = self._ref(enum_info.name, "enum")
617
+ head = alias if alias == enum_info.name else f'"{self._text(enum_info.name)}" as {alias}'
618
+ lines = [f"enum {head} << (E,#FFCC00) >> {{"]
523
619
  for value in enum_info.values:
524
- lines.append(f" {value}")
620
+ lines.append(f" {self._text(value)}")
525
621
  lines.append("}")
526
622
  return lines
527
623
 
528
- def _format_field(self, field: FieldInfo) -> str:
529
- """Format a field for PlantUML."""
624
+ def _format_field(self, field: FieldInfo, fields: List[FieldInfo]) -> str:
625
+ """Format a field for PlantUML; ``fields`` are the entity's columns."""
530
626
  if field.is_primary_key:
531
627
  prefix = "primary_key"
532
628
  elif field.is_foreign_key:
@@ -542,16 +638,22 @@ class PlantUMLGenerator(_ERGenerator):
542
638
  default_val = field.default_value
543
639
  if "." in default_val:
544
640
  default_val = default_val.split(".")[-1]
545
- default = f" = {default_val}"
641
+ default = f" = {self._text(default_val)}"
546
642
 
547
- unique = " UK" if field.is_unique and not field.is_primary_key else ""
643
+ # A sole primary key is unique by being the key; a composite member
644
+ # that is unique on its own shows UK (#331).
645
+ unique = " UK" if field.is_unique and not is_sole_primary_key(field, fields) else ""
646
+ name = self._text(field.name)
647
+ if name != field.name or any(c in name for c in ",()"):
648
+ # A macro argument: quoted, it may hold a comma or parenthesis.
649
+ name = f'"{name}"'
548
650
 
549
651
  # Omit the type suffix entirely when the type is unknown (e.g. an
550
652
  # untyped Core Column on a synthesized link table) to avoid a dangling ":".
551
653
  if not type_str:
552
- return f"{prefix}({field.name}){unique}"
654
+ return f"{prefix}({name}){unique}"
553
655
 
554
- return f"{prefix}({field.name}) : {type_str}{nullable}{default}{unique}"
656
+ return f"{prefix}({name}) : {type_str}{nullable}{default}{unique}"
555
657
 
556
658
 
557
659
  class MermaidGenerator(_ERGenerator):
@@ -566,12 +668,85 @@ class MermaidGenerator(_ERGenerator):
566
668
  include_relationships: Draw relationship lines.
567
669
  """
568
670
 
671
+ # The grammar these mirror is Mermaid 11's ``erDiagram`` lexer. Its
672
+ # character classes are ASCII plus everything from U+00C0 (attributes) or
673
+ # U+0080 (entities) up, and its ``\b`` is ASCII-only, hence ``_NOT_WORD``.
674
+ _NOT_WORD = r"(?![0-9A-Za-z_])"
675
+ #: An entity name Mermaid reads unquoted ...
676
+ _BARE_ENTITY = re.compile(r"[0-9A-Za-z_\u0080-\U0010ffff][-0-9A-Za-z_\u0080-\U0010ffff]*")
677
+ #: ... unless it starts with a keyword (``one``, ``to``, ``class``, ...).
678
+ _ENTITY_KEYWORD = re.compile(
679
+ r"(?:erdiagram|style|classdef|class|one|many|to|u|1|acctitle|accdescr)" + _NOT_WORD,
680
+ re.IGNORECASE,
681
+ )
682
+ #: An attribute name or type, which must not start with a key (``PK``).
683
+ _ATTRIBUTE_CHARS = r"-*0-9A-Za-z_\[\]()\u00c0-\U0010ffff"
684
+ _ATTRIBUTE_WORD = re.compile(rf"[*A-Za-z_\u00c0-\U0010ffff][{_ATTRIBUTE_CHARS}]*")
685
+ _ATTRIBUTE_KEY = re.compile(r"(?:pk|fk|uk)" + _NOT_WORD, re.IGNORECASE)
686
+ #: Characters quoted text writes as Mermaid entity codes, which it decodes
687
+ #: when drawing: a quote or ``%`` / backslash (not allowed in a quoted
688
+ #: entity name), markup, ``#`` (starts a code) and ``~`` (a generic type
689
+ #: inside an entity block, even within quotes).
690
+ _CODES = {
691
+ "#": "#35;",
692
+ '"': "#quot;",
693
+ "%": "#37;",
694
+ "\\": "#92;",
695
+ "&": "#38;",
696
+ "<": "#lt;",
697
+ ">": "#gt;",
698
+ "~": "#126;",
699
+ }
700
+ #: A layout statement Mermaid finds even in a quoted entity name; written
701
+ #: as codes in all quoted text, which draws the same.
702
+ _DIRECTION = re.compile(r"(direction)(\s+)(?=(?:tb|bt|rl|lr))", re.IGNORECASE)
703
+
704
+ def _identifier(self, name: str) -> str:
705
+ """The entity name as quoted text (:meth:`_text`)."""
706
+ return self._text(name) or "_"
707
+
708
+ def _render_ref(self, identifier: str) -> str:
709
+ """Unquoted when Mermaid reads the name as one word, quoted otherwise."""
710
+ if self._BARE_ENTITY.fullmatch(identifier) and not self._ENTITY_KEYWORD.match(identifier):
711
+ return identifier
712
+ return f'"{identifier}"'
713
+
714
+ def _label(self, text: str) -> str:
715
+ """A quoted relationship label."""
716
+ return f'"{self._text(text)}"'
717
+
718
+ @classmethod
719
+ def _text(cls, text: str) -> str:
720
+ """Text for inside double quotes, drawn as it is: ``R&D "x"`` -> ``R#38;D #quot;x#quot;``.
721
+
722
+ A control character (line break) becomes a space, and each space in
723
+ ``direction TB`` (``LR``, ...) the code ``#32;``.
724
+ """
725
+ text = re.sub(r"[\x00-\x1f\x7f]", " ", text)
726
+ text = "".join(cls._CODES.get(c, c) for c in text)
727
+ return cls._DIRECTION.sub(lambda m: m.group(1) + "#32;" * len(m.group(2)), text)
728
+
729
+ @classmethod
730
+ def _attribute_word(cls, name: str) -> str:
731
+ """``name`` as an attribute word: ``Author Key`` -> ``Author_Key``, ``1st`` -> ``_1st``.
732
+
733
+ Characters Mermaid doesn't allow become ``_``; a name starting with a
734
+ digit or hyphen, or with a key (``pk``), gets a leading ``_``.
735
+ """
736
+ if cls._ATTRIBUTE_WORD.fullmatch(name) and not cls._ATTRIBUTE_KEY.match(name):
737
+ return name
738
+ word = re.sub(rf"[^{cls._ATTRIBUTE_CHARS}]+", "_", name)
739
+ if not cls._ATTRIBUTE_WORD.fullmatch(word) or cls._ATTRIBUTE_KEY.match(word):
740
+ word = "_" + word
741
+ return word
742
+
569
743
  def generate(self) -> str:
570
744
  """Render the diagram.
571
745
 
572
746
  Returns:
573
747
  Mermaid ``erDiagram`` source.
574
748
  """
749
+ self._ids = None # the entities may have changed since the last call
575
750
  lines = ["erDiagram"]
576
751
 
577
752
  for entity in self.entities.values():
@@ -590,22 +765,27 @@ class MermaidGenerator(_ERGenerator):
590
765
 
591
766
  def _generate_entity(self, entity: EntityInfo) -> List[str]:
592
767
  """Generate a Mermaid entity block."""
593
- lines = [f" {entity.name} {{"]
768
+ lines = [f" {self._ref(entity.name)} {{"]
594
769
  for field in entity.fields:
595
- lines.append(f" {self._format_attr(field)}")
770
+ lines.append(f" {self._format_attr(field, entity.fields)}")
596
771
  lines.append(" }")
597
772
  return lines
598
773
 
599
774
  def _generate_enum(self, enum_info: EnumInfo) -> List[str]:
600
775
  """Render an enum as a Mermaid entity block listing its values."""
601
- lines = [f" {enum_info.name} {{"]
776
+ lines = [f" {self._ref(enum_info.name, 'enum')} {{"]
602
777
  for value in enum_info.values:
603
- lines.append(f" enum {value}")
778
+ word = self._attribute_word(value)
779
+ comment = "" if word == value else f' "{self._text(value)}"'
780
+ lines.append(f" enum {word}{comment}")
604
781
  lines.append(" }")
605
782
  return lines
606
783
 
607
- def _format_attr(self, field: FieldInfo) -> str:
608
- """Format a Mermaid attribute line: ``<type> <name> [keys] ["comment"]``."""
784
+ def _format_attr(self, field: FieldInfo, fields: List[FieldInfo]) -> str:
785
+ """Format a Mermaid attribute line: ``<type> <name> [keys] ["comment"]``.
786
+
787
+ ``fields`` are the entity's columns.
788
+ """
609
789
  type_token = self._mermaid_type(field.type_str)
610
790
 
611
791
  keys = []
@@ -613,11 +793,12 @@ class MermaidGenerator(_ERGenerator):
613
793
  keys.append("PK")
614
794
  if field.is_foreign_key:
615
795
  keys.append("FK")
616
- if field.is_unique and not field.is_primary_key:
796
+ if field.is_unique and not is_sole_primary_key(field, fields): # #331
617
797
  keys.append("UK")
618
798
  key_str = ",".join(keys)
619
799
 
620
- comment_parts = []
800
+ name = self._attribute_word(field.name)
801
+ comment_parts = [] if name == field.name else [field.name]
621
802
  if field.is_nullable:
622
803
  comment_parts.append("nullable")
623
804
  if field.default_value is not None:
@@ -626,12 +807,12 @@ class MermaidGenerator(_ERGenerator):
626
807
  default_val = default_val.split(".")[-1]
627
808
  comment_parts.append(f"default {default_val}")
628
809
 
629
- parts = [type_token, field.name]
810
+ parts = [type_token, name]
630
811
  if key_str:
631
812
  parts.append(key_str)
632
813
  line = " ".join(parts)
633
814
  if comment_parts:
634
- line += f' "{", ".join(comment_parts)}"'
815
+ line += f' "{self._text(", ".join(comment_parts))}"'
635
816
  return line
636
817
 
637
818
  @staticmethod
@@ -643,7 +824,7 @@ class MermaidGenerator(_ERGenerator):
643
824
  """
644
825
  cleaned = type_str.split(".")[-1]
645
826
  token = re.sub(r"[^0-9A-Za-z_]+", "_", cleaned).strip("_")
646
- return token or "unknown"
827
+ return MermaidGenerator._attribute_word(token or "unknown")
647
828
 
648
829
 
649
830
  def generate_plantuml(
@@ -799,7 +980,9 @@ def generate_html(
799
980
  Render a self-contained HTML page that draws the ERD with Mermaid.
800
981
 
801
982
  The page loads Mermaid from a pinned CDN (``MERMAID_CDN``), so it needs
802
- internet access to render. Open it in a browser to view the diagram.
983
+ internet access to render. Open it in a browser to view the diagram. The
984
+ diagram source is HTML-escaped (a name may hold ``<`` or ``&``); Mermaid
985
+ decodes it before parsing.
803
986
 
804
987
  Args:
805
988
  entities: Dictionary of entity name to EntityInfo
@@ -833,7 +1016,7 @@ def generate_html(
833
1016
  "<body>\n"
834
1017
  f" <h1>{safe_title}</h1>\n"
835
1018
  ' <pre class="mermaid">\n'
836
- f"{diagram}\n"
1019
+ f"{html.escape(diagram, quote=False)}\n"
837
1020
  " </pre>\n"
838
1021
  " <script>mermaid.initialize({ startOnLoad: true });</script>\n"
839
1022
  "</body>\n"
@@ -8,7 +8,7 @@ from fnmatch import fnmatchcase
8
8
  from pathlib import Path
9
9
  from typing import Callable, Dict, List, Mapping, Tuple
10
10
 
11
- from ..config import EntityInfo, EnumInfo, is_structural_link_table
11
+ from ..config import EntityInfo, EnumInfo, is_structural_link_table, normalize_key_uniqueness
12
12
  from .aliases import AliasResolver
13
13
  from .common import is_enum_class
14
14
  from .dialects import DIALECTS, ParseContext
@@ -188,6 +188,8 @@ class ASTDatabaseParser:
188
188
  # #275, #292).
189
189
  for dialect in self._ctx.all_dialects():
190
190
  dialect.finalize(self._entities)
191
+ for entity in self._entities.values():
192
+ normalize_key_uniqueness(entity.fields)
191
193
 
192
194
  # Third pass: apply exclude patterns
193
195
  self._apply_exclude_patterns()
@@ -233,8 +233,8 @@ class AnnotatedDialect(Dialect):
233
233
  foreign_table=foreign_table,
234
234
  index=index,
235
235
  default_value=default_value,
236
- # is_unique is reserved for non-PK uniqueness (see FieldInfo).
237
- is_unique=is_unique and not is_primary_key,
236
+ # Cleared on a sole primary key once the entity is built (#331).
237
+ is_unique=is_unique,
238
238
  )
239
239
 
240
240
  def _extract_default_value(self, node: ast.AnnAssign) -> str | None:
@@ -272,17 +272,25 @@ class Dialect:
272
272
  entities' foreign keys reference.
273
273
  """
274
274
 
275
+ def unique_columns(self, class_node: ast.ClassDef) -> Tuple[Set[str], Set[str]]:
276
+ """Columns a class-level constraint makes unique on their own.
277
+
278
+ Returns ``(db_columns, attribute_refs)`` like
279
+ :meth:`_table_args_unique_columns`, which is the default: SQLAlchemy's
280
+ ``__table_args__`` (#218). Django reads its ``Meta`` instead (#274).
281
+ """
282
+ return self._table_args_unique_columns(class_node)
283
+
275
284
  def finish(self, entity: EntityInfo, class_node: ast.ClassDef) -> None:
276
- """Adjust the built entity: mark columns made unique by ``__table_args__``."""
285
+ """Adjust the built entity: mark columns made unique by a class-level constraint."""
277
286
  # Single-column UniqueConstraint / unique Index in __table_args__ (#218).
278
287
  # Constraints name the *database* column, which mapped_column("col", ...)
279
288
  # may set apart from the attribute name (#221).
280
289
  # A string names the DB column; a bare reference names the attribute.
281
- unique_cols, unique_refs = self._table_args_unique_columns(class_node)
290
+ unique_cols, unique_refs = self.unique_columns(class_node)
282
291
  db_names = self._db_column_names(class_node)
283
292
  for f in entity.fields:
284
- if f.is_primary_key:
285
- continue
293
+ # A sole primary key is cleared again later; a composite member keeps it (#331).
286
294
  if db_names.get(f.name, f.name) in unique_cols or f.name in unique_refs:
287
295
  f.is_unique = True
288
296
 
@@ -6,7 +6,7 @@ from typing import Dict, Iterable, List, Mapping, Set, Tuple
6
6
 
7
7
  from ...config import EntityInfo, FieldInfo
8
8
  from ..annotations import expr_name
9
- from ..common import _Rel, is_enum_class
9
+ from ..common import _ClassMembers, _Rel, is_enum_class
10
10
  from .base import Dialect, ParseContext
11
11
  from .django_apps import app_label, app_package
12
12
  from .django_contrib import (
@@ -21,6 +21,15 @@ from .django_contrib import (
21
21
  #: Django relationship field constructs (everything else ending in "Field" is a column).
22
22
  DJANGO_RELATIONSHIP_FIELDS = frozenset({"ForeignKey", "OneToOneField", "ManyToManyField"})
23
23
 
24
+ #: Django 5.2's composite primary key: a model field that makes no column (#276).
25
+ COMPOSITE_PRIMARY_KEY = "CompositePrimaryKey"
26
+
27
+ #: Bases that never make a class a Django model (plain mixins may use them).
28
+ _NON_MODEL_BASES = frozenset({"object", "Generic", "Protocol", "ABC"})
29
+
30
+ #: (field type, call, declaring class) of a model field.
31
+ _Declaration = Tuple[str, ast.Call, str]
32
+
24
33
  #: Conservative Django field -> Python type map for readable, source-consistent
25
34
  #: output. Ambiguous/lossy fields (JSONField, FileField, ImageField, custom or
26
35
  #: third-party fields) are intentionally omitted so they fall back to the Django
@@ -84,6 +93,7 @@ class DjangoDialect(Dialect):
84
93
  self._user_model_name: str | None = None
85
94
  self._declaring: Dict[int, ast.ClassDef] | None = None
86
95
  self._bindings: Dict[Tuple[int, int], Dict[str, str]] = {}
96
+ self._declarations: Dict[str, Dict[str, _Declaration]] = {}
87
97
 
88
98
  @classmethod
89
99
  def builtin_classes(
@@ -99,10 +109,10 @@ class DjangoDialect(Dialect):
99
109
  return not (self._meta_flag(class_node, "abstract") or self._meta_flag(class_node, "proxy"))
100
110
 
101
111
  def table_name(self, class_node: ast.ClassDef) -> str | None:
102
- """``__tablename__`` if set, else ``class Meta: db_table = "..."``."""
112
+ """``__tablename__`` if set, else ``Meta.db_table``, also an inherited one (#279)."""
103
113
  table_name = super().table_name(class_node)
104
114
  if not table_name:
105
- db_table = self._meta_value(class_node, "db_table")
115
+ db_table = self._meta_constant(class_node, "db_table")
106
116
  if isinstance(db_table, str):
107
117
  table_name = db_table
108
118
  return table_name
@@ -177,8 +187,8 @@ class DjangoDialect(Dialect):
177
187
  return f"{label}_{model_name}" if label else model_name
178
188
 
179
189
  def _app_label(self, class_node: ast.ClassDef) -> str | None:
180
- """``Meta.app_label``, else the label of the app the model's file is in."""
181
- label = self._meta_value(class_node, "app_label")
190
+ """``Meta.app_label`` (also inherited, #279), else the label of the model's app."""
191
+ label = self._meta_constant(class_node, "app_label")
182
192
  if isinstance(label, str) and label:
183
193
  return label
184
194
  model_file = self.ctx.file_of(class_node)
@@ -208,15 +218,36 @@ class DjangoDialect(Dialect):
208
218
  excluded.update(self.classes.mro(parent) or self.classes.dfs_order(parent_node, set()))
209
219
  return {name for name in names if name not in excluded}
210
220
 
211
- def drop_on_merge(
221
+ def merge(
212
222
  self,
213
- fields: Dict[str, FieldInfo],
214
- rels: Dict[str, _Rel],
215
- attr: str,
216
- class_fields: Dict[str, FieldInfo],
217
- class_rels: Dict[str, _Rel],
223
+ class_node: ast.ClassDef,
224
+ merge_order: List[str],
225
+ members: Dict[str, _ClassMembers],
226
+ ) -> Tuple[Dict[str, FieldInfo], Dict[str, _Rel]]:
227
+ """Take each field from the class whose declaration Django keeps.
228
+
229
+ Which one that is follows Django, not Python attribute lookup
230
+ (:meth:`_own_declarations`, #272, #280).
231
+ """
232
+ fields: Dict[str, FieldInfo] = {}
233
+ rels: Dict[str, _Rel] = {}
234
+ for attr, (field_type, _call, owner) in self._own_declarations(class_node).items():
235
+ owner_fields, owner_rels, _ = members.get(owner, ({}, {}, []))
236
+ if field_type in ("ForeignKey", "OneToOneField"):
237
+ key = f"{attr}_id"
238
+ if key in owner_fields:
239
+ fields[key] = owner_fields[key]
240
+ elif field_type == "ManyToManyField":
241
+ if attr in owner_rels:
242
+ rels[attr] = owner_rels[attr]
243
+ elif attr in owner_fields:
244
+ fields[attr] = owner_fields[attr]
245
+ return fields, rels
246
+
247
+ def drop_on_listing(
248
+ self, fields: Dict[str, FieldInfo], rels: Dict[str, _Rel], attr: str
218
249
  ) -> None:
219
- """Drop whatever earlier classes stored for a redeclared Django attribute.
250
+ """A Django body's redeclaration moves the attribute to the body's position.
220
251
 
221
252
  A Django attribute is stored under a key that depends on its kind
222
253
  (relationship ``owner`` vs. FK column ``owner_id``, #224), so all of
@@ -228,19 +259,73 @@ class DjangoDialect(Dialect):
228
259
  if inherited_fk is not None and inherited_fk.is_foreign_key:
229
260
  del fields[f"{attr}_id"]
230
261
 
231
- def drop_on_listing(
232
- self, fields: Dict[str, FieldInfo], rels: Dict[str, _Rel], attr: str
233
- ) -> None:
234
- """A Django body's redeclaration moves the attribute to the body's position."""
235
- self.drop_on_merge(fields, rels, attr, {}, {})
262
+ def unique_columns(self, class_node: ast.ClassDef) -> Tuple[Set[str], Set[str]]:
263
+ """Columns ``Meta`` makes unique on their own; Django ignores ``__table_args__`` (#274).
264
+
265
+ A single-field, unconditional ``UniqueConstraint(fields=[...])`` in
266
+ ``Meta.constraints``, or a one-field ``Meta.unique_together`` entry.
267
+ Composite, conditional (``condition=``) and expression constraints
268
+ don't make one column unique. ``Meta`` may be inherited (#279).
269
+ """
270
+ declared = self._own_declarations(class_node)
271
+ columns: Set[str] = set()
272
+ for group in self._meta_unique_groups(class_node):
273
+ if len(group) != 1:
274
+ continue
275
+ name = group[0]
276
+ # A field name or an attname (`owner_id`), as Meta.get_field() accepts.
277
+ if declared.get(name, ("",))[0] in ("ForeignKey", "OneToOneField"):
278
+ name = f"{name}_id"
279
+ columns.add(name)
280
+ return set(), columns
281
+
282
+ def _meta_unique_groups(self, class_node: ast.ClassDef) -> List[Tuple[str, ...]]:
283
+ """The field-name groups of ``Meta.constraints`` / ``Meta.unique_together``.
284
+
285
+ Only literal names count; a conditional or expression constraint, or
286
+ one whose fields aren't literal, is left out.
287
+ """
288
+ groups: List[Tuple[str, ...]] = []
289
+ constraints = self._meta_option(class_node, "constraints")
290
+ if isinstance(constraints, (ast.List, ast.Tuple)):
291
+ for item in constraints.elts:
292
+ if not (isinstance(item, ast.Call) and expr_name(item.func) == "UniqueConstraint"):
293
+ continue
294
+ if item.args or any(
295
+ kw.arg == "condition"
296
+ and not (isinstance(kw.value, ast.Constant) and kw.value.value is None)
297
+ for kw in item.keywords
298
+ ):
299
+ continue # expressions / a partial constraint
300
+ names = next(
301
+ (_literal_names(kw.value) for kw in item.keywords if kw.arg == "fields"), None
302
+ )
303
+ if names:
304
+ groups.append(names)
305
+ together = self._meta_option(class_node, "unique_together")
306
+ if isinstance(together, (ast.List, ast.Tuple)) and together.elts:
307
+ # Django's normalize_together(): a flat ("a", "b") is one group.
308
+ flat = _literal_names(together)
309
+ if flat is not None:
310
+ groups.append(flat)
311
+ else:
312
+ for item in together.elts:
313
+ names = _literal_names(item)
314
+ if names:
315
+ groups.append(names)
316
+ return groups
236
317
 
237
318
  def finish(self, entity: EntityInfo, class_node: ast.ClassDef) -> None:
238
- """Add the parent links and Django's implicit ``id`` primary key."""
319
+ """Add the composite key, parent links and Django's implicit ``id`` primary key."""
320
+ self._mark_composite_primary_key(entity, class_node)
239
321
  super().finish(entity, class_node)
240
322
  self._add_parent_links(entity, class_node)
241
323
  # Django implicitly adds an `id` primary key (BigAutoField since Django 3.2)
242
- # when no field declares primary_key=True and there is no parent link.
243
- if not any(f.is_primary_key for f in entity.fields):
324
+ # when no field declares primary_key=True and there is no parent link,
325
+ # nor a composite key (even one whose fields erdify can't read).
326
+ if not any(f.is_primary_key for f in entity.fields) and (
327
+ self._composite_primary_key(class_node) is None
328
+ ):
244
329
  entity.fields.insert(
245
330
  0,
246
331
  FieldInfo(
@@ -250,6 +335,42 @@ class DjangoDialect(Dialect):
250
335
  ),
251
336
  )
252
337
 
338
+ def _composite_primary_key(self, class_node: ast.ClassDef) -> List[str] | None:
339
+ """The column keys of a ``CompositePrimaryKey`` the model has, if any (#276).
340
+
341
+ Its arguments name fields or attnames (``order`` / ``order_id``); a
342
+ ``ForeignKey`` is the ``<name>_id`` column. Non-literal arguments are
343
+ left out, so the list may be empty.
344
+ """
345
+ declared = self._own_declarations(class_node)
346
+ call = next(
347
+ (c for t, c, _ in reversed(declared.values()) if t == COMPOSITE_PRIMARY_KEY), None
348
+ )
349
+ if call is None:
350
+ return None
351
+ keys: List[str] = []
352
+ for arg in call.args:
353
+ if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
354
+ name = arg.value
355
+ if declared.get(name, ("",))[0] in ("ForeignKey", "OneToOneField"):
356
+ name = f"{name}_id"
357
+ keys.append(name)
358
+ return keys
359
+
360
+ def _mark_composite_primary_key(self, entity: EntityInfo, class_node: ast.ClassDef) -> None:
361
+ """Make the columns of a ``CompositePrimaryKey`` the primary key (#276).
362
+
363
+ Each column keeps its own ``unique``: it is not a key on its own, and
364
+ Django adds its UNIQUE constraint.
365
+ """
366
+ keys = self._composite_primary_key(class_node)
367
+ if not keys:
368
+ return
369
+ for f in entity.fields:
370
+ if f.name in keys:
371
+ f.is_primary_key = True
372
+ f.is_nullable = False
373
+
253
374
  def _concrete_parents(self, class_node: ast.ClassDef) -> List[str]:
254
375
  """The concrete models ``class_node`` inherits a table link to, in base order.
255
376
 
@@ -427,6 +548,70 @@ class DjangoDialect(Dialect):
427
548
  value = assigned.value if isinstance(assigned, ast.Constant) else None
428
549
  return value
429
550
 
551
+ def _meta_constant(self, class_node: ast.ClassDef, attr: str) -> object | None:
552
+ """A ``Meta`` option's constant value, also an inherited one (#279); else None."""
553
+ value = self._meta_option(class_node, attr)
554
+ return value.value if isinstance(value, ast.Constant) else None
555
+
556
+ def _meta_option(self, class_node: ast.ClassDef, attr: str) -> ast.expr | None:
557
+ """The expression a model's ``Meta`` assigns to ``attr``, as Django reads it (#279).
558
+
559
+ Django pops ``class Meta`` off a model and puts it back on an abstract
560
+ one only, so a model without its own ``Meta`` gets the nearest one in
561
+ its MRO that is not a concrete model's: an abstract base's. Its own
562
+ ``Meta`` inherits options only by subclassing (``class
563
+ Meta(Base.Meta)``). Not for ``abstract``, which Django resets on an
564
+ abstract base's ``Meta`` (:meth:`_meta_flag` reads the model's own).
565
+ """
566
+ meta = self._get_meta_class(class_node)
567
+ if meta is None:
568
+ for name in (self.classes.mro(class_node.name) or [class_node.name])[1:]:
569
+ if self._is_concrete_django_model(name):
570
+ continue
571
+ meta = self._get_meta_class(self.classes.all[name])
572
+ if meta is not None:
573
+ break
574
+ return self._meta_class_option(meta, attr, ()) if meta is not None else None
575
+
576
+ def _meta_class_option(
577
+ self, meta: ast.ClassDef, attr: str, stack: Tuple[int, ...]
578
+ ) -> ast.expr | None:
579
+ """``attr`` as a ``Meta`` class body sets it (the last assignment), else its bases'.
580
+
581
+ A base is another model's ``Meta`` (``Base.Meta``) or a scanned class;
582
+ anything else is unknown.
583
+ """
584
+ if id(meta) in stack:
585
+ return None
586
+ value: ast.expr | None = None
587
+ for node in meta.body:
588
+ if isinstance(node, ast.Assign):
589
+ targets = node.targets
590
+ elif isinstance(node, ast.AnnAssign) and node.value is not None:
591
+ targets = [node.target]
592
+ else:
593
+ continue
594
+ if any(isinstance(t, ast.Name) and t.id == attr for t in targets):
595
+ value = node.value
596
+ if value is not None:
597
+ return value
598
+ for base in meta.bases:
599
+ base_meta: ast.ClassDef | None = None
600
+ if (
601
+ isinstance(base, ast.Attribute)
602
+ and base.attr == "Meta"
603
+ and isinstance(base.value, ast.Name)
604
+ and base.value.id in self.classes.all
605
+ ):
606
+ base_meta = self._get_meta_class(self.classes.all[base.value.id])
607
+ elif isinstance(base, ast.Name) and base.id in self.classes.all:
608
+ base_meta = self.classes.all[base.id]
609
+ if base_meta is not None:
610
+ found = self._meta_class_option(base_meta, attr, stack + (id(meta),))
611
+ if found is not None:
612
+ return found
613
+ return None
614
+
430
615
  def _django_self_owner(self, name: str, merge_order: List[str]) -> str:
431
616
  """The model a Django ``"self"`` relation declared in class ``name`` points at.
432
617
 
@@ -511,6 +696,8 @@ class DjangoDialect(Dialect):
511
696
  rel = self._parse_django_many_to_many(name, call, concrete)
512
697
  if rel:
513
698
  relationships[name] = rel
699
+ elif field_type == COMPOSITE_PRIMARY_KEY:
700
+ continue # no column; finish() marks the key's columns (#276)
514
701
  else:
515
702
  fields[name] = self._parse_django_column(name, field_type, call)
516
703
 
@@ -565,8 +752,8 @@ class DjangoDialect(Dialect):
565
752
  is_primary_key = bool(keyword.value.value)
566
753
 
567
754
  # ForeignKey(primary_key=True) makes `<name>_id` the table's primary key,
568
- # so Django adds no implicit `id` (#224). A PK is never NULL, and its
569
- # uniqueness is tracked by is_primary_key, not is_unique.
755
+ # so Django adds no implicit `id` (#224). A PK is never NULL; is_unique
756
+ # stays as declared and is cleared later on a sole primary key (#331).
570
757
  to_field = self._django_to_field(call)
571
758
  # A to_field column of a multi-table parent lives in the parent's table.
572
759
  if to_field is not None:
@@ -578,7 +765,7 @@ class DjangoDialect(Dialect):
578
765
  is_primary_key=is_primary_key,
579
766
  is_foreign_key=True,
580
767
  is_nullable=is_nullable and not is_primary_key,
581
- is_unique=is_unique and not is_primary_key,
768
+ is_unique=is_unique, # cleared on a sole primary key (#331)
582
769
  foreign_table=f"{self._django_target_table(target)}.{column}",
583
770
  )
584
771
  self._fk_targets[id(fk)] = target
@@ -600,26 +787,90 @@ class DjangoDialect(Dialect):
600
787
  return owner
601
788
  return None
602
789
 
603
- def _own_declarations(self, node: ast.ClassDef) -> Dict[str, Tuple[str, ast.Call, str]]:
604
- """The winning ``(field type, call, declaring class)`` of each attribute in the table.
605
-
606
- Resolved like the fields (#228), after removals (``name = None``) and
607
- overrides; a concrete parent's fields live in the parent's table (#233).
790
+ def _own_declarations(self, node: ast.ClassDef) -> Dict[str, _Declaration]:
791
+ """The fields Django builds into the model's own table, by attribute.
792
+
793
+ Django's ``ModelBase`` (#272, #280): the class body's fields, then,
794
+ along the MRO, each *direct* base that is an abstract model adds the
795
+ fields it has itself (its own and those it copied) unless the name is
796
+ already taken. Every other class in the MRO only takes names: a
797
+ concrete parent its fields (they stay in its table, #233), a plain
798
+ mixin or an indirect ancestor every name its body binds. So a field on
799
+ a plain mixin is no column, and a diamond keeps the first copy. A base
800
+ that is not known to be plain (it extends a class outside the scanned
801
+ files) is read like an abstract model.
608
802
  """
609
- merge_order = self.classes.merge_order(node)
610
- own = self.table_classes(node, merge_order)
611
- declared: Dict[str, Tuple[str, ast.Call, str]] = {}
612
- for class_name in merge_order:
613
- if class_name not in own:
803
+ cached = self._declarations.get(node.name)
804
+ if cached is not None:
805
+ return cached
806
+ declared: Dict[str, _Declaration] = {}
807
+ self._declarations[node.name] = declared # a cyclic hierarchy finds it empty
808
+ for attr, field_type, call in self._django_field_calls(node):
809
+ declared.pop(attr, None)
810
+ declared[attr] = (field_type, call, node.name)
811
+ taken = self._body_names(node)
812
+ direct = set(self.classes.local_bases(node))
813
+ mro = self.classes.mro(node.name) or self.classes.dfs_order(node, set())[::-1]
814
+ for base in mro:
815
+ if base == node.name:
614
816
  continue
615
- class_node = self.classes.all[class_name]
616
- for attr in self._django_removed_names(class_node):
617
- declared.pop(attr, None)
618
- for attr, field_type, call in self._django_field_calls(class_node):
619
- declared.pop(attr, None)
620
- declared[attr] = (field_type, call, class_name)
817
+ base_node = self.classes.all[base]
818
+ inherited = self._own_declarations(base_node)
819
+ if self._is_concrete_django_model(base):
820
+ # Its local fields, including the implicit `id` / `<x>_ptr` links.
821
+ taken |= self._own_column_names(base_node)
822
+ if base not in direct:
823
+ taken |= self._body_names(base_node)
824
+ elif base not in direct or self._is_plain_class(base, ()):
825
+ taken |= self._body_names(base_node) | set(inherited)
826
+ else:
827
+ for attr, declaration in inherited.items():
828
+ if attr not in declared and attr not in taken:
829
+ declared[attr] = declaration
621
830
  return declared
622
831
 
832
+ @staticmethod
833
+ def _body_names(node: ast.ClassDef) -> Set[str]:
834
+ """Every name a class body binds (its ``__dict__``), ``name = None`` included.
835
+
836
+ A bare annotation binds nothing, so it doesn't block an inherited field.
837
+ """
838
+ names: Set[str] = set()
839
+ for stmt in node.body:
840
+ if isinstance(stmt, ast.Assign):
841
+ names.update(t.id for t in stmt.targets if isinstance(t, ast.Name))
842
+ elif (
843
+ isinstance(stmt, ast.AnnAssign)
844
+ and stmt.value is not None
845
+ and isinstance(stmt.target, ast.Name)
846
+ ):
847
+ # A bare annotation (`id: UUID`) only writes __annotations__.
848
+ names.add(stmt.target.id)
849
+ elif isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
850
+ names.add(stmt.name)
851
+ names.discard("Meta") # Django pops it off the class
852
+ return names
853
+
854
+ def _is_plain_class(self, name: str, stack: Tuple[str, ...]) -> bool:
855
+ """Whether a class is known not to be a Django model.
856
+
857
+ Every base is ``object``, ``Generic[...]``, ``Protocol``, ``ABC`` or a
858
+ scanned plain class. Any other base outside the scanned files might be
859
+ a model, so such a class is not known to be plain.
860
+ """
861
+ node = self.classes.all.get(name)
862
+ if node is None or name in stack:
863
+ return False
864
+ for base in node.bases:
865
+ inner = base.value if isinstance(base, ast.Subscript) else base # Typed[str]
866
+ if expr_name(inner) in _NON_MODEL_BASES:
867
+ continue
868
+ if not (
869
+ isinstance(inner, ast.Name) and self._is_plain_class(inner.id, stack + (name,))
870
+ ):
871
+ return False
872
+ return True
873
+
623
874
  def _own_column_names(self, node: ast.ClassDef) -> Set[str]:
624
875
  """Field names (and FK attnames) stored in the model's own table."""
625
876
  names: Set[str] = set()
@@ -633,7 +884,8 @@ class DjangoDialect(Dialect):
633
884
  names.update((link, f"{link}_id"))
634
885
  # Django's implicit `id`, when nothing else is the primary key.
635
886
  if not links and not any(
636
- self._has_true_kw(call, "primary_key") for _, call, _ in declared.values()
887
+ field_type == COMPOSITE_PRIMARY_KEY or self._has_true_kw(call, "primary_key")
888
+ for field_type, call, _ in declared.values()
637
889
  ):
638
890
  names.add("id")
639
891
  return names
@@ -753,7 +1005,7 @@ class DjangoDialect(Dialect):
753
1005
  node = self.classes.all.get(class_name)
754
1006
  if node is None:
755
1007
  return CONTRIB_TABLES.get(class_name, class_name.lower())
756
- db_table = self._meta_value(node, "db_table")
1008
+ db_table = self._meta_constant(node, "db_table")
757
1009
  if isinstance(db_table, str):
758
1010
  return db_table
759
1011
  return self.default_table_name(node)
@@ -764,6 +1016,8 @@ class DjangoDialect(Dialect):
764
1016
 
765
1017
  Only constructs that are relationship fields or end in "Field" qualify,
766
1018
  which filters out non-field assignments such as ``objects = Manager()``.
1019
+ ``CompositePrimaryKey`` is returned too: a model field that makes no
1020
+ column (#276).
767
1021
  """
768
1022
  func = call.func
769
1023
  if isinstance(func, ast.Attribute):
@@ -774,6 +1028,8 @@ class DjangoDialect(Dialect):
774
1028
  return None
775
1029
  if name in DJANGO_RELATIONSHIP_FIELDS or name.endswith("Field"):
776
1030
  return name
1031
+ if name == COMPOSITE_PRIMARY_KEY:
1032
+ return name
777
1033
  return None
778
1034
 
779
1035
  def _parse_django_column(self, name: str, field_type: str, call: ast.Call) -> FieldInfo:
@@ -804,7 +1060,7 @@ class DjangoDialect(Dialect):
804
1060
  is_primary_key=is_primary_key,
805
1061
  is_nullable=is_nullable and not is_primary_key,
806
1062
  default_value=default_value,
807
- is_unique=is_unique and not is_primary_key,
1063
+ is_unique=is_unique, # cleared on a sole primary key (#331)
808
1064
  )
809
1065
 
810
1066
  def _django_choices_enum(self, call: ast.Call) -> str | None:
@@ -976,3 +1232,11 @@ class DjangoDialect(Dialect):
976
1232
  if parent is not None and self._builds_on(parent, base_name, seen):
977
1233
  return True
978
1234
  return False
1235
+
1236
+
1237
+ def _literal_names(node: ast.expr) -> Tuple[str, ...] | None:
1238
+ """The strings of a list / tuple of string literals, else None."""
1239
+ if not isinstance(node, (ast.List, ast.Tuple)):
1240
+ return None
1241
+ names = [e.value for e in node.elts if isinstance(e, ast.Constant) and isinstance(e.value, str)]
1242
+ return tuple(names) if len(names) == len(node.elts) else None
@@ -1046,7 +1046,7 @@ def core_table_fields(call: ast.Call) -> List[FieldInfo]:
1046
1046
  for f in fields:
1047
1047
  if f.is_primary_key:
1048
1048
  f.is_nullable = False # a primary key is never NULL
1049
- f.is_unique = False
1049
+ # is_unique stays: the parser clears it on a sole primary key (#331).
1050
1050
  return fields
1051
1051
 
1052
1052
 
@@ -1105,7 +1105,7 @@ def parse_core_column(call: ast.Call) -> FieldInfo | None:
1105
1105
  foreign_table=fk_target,
1106
1106
  index=bool(flag("index")),
1107
1107
  default_value=default_value,
1108
- is_unique=bool(flag("unique")) and not is_primary_key,
1108
+ is_unique=bool(flag("unique")), # cleared on a sole primary key (#331)
1109
1109
  )
1110
1110
 
1111
1111
 
@@ -16,7 +16,8 @@ class RedeclarationRule(Protocol):
16
16
  """What a class body's redeclared attribute removes from what its bases stored.
17
17
 
18
18
  Implemented by every dialect (:class:`~.dialects.base.Dialect`); Django
19
- overrides it because its storage key depends on the field kind.
19
+ overrides the listing rule because its storage key depends on the field
20
+ kind (and resolves the winners itself, ``DjangoDialect.merge``).
20
21
  """
21
22
 
22
23
  def drop_on_merge(
@@ -9,7 +9,13 @@ from fnmatch import fnmatchcase
9
9
  from pathlib import Path
10
10
  from typing import Any
11
11
 
12
- from .config import EntityInfo, EnumInfo, FieldInfo, is_structural_link_table
12
+ from .config import (
13
+ EntityInfo,
14
+ EnumInfo,
15
+ FieldInfo,
16
+ is_structural_link_table,
17
+ normalize_key_uniqueness,
18
+ )
13
19
  from .parser import ModelParseError
14
20
  from .parser.discovery import DEFAULT_EXCLUDE_DIRS, _match_include
15
21
 
@@ -354,16 +360,11 @@ class SqlSchemaParser:
354
360
  for c in constraints
355
361
  )
356
362
  default = self._default_value(constraints, exp)
357
- # A primary key is inherently unique, but is_unique is reserved for a
358
- # *non-PK* uniqueness that implies a 1:1 relationship (a PK is tracked
359
- # by is_primary_key). Never mark a PK column unique, even when it also
360
- # carries an explicit UNIQUE constraint.
361
- is_unique = not is_pk and (
362
- name in unique_cols
363
- or self._has_constraint(
364
- constraints,
365
- exp.UniqueColumnConstraint, # type: ignore[attr-defined]
366
- )
363
+ # Kept as declared: a member of a composite primary key is unique on
364
+ # its own only through UNIQUE; _finalize() clears it on a sole PK (#331).
365
+ is_unique = name in unique_cols or self._has_constraint(
366
+ constraints,
367
+ exp.UniqueColumnConstraint, # type: ignore[attr-defined]
367
368
  )
368
369
  return FieldInfo(
369
370
  name=name,
@@ -518,7 +519,7 @@ class SqlSchemaParser:
518
519
  Each plain column of the index gets ``FieldInfo.index``; an expression
519
520
  (``lower(col)``) is not a column. A unique index on one plain column,
520
521
  without a ``WHERE`` clause, makes that column unique like a ``UNIQUE``
521
- constraint (a primary key is never marked, see :meth:`_column`).
522
+ constraint (cleared again on a sole primary key, see :meth:`_finalize`).
522
523
  """
523
524
  index = create.this # type: ignore[attr-defined] # exp.Index
524
525
  table_node = index.find(exp.Table) # type: ignore[attr-defined]
@@ -547,7 +548,7 @@ class SqlSchemaParser:
547
548
  for f in entity.fields:
548
549
  if f.name in indexed:
549
550
  f.index = True
550
- if unique and not f.is_primary_key:
551
+ if unique:
551
552
  f.is_unique = True
552
553
 
553
554
  @staticmethod
@@ -560,6 +561,7 @@ class SqlSchemaParser:
560
561
  def _finalize(self) -> None:
561
562
  """Detect link tables, then apply ``exclude_patterns``."""
562
563
  for entity in self._entities.values():
564
+ normalize_key_uniqueness(entity.fields)
563
565
  entity.is_link_table = is_structural_link_table(entity.fields)
564
566
  self._apply_excludes()
565
567
 
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes