Merge remote-tracking branch 'origin/main'

Author: braboj

README.md

@@ -68,6 +68,12 @@ You can also run the examples from the command line. For example, to run the
 python examples/A01_introduction/hello_world.py
 ```
 
+To see how relative imports work within packages, run the `import_relative.py` example using the `-m` flag:
+
+```bash
+python -m examples.A21_import_system.import_relative
+```
+
 
 ## License
 

examples/A10_modules/01_custom_module.py

@@ -0,0 +1,11 @@
+# Using a custom module defined in the same directory
+# ------------------------------------------------------------------------------
+# A *module* is simply a Python file that defines variables, functions, or
+# classes. This example imports ``mymodule`` and calls its functions. Modules
+# help organize related code and can be reused across projects.
+
+import mymodule
+
+print(mymodule.greet('World'))
+print('Area of circle:', mymodule.area_circle(3))
+print('Module name:', mymodule.__name__)

examples/A10_modules/02_builtin_modules.py

@@ -0,0 +1,12 @@
+# Using built-in Python modules
+# ------------------------------------------------------------------------------
+# Python ships with a rich *standard library* of modules that you can use
+# without installing anything extra. This example demonstrates ``math`` and
+# ``random``.
+
+import math
+import random
+
+print('Square root of 16 is', math.sqrt(16))
+print('Value of pi is', math.pi)
+print('Random number between 1 and 6:', random.randint(1, 6))

examples/A10_modules/03_package_import.py

@@ -0,0 +1,10 @@
+# Importing from a package
+# ------------------------------------------------------------------------------
+# A *package* is a directory containing an ``__init__.py`` file and one or more
+# modules. Packages allow related modules to be grouped together. This example
+# imports the ``hello`` function from ``my_package`` defined in the same
+# directory.
+
+from my_package import hello
+
+hello()

examples/A10_modules/__init__.py

@@ -0,0 +1,2 @@
+# Examples related to Python modules and packages
+# ------------------------------------------------------------------------------

examples/A10_modules/my_package/__init__.py

@@ -0,0 +1,9 @@
+# Example package with a single submodule
+# ------------------------------------------------------------------------------
+# Packages are directories containing an ``__init__.py`` file. This file is
+# executed when the package is imported and can expose objects from submodules.
+# Packages allow modules to be organized hierarchically.
+
+from .submodule import hello
+
+__all__ = ['hello']

examples/A10_modules/my_package/submodule.py

@@ -0,0 +1,8 @@
+# Submodule inside ``my_package``
+# ------------------------------------------------------------------------------
+# This module defines the ``hello`` function. ``__init__.py`` re-exports this
+# function so it can be imported directly from ``my_package``.
+
+
+def hello():
+    print('Hello from submodule')

examples/A10_modules/mymodule.py

@@ -0,0 +1,23 @@
+# Example custom module with variables and functions
+# ------------------------------------------------------------------------------
+# Modules are Python files that can define variables, functions and classes.
+# They allow code to be organized into reusable components. When a module is
+# imported, its top-level code executes once.
+
+PI = 3.14159
+
+
+def greet(name):
+    """Return a greeting string."""
+    return f"Hello, {name}"
+
+
+def area_circle(radius):
+    """Return the area of a circle with the given radius."""
+    return PI * radius * radius
+
+
+if __name__ == '__main__':
+    # Code executed only when running this module directly
+    print(greet('module'))
+    print('Area:', area_circle(2))

examples/A21_import_system/import_absolute.py

@@ -1,12 +1,11 @@
 # Shows how to enforce and use absolute imports.
 # ------------------------------------------------------------------------------
 # Example script demonstrating absolute imports.
+from __future__ import absolute_import
+
 # Using absolute imports
 import asyncio
 
-# Enforce absolute imports
-from __future__ import absolute_import
-
 # Absolute imports
 from foo.api.submodule1 import func1
 from foo.core.submodule2 import func2

examples/A21_import_system/import_relative.py

@@ -0,0 +1,11 @@
+# Shows how to use relative imports within a package.
+# ------------------------------------------------------------------------------
+# Demonstrates importing modules from the current package using relative syntax.
+
+from .foo.api.submodule1 import func1
+from .foo.core.submodule2 import func2
+# Relative imports are scoped to packages.
+
+# Call the imported functions
+func1()
+func2()