Merge pull request #9226 from bluetech/doc-setup-py

doc: modernize discussion of setup.py in "Good Integration Practices"

Author: bluetech

doc/en/explanation/goodpractices.rst

@@ -12,23 +12,43 @@ pip_ for installing your application and any dependencies,
 as well as the ``pytest`` package itself.
 This ensures your code and dependencies are isolated from your system Python installation.
 
-Next, place a ``setup.py`` file in the root of your package with the following minimum content:
+Next, place a ``pyproject.toml`` file in the root of your package:
 
-.. code-block:: python
+.. code-block:: toml
 
-    from setuptools import setup, find_packages
+    [build-system]
+    requires = ["setuptools>=42", "wheel"]
+    build-backend = "setuptools.build_meta"
 
-    setup(name="PACKAGENAME", packages=find_packages())
+and a ``setup.cfg`` file containing your package's metadata with the following minimum content:
 
-Where ``PACKAGENAME`` is the name of your package. You can then install your package in "editable" mode by running from the same directory:
+.. code-block:: ini
+
+    [metadata]
+    name = PACKAGENAME
+
+    [options]
+    packages = find:
+
+where ``PACKAGENAME`` is the name of your package.
+
+.. note::
+
+    If your pip version is older than ``21.3``, you'll also need a ``setup.py`` file:
+
+    .. code-block:: python
+
+        from setuptools import setup
+
+        setup()
+
+You can then install your package in "editable" mode by running from the same directory:
 
 .. code-block:: bash
 
      pip install -e .
 
 which lets you change your source code (both tests and application) and rerun tests at will.
-This is similar to running ``python setup.py develop`` or ``conda develop`` in that it installs
-your package using a symlink to your development code.
 
 .. _`test discovery`:
 .. _`Python test discovery`:
@@ -68,7 +88,8 @@ to keep tests separate from actual application code (often a good idea):
 
 .. code-block:: text
 
-    setup.py
+    pyproject.toml
+    setup.cfg
     mypkg/
         __init__.py
         app.py
@@ -82,7 +103,7 @@ This has the following benefits:
 
 * Your tests can run against an installed version after executing ``pip install .``.
 * Your tests can run against the local copy with an editable install after executing ``pip install --editable .``.
-* If you don't have a ``setup.py`` file and are relying on the fact that Python by default puts the current
+* If you don't use an editable install and are relying on the fact that Python by default puts the current
   directory in ``sys.path`` to import your package, you can execute ``python -m pytest`` to execute the tests against the
   local copy directly, without using ``pip``.
 
@@ -103,7 +124,8 @@ If you need to have test modules with the same name, you might add ``__init__.py
 
 .. code-block:: text
 
-    setup.py
+    pyproject.toml
+    setup.cfg
     mypkg/
         ...
     tests/
@@ -130,7 +152,8 @@ sub-directory of your root:
 
 .. code-block:: text
 
-    setup.py
+    pyproject.toml
+    setup.cfg
     src/
         mypkg/
             __init__.py
@@ -167,7 +190,8 @@ want to distribute them along with your application:
 
 .. code-block:: text
 
-    setup.py
+    pyproject.toml
+    setup.cfg
     mypkg/
         __init__.py
         app.py
@@ -191,11 +215,11 @@ Note that this layout also works in conjunction with the ``src`` layout mentione
 
 .. note::
 
-    You can use Python3 namespace packages (PEP420) for your application
+    You can use namespace packages (PEP420) for your application
     but pytest will still perform `test package name`_ discovery based on the
     presence of ``__init__.py`` files.  If you use one of the
     two recommended file system layouts above but leave away the ``__init__.py``
-    files from your directories it should just work on Python3.3 and above.  From
+    files from your directories, it should just work.  From
     "inlined tests", however, you will need to use absolute imports for
     getting at your application code.
 
@@ -230,8 +254,6 @@ Note that this layout also works in conjunction with the ``src`` layout mentione
     much less surprising.
 
 
-.. _`virtualenv`: https://pypi.org/project/virtualenv/
-.. _`buildout`: http://www.buildout.org/en/latest/
 .. _pip: https://pypi.org/project/pip/
 
 .. _`use tox`: