In [1]:
Copied!
import inspect
import rich.syntax
import erdantic.examples.pydantic
rich.syntax.Syntax(
inspect.getsource(erdantic.examples.pydantic), "python", theme="default", line_numbers=True
)
import inspect
import rich.syntax
import erdantic.examples.pydantic
rich.syntax.Syntax(
inspect.getsource(erdantic.examples.pydantic), "python", theme="default", line_numbers=True
)
Out[1]:
1 """Example data model classes using [Pydantic](https://pydantic-docs.helpmanual.io/).""" 2 3 from datetime import datetime 4 from enum import Enum 5 from typing import List, Optional 6 7 from pydantic import BaseModel 8 9 10 class Alignment(str, Enum): 11 LAWFUL_GOOD = "lawful_good" 12 NEUTRAL_GOOD = "neutral_good" 13 CHAOTIC_GOOD = "chaotic_good" 14 LAWFUL_NEUTRAL = "lawful_neutral" 15 TRUE_NEUTRAL = "true_neutral" 16 CHAOTIC_NEUTRAL = "chaotic_neutral" 17 LAWFUL_EVIL = "lawful_evil" 18 NEUTRAL_EVIL = "neutral_evil" 19 CHAOTIC_EVIL = "chaotic_evil" 20 21 22 class Adventurer(BaseModel): 23 """A person often late for dinner but with a tale or two to tell. 24 25 Attributes: 26 name (str): Name of this adventurer 27 profession (str): Profession of this adventurer 28 alignment (Alignment): Alignment of this adventurer 29 level (int): Level of this adventurer 30 """ 31 32 name: str 33 profession: str 34 alignment: Alignment 35 level: int = 1 36 37 38 class QuestGiver(BaseModel): 39 """A person who offers a task that needs completing. 40 41 Attributes: 42 name (str): Name of this quest giver 43 faction (str): Faction that this quest giver belongs to 44 location (str): Location this quest giver can be found 45 """ 46 47 name: str 48 faction: Optional[str] = None 49 location: str = "Adventurer's Guild" 50 51 52 class Quest(BaseModel): 53 """A task to complete, with some monetary reward. 54 55 Attributes: 56 name (str): Name by which this quest is referred to 57 giver (QuestGiver): Person who offered the quest 58 reward_gold (int): Amount of gold to be rewarded for quest completion 59 """ 60 61 name: str 62 giver: QuestGiver 63 reward_gold: int = 100 64 65 66 class Party(BaseModel): 67 """A group of adventurers finding themselves doing and saying things altogether unexpected. 68 69 Attributes: 70 name (str): Name that party is known by 71 formed_datetime (datetime): Timestamp of when the party was formed 72 members (List[Adventurer]): Adventurers that belong to this party 73 active_quest (Optional[Quest]): Current quest that party is actively tackling 74 """ 75 76 name: str 77 formed_datetime: datetime 78 members: List[Adventurer] = [] 79 active_quest: Optional[Quest] = None 80
Using the CLI¶
The fastest way to rendering a diagram is to use the command-line interface. Below we use IPython's ! to run a command in the system shell. We pass the full dotted path to the root class of our composition hierarchy, along with an output file path. erdantic will walk the composition graph to find all child classes.
In [2]:
Copied!
!erdantic erdantic.examples.pydantic.Party -o diagram.png
!erdantic erdantic.examples.pydantic.Party -o diagram.png
2024-09-19 23:31:45,123 | erdantic.core | INFO | Adding model 'erdantic.examples.pydantic.Party' to diagram... 2024-09-19 23:31:45,125 | erdantic.core | INFO | Rendering diagram to diagram.png
2024-09-19 23:31:45,165 | erdantic.cli | INFO | Rendered diagram to diagram.png
The format rendered is inferred from the file extension.
Using the Python library¶
You can also use the erdantic Python library, which lets you inspect the diagram object. The diagram object contains all of the data that erdantic extracted about the model you provide, as well as any related models. As demonstrated below, the diagram object automatically pretty-prints in IPython or Jupyter notebooks and even automatically renders in Jupyter notebooks.
In [3]:
Copied!
import erdantic as erd
from erdantic.examples.pydantic import Party
diagram = erd.create(Party)
diagram
import erdantic as erd
from erdantic.examples.pydantic import Party
diagram = erd.create(Party)
diagram
EntityRelationshipDiagram( models={ 'erdantic.examples.pydantic.Adventurer': ModelInfo(...), 'erdantic.examples.pydantic.Party': ModelInfo(...), 'erdantic.examples.pydantic.Quest': ModelInfo(...), 'erdantic.examples.pydantic.QuestGiver': ModelInfo(...) }, edges={ 'erdantic.examples.pydantic.Party-active_quest-erdantic.examples.pydantic.Quest': Edge(...), 'erdantic.examples.pydantic.Party-members-erdantic.examples.pydantic.Adventurer': Edge(...), 'erdantic.examples.pydantic.Quest-giver-erdantic.examples.pydantic.QuestGiver': Edge(...) } )
Out[3]:
Inspecting the data¶
The models attribute gives you access to a dictionary of ModelInfo objects that contain the data for each model in the diagram. All of erdantic's data objects are Pydantic models.
Tip
If you have the rich library installed, the IPython/Jupyter representation of erdantic's data objects will be nicely colored.
In [4]:
Copied!
list(diagram.models.keys())
list(diagram.models.keys())
Out[4]:
['erdantic.examples.pydantic.Adventurer', 'erdantic.examples.pydantic.Party', 'erdantic.examples.pydantic.Quest', 'erdantic.examples.pydantic.QuestGiver']
In [5]:
Copied!
diagram.models["erdantic.examples.pydantic.Party"]
diagram.models["erdantic.examples.pydantic.Party"]
ModelInfo( full_name=FullyQualifiedName(module='erdantic.examples.pydantic', qual_name='Party'), name='Party', fields={ 'name': FieldInfo( model_full_name=FullyQualifiedName(module='erdantic.examples.pydantic', qual_name='Party'), name='name', type_name='str' ), 'formed_datetime': FieldInfo( model_full_name=FullyQualifiedName(module='erdantic.examples.pydantic', qual_name='Party'), name='formed_datetime', type_name='datetime' ), 'members': FieldInfo( model_full_name=FullyQualifiedName(module='erdantic.examples.pydantic', qual_name='Party'), name='members', type_name='List[Adventurer]' ), 'active_quest': FieldInfo( model_full_name=FullyQualifiedName(module='erdantic.examples.pydantic', qual_name='Party'), name='active_quest', type_name='Optional[Quest]' ) }, description='erdantic.examples.pydantic.Party\n\nA group of adventurers finding themselves doing and saying things altogether unexpected.\n\nAttributes:\n name (str): Name that party is known by\n formed_datetime (datetime): Timestamp of when the party was formed\n members (List[Adventurer]): Adventurers that belong to this party\n active_quest (Optional[Quest]): Current quest that party is actively tackling\n' )
Out[5]:
And the edges attribute gives you access to a dictionary of Edge objects that contain the data for each relationship between the models.
In [6]:
Copied!
list(diagram.edges.keys())
list(diagram.edges.keys())
Out[6]:
['erdantic.examples.pydantic.Party-active_quest-erdantic.examples.pydantic.Quest', 'erdantic.examples.pydantic.Party-members-erdantic.examples.pydantic.Adventurer', 'erdantic.examples.pydantic.Quest-giver-erdantic.examples.pydantic.QuestGiver']
In [7]:
Copied!
diagram.edges["erdantic.examples.pydantic.Party-members-erdantic.examples.pydantic.Adventurer"]
diagram.edges["erdantic.examples.pydantic.Party-members-erdantic.examples.pydantic.Adventurer"]
Edge( source_model_full_name=FullyQualifiedName(module='erdantic.examples.pydantic', qual_name='Party'), source_field_name='members', target_model_full_name=FullyQualifiedName(module='erdantic.examples.pydantic', qual_name='Adventurer'), target_cardinality=<Cardinality.MANY: 'many'>, target_modality=<Modality.UNSPECIFIED: 'unspecified'>, source_cardinality=<Cardinality.UNSPECIFIED: 'unspecified'>, source_modality=<Modality.UNSPECIFIED: 'unspecified'> )
Out[7]:
Rendering the diagram to an image file¶
You can use the draw method to render the diagram to disk.
In [8]:
Copied!
diagram.draw("diagram.svg")
# Equivalently, use erd.draw directly from Party
# erd.draw(Party, out="diagram.svg")
diagram.draw("diagram.svg")
# Equivalently, use erd.draw directly from Party
# erd.draw(Party, out="diagram.svg")
erdantic uses Graphviz, a well-established open-source C library, to create the diagram. Graphviz uses the DOT language for describing graphs. You use the to_dot method to get the DOT representation as a string.
In [9]:
Copied!
print(diagram.to_dot())
# Equivalently, use erd.to_dot directly from Party
assert diagram.to_dot() == erd.to_dot(Party)
print(diagram.to_dot())
# Equivalently, use erd.to_dot directly from Party
assert diagram.to_dot() == erd.to_dot(Party)
digraph "Entity Relationship Diagram created by erdantic" {
graph [fontcolor=gray66,
fontname="Times New Roman,Times,Liberation Serif,serif",
fontsize=9,
label="Created by erdantic v1.0.5 <https://github.com/drivendataorg/erdantic>",
nodesep=0.5,
rankdir=LR,
ranksep=1.5
];
node [fontname="Times New Roman,Times,Liberation Serif,serif",
fontsize=14,
label="\N",
shape=plain
];
edge [dir=both];
"erdantic.examples.pydantic.Adventurer" [label=<<table border="0" cellborder="1" cellspacing="0"><tr><td port="_root" colspan="2"><b>Adventurer</b></td></tr><tr><td>name</td><td port="name">str</td></tr><tr><td>profession</td><td port="profession">str</td></tr><tr><td>alignment</td><td port="alignment">Alignment</td></tr><tr><td>level</td><td port="level">int</td></tr></table>>,
tooltip="erdantic.examples.pydantic.Adventurer

A person often late for dinner but with a tale or two to tell.

Attributes:&#\
xA; name (str): Name of this adventurer
 profession (str): Profession of this adventurer
 alignment (Alignment): \
Alignment of this adventurer
 level (int): Level of this adventurer
"];
"erdantic.examples.pydantic.Party" [label=<<table border="0" cellborder="1" cellspacing="0"><tr><td port="_root" colspan="2"><b>Party</b></td></tr><tr><td>name</td><td port="name">str</td></tr><tr><td>formed_datetime</td><td port="formed_datetime">datetime</td></tr><tr><td>members</td><td port="members">List[Adventurer]</td></tr><tr><td>active_quest</td><td port="active_quest">Optional[Quest]</td></tr></table>>,
tooltip="erdantic.examples.pydantic.Party

A group of adventurers finding themselves doing and saying things altogether unexpected.&#\
xA;
Attributes:
 name (str): Name that party is known by
 formed_datetime (datetime): Timestamp of when the party \
was formed
 members (List[Adventurer]): Adventurers that belong to this party
 active_quest (Optional[Quest]): Current \
quest that party is actively tackling
"];
"erdantic.examples.pydantic.Party":members:e -> "erdantic.examples.pydantic.Adventurer":_root:w [arrowhead=crownone,
arrowtail=nonenone];
"erdantic.examples.pydantic.Quest" [label=<<table border="0" cellborder="1" cellspacing="0"><tr><td port="_root" colspan="2"><b>Quest</b></td></tr><tr><td>name</td><td port="name">str</td></tr><tr><td>giver</td><td port="giver">QuestGiver</td></tr><tr><td>reward_gold</td><td port="reward_gold">int</td></tr></table>>,
tooltip="erdantic.examples.pydantic.Quest

A task to complete, with some monetary reward.

Attributes:
 name (str): \
Name by which this quest is referred to
 giver (QuestGiver): Person who offered the quest
 reward_gold (int): Amount \
of gold to be rewarded for quest completion
"];
"erdantic.examples.pydantic.Party":active_quest:e -> "erdantic.examples.pydantic.Quest":_root:w [arrowhead=noneteeodot,
arrowtail=nonenone];
"erdantic.examples.pydantic.QuestGiver" [label=<<table border="0" cellborder="1" cellspacing="0"><tr><td port="_root" colspan="2"><b>QuestGiver</b></td></tr><tr><td>name</td><td port="name">str</td></tr><tr><td>faction</td><td port="faction">Optional[str]</td></tr><tr><td>location</td><td port="location">str</td></tr></table>>,
tooltip="erdantic.examples.pydantic.QuestGiver

A person who offers a task that needs completing.

Attributes:
 name (\
str): Name of this quest giver
 faction (str): Faction that this quest giver belongs to
 location (str): Location \
this quest giver can be found
"];
"erdantic.examples.pydantic.Quest":giver:e -> "erdantic.examples.pydantic.QuestGiver":_root:w [arrowhead=noneteetee,
arrowtail=nonenone];
}
Terminal Models¶
If you have an enormous composition graph and want to chop it up, you can make that work by specifying models to be terminal nodes.
For the CLI, use the -t option to specify a model to be a terminus. To specify more than one, used repeated -t options. So, for example, if you want one diagram rooted by Party that terminates at Quest, and another diagram that is rooted by Quest, you can use the following two shell commands.
erdantic erdantic.examples.pydantic.Party \
-t erdantic erdantic.examples.pydantic.Quest \
-o party.png
erdantic erdantic.examples.pydantic.Quest -o quest.png
When using the Python library, pass your terminal node in a list to the terminal_models keyword argument. Below is the Python code for creating diagrams equivalent to the above shell commands.
In [10]:
Copied!
from erdantic.examples.pydantic import Quest
diagram1 = erd.create(Party, terminal_models=[Quest])
diagram1
from erdantic.examples.pydantic import Quest
diagram1 = erd.create(Party, terminal_models=[Quest])
diagram1
EntityRelationshipDiagram( models={ 'erdantic.examples.pydantic.Adventurer': ModelInfo(...), 'erdantic.examples.pydantic.Party': ModelInfo(...), 'erdantic.examples.pydantic.Quest': ModelInfo(...) }, edges={ 'erdantic.examples.pydantic.Party-active_quest-erdantic.examples.pydantic.Quest': Edge(...), 'erdantic.examples.pydantic.Party-members-erdantic.examples.pydantic.Adventurer': Edge(...) } )
Out[10]:
In [11]:
Copied!
diagram2 = erd.create(Quest)
diagram2
diagram2 = erd.create(Quest)
diagram2
EntityRelationshipDiagram( models={ 'erdantic.examples.pydantic.Quest': ModelInfo(...), 'erdantic.examples.pydantic.QuestGiver': ModelInfo(...) }, edges={'erdantic.examples.pydantic.Quest-giver-erdantic.examples.pydantic.QuestGiver': Edge(...)} )
Out[11]:
