Usage Example: attrs¶

This notebook shows an example of using erdantic with classes created with the attrs package.

Let's take a look at the attrs classes (from here on in referred to as "models") from the erdantic.examples.attrs module. Here's their source code for clarity.

In [1]:

import inspect
import rich.syntax

import erdantic.examples.attrs


rich.syntax.Syntax(
    inspect.getsource(erdantic.examples.attrs), 
    "python",
    theme="default",
    line_numbers=True
)

import inspect import rich.syntax import erdantic.examples.attrs rich.syntax.Syntax( inspect.getsource(erdantic.examples.attrs), "python", theme="default", line_numbers=True )

Out[1]:

   1 """Example data model classes using standard library's                                                        
   2 [`dataclasses`](https://docs.python.org/3/library/dataclasses.html) module."""                                
   3                                                                                                               
   4 from datetime import datetime                                                                                 
   5 from enum import Enum                                                                                         
   6 from typing import List, Optional                                                                             
   7                                                                                                               
   8 from attrs import define, field                                                                               
   9                                                                                                               
  10                                                                                                               
  11 class Alignment(str, Enum):                                                                                   
  12     LAWFUL_GOOD = "lawful_good"                                                                               
  13     NEUTRAL_GOOD = "neutral_good"                                                                             
  14     CHAOTIC_GOOD = "chaotic_good"                                                                             
  15     LAWFUL_NEUTRAL = "lawful_neutral"                                                                         
  16     TRUE_NEUTRAL = "true_neutral"                                                                             
  17     CHAOTIC_NEUTRAL = "chaotic_neutral"                                                                       
  18     LAWFUL_EVIL = "lawful_evil"                                                                               
  19     NEUTRAL_EVIL = "neutral_evil"                                                                             
  20     CHAOTIC_EVIL = "chaotic_evil"                                                                             
  21                                                                                                               
  22                                                                                                               
  23 @define                                                                                                       
  24 class Adventurer:                                                                                             
  25     """A person often late for dinner but with a tale or two to tell.                                         
  26                                                                                                               
  27     Attributes:                                                                                               
  28         name (str): Name of this adventurer                                                                   
  29         profession (str): Profession of this adventurer                                                       
  30         level (int): Level of this adventurer                                                                 
  31         alignment (Alignment): Alignment of this adventurer                                                   
  32     """                                                                                                       
  33                                                                                                               
  34     name: str                                                                                                 
  35     profession: str                                                                                           
  36     alignment: Alignment                                                                                      
  37     level: int = 1                                                                                            
  38                                                                                                               
  39                                                                                                               
  40 @define                                                                                                       
  41 class QuestGiver:                                                                                             
  42     """A person who offers a task that needs completing.                                                      
  43                                                                                                               
  44     Attributes:                                                                                               
  45         name (str): Name of this quest giver                                                                  
  46         faction (str): Faction that this quest giver belongs to                                               
  47         location (str): Location this quest giver can be found                                                
  48     """                                                                                                       
  49                                                                                                               
  50     name: str                                                                                                 
  51     faction: Optional[str] = None                                                                             
  52     location: str = "Adventurer's Guild"                                                                      
  53                                                                                                               
  54                                                                                                               
  55 @define                                                                                                       
  56 class Quest:                                                                                                  
  57     """A task to complete, with some monetary reward.                                                         
  58                                                                                                               
  59     Attributes:                                                                                               
  60         name (str): Name by which this quest is referred to                                                   
  61         giver (QuestGiver): Person who offered the quest                                                      
  62         reward_gold (int): Amount of gold to be rewarded for quest completion                                 
  63     """                                                                                                       
  64                                                                                                               
  65     name: str                                                                                                 
  66     giver: QuestGiver                                                                                         
  67     reward_gold: int = 100                                                                                    
  68                                                                                                               
  69                                                                                                               
  70 @define                                                                                                       
  71 class Party:                                                                                                  
  72     """A group of adventurers finding themselves doing and saying things altogether unexpected.               
  73                                                                                                               
  74     Attributes:                                                                                               
  75         name (str): Name that party is known by                                                               
  76         formed_datetime (datetime): Timestamp of when the party was formed                                    
  77         members (List[Adventurer]): Adventurers that belong to this party                                     
  78         active_quest (Optional[Quest]): Current quest that party is actively tackling                         
  79     """                                                                                                       
  80                                                                                                               
  81     name: str                                                                                                 
  82     formed_datetime: datetime                                                                                 
  83     members: List[Adventurer] = field(factory=list)                                                           
  84     active_quest: Optional[Quest] = None                                                                      
  85                                                                                                               

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]:

