Merge pull request #91 from braboj/codex/add-headers-describing-import-mechanics

braboj · web-flow · commit e5229727ec82 · 2025-06-11T09:41:36.000+03:00
Add headers to import system examples
diff --git a/examples/17_import_system/__init__.py b/examples/17_import_system/__init__.py
@@ -0,0 +1 @@
+"""Examples showing different aspects of Python's import system."""
diff --git a/examples/17_import_system/circular/__init__.py b/examples/17_import_system/circular/__init__.py
@@ -0,0 +1 @@
+"""Package demonstrating circular imports."""
diff --git a/examples/17_import_system/circular/submodule1.py b/examples/17_import_system/circular/submodule1.py
@@ -1,3 +1,4 @@
+"""First module in a circular import chain."""
 from . import submodule2
 
 
diff --git a/examples/17_import_system/circular/submodule2.py b/examples/17_import_system/circular/submodule2.py
@@ -1,3 +1,4 @@
+"""Second module that completes the circular import chain."""
 from . import submodule1
 
 def func2():
diff --git a/examples/17_import_system/export_decorator.py b/examples/17_import_system/export_decorator.py
@@ -1,3 +1,4 @@
+"""Defines an export decorator for populating a package's __all__."""
 # Example of the export decorator that shall be placed in the __init__.py file of the package
 
 # Export decorator
diff --git a/examples/17_import_system/foo/__init__.py b/examples/17_import_system/foo/__init__.py
@@ -1,3 +1,4 @@
+"""Demo package with relative imports and an export decorator."""
 # Define the packet API
 __version__ = '1.0.0'
 
diff --git a/examples/17_import_system/foo/__main__.py b/examples/17_import_system/foo/__main__.py
@@ -1,3 +1,4 @@
+"""Entry point executed when running the package with -m."""
 import sys
 import os.path
 
diff --git a/examples/17_import_system/foo/api/__init__.py b/examples/17_import_system/foo/api/__init__.py
@@ -1 +1,2 @@
+"""API subpackage exposing a version constant."""
 __version__ = '0.1.0'
diff --git a/examples/17_import_system/foo/api/submodule1.py b/examples/17_import_system/foo/api/submodule1.py
@@ -1,3 +1,4 @@
+"""Submodule used to demonstrate absolute and relative imports."""
 # Define a constant
 my_id = 1
 
diff --git a/examples/17_import_system/foo/core/__init__.py b/examples/17_import_system/foo/core/__init__.py
@@ -0,0 +1 @@
+"""Core subpackage used in import examples."""
diff --git a/examples/17_import_system/foo/core/submodule2.py b/examples/17_import_system/foo/core/submodule2.py
@@ -1,3 +1,4 @@
+"""Submodule used in absolute import demonstrations."""
 # Define a constant
 my_id = 2
 
diff --git a/examples/17_import_system/foo/gui/__init__.py b/examples/17_import_system/foo/gui/__init__.py
@@ -0,0 +1 @@
+"""GUI subpackage used in import examples."""
diff --git a/examples/17_import_system/foo/gui/submodule3.py b/examples/17_import_system/foo/gui/submodule3.py
@@ -1,3 +1,4 @@
+"""Submodule used by GUI package import examples."""
 # Define a constant
 my_id = 3
 
diff --git a/examples/17_import_system/import_absolute.py b/examples/17_import_system/import_absolute.py
@@ -1,3 +1,4 @@
+"""Shows how to enforce and use absolute imports."""
 # Example: Absolute imports
 import asyncio
 
diff --git a/examples/17_import_system/import_circular.py b/examples/17_import_system/import_circular.py
@@ -1,3 +1,4 @@
+"""Triggers a circular import between two submodules."""
 import circular.submodule1 as submodule1
 
 submodule1.func1()
diff --git a/examples/17_import_system/import_conditional.py b/examples/17_import_system/import_conditional.py
@@ -1,3 +1,4 @@
+"""Shows conditional imports based on Python version."""
 import sys
 
 # Option 1
