mi-flatland 2.0.0__py3-none-any.whl

flatland/__init__.py

@@ -0,0 +1 @@
+version = "2.0.0"

flatland/__main__.py

@@ -0,0 +1,162 @@
+"""
+Flatland Diagram Editor
+
+"""
+# System
+import logging
+import logging.config
+import sys
+import atexit
+import argparse
+from pathlib import Path
+
+# Flatland
+from flatland.xuml.xuml_classdiagram import XumlClassDiagram
+from flatland.xuml.xuml_statemachine_diagram import XumlStateMachineDiagram
+from flatland.database.flatland_db import FlatlandDB
+from flatland import version
+
+_logpath = Path("flatland.log")
+
+def clean_up():
+    """Normal and exception exit activities"""
+    _logpath.unlink(missing_ok=True)
+
+def get_logger():
+    """Initiate the logger"""
+    log_conf_path = Path(__file__).parent / 'log.conf'  # Logging configuration is in this file
+    logging.config.fileConfig(fname=log_conf_path, disable_existing_loggers=False)
+    return logging.getLogger(__name__)  # Create a logger for this module
+
+# Configure the expected parameters and actions for the argparse module
+def parse(cl_input):
+    parser = argparse.ArgumentParser(description='Flatland model diagram generator')
+    parser.add_argument('-m', '--model', action='store',
+                        help='xuml model file name defining model connectivity without any layout information')
+    parser.add_argument('-l', '--layout', action='store',
+                        help='Flatland layout file defining all layout information with light\
+                         references to model file.')
+    parser.add_argument('-d', '--diagram', action='store', default='diagram.pdf',
+                        help='Name of file to generate, .pdf extension automatically added')
+    parser.add_argument('-D', '--docs', action='store_true',
+                        help='Copy the project documentation directory into the local directory')
+    parser.add_argument('-CF', '--configuration', action='store_true',
+                        help="Create a new configuration directory in user's flatland home")
+    parser.add_argument('-E', '--examples', action='store_true',
+                        help='Create a directory of examples in the current directory')
+    parser.add_argument('-L', '--log', action='store_true',
+                        help='Generate a diagnostic flatland.log file')
+    parser.add_argument('-N', '--nodes_only', action='store_true',
+                        help='Do not draw any connectors. Helpful to diagnose connector failures due\
+                         to bad node cplace.')
+    parser.add_argument('-NC', '--no_color', action='store_true',
+                        help='Use white instead of the specified sheet color. Useful when creating printer output.'),
+    parser.add_argument('-V', '--version', action='store_true',
+                        help='Print the current version of flatland')
+    parser.add_argument('-G', '--grid', action='store_true',
+                        help='Print the grid so you can diagnose output with row and column boundaries visible')
+    parser.add_argument('-RT', '--show_ref_types', action='store_true',
+                        help='Display referential attribute types on class diagrams')
+    parser.add_argument('-RUL', '--rulers', action='store_true',
+                        help='Print the ruler grid so you check canvas positions')
+    parser.add_argument('-R', '--rebuild', action='store_true',
+                        help='Rebuild the flatland database. Necessary only if corrupted.')
+    return parser.parse_args(cl_input)
+
+
+def main():
+    # Start logging
+    logger = get_logger()
+    logger.info(f'Flatland version: {version}')
+
+    # Keep track of whether or not Config has been run by some command line option so we don't re-run it
+    already_configured = False
+
+    # Parse the command line args
+    args = parse(sys.argv[1:])
+
+    if not args.log:
+        # If no log file is requested, remove the log file before termination
+        atexit.register(clean_up)
+
+    if args.version:
+        # Just print the version and quit
+        print(f'Flatland version: {version}')
+        sys.exit(0)
+
+    # if args.examples:
+    #     # Copy the entire example directory into the users local dir if it does not already exist
+    #     import shutil
+    #     ex_path = Path(__file__).parent / 'examples'
+    #     local_ex_path = Path.cwd() / 'examples'
+    #     if local_ex_path.exists():
+    #         logger.warning("Examples already exist in the current directory. Delete or move it if you want the latest.")
+    #     else:
+    #         logger.info("Copying example directory users local directory")
+    #         shutil.copytree(ex_path, local_ex_path)  # Copy the example directory
+    #         test_gen_path = Path(__file__).parent / 'tests' / 'gen_example_diagrams.py'
+    #         shutil.copy(test_gen_path, local_ex_path)  # Copy the gen_example file into the copied example dir
+    #
+    # if args.docs:
+    #     # Copy the entire docs directory into the users local dir if it does not already exist
+    #     import shutil
+    #     docs_path = Path(__file__).parent / 'documentation'
+    #     local_docs_path = Path.cwd() / 'documentation'
+    #     if local_docs_path.exists():
+    #         logger.warning("Documentation already exists in the current directory.\
+    #          Delete or move it if you want the latest.")
+    #     else:
+    #         logger.info("Copying doc directory to users local directory")
+    #         shutil.copytree(docs_path, local_docs_path)
+    #
+    if args.model and not args.layout:
+        logger.error("A layout file must be specified for your model.")
+        sys.exit(1)
+
+    if args.layout and not args.model:
+        logger.error("A model file must be specified to layout.")
+        sys.exit(1)
+
+    # At this point we either have both model and layout or neither
+    # If neither, the only thing we might do at this point is rebuild the database if requested
+
+    # Do any configuration tasks necessary before starting up the app
+    # The database will be rebuilt if requested
+    if not already_configured:
+        FlatlandDB.create_db(rebuild=args.rebuild)
+
+    # if args.model and args.layout:  # Just making sure we have them both
+        model_path = Path(args.model)
+        layout_path = Path(args.layout)
+        diagram_path = Path(args.diagram)
+
+        # Generate the xuml class diagram (we don't do anything with the returned variable yet)
+        mtype = model_path.suffix
+        if mtype == '.xcm':
+            XumlClassDiagram(
+                xuml_model_path=model_path,
+                flatland_layout_path=layout_path,
+                diagram_file_path=diagram_path,
+                show_grid=args.grid,
+                nodes_only=args.nodes_only,
+                no_color=args.no_color,
+                show_rulers=args.rulers,
+                show_ref_types=args.show_ref_types
+            )
+        elif mtype == '.xsm':
+            statemodel_diagram = XumlStateMachineDiagram(
+                xuml_model_path=model_path,
+                flatland_layout_path=layout_path,
+                diagram_file_path=diagram_path,
+                show_grid=args.grid,
+                nodes_only=args.nodes_only,
+                show_rulers=args.rulers,
+                no_color=args.no_color,
+            )
+
+    logger.info("No problemo")  # We didn't die on an exception, basically
+    print("No problemo")
+
+
+if __name__ == "__main__":
+    main()