!erdantic erdantic.examples.attrs.Party -o diagram.png

!erdantic erdantic.examples.attrs.Party -o diagram.png

2024-07-16 17:47:28,723 | erdantic.core | INFO | Adding model 'erdantic.examples.attrs.Party' to diagram...

2024-07-16 17:47:28,726 | erdantic.core | INFO | Rendering diagram to diagram.png

2024-07-16 17:47:30,040 | 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]:

import erdantic as erd
from erdantic.examples.attrs import Party


diagram = erd.create(Party)
diagram

import erdantic as erd from erdantic.examples.attrs import Party diagram = erd.create(Party) diagram

EntityRelationshipDiagram(
    models={
        'erdantic.examples.attrs.Adventurer': ModelInfo(...),
        'erdantic.examples.attrs.Party': ModelInfo(...),
        'erdantic.examples.attrs.Quest': ModelInfo(...),
        'erdantic.examples.attrs.QuestGiver': ModelInfo(...)
    },
    edges={
        'erdantic.examples.attrs.Party-active_quest-erdantic.examples.attrs.Quest': Edge(...),
        'erdantic.examples.attrs.Party-members-erdantic.examples.attrs.Adventurer': Edge(...),
        'erdantic.examples.attrs.Quest-giver-erdantic.examples.attrs.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]:

list(diagram.models.keys())

list(diagram.models.keys())

Out[4]:

['erdantic.examples.attrs.Adventurer',
 'erdantic.examples.attrs.Party',
 'erdantic.examples.attrs.Quest',
 'erdantic.examples.attrs.QuestGiver']

In [5]:

diagram.models['erdantic.examples.attrs.Party']

diagram.models['erdantic.examples.attrs.Party']

ModelInfo(
    full_name=FullyQualifiedName(module='erdantic.examples.attrs', qual_name='Party'),
    name='Party',
    fields={
        'name': FieldInfo(
            model_full_name=FullyQualifiedName(module='erdantic.examples.attrs', qual_name='Party'),
            name='name',
            type_name='str'
        ),
        'formed_datetime': FieldInfo(
            model_full_name=FullyQualifiedName(module='erdantic.examples.attrs', qual_name='Party'),
            name='formed_datetime',
            type_name='datetime'
        ),
        'members': FieldInfo(
            model_full_name=FullyQualifiedName(module='erdantic.examples.attrs', qual_name='Party'),
            name='members',
            type_name='List[Adventurer]'
        ),
        'active_quest': FieldInfo(
            model_full_name=FullyQualifiedName(module='erdantic.examples.attrs', qual_name='Party'),
            name='active_quest',
            type_name='Optional[Quest]'
        )
    },
    description='erdantic.examples.attrs.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]:

list(diagram.edges.keys())

list(diagram.edges.keys())

Out[6]:

['erdantic.examples.attrs.Party-active_quest-erdantic.examples.attrs.Quest',
 'erdantic.examples.attrs.Party-members-erdantic.examples.attrs.Adventurer',
 'erdantic.examples.attrs.Quest-giver-erdantic.examples.attrs.QuestGiver']

In [7]:

diagram.edges["erdantic.examples.attrs.Party-members-erdantic.examples.attrs.Adventurer"]

diagram.edges["erdantic.examples.attrs.Party-members-erdantic.examples.attrs.Adventurer"]

Edge(
    source_model_full_name=FullyQualifiedName(module='erdantic.examples.attrs', qual_name='Party'),
    source_field_name='members',
    target_model_full_name=FullyQualifiedName(module='erdantic.examples.attrs', 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]:

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]:

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.4 <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.attrs.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.attrs.Adventurer&#xA;&#xA;A person often late for dinner but with a tale or two to tell.&#xA;&#xA;Attributes:&#\
xA;    name (str): Name of this adventurer&#xA;    profession (str): Profession of this adventurer&#xA;    level (int): Level of \
this adventurer&#xA;    alignment (Alignment): Alignment of this adventurer&#xA;"];
	"erdantic.examples.attrs.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.attrs.Party&#xA;&#xA;A group of adventurers finding themselves doing and saying things altogether unexpected.&#\
xA;&#xA;Attributes:&#xA;    name (str): Name that party is known by&#xA;    formed_datetime (datetime): Timestamp of when the party \
was formed&#xA;    members (List[Adventurer]): Adventurers that belong to this party&#xA;    active_quest (Optional[Quest]): Current \
quest that party is actively tackling&#xA;"];
	"erdantic.examples.attrs.Party":members:e -> "erdantic.examples.attrs.Adventurer":_root:w	[arrowhead=crownone,
		arrowtail=nonenone];
	"erdantic.examples.attrs.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.attrs.Quest&#xA;&#xA;A task to complete, with some monetary reward.&#xA;&#xA;Attributes:&#xA;    name (str): Name \
by which this quest is referred to&#xA;    giver (QuestGiver): Person who offered the quest&#xA;    reward_gold (int): Amount of \
gold to be rewarded for quest completion&#xA;"];
	"erdantic.examples.attrs.Party":active_quest:e -> "erdantic.examples.attrs.Quest":_root:w	[arrowhead=noneteeodot,
		arrowtail=nonenone];
	"erdantic.examples.attrs.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.attrs.QuestGiver&#xA;&#xA;A person who offers a task that needs completing.&#xA;&#xA;Attributes:&#xA;    name (\
str): Name of this quest giver&#xA;    faction (str): Faction that this quest giver belongs to&#xA;    location (str): Location \
this quest giver can be found&#xA;"];
	"erdantic.examples.attrs.Quest":giver:e -> "erdantic.examples.attrs.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.attrs.Party \ 
    -t erdantic erdantic.examples.attrs.Quest \
    -o party.png