diff --git a/examples/17_import_system/import_main_module.py b/examples/17_import_system/import_main_module.py
@@ -1,3 +1,4 @@
+"""Demonstrates __main__ name when executing a module as a script."""
 # Example: Main program
 
 import pprint
diff --git a/examples/17_import_system/import_module_objects.py b/examples/17_import_system/import_module_objects.py
@@ -1,3 +1,4 @@
+"""Shows manual creation of ModuleType objects to demonstrate import internals."""
 from types import ModuleType
 
 # Create a new module object
diff --git a/examples/17_import_system/import_namespaces.py b/examples/17_import_system/import_namespaces.py
@@ -1,3 +1,4 @@
+"""Explores namespaces at different scopes using builtins and custom classes."""
 # Example: Namespace of the builtins module
 
 import pprint
diff --git a/examples/17_import_system/import_packages.py b/examples/17_import_system/import_packages.py
@@ -1,3 +1,4 @@
+"""Demonstrates importing a package and using its public API."""
 import product
 
 # Use the public API defined in __init__.py
diff --git a/examples/17_import_system/import_process.py b/examples/17_import_system/import_process.py
@@ -1,3 +1,4 @@
+"""Implements a minimal importer to show how Python loads modules."""
 # Example: Very naive implementation of the import statement
 
 import marshal
diff --git a/examples/17_import_system/import_search_path.py b/examples/17_import_system/import_search_path.py
@@ -1,3 +1,4 @@
+"""Displays and modifies sys.path to demonstrate search paths."""
 # Example: Import Search Path
 
 import sys
diff --git a/examples/17_import_system/import_skip_execution.py b/examples/17_import_system/import_skip_execution.py
@@ -1,3 +1,4 @@
+"""Demonstrates guarding code with __name__ to skip execution on import."""
 # Example: Main program
 
 
diff --git a/examples/17_import_system/import_statements.py b/examples/17_import_system/import_statements.py
@@ -1,3 +1,4 @@
+"""Illustrates various forms of the import statement."""
 # Example: Import Statements
 
 # Importing the package
diff --git a/examples/17_import_system/import_sys_path.py b/examples/17_import_system/import_sys_path.py
@@ -1,3 +1,4 @@
+"""Shows sys.path details via prefix values."""
 import sys
 print(sys.prefix)
 print(sys.exec_prefix)
diff --git a/examples/17_import_system/import_tracking.py b/examples/17_import_system/import_tracking.py
@@ -1,3 +1,4 @@
+"""Replaces builtins.__import__ to trace loaded modules."""
 def my_import(modname, *args, imp=__import__):
     print('importing', modname)
     return imp(modname, *args)
diff --git a/examples/17_import_system/rootdir.py b/examples/17_import_system/rootdir.py
@@ -1,3 +1,4 @@
+"""Holds the absolute path to this directory for search path examples."""
 import os
 
 ROOT_DIR = os.path.dirname(os.path.abspath(__file__))

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+"""Examples showing different aspects of Python's import system."""`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+"""Package demonstrating circular imports."""`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+"""First module in a circular import chain."""`
`1`	`2`	`from . import submodule2`
`2`	`3`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+"""Second module that completes the circular import chain."""`
`1`	`2`	`from . import submodule1`
`2`	`3`
`3`	`4`	`def func2():`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+"""Defines an export decorator for populating a package's __all__."""`
`1`	`2`	`# Example of the export decorator that shall be placed in the __init__.py file of the package`
`2`	`3`
`3`	`4`	`# Export decorator`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+"""Demo package with relative imports and an export decorator."""`
`1`	`2`	`# Define the packet API`
`2`	`3`	`__version__ = '1.0.0'`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+"""Entry point executed when running the package with -m."""`
`1`	`2`	`import sys`
`2`	`3`	`import os.path`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
	`1`	`+"""API subpackage exposing a version constant."""`
`1`	`2`	`__version__ = '0.1.0'`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+"""Submodule used to demonstrate absolute and relative imports."""`
`1`	`2`	`# Define a constant`
`2`	`3`	`my_id = 1`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+"""Core subpackage used in import examples."""`