flatland/configuration/configDB.py

@@ -0,0 +1,51 @@
+""" configDB.py - Load configuration data """
+
+# System
+from pathlib import Path
+from collections import namedtuple
+from typing import NamedTuple
+
+# Model Integration
+from mi_config.config import Config
+
+# Flatland
+from flatland.names import app
+
+ConfigItem = namedtuple('ConfigItem', 'name collector')
+
+class SheetData(NamedTuple):
+    standard: str
+    height: float
+    width: float
+    size_group: str
+
+class ConfigDB:
+    """
+    A set of yaml config files are processed to build a dictionary of
+    config item data
+    """
+
+    config_path = Path(__file__).parent  # Location of the system yaml files
+
+    item_data = {}
+
+    config_items = [ # Yaml file prefix and tuple, if any, to load data from file
+        ConfigItem(name="metadata", collector=None),
+        ConfigItem(name="sheet", collector=SheetData),
+        ConfigItem(name="titleblock", collector=None),
+        ConfigItem(name="frame", collector=None),
+        ConfigItem(name="notation", collector=None),
+        ConfigItem(name="layout_specification", collector=None),
+        ConfigItem(name="diagram_type", collector=None),
+        ConfigItem(name="connector_type", collector=None),
+        ConfigItem(name="name_placement", collector=None),
+    ]
+
+    @classmethod
+    def __init__(cls):
+        """
+        Load all config items in corresponding yaml files into item_data dictionary
+        """
+        for item in cls.config_items:
+            c = Config(app_name=app, lib_config_dir=cls.config_path, fspec={item.name:item.collector})
+            cls.item_data[item.name] = c.loaded_data[item.name]

flatland/configuration/connector_type.yaml

