erdify 1.2.0__tar.gz → 1.4.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.
Files changed (27) hide show
  1. {erdify-1.2.0 → erdify-1.4.0}/PKG-INFO +1 -1
  2. {erdify-1.2.0 → erdify-1.4.0}/pyproject.toml +1 -1
  3. {erdify-1.2.0 → erdify-1.4.0}/pyproject.toml.orig +1 -1
  4. {erdify-1.2.0 → erdify-1.4.0}/src/erdify/cli.py +1 -1
  5. {erdify-1.2.0 → erdify-1.4.0}/src/erdify/config.py +6 -1
  6. {erdify-1.2.0 → erdify-1.4.0}/src/erdify/generator.py +245 -35
  7. erdify-1.4.0/src/erdify/parser/__init__.py +26 -0
  8. erdify-1.4.0/src/erdify/parser/annotations.py +373 -0
  9. erdify-1.4.0/src/erdify/parser/common.py +48 -0
  10. erdify-1.4.0/src/erdify/parser/core.py +538 -0
  11. erdify-1.4.0/src/erdify/parser/dialects/__init__.py +22 -0
  12. erdify-1.4.0/src/erdify/parser/dialects/annotated.py +325 -0
  13. erdify-1.4.0/src/erdify/parser/dialects/base.py +368 -0
  14. erdify-1.4.0/src/erdify/parser/dialects/django.py +776 -0
  15. erdify-1.4.0/src/erdify/parser/dialects/keyless.py +201 -0
  16. erdify-1.4.0/src/erdify/parser/dialects/sqlalchemy.py +148 -0
  17. erdify-1.4.0/src/erdify/parser/discovery.py +180 -0
  18. erdify-1.4.0/src/erdify/parser/inheritance.py +177 -0
  19. {erdify-1.2.0 → erdify-1.4.0}/src/erdify/sql_parser.py +2 -1
  20. erdify-1.2.0/src/erdify/parser.py +0 -2025
  21. {erdify-1.2.0 → erdify-1.4.0}/LICENSE +0 -0
  22. {erdify-1.2.0 → erdify-1.4.0}/README.md +0 -0
  23. {erdify-1.2.0 → erdify-1.4.0}/src/erdify/__init__.py +0 -0
  24. {erdify-1.2.0 → erdify-1.4.0}/src/erdify/__main__.py +0 -0
  25. {erdify-1.2.0 → erdify-1.4.0}/src/erdify/inject.py +0 -0
  26. {erdify-1.2.0 → erdify-1.4.0}/src/erdify/py.typed +0 -0
  27. {erdify-1.2.0 → erdify-1.4.0}/src/erdify/pyproject.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: erdify
3
- Version: 1.2.0
3
+ Version: 1.4.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
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "erdify"
3
- version = "1.2.0"
3
+ version = "1.4.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"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "erdify"
3
- version = "1.2.0"
3
+ version = "1.4.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"
@@ -144,7 +144,7 @@ def build_parser() -> argparse.ArgumentParser:
144
144
  parser.add_argument(
145
145
  "--no-relationships",
146
146
  action="store_true",
147
- help="Skip relationship lines in output",
147
+ help="Draw no relationship lines (edges) in any format, foreign-key edges included",
148
148
  )
