drawpyo 0.1__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.
drawpyo-0.1/PKG-INFO ADDED
@@ -0,0 +1,141 @@
1
+ Metadata-Version: 2.1
2
+ Name: drawpyo
3
+ Version: 0.1
4
+ Summary: A Python library for programmatically generating Draw.io charts.
5
+ Keywords: draw.io,diagrams.net,diagrams
6
+ Author-email: Xander Cesari <xander@merriman.industries>
7
+ Requires-Python: >=3.8
8
+ Description-Content-Type: text/markdown
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Operating System :: OS Independent
12
+ Requires-Dist: toml >= 0.10.2; python_version < '3.11'
13
+ Requires-Dist: mkdocstrings[python] >= 0.18
14
+ Project-URL: Homepage, https://github.com/MerrimanInd/drawpyo
15
+ Project-URL: Issues, https://github.com/MerrimanInd/drawpyo/issues
16
+
17
+ # drawpyo
18
+
19
+ Drawpyo is a Python library for programmatically generating Diagrams.net/Draw.io charts. It enables creating a diagram object, placing and styling objects, then writing the object to a file.
20
+
21
+ # History/Justification
22
+
23
+ I love Draw.io! Compared to expensive and heavy commercial options like Visio and Miro, Draw.io's free and lightweight app allows wider and more universal distribution of diagrams. Because the files are stored in plaintext they can be versioned alongside code in a repository as documentation. The XML-based file format makes these diagrams semi-portable, and could easily be ported to other applications if Draw.io ever failed you. For these reason, I think it's one of the best options for documentation diagrams.
24
+
25
+ When I had a need to generate heirarchical tree diagrams of requirement structures I was surprised to find there wasn't even a single existing Python library for working with these files. I took the project home and spent a weekend building the initial functionality. I've been adding functionality, robustness, and documentation intermittently since.
26
+
27
+ # Full Documentation
28
+
29
+ Available here!
30
+
31
+ https://merrimanind.github.io/drawpyo/
32
+
33
+ # Basic Usage
34
+
35
+ The basic mode of interacting with drawpyo is to manually create, style, and place objects just like you would using the Draw.io UI. There are a number of ways to style objects and you can write your own functionality for automatically handling style or placement.
36
+
37
+ ## Make a new file
38
+
39
+ ```python
40
+ import drawpyo
41
+ diagram = drawpyo.File()
42
+ file.file_path = r"C:\drawpyo"
43
+ file.file_name = "Test Generated Edges.drawio"
44
+ # Add a page
45
+ page = drawpy.Page(file=file)
46
+ ```
47
+
48
+ ## Add an object
49
+
50
+ ```python
51
+ item = drawpyo.diagram.Object(page=page, value="new object")
52
+ item.position = (0, 0)
53
+ ```
54
+
55
+ ## Create an object from the base style libraries available in the Draw.io UI
56
+
57
+ ```python
58
+ item_from_lib = drawpyo.diagram.object_from_library(
59
+ page=page,
60
+ library="general",
61
+ obj_name="process",
62
+ value="New Process",
63
+ )
64
+ ```
65
+
66
+ ## Style an object from a string
67
+
68
+ ```python
69
+ item_from_stylestr = drawpyo.diagram.Object(page=page)
70
+ item_from_stylestr.apply_style_string("rounded=1;whiteSpace=wrap;html=1;fillColor=#6a00ff;fontColor=#ffffff;strokeColor=#000000;gradientColor=#FF33FF;strokeWidth=4;")
71
+ ```
72
+
73
+ ## Write the file
74
+
75
+ ```python
76
+ file.write()
77
+ ```
78
+
79
+ # Usage with a diagram type
80
+
81
+ There is also functionality available in drawpyo that extends what can be done in Draw.io's app! These diagram types allow for easy and automatic creation of specific diagrams.
82
+
83
+ The only diagram type that's released is the tree diagram. Varying level of conceptual work has been started for:
84
+
85
+ - Automatic class/object/inheritance diagrams of a python module
86
+
87
+ - Flowcharts
88
+
89
+ - Process diagrams
90
+
91
+ ## Working with TreeDiagrams
92
+
93
+ Create a new tree diagram:
94
+
95
+ ```python
96
+ from drawpyo.diagram_types import TreeDiagram, NodeObject
97
+
98
+ tree = TreeDiagram(
99
+ file_path = path.join(path.expanduser('~'), "Test Drawpyo Charts"),
100
+ file_name = "Coffee Grinders.drawio",
101
+ direction = "down",
102
+ link_style = "orthogonal",
103
+ )
104
+ ```
105
+
106
+ The direction property sets which way the leaf nodes grow from the root: up, down, left, or right. The link_style can be orthogonal, straight, or curved.
107
+
108
+ Create some NodeObjects:
109
+
110
+ ```python
111
+ # Top object
112
+ grinders = NodeObject(tree=tree, value="Appliances for Grinding Coffee", base_style="rounded rectangle")
113
+
114
+ # Main categories
115
+ blade_grinders = NodeObject(tree=tree, value="Blade Grinders", parent=grinders)
116
+ burr_grinders = NodeObject(tree=tree, value="Burr Grinders", parent=grinders)
117
+ blunt_objects = NodeObject(tree=tree, value="Blunt Objects", parent=grinders)
118
+ ```
119
+
120
+ Note that the base_style was manually declared for the first object. But NodeObjects will default to "rounded rectangle" so it's not necessary for every one. Any NodeObject can be a parent, so you can keep adding objects down the tree:
121
+
122
+ ```python
123
+ # Other
124
+ elec_blade = NodeObject(tree=tree, value="Electric Blade Grinder", parent=blade_grinders)
125
+ mnp = NodeObject(tree=tree, value="Mortar and Pestle", parent=blunt_objects)
126
+
127
+ # Conical Burrs
128
+ conical = NodeObject(tree=tree, value="Conical Burrs", parent=burr_grinders)
129
+ elec_conical = NodeObject(tree=tree, value="Electric", parent=conical)
130
+ manual_conical = NodeObject(tree=tree, value="Manual", parent=conical)
131
+ ```
132
+
133
+ > **Important Note:** TreeDiagrams do not currently support NodeObjects with multiple parents! It may not ever as this seriously complicates the auto layout process. However, you can add links between any two objects in the tree and render them in the diagram. They just may look ugly until you manually rearrange the diagram.
134
+
135
+ Finally, before writing the diagram you'll want to run the magic penultimate step: auto layout.
136
+
137
+ ```python
138
+ tree.auto_layout()
139
+ tree.write()
140
+ ```
141
+
drawpyo-0.1/README.md ADDED
@@ -0,0 +1,124 @@
1
+ # drawpyo
2
+
3
+ Drawpyo is a Python library for programmatically generating Diagrams.net/Draw.io charts. It enables creating a diagram object, placing and styling objects, then writing the object to a file.
4
+
5
+ # History/Justification
6
+
7
+ I love Draw.io! Compared to expensive and heavy commercial options like Visio and Miro, Draw.io's free and lightweight app allows wider and more universal distribution of diagrams. Because the files are stored in plaintext they can be versioned alongside code in a repository as documentation. The XML-based file format makes these diagrams semi-portable, and could easily be ported to other applications if Draw.io ever failed you. For these reason, I think it's one of the best options for documentation diagrams.
8
+
9
+ When I had a need to generate heirarchical tree diagrams of requirement structures I was surprised to find there wasn't even a single existing Python library for working with these files. I took the project home and spent a weekend building the initial functionality. I've been adding functionality, robustness, and documentation intermittently since.
10
+
11
+ # Full Documentation
12
+
13
+ Available here!
14
+
15
+ https://merrimanind.github.io/drawpyo/
16
+
17
+ # Basic Usage
18
+
19
+ The basic mode of interacting with drawpyo is to manually create, style, and place objects just like you would using the Draw.io UI. There are a number of ways to style objects and you can write your own functionality for automatically handling style or placement.
20
+
21
+ ## Make a new file
22
+
23
+ ```python
24
+ import drawpyo
25
+ diagram = drawpyo.File()
26
+ file.file_path = r"C:\drawpyo"
27
+ file.file_name = "Test Generated Edges.drawio"
28
+ # Add a page
29
+ page = drawpy.Page(file=file)
30
+ ```
31
+
32
+ ## Add an object
33
+
34
+ ```python
35
+ item = drawpyo.diagram.Object(page=page, value="new object")
36
+ item.position = (0, 0)
37
+ ```
38
+
39
+ ## Create an object from the base style libraries available in the Draw.io UI
40
+
41
+ ```python
42
+ item_from_lib = drawpyo.diagram.object_from_library(
43
+ page=page,
44
+ library="general",
45
+ obj_name="process",
46
+ value="New Process",
47
+ )
48
+ ```
49
+
50
+ ## Style an object from a string
51
+
52
+ ```python
53
+ item_from_stylestr = drawpyo.diagram.Object(page=page)
54
+ item_from_stylestr.apply_style_string("rounded=1;whiteSpace=wrap;html=1;fillColor=#6a00ff;fontColor=#ffffff;strokeColor=#000000;gradientColor=#FF33FF;strokeWidth=4;")
55
+ ```
56
+
57
+ ## Write the file
58
+
59
+ ```python
60
+ file.write()
61
+ ```
62
+
63
+ # Usage with a diagram type
64
+
65
+ There is also functionality available in drawpyo that extends what can be done in Draw.io's app! These diagram types allow for easy and automatic creation of specific diagrams.
66
+
67
+ The only diagram type that's released is the tree diagram. Varying level of conceptual work has been started for:
68
+
69
+ - Automatic class/object/inheritance diagrams of a python module
70
+
71
+ - Flowcharts
72
+
73
+ - Process diagrams
74
+
75
+ ## Working with TreeDiagrams
76
+
77
+ Create a new tree diagram:
78
+
79
+ ```python
80
+ from drawpyo.diagram_types import TreeDiagram, NodeObject
81
+
82
+ tree = TreeDiagram(
83
+ file_path = path.join(path.expanduser('~'), "Test Drawpyo Charts"),
84
+ file_name = "Coffee Grinders.drawio",
85
+ direction = "down",
86
+ link_style = "orthogonal",
87
+ )
88
+ ```
89
+
90
+ The direction property sets which way the leaf nodes grow from the root: up, down, left, or right. The link_style can be orthogonal, straight, or curved.
91
+
92
+ Create some NodeObjects:
93
+
94
+ ```python
95
+ # Top object
96
+ grinders = NodeObject(tree=tree, value="Appliances for Grinding Coffee", base_style="rounded rectangle")
97
+
98
+ # Main categories
99
+ blade_grinders = NodeObject(tree=tree, value="Blade Grinders", parent=grinders)
100
+ burr_grinders = NodeObject(tree=tree, value="Burr Grinders", parent=grinders)
101
+ blunt_objects = NodeObject(tree=tree, value="Blunt Objects", parent=grinders)
102
+ ```
103
+
104
+ Note that the base_style was manually declared for the first object. But NodeObjects will default to "rounded rectangle" so it's not necessary for every one. Any NodeObject can be a parent, so you can keep adding objects down the tree:
105
+
106
+ ```python
107
+ # Other
108
+ elec_blade = NodeObject(tree=tree, value="Electric Blade Grinder", parent=blade_grinders)
109
+ mnp = NodeObject(tree=tree, value="Mortar and Pestle", parent=blunt_objects)
110
+
111
+ # Conical Burrs
112
+ conical = NodeObject(tree=tree, value="Conical Burrs", parent=burr_grinders)
113
+ elec_conical = NodeObject(tree=tree, value="Electric", parent=conical)
114
+ manual_conical = NodeObject(tree=tree, value="Manual", parent=conical)
115
+ ```
116
+
117
+ > **Important Note:** TreeDiagrams do not currently support NodeObjects with multiple parents! It may not ever as this seriously complicates the auto layout process. However, you can add links between any two objects in the tree and render them in the diagram. They just may look ugly until you manually rearrange the diagram.
118
+
119
+ Finally, before writing the diagram you'll want to run the magic penultimate step: auto layout.
120
+
121
+ ```python
122
+ tree.auto_layout()
123
+ tree.write()
124
+ ```
@@ -0,0 +1,31 @@
1
+ [build-system]
2
+ requires = ["flit_core >=3.2,<4"]
3
+ build-backend = "flit_core.buildapi"
4
+
5
+ [project]
6
+ name = "drawpyo"
7
+ authors = [{name = "Xander Cesari", email = "xander@merriman.industries"}]
8
+ description = "A Python library for programmatically generating Draw.io charts."
9
+ keywords = ["draw.io", "diagrams.net", "diagrams"]
10
+ readme = "README.md"
11
+ license = {text = "MIT License"}
12
+ classifiers = [
13
+ "Programming Language :: Python :: 3",
14
+ "License :: OSI Approved :: MIT License",
15
+ "Operating System :: OS Independent",
16
+ ]
17
+ requires-python = ">=3.8"
18
+ dynamic = ["version"]
19
+ dependencies = [
20
+ "toml >= 0.10.2; python_version < '3.11'",
21
+ "mkdocstrings[python] >= 0.18",
22
+ ]
23
+
24
+ [project.urls]
25
+ Homepage = "https://github.com/MerrimanInd/drawpyo"
26
+ Issues = "https://github.com/MerrimanInd/drawpyo/issues"
27
+
28
+ [tool.pytest.ini_options]
29
+ addopts = [
30
+ "--import-mode=importlib",
31
+ ]
@@ -0,0 +1,8 @@
1
+ from .xml_base import XMLBase
2
+ from .file import File
3
+ from .page import Page
4
+
5
+ from drawpyo import diagram
6
+ from drawpyo import diagram_types
7
+
8
+ __version__ = "0.1"
@@ -0,0 +1,3 @@
1
+ from .base_diagram import *
2
+ from .edges import *
3
+ from .objects import *
@@ -0,0 +1,296 @@
1
+ from ..xml_base import XMLBase
2
+ from os import path
3
+
4
+
5
+ __all__ = [
6
+ "DiagramBase",
7
+ "style_str_from_dict",
8
+ "import_shape_database",
9
+ "color_input_check",
10
+ ]
11
+
12
+
13
+ def color_input_check(color_str):
14
+ if color_str == None:
15
+ return None
16
+ elif color_str == "none":
17
+ return color_str
18
+ elif color_str == "default":
19
+ return color_str
20
+ elif color_str[0] == "#" and len(color_str) == 7:
21
+ return color_str
22
+
23
+
24
+ def import_shape_database(file_name, relative=False):
25
+ """
26
+ This function imports a TOML shape database and returns a dictionary of the
27
+ shapes defined therein. It supports inheritance, meaning that if there is
28
+ an inherit value in any of the shape dictionaries it will attempt to go
29
+ find the inherited master shape and use it as a starting format, but
30
+ overwriting any styles defined in both with the style defined in the child
31
+ object.
32
+
33
+ Parameters
34
+ ----------
35
+ filename : str
36
+ The path to a TOML file containing a style library database.
37
+
38
+ Returns
39
+ -------
40
+ data : dict
41
+ A database of shapes defined in the TOML file.
42
+
43
+ """
44
+ # Import the shape and edge definitions
45
+ from sys import version_info
46
+
47
+ if relative:
48
+ # toml path
49
+ dirname = path.dirname(__file__)
50
+ dirname = path.split(dirname)[0]
51
+ file_name = path.join(dirname, file_name)
52
+
53
+ if version_info.minor < 11:
54
+ import toml
55
+
56
+ data = toml.load(file_name)
57
+ else:
58
+ import tomllib
59
+
60
+ with open(file_name, "rb") as f:
61
+ data = tomllib.load(f)
62
+
63
+ for obj in data.values():
64
+ if "inherit" in obj:
65
+ obj.update(data[obj["inherit"]])
66
+
67
+ return data
68
+
69
+
70
+ def style_str_from_dict(style_dict):
71
+ """
72
+ This function returns a concatenated style string from a style dictionary.
73
+ This format is:
74
+ baseStyle;attr1=value;attr2=value
75
+ It will concatenate the key:value pairs with the appropriate semicolons and
76
+ equals except for the baseStyle, which it will prepend to the front with no
77
+ equals sign.
78
+
79
+ Parameters
80
+ ----------
81
+ style_dict : dict
82
+ A dictionary of style:value pairs.
83
+
84
+ Returns
85
+ -------
86
+ str
87
+ A string with the style_dicts values concatenated correctly.
88
+
89
+ """
90
+ if "baseStyle" in style_dict:
91
+ style_str = [style_dict.pop("baseStyle")]
92
+ else:
93
+ style_str = []
94
+ style_str = style_str + [
95
+ "{0}={1}".format(att, style)
96
+ for (att, style) in style_dict.items()
97
+ if style != "" and style != None
98
+ ]
99
+ return ";".join(style_str)
100
+
101
+
102
+ class DiagramBase(XMLBase):
103
+ """
104
+ This class is the base for all diagram objects to inherit from. It defines some general creation methods and properties to make diagram objects printable and useful.
105
+ """
106
+
107
+ def __init__(self, **kwargs):
108
+ super().__init__(**kwargs)
109
+ self._style_attributes = ["html"]
110
+ self.page = kwargs.get("page", None)
111
+ self.xml_parent = kwargs.get("xml_parent", None)
112
+
113
+ @classmethod
114
+ def create_from_library(cls, library, obj):
115
+ return cls
116
+
117
+ # XML_parent property
118
+ @property
119
+ def xml_parent_id(self):
120
+ if self.xml_parent is not None:
121
+ return self.xml_parent.id
122
+ else:
123
+ return 1
124
+
125
+ # Parent object linking
126
+ @property
127
+ def xml_parent(self):
128
+ return self._xml_parent
129
+
130
+ @xml_parent.setter
131
+ def xml_parent(self, p):
132
+ if p is not None:
133
+ p.add_object(self)
134
+ self._xml_parent = p
135
+ else:
136
+ self._xml_parent = None
137
+
138
+ @xml_parent.deleter
139
+ def xml_parent(self):
140
+ self._xml_parent.remove_object(self)
141
+ self._xml_parent = None
142
+
143
+ # Page property
144
+ @property
145
+ def page_id(self):
146
+ if self.page is not None:
147
+ return self.page.id
148
+ else:
149
+ return 1
150
+
151
+ # page object linking
152
+ @property
153
+ def page(self):
154
+ return self._page
155
+
156
+ @page.setter
157
+ def page(self, p):
158
+ if p is not None:
159
+ p.add_object(self)
160
+ self._page = p
161
+ else:
162
+ self._page = None
163
+
164
+ @page.deleter
165
+ def page(self):
166
+ self._page.remove_object(self)
167
+ self._page = None
168
+
169
+ ###########################################################
170
+ # Style properties
171
+ ###########################################################
172
+ def add_style_attribute(self, style_attr):
173
+ if style_attr not in self._style_attributes:
174
+ self._style_attributes.append(style_attr)
175
+
176
+ @property
177
+ def style_attributes(self):
178
+ """
179
+ The style attributes are the list of style tags that should be printed into the style XML attribute. This is a subset of the attributes defined on the object method.
180
+
181
+ Returns:
182
+ list: A list of the names of the style_attributes.
183
+ """
184
+ return self._style_attributes
185
+
186
+ @style_attributes.setter
187
+ def style_attributes(self, value):
188
+ self._style_attributes = value
189
+
190
+ @property
191
+ def style(self):
192
+ """
193
+ This function returns the style string of the object to be appended into the style XML attribute.
194
+
195
+ First it searches the object properties called out in
196
+ self.style_attributes. If the property is initialized to something
197
+ that isn't None or an empty string, it will add it. Otherwise it
198
+ searches the base_style defined by the object template.
199
+
200
+ Returns:
201
+ str: The style string of the object.
202
+
203
+ """
204
+
205
+ style_str = ""
206
+ if (
207
+ hasattr(self, "baseStyle")
208
+ and getattr(self, "baseStyle") is not None
209
+ and getattr(self, "baseStyle") != ""
210
+ ):
211
+ style_str = getattr(self, "baseStyle") + ";"
212
+
213
+ for attribute in self.style_attributes:
214
+ if hasattr(self, attribute) and getattr(self, attribute) is not None:
215
+ attr_val = getattr(self, attribute)
216
+ # reformat different datatypes to strings
217
+ if isinstance(attr_val, bool):
218
+ attr_val = format(attr_val * 1)
219
+ style_str = style_str + "{0}={1};".format(attribute, attr_val)
220
+ return style_str
221
+
222
+ def _add_and_set_style_attrib(self, attrib, value):
223
+ if hasattr(self, attrib):
224
+ setattr(self, attrib, value)
225
+ else:
226
+ setattr(self, attrib, value)
227
+ self.add_style_attribute(attrib)
228
+
229
+ def apply_style_string(self, style_str):
230
+ """
231
+ This function will apply a passed in style string to the object. This style string can be obtained from the Draw.io app by selecting Edit Style from the context menu of any object. This function will iterate through the attributes in the style string and assign the corresponding property the value.
232
+
233
+ Args:
234
+ style_str (str): A Draw.io style string
235
+ """
236
+ for attrib in style_str.split(";"):
237
+ if attrib == "":
238
+ pass
239
+ elif "=" in attrib:
240
+ a_name = attrib.split("=")[0]
241
+ a_value = attrib.split("=")[1]
242
+ if a_value.isdigit():
243
+ if "." in a_value:
244
+ a_value = float(a_value)
245
+ else:
246
+ a_value = int(a_value)
247
+ elif a_value == "True" or a_value == "False":
248
+ a_value = bool(a_value)
249
+
250
+ self._add_and_set_style_attrib(a_name, a_value)
251
+ else:
252
+ self.baseStyle = attrib
253
+
254
+ def _apply_style_from_template(self, template):
255
+ for attrib in template.style_attributes:
256
+ value = getattr(template, attrib)
257
+ self._add_and_set_style_attrib(attrib, value)
258
+
259
+ def apply_attribute_dict(self, attr_dict):
260
+ """
261
+ This function takes in a dictionary of attributes and applies them
262
+ to the object. These attributes can be style or properties. If the
263
+ attribute isn't already defined as a property of the class it's
264
+ assumed to be a style attribute. It will then be added as a property
265
+ and also appended to the .style_attributes list.
266
+
267
+ Parameters
268
+ ----------
269
+ attr_dict : dict
270
+ A dictionary of attributes to set or add to the object.
271
+
272
+ Returns
273
+ -------
274
+ None.
275
+
276
+ """
277
+ for attr, val in attr_dict.items():
278
+ self._add_and_set_style_attrib(attr, val)
279
+
280
+ @classmethod
281
+ def from_style_string(cls, style_string):
282
+ """
283
+ This classmethod allows the intantiation of an object from a style
284
+ string. This is useful since Draw.io allows copying the style string
285
+ out of an object in their UI. This string can then be copied into the
286
+ Python environment and further objects created that match the style.
287
+
288
+ Args:
289
+ style_string (str): A Draw.io style string
290
+
291
+ Returns:
292
+ BaseDiagram: A BaseDiagram or subclass instantiated with the style from the Draw.io string
293
+ """
294
+ new_obj = cls()
295
+ new_obj.apply_style_string(style_string)
296
+ return new_obj