@@ -0,0 +1,65 @@
+# cconnector_type_name.yaml – Connector type data
+
+# Diagram type / Connector Type / Stem Type, etc
+
+# TODO: clarify meaning of stem type geometry in comment below
+
+class:  # Diagram type
+    stem semantics: [ Mc mult, 1c mult, 1 mult, M mult, superclass, ordinal ] # stem semantics
+    connector types:
+      binary association: # Connector type
+        geometry: binary  # unary, binary, or tree
+        about: Connects an anchor point on one node to an anchor point on the same or another node
+        stem positions:
+          class face:  # Name of stem position
+            about: How many instances may be associated
+            minimum length: 20
+            stretch: fixed  # fixed, hanging, or free
+          association:
+            about: How many association class instances per pair of associated instances
+            minimum length: 24
+            stretch: hanging
+      generalization:
+        geometry: tree
+        about: A superset class compeletely split into disjoint subset classes
+        stem positions:
+          superclass face:
+            about: The superset of all subclass instances
+            minimum length: 15
+            stretch: fixed
+          subclass face:
+            about: A disjoint subset of the superclass set of instances
+            minimum length: 10
+            stretch: fixed
+
+state machine:
+    stem semantics: [ target state, initial pseudo state, final pseudo state ] # stem semantics
+    connector types:
+      initial transition:
+        geometry: unary
+        about: Designates an initial state
+        stem positions:
+          to initial state:
+            about: Points to a designated state as an initial state
+            minimum length: 60
+            stretch: free
+      deletion transition:
+        geometry: unary
+        about: Designates implicit instance deletion after a state executes its activity
+        stem positions:
+          from final state:
+            about: Points away from a final state to indicate deletion
+            minimum length: 10
+            stretch: free
+      transition:
+        geometry: binary
+        about: Defines a path from one state to another
+        stem positions:
+          from state:
+            about: Points to the source state in a transition
+            minimum length: 10
+            stretch: fixed
+          to state:
+            about: Points to the destination state in a transition
+            minimum length: 15
+            stretch: fixed

flatland/configuration/diagram_type.yaml

@@ -0,0 +1,223 @@
+# diagram_type.yaml – Diagram Types
+
+class:  # Diagram type name (class diagram)
+  abbreviation: CD
+  about: >
+    Show data, logic and constraints in a domain
+  notations:  # Supported notations
+    - Starr
+    - xUML
+    - Shlaer-Mellor
+  node types:  # The kinds of nodes that can be drawn on this diagram type
+    class:  # Node type name (a class node)
+      about: >
+        Abstraction of a set of things with the same properties, behavior, 
+        and subject to the same rules and constraints
+      default size:
+        height: 80  # Default size if text fits and user has not specified otherwise
+        width: 110
+      max size:
+        height: 180  # Will not be drawn larger than this size
+        width: 144
+      compartment types:  # The types of compartments that may be stacked inside this node
+        name: # Name of the compartment, in this case the name/title of a class
+          alignment:  # How the text is aligned within this compartment
+            horizontal: center
+            vertical: center
+          padding:  # Margin between internal text and external boundary
+            top: 5
+            bottom: 10
+            left: 5
+            right: 5
+          stack order: 1  # Appearance of compartment with 1 at the top, descending vertically
+        attribute:
+          alignment:
+            horizontal: left
+            vertical: top
+          padding:
+            top: 5
+            bottom: 10
+            left: 5
+            right: 5
+          stack order: 2
+        method:
+          alignment:
+            horizontal: left
+            vertical: top
+          padding:
+            top: 5
+            bottom: 4
+            left: 5
+            right: 5
+          stack order: 3
+
+    imported class:
+      about: >
+        Used when you have a relationship to a class in some other 
+        subsystem of your domain.
+      default size:
+        height: 80
+        width: 110
+      max size:
+        height: 180
+        width: 144
+      compartment types:
+        name:
+          alignment:
+            horizontal: center
+            vertical: center
+          padding:
+            top: 5
+            bottom: 10
+            left: 5
+            right: 5
+          stack order: 1
+        attribute:
+          alignment:
+            horizontal: left
+            vertical: top
+          padding:
+            top: 5
+            bottom: 10
+            left: 5
+            right: 5
+          stack order: 2
+
+state machine:
+  abbreviation: SMD
+  about: >
+    Lifecycle of a class or assigner relationship
+  notations:
+    - xUML
+  node types:
+    state name only:
+      about: >
+        A state with no activity, distinct node type since it is drawn with different padding for the state name
+      default size:
+        height: 50
+        width: 110
+      max size:
+        height: 100
+        width: 300
+      compartment types:
+        name:
+          alignment:
+            horizontal: center
+            vertical: center
+          padding:
+            top: 20
+            bottom: 20
+            left: 10
+            right: 10
+          stack order: 1
+    state:
+      about: >
+        A context of some duration during an instance's existence
+      default size:
+        height: 50
+        width: 110
+      max size:
+        height: 100
+        width: 300
+      compartment types:
+        name:
+          alignment:
+            horizontal: center
+            vertical: center
+          padding:
+            top: 5
+            bottom: 10
+            left: 10
+            right: 10
+          stack order: 1
+        activity:
+          alignment:
+            horizontal: left
+            vertical: top
+          padding:
+            top: 4
+            bottom: 10
+            left: 5
+            right: 5
+          stack order: 2
+
+class collaboration:
+  abbreviation: CCD
+  about: >
+    Shows interactions among classes and external entities in a domain
+  notations:
+    - Starr
+    - xUML
+  node types:
+    overview class:
+      about: >
+        Used to represent class in a collaboration or other non-class diagram
+      default size:
+        height: 25
+        width: 100
+      max size:
+        height: 60
+        width: 300
+      compartment types:
+          name:
+            alignment:
+              horizontal: center
+              vertical: center
+            padding:
+              top: 5
+              bottom: 5
+              left: 5
+              right: 5
+            stack order: 1
+    external entity:
+      about: >
+        Proxy for an external domain or some aspect of an external domain
+      default size:
+        height: 25
+        width: 100
+      max size:
+        height: 60
+        width: 300
+      compartment types:
+        name:
+          alignment:
+            horizontal: center
+            vertical: center
+          padding:
+            top: 5
+            bottom: 5
+            left: 5
+            right: 5
+          stack order: 1
+
+domain:
+  abbreviation: DD
+  about: >
+    Illustrates the diverse subject matters in your project
+    as a network of platform independent domains with requirements dependencies
+  notations:
+    - Starr
+    - xUML
+  node types:
+    domain:
+      about: >
+        A distinct subject matter with its own vocabulary and rules 
+        like "Linear Algebra" or "Configuration Management"
+      default size:
+        height: 60
+        width: 100
+      max size:
+        height: 110
+        width: 300
+      compartment types:
+        name:
+          alignment:
+            horizontal: center
+            vertical: center
+          padding:
+            top: 5
+            bottom: 5
+            left: 5
+            right: 5
+          stack order: 1
+

