feature: Add simple CLI (#9)

0.4.0 Add simple CLI, consistency tests, documentation

Co-authored-by: Luc Sorel-Giffo <[email protected]>

Author: jjerphan

README.md

@@ -38,7 +38,7 @@ If you like tools around PlantUML, you may also be interested in this [lucsorel/
 
 # Install
 
-Install from the github repository:
+Install from PyPI:
 
 * with `pip`:
 
@@ -60,22 +60,16 @@ pipenv install py2puml
 
 # Usage
 
-For example, to create the diagram of the classes used by `py2puml`:
-
-* import the py2puml function in your script (see [py2puml/example.py](py2puml/example.py)):
+## CLI
 
-```python
-from py2puml.py2puml import py2puml
+Once `py2puml` is installed at the system level, an eponymous command is available in your environment shell.
 
-# outputs the PlantUML content in the terminal
-print(''.join(py2puml('py2puml/domain', 'py2puml.domain')))
-
-# writes the PlantUML content in a file
-with open('py2puml/domain.puml', 'w') as puml_file:
-    puml_file.writelines(py2puml('py2puml/domain', 'py2puml.domain'))
+For example, to create the diagram of the classes used by `py2puml`, one can use:
+```sh
+py2puml py2puml/domain py2puml.domain
 ```
 
-* running it (`python3 -m py2puml.example`) will output the PlantUML diagram in the terminal and write it in a file
+This will output the following PlantUML script:
 
 ```plantuml
 @startuml
@@ -114,9 +108,54 @@ py2puml.domain.umlrelation.UmlRelation *-- py2puml.domain.umlrelation.RelType
 @enduml
 ```
 
-Which renders like this:
+Using PlantUML, this script renders this diagram:
+
+![py2puml UML Diagram](https://www.plantuml.com/plantuml/png/ZP91IyGm48Nl-HKvBsmF7iiUTbaA1jnMQZs9I7OxIY19Qp8H5jV_xZIse5GsFULrQBvvCozRZz9XC9gTjFIUz-URdhwojZDIsOnah6UFHkyGdJe61Fx9EBVIGCuzEj9uxaVzbSRi1n4HSWBwdDyfZq-_cpnVOIa4Cw04dJCph--jJPa16qns07C4Dxl_8NM0HG1oKD0P2IR2fa5-qCC8mu__t7UW9QhEPZNeXhON6VlgS5yzY4PKPSvNL13bRL6BPbVkYvnlBdC_SnvvgaSTcRuBxWGlSIbJMjAz0SRItm17BzGc6TzglLxqL5WYlCs5GAbkBB5_CdCzuoKk4Y6pPJkFNj9niotObkhi6m00)
+
+For a full overview of the CLI, run:
+
+```sh
+py2puml --help
+```
+
+The CLI can also be launched as a python module:
+
+```sh
+python -m py2puml py2puml/domain py2puml.domain
+```
+
+Pipe the result of the CLI with a PlantUML server for instantaneous documentation (rendered by ImageMagick):
+
+```sh
+# runs a local PlantUML server from a docker container:
+docker run -d -p 1234:8080 --name plantumlserver plantuml/plantuml-server:jetty 
+
+py2puml py2puml/domain py2puml.domain | curl -X POST --data-binary @- http://localhost:1234/svg/ --output - | display
+
+# stops the container when you don't need it anymore, restarts it later, removes it
+docker stop plantumlserver
+docker start plantumlserver
+docker rm plantumlserver
+```
+
+## Python API
+
+For example, to create the diagram of the classes used by `py2puml`:
+
+* import the py2puml function in your script (see [py2puml/example.py](py2puml/example.py)):
+
+```python
+from py2puml.py2puml import py2puml
+
+# outputs the PlantUML content in the terminal
+print(''.join(py2puml('py2puml/domain', 'py2puml.domain')))
+
+# writes the PlantUML content in a file
+with open('py2puml/domain.puml', 'w') as puml_file:
+    puml_file.writelines(py2puml('py2puml/domain', 'py2puml.domain'))
+```
+* running it (`python3 -m py2puml.example`) will output the previous PlantUML diagram in the terminal and write it in a file.
 
-![](https://www.plantuml.com/plantuml/png/ZP91IyGm48Nl-HKvBsmF7iiUTbaA1jnMQZs9I7OxIY19Qp8H5jV_xZIse5GsFULrQBvvCozRZz9XC9gTjFIUz-URdhwojZDIsOnah6UFHkyGdJe61Fx9EBVIGCuzEj9uxaVzbSRi1n4HSWBwdDyfZq-_cpnVOIa4Cw04dJCph--jJPa16qns07C4Dxl_8NM0HG1oKD0P2IR2fa5-qCC8mu__t7UW9QhEPZNeXhON6VlgS5yzY4PKPSvNL13bRL6BPbVkYvnlBdC_SnvvgaSTcRuBxWGlSIbJMjAz0SRItm17BzGc6TzglLxqL5WYlCs5GAbkBB5_CdCzuoKk4Y6pPJkFNj9niotObkhi6m00)
 
 # Tests
 
@@ -130,6 +169,7 @@ python3 -m pytest -v
 
 # Changelog
 
+* `0.4.0`: add a simple CLI
 * `0.3.1`: inspect sub-folders recursively
 * `0.3.0`: handle classes derived from namedtuples (attribute types are `any`)
 * `0.2.0`: handle inheritance relationships and enums. Unit tested
@@ -143,6 +183,7 @@ Unless stated otherwise all works are licensed under the [MIT license](http://sp
 
 * [Luc Sorel-Giffo](https://github.com/lucsorel)
 * [Doyou Jung](https://github.com/doyou89)
+* [Julien Jerphanion](https://github.com/jjerphan)
 
 Pull-requests are welcome and will be processed on a best-effort basis.
 

py2puml/__init__.py

@@ -1,17 +0,0 @@
-from os.path import dirname, realpath, join
-from re import compile, Match
-
-# exports the version read from the pyproject.toml file
-try:
-    PARENT_DIR = dirname(dirname(realpath(__file__)))
-    VERSION_PATTERN = compile('^version = "([^"]+)"$')
-    with open(join(PARENT_DIR, 'pyproject.toml')) as pyproject:
-        version_match: Match = next((
-            match for match in (VERSION_PATTERN.search(line) for line in pyproject.readlines())
-            if match is not None
-        ), None)
-
-        __version__ = version_match.group(1)
-except:
-    __version__ = None
-

py2puml/__main__.py

@@ -0,0 +1,4 @@
+from py2puml.cli import run
+
+if __name__ == '__main__':
+    run()

py2puml/cli.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from argparse import ArgumentParser
+
+from py2puml.py2puml import py2puml
+
+
+def run():
+    argparser = ArgumentParser(description='Generate Plantuml diagrams to document your python code')
+
+    argparser.add_argument('-v', '--version', action='version', version='py2puml 0.4.0')
+    argparser.add_argument('path', metavar='path', type=str, help='the path of the domain')
+    argparser.add_argument('module', metavar='module', type=str, help='the module of the domain', default=None)
+
+    args = argparser.parse_args()
+    print(''.join(py2puml(args.path, args.module)))

pyproject.toml

@@ -1,14 +1,17 @@
 [tool.poetry]
 name = "py2puml"
-version = "0.3.1"
-description = "Generate Plantuml diagrams to document your python code "
+version = "0.4.0"
+description = "Generate Plantuml diagrams to document your python code"
 keywords = ["class diagram", "PlantUML", "documentation"]
 readme = "README.md"
 repository = "https://github.com/lucsorel/py2puml"
 authors = ["Luc Sorel-Giffo"]
 maintainers = ["Luc Sorel-Giffo"]
 license = "MIT"
 
+[tool.poetry.scripts]
+py2puml = 'py2puml.cli:run'
+
 [tool.poetry.dependencies]
 python = "^3.7"
 

tests/__init__.py

@@ -0,0 +1,23 @@
+from os.path import dirname, realpath, join
+from re import compile
+from itertools import takewhile
+
+# exports the version and the project description read from the pyproject.toml file
+__version__ = None
+__description__ = None
+
+PARENT_DIR = dirname(dirname(realpath(__file__)))
+VERSION_PATTERN = compile('^version = "([^"]+)"$')
+DESCRIPTION_PATTERN = compile('^description = "([^"]+)"$')
+
+def get_from_line_and_pattern(line: str, pattern) -> str:
+    pattern_match = pattern.search(line)
+    if pattern_match is None:
+        return None
+    else:
+        return pattern_match.group(1)
+
+with open(join(PARENT_DIR, 'pyproject.toml')) as pyproject:
+    for line in takewhile(lambda _: __version__ is None or __description__ is None, pyproject):
+        __version__ = __version__ if __version__ is not None else get_from_line_and_pattern(line, VERSION_PATTERN)
+        __description__ = __description__ if __description__ is not None else get_from_line_and_pattern(line, DESCRIPTION_PATTERN)

tests/py2puml/test__init__.py

@@ -0,0 +1,9 @@
+from tests import __version__, __description__
+
+# Ensures the library version is modified in the pyproject.toml file when upgrading it (pull request)
+def test_version():
+    assert __version__ == '0.4.0'
+
+# Description also output in the CLI
+def test_description():
+    assert __description__ == 'Generate Plantuml diagrams to document your python code'

tests/py2puml/test_cli.py

@@ -0,0 +1,62 @@
+from typing import List
+
+from pytest import mark
+from subprocess import run, PIPE
+
+from py2puml import py2puml
+from tests import __version__, __description__
+
+@mark.parametrize(
+    'entrypoint', [
+        ['py2puml'],
+        ['python', '-m', 'py2puml']
+    ]
+)
+def test_cli_consistency_with_the_default_configuration(entrypoint: List[str]):
+    command = entrypoint + ['py2puml/domain', 'py2puml.domain']
+    cli_stdout = run(command,
+        stdout=PIPE, stderr=PIPE,
+        text=True, check=True
+    ).stdout
+
+    puml_content = py2puml.py2puml('py2puml/domain', 'py2puml.domain')
+
+    assert ''.join(puml_content).strip() == cli_stdout.strip()
+
+@mark.parametrize(
+    'version_command', [
+        ['-v'],
+        ['--version']
+    ]
+)
+def test_cli_version(version_command: List[str]):
+    '''
+    Ensures the consistency between the CLI version and the project version set in pyproject.toml
+    which is not included when the CLI is installed system-wise
+    '''
+    command = ['py2puml'] + version_command
+    cli_version = run(command,
+        stdout=PIPE, stderr=PIPE,
+        text=True, check=True
+    ).stdout
+
+    assert cli_version == f'py2puml {__version__}\n'
+
+@mark.parametrize(
+    'help_command', [
+        ['-h'],
+        ['--help']
+    ]
+)
+def test_cli_help(help_command: List[str]):
+    '''
+    Ensures the consistency between the CLI help and the project description set in pyproject.toml
+    which is not included when the CLI is installed system-wise
+    '''
+    command = ['py2puml'] + help_command
+    help_text = run(command,
+        stdout=PIPE, stderr=PIPE,
+        text=True, check=True
+    ).stdout
+
+    assert __description__ in help_text

tests/py2puml/test_py2puml.py

@@ -1,12 +1,8 @@
-from py2puml import __version__, py2puml
 
+from py2puml import py2puml
 
-def test_version():
-    assert __version__ == '0.3.1'
 
-
-def test_py2puml_model():
-    """test py2puml on py2puml/domain."""
+def test_py2puml_model_on_py2uml_domain():
     expected = """@startuml
 class py2puml.domain.umlclass.UmlAttribute {
   name: str