mi-flatland 2.0.0__tar.gz

mi_flatland-2.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include src/flatland/log.conf
+include src/flatland/configuration/*.yaml

mi_flatland-2.0.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.2
+Name: mi-flatland
+Version: 2.0.0
+Summary: Model text file + layout text file -> beautiful diagram
+Author-email: Leon Starr <leon_starr@modelint.com>
+Project-URL: repository, https://github.com/modelint/flatland
+Project-URL: documentation, https://github.com/modelint/flatland
+Keywords: 2D,draw,graphics,canvas,mbse,xuml,xtuml,sysml
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: mi-configurator
+Requires-Dist: mi-pyral
+Requires-Dist: mi-tabletqt
+Requires-Dist: mls-parser
+Requires-Dist: numpy
+Requires-Dist: xcm-parser
+Requires-Dist: xsm-parser
+Requires-Dist: tomli; python_version < "3.12"
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Provides-Extra: dev
+Requires-Dist: bump2version; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# Flatland Model Diagram (non) Editor
+
+NEW Status January 13, 2025
+
+I have recently rebuilt the entire application based on a series of modules available on GitHub and PyPI. 
+Will be deploying in ernest in the coming days.
+
+Am de-commisioning the old version on GitHub and PyPI named 'flatland-model-diagram-editor'
+Now it is just 'flatland' here on GitHub and 'mi-flatland' on PyPI
+
+Ah yes, yet another tool for generating diagrams from text. But this one is different (otherwise I wouldn't have wasted all this time building it!)
+
+I built Flatland because the following benefits are critical for productive model development:
+
+1. Complete separation of the model semantics from the diagram layout
+2. Complete separation of model semantics from model notation
+3. Consistent layout of model diagrams without forcing the user to accept or hack awkard, non-sensical placements of nodes and connectors (yeah, I'm lookin at YOU PlantUML)
+4. Maximum layout power with minimal specification:  No more carpal tunnel pixel pushing!
+5. Beautiful, readable diagram output in many output formats (pdf, svg, etc)
+6. Support for industrial strength modeling (many hundreds and thousands of model elements)
+7. Use your favorite text editor and all the advanced facilities of it and whatever IDE you like without having to learn yet another draw tool that makes you and your team's life difficult.
+8. And since we're here on GitHub, wouldn't it be nice if all of your models were under proper configuration management where you and your team can diff and merge to your heart's content? Wouldn't it be nice to update a diagram layout without touching the underlying model (and vice versa)?
+
+Basically, I have wasted way too many hours of my career pushing pixels around and I just couldn't take it anymore!
+
+Flatland is a model diagram non-editor written by me [Leon Starr](mailto:leon_starr@modelint.com) that generates
+beautiful PDFs (and other output formats) based on two very
+human-readable input text files. The model file specifies model semantics
+(state transitions, generalizations, classes etc)
+while the layout file specifies (node placement and alignment, connector anchors) and lightly refers to some elements
+in the model file. You can think of the layout file as a "style sheet" for your models.
+Some benefits:
+
+Follow me on BlueSky and [LinkedIn](https://linkedin.com/in/modelint) for updates.
+
+## Models to Code
+
+In the meantime, if you are curious about the whole MBSE thing that this tool supports, take a look at our [book](https://modelstocode.com).
+Also, various resources at the [Model Integration](https://modelint.com/mbse) website.
+
+## Installation
+
+Notes here are for those familiar with python installation procedures.  I will write a more detailed set of procedures
+for those who are not in a later release.
+
+You should also ensure that you have Python 3.12+ installed. A virtual environment is highly recommended.
+
+You can install the Flatland Model Diagram Editor from [PyPI](https://pypi.org/project/flatland-model-diagram-editor/):
+
+    $ pip install mi-flatland
+
+Flatland is supported on Python 3.12 and above
+
+## How to use
+
+At this point I refer you to the [wiki](https://github.com/modelint/flatland/wiki) on this site for all of the user documentation. Enjoy (and feel free to contact me if you have any questions.

mi_flatland-2.0.0/README.md

@@ -0,0 +1,56 @@
+# Flatland Model Diagram (non) Editor
+
+NEW Status January 13, 2025
+
+I have recently rebuilt the entire application based on a series of modules available on GitHub and PyPI. 
+Will be deploying in ernest in the coming days.
+
+Am de-commisioning the old version on GitHub and PyPI named 'flatland-model-diagram-editor'
+Now it is just 'flatland' here on GitHub and 'mi-flatland' on PyPI
+
+Ah yes, yet another tool for generating diagrams from text. But this one is different (otherwise I wouldn't have wasted all this time building it!)
+
+I built Flatland because the following benefits are critical for productive model development:
+
+1. Complete separation of the model semantics from the diagram layout
+2. Complete separation of model semantics from model notation
+3. Consistent layout of model diagrams without forcing the user to accept or hack awkard, non-sensical placements of nodes and connectors (yeah, I'm lookin at YOU PlantUML)
+4. Maximum layout power with minimal specification:  No more carpal tunnel pixel pushing!
+5. Beautiful, readable diagram output in many output formats (pdf, svg, etc)
+6. Support for industrial strength modeling (many hundreds and thousands of model elements)
+7. Use your favorite text editor and all the advanced facilities of it and whatever IDE you like without having to learn yet another draw tool that makes you and your team's life difficult.
+8. And since we're here on GitHub, wouldn't it be nice if all of your models were under proper configuration management where you and your team can diff and merge to your heart's content? Wouldn't it be nice to update a diagram layout without touching the underlying model (and vice versa)?
+
+Basically, I have wasted way too many hours of my career pushing pixels around and I just couldn't take it anymore!
+
+Flatland is a model diagram non-editor written by me [Leon Starr](mailto:leon_starr@modelint.com) that generates
+beautiful PDFs (and other output formats) based on two very
+human-readable input text files. The model file specifies model semantics
+(state transitions, generalizations, classes etc)
+while the layout file specifies (node placement and alignment, connector anchors) and lightly refers to some elements
+in the model file. You can think of the layout file as a "style sheet" for your models.
+Some benefits:
+
+Follow me on BlueSky and [LinkedIn](https://linkedin.com/in/modelint) for updates.
+
+## Models to Code
+
+In the meantime, if you are curious about the whole MBSE thing that this tool supports, take a look at our [book](https://modelstocode.com).
+Also, various resources at the [Model Integration](https://modelint.com/mbse) website.
+
+## Installation
+
+Notes here are for those familiar with python installation procedures.  I will write a more detailed set of procedures
+for those who are not in a later release.
+
+You should also ensure that you have Python 3.12+ installed. A virtual environment is highly recommended.
+
+You can install the Flatland Model Diagram Editor from [PyPI](https://pypi.org/project/flatland-model-diagram-editor/):
+
+    $ pip install mi-flatland
+
+Flatland is supported on Python 3.12 and above
+
+## How to use
+
+At this point I refer you to the [wiki](https://github.com/modelint/flatland/wiki) on this site for all of the user documentation. Enjoy (and feel free to contact me if you have any questions.

mi_flatland-2.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires      = ["setuptools>=75.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mi-flatland"
+version = "2.0.0"
+description = "Model text file + layout text file -> beautiful diagram"
+readme = "README.md"
+authors = [{ name = "Leon Starr", email = "leon_starr@modelint.com" }]
+license = { file = "LICENSE" }
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+]
+keywords = ["2D", "draw", "graphics", "canvas", "mbse", "xuml", "xtuml", "sysml"]
+dependencies = ['mi-configurator', 'mi-pyral', 'mi-tabletqt', 'mls-parser', 'numpy',
+    'xcm-parser', 'xsm-parser', 'tomli; python_version < "3.12"']
+requires-python = ">=3.12"
+
+[project.optional-dependencies]
+build = ["build", "twine"]
+dev = ["bump2version", "pytest"]
+
+[project.scripts]
+tablet = "flatland.__main__:main"
+
+[project.urls]
+repository    = "https://github.com/modelint/flatland"
+documentation = "https://github.com/modelint/flatland"

mi_flatland-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mi_flatland-2.0.0/src/flatland/__init__.py

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

mi_flatland-2.0.0/src/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()

mi_flatland-2.0.0/src/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]

mi_flatland-2.0.0/src/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