Improve examples

Author: RobertoPrevato

.github/workflows/build.yml

@@ -55,10 +55,6 @@ jobs:
           pip install -e .
           pytest --doctest-modules --junitxml=junit/pytest-results-${{ matrix.python-version }}.xml --cov=$PROJECT_NAME --cov-report=xml tests/
 
-      - name: Test examples
-        run: |
-          for f in ./examples/*.py; do echo "Processing $f file..." && python $f; done
-
       - name: Run linters
         run: |
           echo "Running linters - if build fails here, please be patient!"

examples-summary.py

@@ -0,0 +1,31 @@
+"""
+Generates a README.md file for the examples folder.
+"""
+
+import glob
+import importlib
+import sys
+
+examples = [file for file in glob.glob("./examples/*.py")]
+examples.sort()
+sys.path.append("./examples")
+
+with open("./examples/README.md", mode="wt", encoding="utf8 ") as examples_readme:
+    examples_readme.write(
+        "<!-- generated file, to update use: python examples-summary.py -->\n\n"
+    )
+    examples_readme.write("""# Examples""")
+
+    for file_path in examples:
+        if "__init__" in file_path:
+            continue
+
+        module_name = file_path.replace("./examples/", "").replace(".py", "")
+
+        module = importlib.import_module(module_name)
+
+        if not module.__doc__:
+            continue
+
+        examples_readme.write(f"\n\n## {module_name}.py\n")
+        examples_readme.write(str(module.__doc__))

examples/README.md

@@ -0,0 +1,25 @@
+<!-- generated file, to update use: python examples-summary.py -->
+
+# Examples
+
+## example-01.py
+
+This example illustrates a basic usage of the Container class to register
+two types, and automatic resolution achieved through types inspection.
+
+Two services are registered as "transient" services, meaning that a new instance is
+created whenever needed.
+
+
+## example-02.py
+
+This example illustrates a basic usage of the Container class to register
+a concrete type by base type, and its activation by base type.
+
+This pattern helps writing code that is decoupled (e.g. business layer logic separated
+from exact implementations of data access logic).
+
+
+## example-03.py
+
+This example illustrates how to configure a singleton object.

tests/test_examples.py

@@ -1,12 +1,17 @@
 import glob
-import subprocess
+import importlib
+import sys
 
 import pytest
 
 examples = [file for file in glob.glob("./examples/*.py")]
 
 
+sys.path.append("./examples")
+
+
 @pytest.mark.parametrize("file_path", examples)
 def test_example(file_path: str):
-    output = subprocess.run(["python", file_path])
-    assert output.returncode == 0
+    module_name = file_path.replace("./examples/", "").replace(".py", "")
+    # assertions are in imported
+    importlib.import_module(module_name)