Merge branch 'master' into update-mcp-client-sdk-v2

Author: realpython-bot

.github/workflows/linters.yml

@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - {name: Linux314, python: '3.14.0', os: ubuntu-latest}
+          - {name: Linux314, python: '3.14', os: ubuntu-latest}
     steps:
     - name: Check out repository
       uses: actions/checkout@v2
@@ -33,9 +33,9 @@ jobs:
       uses: actions/cache@v3
       with:
         path: ./venv
-        key: ${{ matrix.name }}-v1-pip-${{ hashFiles('requirements.txt') }}
+        key: ${{ matrix.name }}-v2-pip-${{ hashFiles('requirements.txt') }}
         restore-keys: |
-          ${{ matrix.name }}-v1-pip-
+          ${{ matrix.name }}-v2-pip-
 
     - name: Install dependencies
       if: steps.cache.outputs.cache-hit != 'true'

absolute-vs-relative-python-imports/README.md

@@ -0,0 +1,57 @@
+# Absolute vs Relative Imports in Python
+
+This folder provides the code examples for the Real Python tutorial [Absolute vs Relative Imports in Python](https://realpython.com/absolute-vs-relative-python-imports/).
+
+The code requires Python 3.3 or later, because `package1/` has no `__init__.py` file and relies on [namespace packages](https://peps.python.org/pep-0420/).
+
+## Example Project
+
+The tutorial's `project/` tree comes in two parallel copies so you can compare both import styles:
+
+- [`absolute/project/`](absolute/project/) uses absolute imports.
+- [`relative/project/`](relative/project/) uses explicit relative imports.
+
+Both copies contain the same files:
+
+- `package1/module1.py`: Imports `function1` from `module2` and prints its result.
+- `package1/module2.py`: Defines `function1()`.
+- `package2/__init__.py`: Defines `class1`.
+- `package2/module3.py`: Imports `class1` and `function2` and prints them.
+- `package2/module4.py`: Part of the tutorial's tree, but empty because no example uses it.
+- `package2/subpackage1/module5.py`: Defines `function2()`.
+- `main.py`: Entry point that runs the imports. In `absolute/project/`, it also holds the tutorial's block of absolute import examples.
+
+Run the examples from inside a `project/` folder so that `package1` and `package2` are importable:
+
+```sh
+$ cd absolute/project/
+$ python main.py
+Absolute imports:
+Hello from function1() in package1/module2.py
+<class1 from package2/__init__.py>
+Hello from function2() in package2/subpackage1/module5.py
+
+module1.main():
+Hello from function1() in package1/module2.py
+
+module3.main():
+<class1 from package2/__init__.py>
+Hello from function2() in package2/subpackage1/module5.py
+```
+
+You can also run a single module with the `-m` switch, which works for both copies:
+
+```sh
+$ cd relative/project/
+$ python -m package2.module3
+<class1 from package2/__init__.py>
+Hello from function2() in package2/subpackage1/module5.py
+```
+
+Running a module as a file path, such as `python package1/module1.py`, fails in both copies. The relative version raises `ImportError: attempted relative import with no known parent package`. The absolute version raises `ModuleNotFoundError` because `project/` isn't on the import path.
+
+## Import Styling
+
+- [`import_style.py`](import_style.py): The tutorial's example of PEP 8 import grouping and ordering.
+
+This file is only a style reference and isn't meant to run. It imports third-party Flask packages and the placeholder modules `local_module` and `local_package`, which don't exist. A `# ruff: noqa: F401` comment at the top stops the linter from flagging the imports as unused.

absolute-vs-relative-python-imports/absolute/project/main.py

@@ -0,0 +1,17 @@
+from package1 import module1
+from package1.module2 import function1
+from package2 import class1
+from package2.subpackage1.module5 import function2
+
+# Also import module3 to run the absolute imports inside it
+from package2 import module3
+
+print("Absolute imports:")
+print(function1())
+print(class1())
+print(function2())
+
+print("\nmodule1.main():")
+module1.main()
+print("\nmodule3.main():")
+module3.main()

absolute-vs-relative-python-imports/absolute/project/package1/module1.py

@@ -0,0 +1,11 @@
+# package1/module1.py
+
+from package1.module2 import function1
+
+
+def main():
+    print(function1())
+
+
+if __name__ == "__main__":
+    main()

absolute-vs-relative-python-imports/absolute/project/package1/module2.py

@@ -0,0 +1,2 @@
+def function1():
+    return "Hello from function1() in package1/module2.py"

absolute-vs-relative-python-imports/absolute/project/package2/__init__.py

@@ -0,0 +1,3 @@
+class class1:
+    def __repr__(self):
+        return "<class1 from package2/__init__.py>"

absolute-vs-relative-python-imports/absolute/project/package2/module3.py

@@ -0,0 +1,13 @@
+# package2/module3.py
+
+from package2 import class1
+from package2.subpackage1.module5 import function2
+
+
+def main():
+    print(class1())
+    print(function2())
+
+
+if __name__ == "__main__":
+    main()

absolute-vs-relative-python-imports/absolute/project/package2/module4.py

@@ -0,0 +1 @@
+# The tutorial's tree includes this module, but none of the examples use it.

absolute-vs-relative-python-imports/absolute/project/package2/subpackage1/module5.py

@@ -0,0 +1,2 @@
+def function2():
+    return "Hello from function2() in package2/subpackage1/module5.py"

absolute-vs-relative-python-imports/import_style.py

@@ -0,0 +1,19 @@
+# ruff: noqa: F401
+"""Illustration of good import statement styling.
+
+Note that the imports come after the docstring.
+
+"""
+
+# Standard library imports
+import datetime
+import os
+
+# Third party imports
+from flask import Flask
+from flask_restful import Api
+from flask_sqlalchemy import SQLAlchemy
+
+# Local application imports
+from local_module import local_class
+from local_package import local_function