flatland/configuration/frame.yaml

@@ -0,0 +1,102 @@
+# system/frame.yaml – System defined frames
+
+Model Integration Snippet: # Frame name
+# Frame for small model examples, no title block to maximize space
+
+  # Each Fitted Frame keyed by sheet name-orientation for the above Frame
+  letter-landscape: # name-orientation   (name defined in sheets.yaml, orientation either portrait or landscape)
+    fields:  # positioned freely on sheet outside of any title block (Free Field)
+      # Each key is a Metadata Item defined in metadata.yaml
+      Title: { x: 8, y: 202, max width: 254, max height: 13 }
+      Copyright notice: { x: 8, y: 31, max width: 254, max height: 57 }
+      Organization logo: { x: 5, y: 4, max width: 180, max height: 24 }
+      Author: { x: 280, y: 22, max width: 20, max height: 5 }
+      Modification date: { x: 230, y: 18, max width: 20, max height: 5 }
+      Document ID: { x: 230, y: 14, max width: 20, max height: 5 }
+      Version: { x: 230, y: 10, max width: 20, max height: 5 }
+
+  letter-portrait:
+    fields:
+      Title: { x: 8, y: 265, max width: 254, max height: 13 }
+      Copyright notice: { x: 10, y: 31, max width: 254, max height: 57 }
+      Organization logo: { x: 8, y: 5, max width: 180, max height: 24 }
+      Author: { x: 170, y: 22, max width: 20, max height: 5 }
+      Modification date: { x: 170, y: 18, max width: 20, max height: 5 }
+      Document ID: { x: 170, y: 14, max width: 20, max height: 5 }
+      Version: { x: 170, y: 10, max width: 20, max height: 5 }
+
+Model Integration Diagram:
+# Frame for medium ot large diagrams with a Title Block in the lower right corner
+
+  # All Fitted Frames below will use this Title Block Pattern
+  title-block-pattern:
+    - SE Simple  # Name of the Title Block Pattern defined in titleblock.yaml
+
+    # Each key below is the Name of a data box defined in titleblock.yaml
+    # Each value is one or more Metadata Items defined in metadata.yaml
+    - bottom:
+        - Organization  # Put the org name in Data Box 3
+      main:
+        - Title
+      rtop:
+        - Author
+        - Modification date  # Stack these two in Data Box 6 with Author on top and Modification date underneath
+      rbottom:
+        - Document ID
+        - Version
+
+  tabloid-landscape:
+    title block placement: { x: 275, y: 9 }
+    fields:  # Note that the Title is displayed both in a Data Box and in a Free Field for easy visibility
+      Title: { x: 8, y: 264, max width: 254, max height: 13 }
+      Copyright notice: { x: 8, y: 28, max width: 254, max height: 57 }
+      Organization logo: { x: 8, y: 9, max width: 180, max height: 24 }
+
+  tabloid-portrait:
+    title block placement: { x: 150, y: 9 }
+    fields:
+      Title: { x: 10, y: 415, max width: 254, max height: 13 }
+      Copyright notice: { x: 8, y: 25, max width: 254, max height: 57 }
+      Organization logo: { x: 5, y: 10, max width: 180, max height: 24 }
+
+  C-landscape:
+    title block placement: { x: 1190, y: 35 }
+    fields:
+      Title: { x: 72, y: 1240, max width: 254, max height: 25 }
+      Copyright notice: { x: 72, y: 270, max width: 254, max height: 57 }
+      Organization logo: { x: 72, y: 70, max width: 191, max height: 25 }
+
+  C-portrait:
+    title block placement: { x: 700, y: 25 }
+    fields:
+      Title: { x: 18, y: 584, max width: 254, max height: 25 }
+      Copyright notice: { x: 400, y: 38, max width: 254, max height: 57 }
+      Organization logo: { x: 19, y: 18, max width: 191, max height: 25 }
+
+  D-landscape:
+    title block placement: { x: 2050, y: 100 }
+    fields:
+      Title: { x: 72, y: 1650, max width: 254, max height: 25 }
+      Copyright notice: { x: 850, y: 220, max width: 254, max height: 57 }
+      Organization logo: { x: 70, y: 150, max width: 191, max height: 25 }
+
+  D-portrait:
+    title block placement: { x: 553, y: 38 }
+    fields:
+      Title: { x: 18, y: 584, max width: 254, max height: 25 }
+      Copyright notice: { x: 400, y: 38, max width: 254, max height: 57 }
+      Organization logo: { x: 19, y: 18, max width: 191, max height: 25 }
+
+  E-landscape:
+    title block placement: { x: 1025, y: 38 }
+    fields:
+      Title: { x: 30, y: 884, max width: 254, max height: 25 }
+      Copyright notice: { x: 500, y: 38, max width: 254, max height: 57 }
+      Organization logo: { x: 30, y: 38, max width: 191, max height: 25 }
+
+  E-portrait:
+    title block placement: { x: 740, y: 25 }
+    fields:
+      Title: { x: 30, y: 1180, max width: 254, max height: 25 }
+      Copyright notice: { x: 220, y: 30, max width: 254, max height: 57 }
+      Organization logo: { x: 30, y: 30, max width: 191, max height: 25 }

