data-flow-diagram 1.10.0__tar.gz → 1.11.0__tar.gz

{data-flow-diagram-1.10.0 → data_flow_diagram-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: data-flow-diagram
-Version: 1.10.0
+Version: 1.11.0
 Summary: Commandline tool to generate data flow diagrams from text
 Home-page: https://github.com/pbauermeister/dfd
 Author: Pascal Bauermeister
@@ -9,7 +9,6 @@ License: GNU General Public License v3 (GPLv3)
 Project-URL: Bug Reports, https://github.com/pbauermeister/dfd/issues
 Project-URL: Source, https://github.com/pbauermeister/dfd
 Keywords: diagram-generator,development,tool
-Platform: UNKNOWN
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Information Technology
 Classifier: Topic :: Software Development
@@ -19,7 +18,21 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10, <4
 Description-Content-Type: text/markdown
 Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
 Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
 
 # DFD
 
@@ -132,5 +145,3 @@ examples.
 [src]: https://github.com/pbauermeister/dfd
 [pypi]: https://pypi.org/project/data-flow-diagram
 [doc]: https://github.com/pbauermeister/dfd/tree/master/doc/README.md
-
-

{data-flow-diagram-1.10.0 → data_flow_diagram-1.11.0}/setup.py

@@ -12,7 +12,7 @@ long_description = (here / "README.md").read_text(encoding="utf-8")
 
 setup(
     name="data-flow-diagram",
-    version="1.10.0",
+    version="1.11.0",
     description="Commandline tool to generate data flow diagrams from text",
     long_description=long_description,
     long_description_content_type="text/markdown",
@@ -39,9 +39,9 @@ setup(
         "test": ["coverage"],
     },
     package_data={
-#        "data_flow_diagram": ["tbdpackage__data.dat"],
+        #        "data_flow_diagram": ["tbdpackage__data.dat"],
     },
-#    data_files=[('data_flow_diagram', ["VERSION"])],
+    #    data_files=[('data_flow_diagram', ["VERSION"])],
     # The following would provide a command called `data-flow-diagram` which
     # executes the function `main` from this package when invoked:
     entry_points={
@@ -51,8 +51,8 @@ setup(
     },
     project_urls={
         "Bug Reports": "https://github.com/pbauermeister/dfd/issues",
-#        "Funding": "https://donate.pypi.org",
-#        "Say Thanks!": "http://saythanks.io/to/example",
+        #        "Funding": "https://donate.pypi.org",
+        #        "Say Thanks!": "http://saythanks.io/to/example",
         "Source": "https://github.com/pbauermeister/dfd",
     },
 )

data_flow_diagram-1.11.0/src/data_flow_diagram/__init__.py

@@ -0,0 +1,211 @@
+"""Command-line DFD diagram generator. Converts a textual description
+into a graphic file.
+
+-----
+
+See https://github.com/pbauermeister/dfd for information, syntax and
+examples.
+
+-----
+
+This module parses the commandline args, prepares the I/Os and calls the stuff.
+"""
+
+import argparse
+import io
+import os
+import re
+import sys
+import tempfile
+from typing import TextIO
+
+import pkg_resources
+
+from . import dfd, dot, markdown, model
+from .error import print_error
+
+try:
+    VERSION = pkg_resources.require("data-flow-diagram")[0].version
+except pkg_resources.DistributionNotFound:
+    VERSION = 'undefined'
+
+
+def parse_args() -> argparse.Namespace:
+    description, epilog = [each.strip() for each in __doc__.split('-----')[:2]]
+
+    parser = argparse.ArgumentParser(description=description, epilog=epilog)
+
+    parser.add_argument(
+        'INPUT_FILE',
+        action='store',
+        default=None,
+        nargs='?',
+        help='UML sequence input file; ' 'if omitted, stdin is used',
+    )
+
+    parser.add_argument(
+        '--output-file',
+        '-o',
+        required=False,
+        help='output file name; pass \'-\' to use stdout; '
+        'if omitted, use INPUT_FILE base name with \'.svg\' '
+        'extension, or stdout',
+    )
+
+    parser.add_argument(
+        '--markdown',
+        '-m',
+        action='store_true',
+        help='consider snippets between opening marker: '
+        '```data-flow-diagram OUTFILE, and closing marker: ``` '
+        'allowing to generate all diagrams contained in an '
+        'INPUT_FILE that is a markdown file',
+    )
+
+    parser.add_argument(
+        '--format',
+        '-f',
+        required=False,
+        default='svg',
+        help='output format: gif, jpg, tiff, bmp, pnm, eps, '
+        'pdf, svg (any supported by Graphviz); default is svg',
+    )
+
+    parser.add_argument(
+        '--percent-zoom',
+        '-p',
+        required=False,
+        default=100,
+        type=int,
+        help='magnification percentage; default is 100',
+    )
+
+    parser.add_argument(
+        '--background-color',
+        '-b',
+        required=False,
+        default='white',
+        help='background color name (including \'none\' for'
+        ' transparent) in web color notation; see'
+        ' https://developer.mozilla.org/en-US/docs/Web/CSS/color_value'
+        ' for a list of valid names; default is white',
+    )
+
+    parser.add_argument(
+        '--no-graph-title',
+        action='store_true',
+        default=False,
+        help='suppress graph title',
+    )
+
+    parser.add_argument(
+        '--no-check-dependencies',
+        action='store_true',
+        default=False,
+        help='suppress dependencies checking',
+    )
+
+    parser.add_argument(
+        '--debug',
+        action='store_true',
+        default=False,
+        help='emit debug messages',
+    )
+
+    parser.add_argument(
+        '--version',
+        '-V',
+        action='store_true',
+        help='print the version and exit',
+    )
+
+    return parser.parse_args()
+
+
+def handle_markdown_source(
+    options: model.Options, provenance: str, input_fp: TextIO
+) -> None:
+    text = input_fp.read()
+    snippets = markdown.extract_snippets(text)
+    markdown.check_snippets_unicity(provenance, snippets)
+    snippets_params = markdown.make_snippets_params(provenance, snippets)
+    for params in snippets_params:
+        dfd.build(
+            params.root,
+            params.input_fp.read(),
+            params.file_name,
+            options,
+            snippet_by_name=params.snippet_by_name,
+        )
+        print(f'{sys.argv[0]}: generated {params.file_name}', file=sys.stderr)
+
+
+def handle_dfd_source(
+    options: model.Options, provenance: str, input_fp: TextIO, output_path: str
+) -> None:
+    root = model.SourceLine("", provenance, None, None)
+    if output_path == '-':
+        # output to stdout
+        with tempfile.TemporaryDirectory() as d:
+            path = os.path.join(d, 'file.svg')
+            dfd.build(root, input_fp.read(), path, options)
+            with open(path) as f:
+                print(f.read())
+    else:
+        # output to file
+        dfd.build(root, input_fp.read(), output_path, options)
+
+
+def run(args: argparse.Namespace) -> None:
+    # adjust input
+    if args.INPUT_FILE is None:
+        input_fp = sys.stdin
+        provenance = '<stdin>'
+    else:
+        input_fp = open(args.INPUT_FILE)
+        provenance = f'<file:{args.INPUT_FILE}>'
+
+    options = model.Options(
+        args.format,
+        args.percent_zoom,
+        args.background_color,
+        args.no_graph_title,
+        args.no_check_dependencies,
+        args.debug,
+    )
+
+    # markdown source
+    if args.markdown:
+        handle_markdown_source(options, provenance, input_fp)
+        return
+
+    # adjust output
+    if args.output_file is None:
+        if args.INPUT_FILE is not None:
+            basename = os.path.splitext(args.INPUT_FILE)[0]
+            output_path = basename + '.' + args.format
+        else:
+            output_path = '-'
+    else:
+        output_path = args.output_file
+
+    # DFD source
+    handle_dfd_source(options, provenance, input_fp, output_path)
+
+
+def main() -> None:
+    """Entry point for the application script"""
+
+    dot.check_installed()
+
+    args = parse_args()
+    if args.version:
+        print('data-flow-diagram', VERSION)
+        sys.exit(0)
+
+    try:
+        run(args)
+    except model.DfdException as e:
+        text = f'ERROR: {e}'
+        print_error(text)
+        sys.exit(1)

{data-flow-diagram-1.10.0 → data_flow_diagram-1.11.0}/src/data_flow_diagram/dependency_checker.py

@@ -3,8 +3,11 @@ import sys
 from . import model, scanner, parser
 
 
-def check(dependencies: model.GraphDependencies, snippet_by_name: model.SnippetByName,
-          options: model.Options) -> None:
+def check(
+    dependencies: model.GraphDependencies,
+    snippet_by_name: model.SnippetByName | None,
+    options: model.Options,
+) -> None:
 
     snippet_by_name = snippet_by_name or {}
     errors: list[str] = []
@@ -37,34 +40,40 @@ def check(dependencies: model.GraphDependencies, snippet_by_name: model.SnippetB
         # if only graph is targetted, we're done
         if dep.to_item is None:
             if dep.to_type != model.NONE:
-                errors.append(f'{prefix}A whole graph may only be referred to '
-                              f'by an item of type "{model.NONE}", and not '
-                              f'"{dep.to_type}"')
+                errors.append(
+                    f'{prefix}A whole graph may only be referred to '
+                    f'by an item of type "{model.NONE}", and not '
+                    f'"{dep.to_type}"'
+                )
             continue
 
         # scan and parse
         lines = scanner.scan(dep.source, text, snippet_by_name, options.debug)
-        statements, _ = parser.parse(lines, options.debug)
+        statements, _, _ = parser.parse(lines, options.debug)
 
         # find name
         item = find_item(dep.to_item, statements)
         if item:
             if dep.to_type != item.type:
-                errors.append(f'{prefix}Referred item "{dep.to_item}" is of '
-                              f'type "{item.type}", but is referred to as '
-                              f'type "{dep.to_type}"')
+                errors.append(
+                    f'{prefix}Referred item "{dep.to_item}" is of '
+                    f'type "{item.type}", but is referred to as '
+                    f'type "{dep.to_type}"'
+                )
 
             continue  # Found!
 
-        errors.append(f'{prefix}Referring to unknown item name "{dep.to_item}"'
-                      f' of {what} "{name}"')
+        errors.append(
+            f'{prefix}Referring to unknown item name "{dep.to_item}"'
+            f' of {what} "{name}"'
+        )
 
     if errors:
         errors.insert(0, 'Dependency error(s) found:')
         raise model.DfdException('\n\n'.join(errors))
 
 
-def find_item(name: str, statements: model.Statements) -> model.Item:
+def find_item(name: str, statements: model.Statements) -> model.Item | None:
     for statement in statements:
         match statement:
             case model.Item() as item:

{data-flow-diagram-1.10.0 → data_flow_diagram-1.11.0}/src/data_flow_diagram/dfd.py

@@ -1,21 +1,26 @@
 """Run the generation process"""
 
 import os.path
+import pprint
 import re
 import textwrap
 from typing import Any, Optional
 
-from . import config
+from . import config, dependency_checker
 from . import dfd_dot_templates as TMPL
-from . import dot, model, parser, scanner, dependency_checker
+from . import dot, model, parser, scanner
 
 
-def build(provenance: model.SourceLine, dfd_src: str, output_path: str,
-          options: model.Options,
-          snippet_by_name: model.SnippetByName = None) -> None:
+def build(
+    provenance: model.SourceLine,
+    dfd_src: str,
+    output_path: str,
+    options: model.Options,
+    snippet_by_name: model.SnippetByName | None = None,
+) -> None:
     """Take a DFD source and build the final image or document"""
     lines = scanner.scan(provenance, dfd_src, snippet_by_name, options.debug)
-    statements, dependencies = parser.parse(lines, options.debug)
+    statements, dependencies, attribs = parser.parse(lines, options.debug)
     if dependencies and not options.no_check_dependencies:
         dependency_checker.check(dependencies, snippet_by_name, options)
     items_by_name = parser.check(statements)
@@ -23,11 +28,11 @@ def build(provenance: model.SourceLine, dfd_src: str, output_path: str,
     statements, graph_options = handle_options(statements)
 
     if options.no_graph_title:
-        title = None
+        title = ""
     else:
         title = os.path.splitext(output_path)[0]
 
-    gen = Generator(graph_options)
+    gen = Generator(graph_options, attribs)
     text = generate_dot(gen, title, statements, items_by_name)
     if options.debug:
         print(text)
@@ -44,11 +49,15 @@ def wrap(text: str, cols: int) -> str:
 class Generator:
     RX_NUMBERED_NAME = re.compile(r'(\d+[.])(.*)')
 
-    def __init__(self, graph_options: model.GraphOptions) -> None:
+    def __init__(
+        self, graph_options: model.GraphOptions, attribs: model.Attribs
+    ) -> None:
         self.lines: list[str] = []
         self.star_nr = 0
         self.frame_nr = 0
         self.graph_options = graph_options
+        self.attribs = attribs
+        self.attribs_rx = self._compile_attribs_names(attribs)
 
     def append(self, line: str, statement: model.Statement) -> None:
         self.lines.append('')
@@ -57,14 +66,16 @@ class Generator:
         self.lines.append(line)
 
     def generate_item(self, item: model.Item) -> None:
-        text = item.text
-        hits = self.RX_NUMBERED_NAME.findall(text)
+        copy = model.Item(**item.__dict__)
+        hits = self.RX_NUMBERED_NAME.findall(copy.text)
         if hits:
-            text = '\\n'.join(hits[0])
+            copy.text = '\\n'.join(hits[0])
 
-        text = wrap(text, self.graph_options.item_text_width)
-        attrs = item.attrs or ''
-        match item.type:
+        copy.text = wrap(copy.text, self.graph_options.item_text_width)
+        attrs = copy.attrs or ''
+        attrs = self._expand_attribs(attrs)
+
+        match copy.type:
             case model.PROCESS:
                 if self.graph_options.is_context:
                     shape = 'circle'
@@ -72,30 +83,37 @@ class Generator:
                 else:
                     shape = 'ellipse'
                     fc = '"#eeeeee"'
-                line = (f'"{item.name}" [shape={shape} label="{text}" '
-                        f'fillcolor={fc} style=filled {attrs}]')
+                line = (
+                    f'"{copy.name}" [shape={shape} label="{copy.text}" '
+                    f'fillcolor={fc} style=filled {attrs}]'
+                )
             case model.CONTROL:
                 fc = '"#eeeeee"'
-                line = (f'"{item.name}" [shape=ellipse label="{text}" '
-                        f'fillcolor={fc} style="filled,dashed" {attrs}]')
+                line = (
+                    f'"{copy.name}" [shape=ellipse label="{copy.text}" '
+                    f'fillcolor={fc} style="filled,dashed" {attrs}]'
+                )
             case model.ENTITY:
-                line = (f'"{item.name}" [shape=rectangle label="{text}" '
-                        f'{attrs}]')
+                line = (
+                    f'"{copy.name}" [shape=rectangle label="{copy.text}" '
+                    f'{attrs}]'
+                )
             case model.STORE:
-                d = self._item_to_html_dict(item)
+                d = self._item_to_html_dict(copy)
                 line = TMPL.STORE.format(**d)
             case model.NONE:
-                line = f'"{item.name}" [shape=none label="{text}" {attrs}]'
+                line = f'"{copy.name}" [shape=none label="{copy.text}" {attrs}]'
             case model.CHANNEL:
-                d = self._item_to_html_dict(item)
+                d = self._item_to_html_dict(copy)
                 if self.graph_options.is_vertical:
                     line = TMPL.CHANNEL_HORIZONTAL.format(**d)
                 else:
                     line = TMPL.CHANNEL.format(**d)
             case _:
-                prefix = model.mk_err_prefix_from(item.source)
-                raise model.DfdException(f'{prefix}Unsupported item type '
-                                         f'"{item.type}"')
+                prefix = model.mk_err_prefix_from(copy.source)
+                raise model.DfdException(
+                    f'{prefix}Unsupported item type ' f'"{copy.type}"'
+                )
         self.append(line, item)
 
     def _item_to_html_dict(self, item: model.Item) -> dict[str, Any]:
@@ -103,6 +121,32 @@ class Generator:
         d['text'] = d['text'].replace('\\n', '<br/>')
         return d
 
+    def _compile_attribs_names(
+        self, attribs: model.Attribs
+    ) -> re.Pattern[str] | None:
+        if not attribs:
+            return None
+        names = [re.escape(k) for k in attribs.keys()]
+        pattern = '|'.join(names)
+        return re.compile(pattern)
+
+    def _expand_attribs(self, attrs: str) -> str:
+        def replacer(m: re.Match[str]) -> str:
+            alias = m[0]
+            if alias not in self.attribs:
+                raise model.DfdException(
+                    f'Alias '
+                    f'"{alias}" '
+                    f'not found in '
+                    f'{pprint.pformat(self.attribs)}'
+                )
+
+            return self.attribs[alias].text
+
+        return (
+            self.attribs_rx.sub(replacer, attrs) if self.attribs_rx else attrs
+        )
+
     def generate_star(self, text: str) -> str:
         text = wrap(text, self.graph_options.item_text_width)
         star_name = f'__star_{self.star_nr}__'
@@ -111,8 +155,12 @@ class Generator:
         self.star_nr += 1
         return star_name
 
-    def generate_connection(self, conn: model.Connection, src_item: model.Item,
-                            dst_item: model.Item) -> None:
+    def generate_connection(
+        self,
+        conn: model.Connection,
+        src_item: model.Item | None,
+        dst_item: model.Item | None,
+    ) -> None:
         text = conn.text or ''
         text = wrap(text, self.graph_options.connection_text_width)
 
@@ -135,8 +183,9 @@ class Generator:
                 dst_port = ':x:c'
 
         attrs = f'label="{text}"'
+
         if conn.attrs:
-            attrs += ' ' + conn.attrs
+            attrs += ' ' + self._expand_attribs(conn.attrs)
 
         match conn.type:
             case model.FLOW:
@@ -158,8 +207,9 @@ class Generator:
                 attrs += ' style=dashed'
             case _:
                 prefix = model.mk_err_prefix_from(conn.source)
-                raise model.DfdException(f'{prefix}Unsupported connection type '
-                                         f'"{conn.type}"')
+                raise model.DfdException(
+                    f'{prefix}Unsupported connection type ' f'"{conn.type}"'
+                )
         if conn.relaxed:
             attrs += ' constraint=false'
 
@@ -204,9 +254,14 @@ class Generator:
         return text
 
 
-def generate_dot(gen: Generator, title: str, statements: model.Statements,
-                 items_by_name: dict[str, model.Item]) -> str:
+def generate_dot(
+    gen: Generator,
+    title: str,
+    statements: model.Statements,
+    items_by_name: dict[str, model.Item],
+) -> str:
     """Iterate over statements and generate a dot source file"""
+
     def get_item(name: str) -> Optional[model.Item]:
         return None if name == '*' else items_by_name[name]
 
@@ -234,8 +289,10 @@ def filter_statements(statements: model.Statements) -> model.Statements:
     connected_items = set()
     for statement in statements:
         match statement:
-            case model.Connection() as conn: pass
-            case _: continue
+            case model.Connection() as conn:
+                pass
+            case _:
+                continue
         for point in conn.src, conn.dst:
             connected_items.add(point)
 
@@ -251,8 +308,9 @@ def filter_statements(statements: model.Statements) -> model.Statements:
     return new_statements
 
 
-def handle_options(statements: model.Statements) -> tuple[
-        model.Statements, model.GraphOptions]:
+def handle_options(
+    statements: model.Statements,
+) -> tuple[model.Statements, model.GraphOptions]:
     new_statements = []
     options = model.GraphOptions()
     for statement in statements:
@@ -278,8 +336,9 @@ def handle_options(statements: model.Statements) -> tuple[
                             raise model.DfdException(f'{prefix}{e}"')
 
                     case _:
-                        raise model.DfdException(f'{prefix}Unsupported style '
-                                                 f'"{style.style}"')
+                        raise model.DfdException(
+                            f'{prefix}Unsupported style ' f'"{style.style}"'
+                        )
 
                 continue
         new_statements.append(statement)

{data-flow-diagram-1.10.0 → data_flow_diagram-1.11.0}/src/data_flow_diagram/dfd_dot_templates.py

@@ -38,17 +38,23 @@ DOT_FONT_GRAPH = 'fontname="helvetica" fontsize=9 fontcolor="#000060"'
 
 DOT_GRAPH_TITLE = """graph[label="\n- {title} -" """ + DOT_FONT_GRAPH + """]"""
 
-DOT = """
+DOT = (
+    """
 digraph D {{
   {graph_params}
-  edge[color=gray """ + DOT_FONT_EDGE + """]
-  node[""" + DOT_FONT_NODE + """]
+  edge[color=gray """
+    + DOT_FONT_EDGE
+    + """]
+  node["""
+    + DOT_FONT_NODE
+    + """]
   {block}
 }}
 """.strip()
+)
 
 
 GRAPH_PARAMS_CONTEXT_DIAGRAM = 'edge [len=2.25]'
 
 
-ITEM_EXTERNAL_ATTRS = 'fillcolor=white color=grey fontcolor=grey'
+ITEM_EXTERNAL_ATTRS = 'fillcolor=white color=grey fontcolor=grey'

{data-flow-diagram-1.10.0 → data_flow_diagram-1.11.0}/src/data_flow_diagram/dot.py

@@ -7,14 +7,15 @@ from . import model
 from .error import print_error
 
 
-def generate_image(graph_options: model.GraphOptions,
-                   text: str, output_path: str, format: str) -> None:
+def generate_image(
+    graph_options: model.GraphOptions, text: str, output_path: str, format: str
+) -> None:
     if graph_options.is_context:
         engine = 'neato'  # circo is not as good
     else:
         engine = 'dot'
 
-    cmd = [engine, f'-T{format}',  f'-o{output_path}']
+    cmd = [engine, f'-T{format}', f'-o{output_path}']
     try:
         subprocess.run(cmd, input=text, encoding='utf-8', check=True)
     except subprocess.CalledProcessError as e:
@@ -22,7 +23,7 @@ def generate_image(graph_options: model.GraphOptions,
             print(f'{n+1:2}: {line}', file=sys.stderr)
         print_error(f'ERROR: {e}')
         sys.exit(1)
-    #print('Generated:', output_path, file=sys.stderr)
+    # print('Generated:', output_path, file=sys.stderr)
 
 
 def check_installed() -> None:

{data-flow-diagram-1.10.0 → data_flow_diagram-1.11.0}/src/data_flow_diagram/error.py

@@ -1,6 +1,7 @@
 import sys
 
+
 def print_error(text: str) -> None:
     if sys.stderr.isatty():
         text = f'\033[31m{text}\033[0m'
-    print(text, file=sys.stderr)
+    print(text, file=sys.stderr)