32 add namespace structure in the PlantUML result (#37)

* mentions the pyreverse alternative, closes #31

* prevents example.py from producing artifacts when being imported

* removed object inheritance, added comments and docstring

* WIP add namespace

* docs(readme): homogenize code formatting

* tests(astvisitors): shorten type annotations

* added py2puml footer

* do not version diagram files generated by the PlantUML vscode extension

* docs: comments about module resolver

* refactor(py2puml): externalize inspect_package for test reuse

* tests(namespace): add integration test with a deeply-nested namespace

* docs(readme): update the PlantUML diagram of the py2puml domain model

* fix(tests): remove undeclared variable, remove unused import

* tests(fixtures): mutualized fixtures for tests that parse modules

* refactor: remove merge files

* build(dependencies): update dev dependencies

Author: lucsorel

.gitignore

@@ -6,3 +6,5 @@ dist/
 .vscode/
 # data generated by pytest-cov
 .coverage
+# directory where the PlantUML extension produced diagram files
+out/

README.md

@@ -74,17 +74,30 @@ For example, to create the diagram of the classes used by `py2puml`, run:
 py2puml py2puml/domain py2puml.domain
 ```
 
-This outputs the following PlantUML script:
+This outputs the following PlantUML content:
 
 ```plantuml
-@startuml
+@startuml py2puml.domain
+namespace py2puml.domain {
+  namespace package {}
+  namespace umlclass {}
+  namespace umlitem {}
+  namespace umlenum {}
+  namespace umlrelation {}
+}
+class py2puml.domain.package.Package {
+  name: str
+  children: List[Package]
+  items_number: int
+}
 class py2puml.domain.umlclass.UmlAttribute {
   name: str
   type: str
   static: bool
 }
 class py2puml.domain.umlclass.UmlClass {
   attributes: List[UmlAttribute]
+  is_abstract: bool
 }
 class py2puml.domain.umlitem.UmlItem {
   name: str
@@ -106,17 +119,19 @@ class py2puml.domain.umlrelation.UmlRelation {
   target_fqn: str
   type: RelType
 }
+py2puml.domain.package.Package *-- py2puml.domain.package.Package
 py2puml.domain.umlclass.UmlClass *-- py2puml.domain.umlclass.UmlAttribute
 py2puml.domain.umlitem.UmlItem <|-- py2puml.domain.umlclass.UmlClass
 py2puml.domain.umlenum.UmlEnum *-- py2puml.domain.umlenum.Member
 py2puml.domain.umlitem.UmlItem <|-- py2puml.domain.umlenum.UmlEnum
 py2puml.domain.umlrelation.UmlRelation *-- py2puml.domain.umlrelation.RelType
+footer Generated by //py2puml//
 @enduml
 ```
 
-Using PlantUML, this script renders this diagram:
+Using PlantUML, this content is rendered as this diagram:
 
-![py2puml UML Diagram](http://www.plantuml.com/plantuml/png/ZPB1Qy8m5CRl-IlUMR277Oi7HOGLfXrTTnfZfFLj59AqIru7elxlUuqQ1ewcftmcvlTzUL-NZgIbNYjHA-aST8U7Zdyb-rRBnYGi_NxogjMAo3PLJmX70M2anXGSMTPqw89c7ZLr2bNRAd6EKzU3y4HvuxiKdXf7RtyztqTO3Q4UK1clTza-lusN8_VHz3hPegxGtbt_aQh7IG0EiE7L4xI7tTvnGGyl6FxuptsBYeVMcgH0LV8iFMETRv_pbwpCybqACpXU1dlcasptk2coShLRRr9OdC9HI3ZYm2cBg_OkhkrjZHzXIW0axHTIs0drNhEnIRJDsNm-wKCIaIuN9mR5t4Ia3muptlca5ECcOjh4VPPu_MA9Pi_xlm00)
+![py2puml domain UML Diagram](https://www.plantuml.com/plantuml/png/ZPD1Yzim48Nl-XLpNbWRUZHxs2M4rj1DbZGzbIN8zcmgAikkD2wO9F-zigqWEw1L3i6HPgJlFUdfsH3NrDKIslvBQxz9rTHSAAPuZQRb9TuKuCG0PaLU_k5776S1IicDkLcGk9RaRT4wRPA18Ut6vMyXAuqgW-_2q2_N_kwgWh0s1zNL1UeCXA9n_iAcdnTamQEApnHTUvAVjNmXqgBeAAoB-dOnDiH9b1aKJIETYBj8gvai07xb6kTtfiMRDWTUM38loV62feVpYNWUMWOXkVq6tNxyLMuO8g7g8gIn9Nd5uQw2e7zSTZX7HJUqqjUU3L2FWElvJRZti6wDafDeb5i_shWb-QvaXtBVjpuMg-ths_P7li-tcmmUu3J5uEAg-URRUfVlNpQhTGPFPr-EUlD4ws-tr0XWcawNU5ZS2W1nVKJoi_EWEjspSxYmo8jyU7oCF5eMoxNV8_BCM2INJsUxKOp68WdnOWAfl5j56CBkl4cd9H8pzj4qX1g-eaBD2IieUaXJjp1DsJEgolvZ_m40)
 
 For a full overview of the CLI, run:
 
@@ -147,40 +162,42 @@ docker start plantumlserver
 
 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)):
+* 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')))
+if __name__ == '__main__':
+    # 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'))
+    # 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.
+* running it (`python3 -m py2puml.example`) outputs the previous PlantUML diagram in the terminal and writes it in a file.
 
 
 # Tests
 
 ```sh
 # directly with poetry
-poetry run python -m pytest -v
+poetry run pytest -v
 
 # in a virtual environment
 python3 -m pytest -v
 ```
 
-Code coverage (with missed [branch statements](https://pytest-cov.readthedocs.io/en/latest/config.html?highlight=--cov-branch)):
+Code coverage (with [missed branch statements](https://pytest-cov.readthedocs.io/en/latest/config.html?highlight=--cov-branch)):
 
 ```sh
-poetry run python -m pytest -v --cov=py2puml --cov-branch --cov-report term-missing --cov-fail-under 90
+poetry run pytest -v --cov=py2puml --cov-branch --cov-report term-missing --cov-fail-under 90
 ```
 
 # Changelog
 
+* `0.7.0`: improved the generated PlantUML documentation (added the namespace structure of the code base, homogenized type  between inspection and parsing), improved relationships management (handle forward references, deduplicate relationships)
 * `0.6.1`: handle class names with digits
 * `0.6.0`: handle abstract classes
 * `0.5.4`: fixed the packaging so that the contribution guide is included in the published package
@@ -231,6 +248,7 @@ Follow the [contributing guide](CONTRIBUTING.md).
 
 If `py2puml` does not meet your needs (suggestions and pull-requests are **welcome**), you can have a look at these projects which follow other approaches (AST, linting, modeling):
 
+* [pyreverse](https://pylint.pycqa.org/en/latest/additional_commands/index.html#pyreverse), which includes a PlantUML printer [since version 2.10.0](https://pylint.pycqa.org/en/latest/whatsnew/changelog.html?highlight=plantuml#what-s-new-in-pylint-2-10-0)
 * [cb109/pyplantuml](https://github.com/cb109/pyplantuml)
 * [deadbok/py-puml-tools](https://github.com/deadbok/py-puml-tools)
 * [caballero/genUML](https://github.com/jose-caballero/genUML)