flatland/configuration/layout_specification.yaml

@@ -0,0 +1,42 @@
+# layout_specification.yaml – Overall diagram layout parameters
+
+- standard:  # Name of the system default diagram layout parameters
+    # Diagram layout
+    default margin:  # Distance from edge of diagram area to nearest drawn element on the diagram
+      top: 10
+      bottom: 10
+      left: 10
+      right: 10
+    default diagram origin:  # Lower left corner of the diagram relative to the Canvas area
+      x: 0  # This origin can be overriden by the user in the mls file with padding values
+      y: 0
+    # Grid/node layout
+    default cell padding:  # Gaps between cell and node edges, forms a margin around a node within a cell
+      top: 5
+      bottom: 5
+      left: 5
+      right: 5
+    default cell alignment:  # Node is aligned this way by default, user can override in mls file
+      vertical: center
+      horizontal: center
+    # Connector layout
+
+    # For a Stem that has no graphic decoration, such as an xUML class binary association connection or a xUML subclass
+    # connection, this is the minimum distance from the node face to either a bend or the opposing Stem end. It prevents
+    # a bend too close to a Node face or a connection too close to another Node.
+    undecorated stem clearance: 11
+    default cname positions: 5  # The number of connector name positions along a bend
+    default stem positions: 5  # Number of positions wher a connector can anchor on a face of a node
+    default rut positions: 5  # Number of positions a connector can follow within a row or column
+    default new path row height: 100  # Minimum space required for a connector traveling outside the
+    default new path col width: 150   #   furthest occupied row or column to bend around to its destination face
+
+    stem spec:
+      vertical access buffer:
+      horizontal access buffer:
+      vertical end buffer:
+      horizontal end buffer:
+      default name:
+      optional:
+
+# Add your own named variations below

flatland/configuration/metadata.yaml

@@ -0,0 +1,20 @@
+# metadata.yaml – System defined metadata
+
+# This is a complete list of all Metadata Items that can be positioned within a Frame
+# These are positioned within Frames in the frame.yaml file
+# Their values are specified in Flatland .mls (model layout sheet) files
+
+text: # Text item
+  - Organization
+  - Creation date
+  - Modification date
+  - Author
+  - Reviewer
+  - Version
+  - Copyright
+  - Title
+  - Document ID
+
+image: # Graphic item such as a *.png file
+  - Organization logo
+  - Copyright notice