149
149
  parser.add_argument(
150
150
  "--format",
@@ -1,7 +1,7 @@
1
1
  """Data classes for erdify."""
2
2
 
3
3
  from dataclasses import dataclass, field
4
- from typing import List, Tuple
4
+ from typing import Dict, List, Tuple
5
5
 
6
6
 
7
7
  @dataclass
@@ -67,6 +67,10 @@ class EntityInfo:
67
67
  reference is optional (e.g. ``user: User | None``); drawn as
68
68
  zero-or-one on the target side. Foreign-key columns carry their own
69
69
  ``FieldInfo.is_nullable`` instead.
70
+ inverse_relationships: Relationship attribute -> the attribute of the
71
+ other side's relationship it pairs with, when the source names it
72
+ (SQLAlchemy / SQLModel ``back_populates=``). Both sides are then
73
+ drawn as one edge.
70
74
  """
71
75
 
72
76
  name: str
@@ -79,6 +83,7 @@ class EntityInfo:
79
83
  base_classes: List[str] = field(default_factory=list)
80
84
  source: str = "sqlmodel"
81
85
  nullable_relationships: List[str] = field(default_factory=list)
86
+ inverse_relationships: Dict[str, str] = field(default_factory=dict)
82
87
 
83
88
 
84
89
  def is_structural_link_table(fields: List[FieldInfo]) -> bool:
@@ -3,7 +3,7 @@
3
3
  import html
4
4
  import json
5
5
  import re
6
- from typing import Dict, List, Tuple
6
+ from typing import Dict, Iterable, List, Tuple
7
7
 
8
8
  from .config import EntityInfo, EnumInfo, FieldInfo
9
9
 
@@ -23,16 +23,27 @@ class _ERGenerator:
23
23
  the relationship logic and only differ in entity/enum block formatting.
24
24
  """
25
25
 
26
+ #: The cardinality a relationship's inverse side declares: a 1:N collection
27
+ #: (``many``) is mirrored by an N:1 reference (``one``), and so on.
28
+ _INVERSE_KIND = {
29
+ "one": "many",
30
+ "many": "one",
31
+ "one_to_one": "one_to_one",
32
+ "many_to_many": "many_to_many",
33
+ }
34
+
26
35
  def __init__(
27
36
  self,
28
37
  entities: Dict[str, EntityInfo],
29
38
  enums: Dict[str, EnumInfo] | None = None,
30
39
  *,
31
40
  title: str = "Database ERD",
41
+ include_relationships: bool = True,
32
42
  ):
33
43
  self.entities = entities
34
44
  self.enums = enums or {}
35
45
  self.title = title
46
+ self.include_relationships = include_relationships
36
47
 
37
48
  def _get_used_enums(self) -> "set[str]":
38
49
  """Get set of enum names used by entity fields."""
@@ -166,31 +177,221 @@ class _ERGenerator:
166
177
 
167
178
  return lines
168
179
 
169
- def _generate_relationship_list_lines(
170
- self, entity: EntityInfo
171
- ) -> "List[Tuple[str, frozenset[str]]]":
172
- """Generate lines from an entity's declared relationships.
180
+ @staticmethod
181
+ def _snake_case(name: str) -> str:
182
+ """``OrderItem`` -> ``order_item``, ``HTTPRequest`` -> ``http_request``.
173
183
 
174
- Returns (line, pair) tuples where pair is the frozenset of the two
175
- connected entity names, so callers can skip already-connected pairs.
184
+ The usual attribute name for a reference to a class; an acronym stays
185
+ one word.
176
186
  """
177
- results: List[Tuple[str, frozenset[str]]] = []
178
- for target_name, rel_type, attr in entity.relationships:
179
- target = self.entities.get(target_name)
180
- if not target:
187
+ return re.sub(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])", "_", name).lower()
188
+
189
+ #: Crow's-foot end at the target for what a relationship declares about
190
+ #: it: (kind, nullable) -> token, written on the target's side.
191
+ _TARGET_END = {
192
+ ("one", False): "||",
193
+ ("one", True): "o|",
194
+ ("many", False): "o{",
195
+ ("one_to_one", False): "||",
196
+ ("many_to_many", False): "o{",
197
+ }
198
+ #: The source end when only one side is declared: kind -> token.
199
+ _DEFAULT_SOURCE_END = {"one": "}o", "many": "||", "one_to_one": "||", "many_to_many": "}o"}
200
+
201
+ @staticmethod
202
+ def _mirror(token: str) -> str:
203
+ """The same end written on the other side of ``--`` (``o{`` -> ``}o``)."""
204
+ return token[::-1].replace("{", "}")
205
+
206
+ def _end(self, entity: EntityInfo, kind: str, attr: str) -> str:
207
+ """The target end of ``entity.attr``; only a ``one`` reference can be optional."""
208
+ if kind not in self._DEFAULT_SOURCE_END:
209
+ kind = "one"
210
+ nullable = kind == "one" and attr in entity.nullable_relationships # #223
211
+ return self._TARGET_END[(kind, nullable)]
212
+
213
+ def _declared_line(self, entity: EntityInfo, target: str, rel_type: str, attr: str) -> str:
214
+ """The edge for one declared relationship of ``entity``, other side undeclared."""
215
+ source = self._DEFAULT_SOURCE_END.get(rel_type, self._DEFAULT_SOURCE_END["one"])
216
+ return f'{entity.name} {source}--{self._end(entity, rel_type, attr)} {target} : "{attr}"'
217
+
218
+ def _declared_relationship_lines(
219
+ self, fk_pairs: "set[frozenset[str]]", link_pairs: "set[frozenset[str]]"
220
+ ) -> List[str]:
221
+ """Edges for declared relationships between pairs no column already connects.
222
+
223
+ A pair joined by a foreign-key column (``fk_pairs``) or a link table
224
+ (``link_pairs``) already has its edge, which an ORM relationship such
225
+ as ``relationship()`` merely mirrors. A many-to-many never mirrors a
226
+ foreign-key column, so only a link table suppresses it: e.g. a Django
227
+ ``ManyToManyField`` to the parent of a multi-table child (#233).
228
+
229
+ Every declared attribute gets its own edge (#230), except that the two
230
+ sides of a bidirectional relationship (e.g. ``User.posts`` and
231
+ ``Post.user``) describe one edge (:meth:`_pair_sides`). That edge is
232
+ drawn from the side whose entity name sorts first, so it does not
233
+ depend on file order, and each end shows what its own side declares
234
+ (#239): ``list[B]`` on ``A`` and ``list[A]`` on ``B`` give ``}o--o{``.
235
+ """
236
+ connected = fk_pairs | link_pairs
237
+ rels = [
238
+ (entity, target, rel_type, attr)
239
+ for entity in self.entities.values()
240
+ for target, rel_type, attr in entity.relationships
241
+ if target in self.entities
242
+ and frozenset((entity.name, target))
243
+ not in (link_pairs if rel_type == "many_to_many" else connected)
244
+ ]
245
+ by_pair: Dict[frozenset[str], List[int]] = {}
246
+ for i, (entity, target, _, _) in enumerate(rels):
247
+ by_pair.setdefault(frozenset((entity.name, target)), []).append(i)
248
+ partner: Dict[int, int] = {}
249
+ for indices in by_pair.values():
250
+ partner.update(self._pair_sides(rels, indices))
251
+ folded = set(partner.values())
252
+ lines: List[str] = []
253
+ for i, (entity, target, rel_type, attr) in enumerate(rels):
254
+ if i in folded:
181
255
  continue
182
- if rel_type == "many":
183
- line = f'{entity.name} ||--o{{ {target.name} : "{attr}"'
184
- elif rel_type == "one_to_one":
185
- line = f'{entity.name} ||--|| {target.name} : "{attr}"'
186
- elif rel_type == "many_to_many":
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}"'
190
- else: # "one"
191
- line = f'{entity.name} }}o--|| {target.name} : "{attr}"'
192
- results.append((line, frozenset((entity.name, target.name))))
193
- return results
256
+ if i in partner:
257
+ lines.append(self._merged_line(rels[i], rels[partner[i]]))
258
+ else:
259
+ lines.append(self._declared_line(entity, target, rel_type, attr))
260
+ return lines
261
+
262
+ def _pair_sides(
263
+ self, rels: "List[Tuple[EntityInfo, str, str, str]]", indices: List[int]
264
+ ) -> Dict[int, int]:
265
+ """Pair the relationships between one pair of entities: kept index -> folded index.
266
+
267
+ 1. **Explicit** (#240): a side naming its inverse (``back_populates=``)
268
+ pairs with that attribute of the other side, mutual declarations
269
+ first. One naming an attribute the other side does not declare is
270
+ guessed like the rest.
271
+ 2. **Guessed**: each relationship of the first side (the entity whose
272
+ name sorts first) folds at most one relationship declared back
273
+ from the other side, best candidates first: the inverse
274
+ cardinality (``many`` for ``one`` and vice versa) with attributes
275
+ named after the class they point at on both sides (``Post.user`` /
276
+ ``User.posts``), then on one side, then any inverse cardinality,
277
+ then (not for a self-reference) anything left.
278
+
279
+ Equal candidates are tried in declaration order within each entity, the
280
+ first side before the other, so the file (entity) order never changes
281
+ the result. The kept side is the first side's relationship; for a
282
+ self-reference, the attribute whose name sorts first. A self-reference
283
+ only folds an N:1 / 1:N inverse (``parent`` / ``children``): two
284
+ references of the same cardinality
285
+ (``friends`` / ``blocked``, both M:N) stay two edges.
286
+ """
287
+
288
+ def attr(i: int) -> str:
289
+ return rels[i][3]
290
+
291
+ def inverse_of(i: int) -> str | None:
292
+ return rels[i][0].inverse_relationships.get(attr(i))
293
+
294
+ def by_attr(idx: Iterable[int]) -> List[int]:
295
+ return sorted(idx, key=attr)
296
+
297
+ names = sorted({rels[i][0].name for i in indices} | {rels[i][1] for i in indices})
298
+ first = names[0]
299
+ self_ref = len(names) == 1
300
+ side_a = {i for i in indices if rels[i][0].name == first}
301
+ side_b = side_a if self_ref else set(indices) - side_a
302
+ pairs: Dict[int, int] = {}
303
+ used: set[int] = set()
304
+
305
+ def other_side(i: int) -> "set[int]":
306
+ return side_b if i in side_a else side_a
307
+
308
+ def pair(i: int, j: int) -> None:
309
+ if self_ref:
310
+ keep, fold = by_attr((i, j))
311
+ else:
312
+ keep, fold = (i, j) if i in side_a else (j, i)
313
+ pairs[keep] = fold
314
+ used.update((i, j))
315
+
316
+ # 1. Explicit: mutual back_populates first, then one-sided ones.
317
+ for mutual in (True, False):
318
+ for i in [*sorted(side_a), *sorted(side_b - side_a)]:
319
+ inverse = inverse_of(i)
320
+ if i in used or inverse is None:
321
+ continue
322
+ j = next(
323
+ (
324
+ j
325
+ for j in sorted(other_side(i))
326
+ if j != i
327
+ and j not in used
328
+ and attr(j) == inverse
329
+ and (inverse_of(j) == attr(i) if mutual else inverse_of(j) is None)
330
+ ),
331
+ None,
332
+ )
333
+ if j is not None:
334
+ pair(i, j)
335
+
336
+ # 2. Guessed: everything not paired whose inverse (if named) does not exist.
337
+ def guessable(i: int) -> bool:
338
+ inverse = inverse_of(i)
339
+ return i not in used and (
340
+ inverse is None or not any(attr(j) == inverse for j in other_side(i))
341
+ )
342
+
343
+ plural_names = {name: self._class_attr_names(name) for name in names}
344
+
345
+ def exact(i: int, j: int) -> bool:
346
+ return rels[j][2] == self._INVERSE_KIND[rels[i][2]]
347
+
348
+ def named(i: int, j: int) -> int:
349
+ entity_i, target_i, _, attr_i = rels[i]
350
+ return int(attr_i in plural_names[target_i]) + int(
351
+ attr(j) in plural_names[entity_i.name]
352
+ )
353
+
354
+ tiers = [
355
+ lambda i, j: exact(i, j) and named(i, j) == 2,
356
+ lambda i, j: exact(i, j) and named(i, j) == 1,
357
+ exact,
358
+ ]
359
+ if not self_ref:
360
+ tiers.append(lambda i, j: True)
361
+ free_a = [i for i in sorted(side_a) if guessable(i)]
362
+ free_b = [j for j in sorted(side_b) if guessable(j)]
363
+ for fits in tiers:
364
+ for i in free_a:
365
+ if i in used:
366
+ continue
367
+ if self_ref and self._INVERSE_KIND[rels[i][2]] == rels[i][2]:
368
+ continue # two M:N / 1:1 self-references are two relationships
369
+ j = next((j for j in free_b if j not in used and j != i and fits(i, j)), None)
370
+ if j is not None:
371
+ pair(i, j)
372
+ return pairs
373
+
374
+ def _class_attr_names(self, name: str) -> "set[str]":
375
+ """Attribute names that refer to class ``name``: ``user``, ``users``, ``categories``."""
376
+ snake = self._snake_case(name)
377
+ names = {snake, snake + "s"}
378
+ if snake.endswith("y") and snake[-2:-1] not in ("a", "e", "i", "o", "u", ""):
379
+ names.add(snake[:-1] + "ies")
380
+ elif snake.endswith(("s", "x", "z", "ch", "sh")):
381
+ names.add(snake + "es")
382
+ return names
383
+
384
+ def _merged_line(
385
+ self,
386
+ kept: "Tuple[EntityInfo, str, str, str]",
387
+ folded: "Tuple[EntityInfo, str, str, str]",
388
+ ) -> str:
389
+ """One edge for both sides of a relationship; each end from its own side (#239)."""
390
+ entity, target, kind, attr = kept
391
+ other, _, other_kind, other_attr = folded
392
+ left = self._mirror(self._end(other, other_kind, other_attr))
393
+ right = self._end(entity, kind, attr)
394
+ return f'{entity.name} {left}--{right} {target} : "{attr}"'
194
395
 
195
396
  def _relationship_lines(self) -> List[str]:
196
397
  """Resolve every relationship line, de-duplicated and ordered.
@@ -198,7 +399,11 @@ class _ERGenerator:
198
399
  Order: direct foreign-key edges, then many-to-many through link tables,
199
400
  then declared relationships for pairs not already connected (so keyless
200
401
  models get edges without duplicating SQLModel/SQLAlchemy foreign keys).
402
+ Empty when the generator was built with ``include_relationships=False``
403
+ (``--no-relationships``, #232).
201
404
  """
405
+ if not self.include_relationships:
406
+ return []
202
407
  link_table_map = self._build_link_table_map()
203
408
  lines: List[str] = []
204
409
  seen: set[str] = set()
@@ -217,20 +422,17 @@ class _ERGenerator:
217
422
  lines.append(rel)
218
423
  seen.add(rel)
219
424
 
220
- connected_pairs = self._connected_pairs()
425
+ link_pairs: set[frozenset[str]] = set()
221
426
  for table_a, table_b in link_table_map:
222
427
  entity_a = self._entity_by_table(table_a)
223
428
  entity_b = self._entity_by_table(table_b)
224
429
  if entity_a and entity_b:
225
- connected_pairs.add(frozenset((entity_a.name, entity_b.name)))
430
+ link_pairs.add(frozenset((entity_a.name, entity_b.name)))
226
431
 
227
- for entity in self.entities.values():
228
- for rel, pair in self._generate_relationship_list_lines(entity):
229
- if pair in connected_pairs or rel in seen:
230
- continue
432
+ for rel in self._declared_relationship_lines(self._connected_pairs(), link_pairs):
433
+ if rel not in seen:
231
434
  lines.append(rel)
232
435
  seen.add(rel)
233
- connected_pairs.add(pair)
234
436
 
235
437
  return lines
236
438
 
@@ -244,6 +446,8 @@ class PlantUMLGenerator(_ERGenerator):
244
446
  entities: Entity name to EntityInfo, as returned by the parsers.
245
447
  enums: Optional enum name to EnumInfo.
246
448
  title: Diagram title.
449
+ include_relationships: Draw relationship lines (``False`` omits the
450
+ whole ``' Relationships`` section).
247
451
  """
248
452
 
249
453
  def generate(self) -> str:
@@ -284,11 +488,12 @@ class PlantUMLGenerator(_ERGenerator):
284
488
  lines.extend(self._generate_entity(entity))
285
489
  lines.append("")
286
490
 
287
- lines.append("' Relationships")
288
- lines.append("")
289
- lines.extend(self._relationship_lines())
491
+ if self.include_relationships:
492
+ lines.append("' Relationships")
493
+ lines.append("")
494
+ lines.extend(self._relationship_lines())
495
+ lines.append("")
290
496
 
291
- lines.append("")
292
497
  lines.append("@enduml")
293
498
 
294
499
  return "\n".join(lines)
@@ -358,6 +563,7 @@ class MermaidGenerator(_ERGenerator):
358
563
  entities: Entity name to EntityInfo, as returned by the parsers.
359
564
  enums: Optional enum name to EnumInfo.
360
565
  title: Accepted for a uniform API; Mermaid ``erDiagram`` has no title.
566
+ include_relationships: Draw relationship lines.
361
567
  """
362
568
 
363
569
  def generate(self) -> str:
@@ -465,6 +671,7 @@ def generate_plantuml(
465
671
  entities=entities,
466
672
  enums=enums if include_enums else None,
467
673
  title=title,
674
+ include_relationships=include_relationships,
468
675
  )
469
676
  return generator.generate()
470
677
 
@@ -494,6 +701,7 @@ def generate_mermaid(
494
701
  entities=entities,
495
702
  enums=enums if include_enums else None,
496
703
  title=title,
704
+ include_relationships=include_relationships,
497
705
  )
498
706
  return generator.generate()
499
707
 
@@ -511,7 +719,8 @@ def generate_json(
511
719
 
512
720
  Shape: ``{schema_version, title, entities: [{name, table_name, source, is_link_table,
513
721
  fields: [{name, type, primary_key, foreign_key, nullable, foreign_table,
514
- index, unique, default}], relationships: [{target, type, attribute, nullable}]}],
722
+ index, unique, default}], relationships: [{target, type, attribute, nullable,
723
+ inverse}]}],
515
724
  enums:
516
725
  [{name, values}]}``. Downstream tools can consume this without re-parsing.
517
726
  ``schema_version`` is :data:`JSON_SCHEMA_VERSION`; consumers should ignore
@@ -559,6 +768,7 @@ def generate_json(
559
768
  "type": rel_type,
560
769
  "attribute": attr,
561
770
  "nullable": rel_type == "one" and attr in entity.nullable_relationships,
771
+ "inverse": entity.inverse_relationships.get(attr),
562
772
  }
563
773
  for target, rel_type, attr in entity.relationships
564
774
  ]
@@ -0,0 +1,26 @@
1
+ """AST-based parser for SQLModel, SQLAlchemy, Django, Pydantic and dataclass models.
2
+
3
+ Re-exports what :mod:`erdify` and the CLI use. The stable public surface is
4
+ ``erdify.__all__``; this package and its submodules are internal and may
5
+ change in any release.
6
+ """
7
+
8
+ from .core import (
9
+ ASTDatabaseParser,
10
+ ModelParseError,
11
+ ScanReport,
12
+ parse_models_directory,
13
+ scan_report,
14
+ )
15
+ from .dialects import MODEL_SOURCES
16
+ from .discovery import DEFAULT_EXCLUDE_DIRS, _match_include, _translate_glob # noqa: F401
17
+
18
+ __all__ = [
19
+ "ASTDatabaseParser",
20
+ "DEFAULT_EXCLUDE_DIRS",
21
+ "MODEL_SOURCES",
22
+ "ModelParseError",
23
+ "ScanReport",
24
+ "parse_models_directory",
25
+ "scan_report",
26
+ ]