erdantic erdantic.examples.attrs.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]:

from erdantic.examples.attrs import Quest

diagram1 = erd.create(Party, terminal_models=[Quest])
diagram1

from erdantic.examples.attrs import Quest diagram1 = erd.create(Party, terminal_models=[Quest]) diagram1

EntityRelationshipDiagram(
    models={
        'erdantic.examples.attrs.Adventurer': ModelInfo(...),
        'erdantic.examples.attrs.Party': ModelInfo(...),
        'erdantic.examples.attrs.Quest': ModelInfo(...)
    },
    edges={
        'erdantic.examples.attrs.Party-active_quest-erdantic.examples.attrs.Quest': Edge(...),
        'erdantic.examples.attrs.Party-members-erdantic.examples.attrs.Adventurer': Edge(...)
    }
)

Out[10]:

In [11]:

diagram2 = erd.create(Quest)
diagram2

diagram2 = erd.create(Quest) diagram2

EntityRelationshipDiagram(
    models={
        'erdantic.examples.attrs.Quest': ModelInfo(...),
        'erdantic.examples.attrs.QuestGiver': ModelInfo(...)
    },
    edges={'erdantic.examples.attrs.Quest-giver-erdantic.examples.attrs.QuestGiver': Edge(...)}
)

Out[11]: