Refactor testing and migrate examples to src-layout

.github/workflows/nox.yml

@@ -1,5 +1,10 @@
 name: nox
 on: [push, pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
 jobs:
   nox:
     strategy:
@@ -15,8 +20,7 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
       - run: python3 --version && python --version
-      - run: pip install --upgrade pip setuptools
-      - run: pip install nox pytest virtualenv
+      - run: pip install -r requirements.txt pytest
       - run: pytest . || true  # See pytest's warnings
       - run: nox --python ${{ matrix.python }}
       # - run: nox --python ${{ matrix.python }} --report report.json && python report_to_table.py

README.md

@@ -12,7 +12,7 @@ namespace packages.
 To run the scenarios:
 
 ```
-$ pip install --upgrade setuptools virtualenv nox
+$ pip install -r requirements.txt
 $ nox --report report.json
 ```
 

native/pkg_a/setup.py

@@ -27,7 +27,8 @@
     author_email='[email protected]',
 
     license='Apache Software License',
-
-    packages=['example_pkg.a'],
+    # This example uses automatic discovery. You can also implement custom discovery like this:
+    # packages=find_namespace_packages(where='src', include=['example_pkg.a']),
+    # package_dir={'': 'src'},
     zip_safe=False,
 )

native/pkg_b/setup.py

@@ -27,7 +27,8 @@
     author_email='[email protected]',
 
     license='Apache Software License',
-
-    packages=['example_pkg.b'],
+    # This example uses automatic discovery. You can also implement custom discovery like this:
+    # packages=find_namespace_packages(where='src', include=['example_pkg.b']),
+    # package_dir={'': 'src'},
     zip_safe=False,
 )

noxfile.py

@@ -17,8 +17,8 @@
 
 HERE = os.path.abspath(os.path.dirname(__file__))
 
-# -- REQUIRES: nox >= 2018.10.17
-# SEE: https://nox.readthedocs.io/en/stable/index.html
+# -- REQUIRES: nox >= 2023.04.22
+# SEE: https://nox.thea.codes/en/stable/index.html
 USE_PYTHON_VERSIONS_DEFAULT = ["3.8", "3.10", "3.12"]
 USE_PYTHON_VERSIONS = os.environ.get("NOXFILE_PYTHON_VERSIONS", "").split()
 if not USE_PYTHON_VERSIONS:
@@ -27,9 +27,8 @@
 
 install_commands = (
     ('pip', 'install', '.'),
-    ('pip', 'install', '-e', '.'),
-    ('python', 'setup.py', 'install'),
-    ('python', 'setup.py', 'develop'))
+    ('pip', 'install', '-e', '.')
+)
 
 
 def install_packages(session, package_a, package_b, command_a, command_b):

pkg_resources/pkg_a/setup.py

@@ -28,7 +28,7 @@
 
     license='Apache Software License',
 
-    packages=find_packages(),
-    namespace_packages=['example_pkg'],
+    packages=find_packages(where='src'),
+    package_dir={'': 'src'},
     zip_safe=False,
 )

pkg_resources/pkg_b/setup.py

@@ -28,7 +28,7 @@
 
     license='Apache Software License',
 
-    packages=find_packages(),
-    namespace_packages=['example_pkg'],
+    packages=find_packages(where='src'),
+    package_dir={'': 'src'},
     zip_safe=False,
 )

pkgutil/README.md

@@ -4,17 +4,15 @@ The following examples demonstrates the usage / installation of `pkgutil` style
 
 ```
 pkgutil/
-├ pkg_a/               # the name of this dir doesn't matter
-│  ├ setup.py
-│  └ example_pkg/      # namespace package name
-│      ├__init__.py    # special pkgutil namespace __init__.py
-│      └ a/            # dir name must match the package name from `setup.py`
-│        └ __init__.py
-│        ├ module1.py
-.
-.
-.
-└ pkg_b/
+├── pkg_a                    # the name of this dir doesn't matter
+│   ├── setup.py
+│   └── src                  # src dir - important for automatic discovery
+│       └── example_pkg      # namespace package name
+│           ├── a
+│           │   └── __init__.py
+│           └── __init__.py  # special pkgutil namespace __init__.py
+├── pkg_b
+
 ```
 
 The anatomy of a namespace package name is `<namespaceA>.<package_name>`.
@@ -28,11 +26,11 @@ The directories `pkg_a` and `pkg_b` in this subdirectory contain two different p
 The names of these directories have no effect on the installed package.
 
 Each of these directories should at least contain:
-1.  `setup.py`.
+1.  A configuration file for packaging tools (in this case `setup.py`).
 2.  A directory, whose name determines the namespace name.
 
 In this example `example_pkg` is the name of the namespace. This directory should contain:
-1. The `__init__.py` file for the namespace package, which must contain only the following:
+1. The `__init__.py` file for the namespace package, which must contain the following:
     ```python
     __path__ = __import__('pkgutil').extend_path(__path__, __name__)
     ```
@@ -50,7 +48,7 @@ For example, here is how to reference the namespace package `"a"` from this repo
     - `setup(name="example_pkg_a")`
 - Installing / Uninstalling a namespace package with `pip`:
     - `pip install example-pkg-a`
-- Importing a namespace package with`python`:
+- Importing a namespace package with `python`:
     - `import example_pkg.a`
 
 From the root directory, running the following command will install a package called `example_pkg.a`.
@@ -61,5 +59,5 @@ cd pkgutil/pkg_a
 pip install .
 
 # Test the install by printing the `name` from the `__init__.py` file.
-python -c "import example_pkg.a as a; print a.name"
+python -c "import example_pkg.a as a; print(a.name)"
 ```

pkgutil/pkg_a/setup.py

@@ -28,6 +28,7 @@
 
     license='Apache Software License',
 
-    packages=find_packages(),
+    packages=find_packages(where='src'),
+    package_dir={'': 'src'},
     zip_safe=False,
 )

pkgutil/pkg_b/setup.py

@@ -28,6 +28,7 @@
 
     license='Apache Software License',
 
-    packages=find_packages(),
+    packages=find_packages(where='src'),
+    package_dir={'': 'src'},
     zip_safe=False,
 )

requirements.txt

@@ -1,6 +1,5 @@
 # -- PYTHON PACKAGE REQUIREMENTS:
 # USE: pip install -r <THIS_FILE>
 
-setuptools 
-virtualenv
-nox >= 2018.10.17
+setuptools >= 68.2.2
+nox >= 2023.04.22