Merge branch 'main' into section-on-file-paths

Author: di

noxfile.py

@@ -6,8 +6,15 @@
 import shutil
 import nox
 
-@nox.session(py="3")
+
+nox.options.sessions = []
+
+
+@nox.session()
 def translation(session):
+    """
+    Build the gettext .pot files.
+    """
     session.install("-r", "requirements.txt")
     target_dir = "locales"
     session.run(
@@ -18,8 +25,11 @@ def translation(session):
         target_dir, # where to put the .pot file
     )
 
-@nox.session(py="3")
+@nox.session()
 def build(session, autobuild=False):
+    """
+    Make the website.
+    """
     session.install("-r", "requirements.txt")
 
     target_build_dir = "build"
@@ -49,14 +59,20 @@ def build(session, autobuild=False):
     )
 
 
-@nox.session(py="3")
+@nox.session()
 def preview(session):
+    """
+    Make and preview the website.
+    """
     session.install("sphinx-autobuild")
     build(session, autobuild=True)
 
 
-@nox.session(py="3")
+@nox.session()
 def linkcheck(session):
+    """
+    Check for broken links.
+    """
     session.install("-r", "requirements.txt")
     session.run(
         "sphinx-build", 

requirements.txt

@@ -1,6 +1,6 @@
-sphinx==4.3.1
+sphinx==4.5.0
 sphinx-autobuild==0.7.1
 sphinx-inline-tabs==2021.4.11b9
-python-docs-theme==2021.5
-sphinx-copybutton==0.4.0
+python-docs-theme==2022.1
+sphinx-copybutton==0.5.0
 git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme

source/_static/overrides.css

@@ -187,9 +187,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-html_css_files = ['overrides.css']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

source/conf.py

@@ -12,3 +12,4 @@ specific topic. If you're just trying to get stuff done, see
    pip-vs-easy-install
    install-requires-vs-requirements
    wheel-vs-egg
+   src-layout-vs-flat-layout

source/discussions/index.rst

@@ -0,0 +1,79 @@
+=========================
+src layout vs flat layout
+=========================
+
+The "flat layout" refers to organising a project's files in a folder or
+repository, such that the various configuration files and
+:term:`import packages <Import Package>` are all in the top-level directory.
+
+::
+
+    .
+    ├── README.md
+    ├── noxfile.py
+    ├── pyproject.toml
+    ├── setup.py
+    ├── awesome_package/
+    │   ├── __init__.py
+    │   └── module.py
+    └── tools/
+        ├── generate_awesomeness.py
+        └── decrease_world_suck.py
+
+The "src layout" deviates from the flat layout by moving the code that is
+intended to be importable (i.e. ``import awesome_package``, also known as
+:term:`import packages <Import Package>`) into a subdirectory. This
+subdirectory is typically named ``src/``, hence "src layout".
+
+::
+
+    .
+    ├── README.md
+    ├── noxfile.py
+    ├── pyproject.toml
+    ├── setup.py
+    ├── src/
+    │    └── awesome_package/
+    │       ├── __init__.py
+    │       └── module.py
+    └── tools/
+        ├── generate_awesomeness.py
+        └── decrease_world_suck.py
+
+Here's a breakdown of the important behaviour differences between the src
+layout and the flat layout:
+
+* The src layout requires installation of the project to be able to run its
+  code, and the flat layout does not.
+
+  This means that the src layout involves an additional step in the
+  development workflow of a project (typically, an
+  :doc:`editable installation <setuptools:userguide/development_mode>`
+  is used for development and a regular installation is used for testing).
+
+* The src layout helps prevent accidental usage of the in-development copy of
+  the code.
+
+  This is relevant since the Python interpreter includes the current working
+  directory as the first item on the import path. This means that if an import
+  package exists in the current working directory with the same name as an
+  installed import package, the variant from the current working directory will
+  be used. This can lead to subtle  misconfiguration of the project's packaging
+  tooling, which could result in files not being included in a distribution.
+
+  The src layout helps avoid this by keeping import packages in a directory
+  separate from the root directory of the project, ensuring that the installed
+  copy is used.
+
+* The src layout helps enforce that an
+  :doc:`editable installation <setuptools:userguide/development_mode>` is only
+  able to import files that were meant to be importable.
+
+  This is especially relevant when the editable installation is implemented
+  using a `path configuration file <https://docs.python.org/3/library/site.html#index-2>`_
+  that adds the directory to the import path.
+
+  The flat layout would add the other project files (eg: ``README.md``,
+  ``tox.ini``) and packaging/tooling configuration files (eg: ``setup.py``,
+  ``noxfile.py``) on the import path. This would make certain imports work
+  in editable installations but not regular installations.

source/discussions/src-layout-vs-flat-layout.rst

@@ -0,0 +1,177 @@
+==================
+The Packaging Flow
+==================
+
+The document aims to outline the flow involved in publishing/distributing a
+:term:`distribution package <Distribution Package>`, usually to the `Python
+Package Index (PyPI)`_. It is written for package publishers, who are assumed
+to be the package author.
+
+.. _Python Package Index (PyPI): https://pypi.org/
+
+While the :doc:`tutorial <tutorials/packaging-projects>` walks through the
+process of preparing a simple package for release, it does not fully enumerate
+what steps and files are required, and for what purpose.
+
+Publishing a package requires a flow from the author's source code to an end
+user's Python environment. The steps to achieve this are:
+
+- Have a source tree containing the package. This is typically a checkout from
+  a version control system (VCS).
+
+- Prepare a configuration file describing the package metadata (name, version
+  and so forth) and how to create the build artifacts. For most packages, this
+  will be a :file:`pyproject.toml` file, maintained manually in the source
+  tree.
+
+- Create build artifacts to be sent to the package distribution service
+  (usually PyPI); these will normally be a
+  :term:`source distribution ("sdist") <Source Distribution (or "sdist")>`
+  and one or more :term:`built distributions ("wheels") <Built Distribution>`.
+  These are made by a build tool using the configuration file from the
+  previous step. Often there is just one generic wheel for a pure Python
+  package.
+
+- Upload the build artifacts to the package distribution service.
+
+At that point, the package is present on the package distribution service.
+To use the package, end users must:
+
+- Download one of the package's build artifacts from the package distribution
+  service.
+
+- Install it in their Python environment, usually in its ``site-packages``
+  directory. This step may involve a build/compile step which, if needed, must
+  be described by the package metadata.
+
+These last 2 steps are typically performed by :ref:`pip` when an end user runs
+``pip install``.
+
+The steps above are described in more detail below.
+
+The source tree
+===============
+
+The source tree contains the package source code, usually a checkout from a
+VCS. The particular version of the code used to create the build artifacts
+will typically be a checkout based on a tag associated with the version.
+
+The configuration file
+======================
+
+The configuration file depends on the tool used to create the build artifacts.
+The standard practice is to use a :file:`pyproject.toml` file in the `TOML
+format`_.
+
+.. _TOML format: https://github.com/toml-lang/toml
+
+At a minimum, the :file:`pyproject.toml` file needs a ``[build-system]`` table
+specifying your build tool. There are many build tools available, including
+but not limited to :ref:`flit`, :ref:`hatch`, :ref:`pdm`, :ref:`poetry`,
+:ref:`setuptools`, `trampolim`_, and `whey`_. Each tool's documentation will
+show what to put in the ``[build-system]`` table.
+
+.. _trampolim: https://pypi.org/project/trampolim/
+.. _whey: https://pypi.org/project/whey/
+
+For example, here is a table for using :ref:`hatch`:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["hatchling"]
+    build-backend = "hatchling.build"
+
+With such a table in the :file:`pyproject.toml` file, a "frontend" tool like
+:ref:`build` can run your chosen build tool's "backend" to create the build
+artifacts. Your build tool may also provide its own frontend. An install tool
+like :ref:`pip` also acts as a frontend when it runs your build tool's backend
+to install from a source distribution.
+
+The particular build tool you choose dictates what additional information is
+required in the :file:`pyproject.toml` file. For example, you might specify:
+
+* a ``[project]`` table containing project
+  :doc:`Core Metadata </specifications/core-metadata/>`
+  (name, version, author and so forth); see
+  :doc:`Declaring project metadata </specifications/declaring-project-metadata/>`
+  for more detail
+
+* a ``[tool]`` table containing tool-specific configuration options
+
+Build artifacts
+===============
+
+The source distribution (sdist)
+-------------------------------
+
+A source distribution contains enough to install the package from source in an
+end user's Python environment. As such, it needs the package source, and may
+also include tests and documentation. These are useful for end users wanting
+to develop your sources, and for end user systems where some local compilation
+step is required (such as a C extension).
+
+The :ref:`build` package knows how to invoke your build tool to create one of
+these:
+
+.. code-block:: bash
+
+    python3 -m build --sdist source-tree-directory
+
+Or, your build tool may provide its own interface for creating an sdist.
+
+
+The built distributions (wheels)
+--------------------------------
+
+A built distribution contains only the files needed for an end user's Python
+environment. No compilation steps are required during the install, and the
+wheel file can simply be unpacked into the ``site-packages`` directory. This
+makes the install faster and more convenient for end users.
+
+A pure Python package typically needs only one "generic" wheel. A package with
+compiled binary extensions needs a wheel for each supported combination of
+Python interpreter, operating system, and CPU architecture that it supports.
+If a suitable wheel file is not available, tools like :ref:`pip` will fall
+back to installing the source distribution.
+
+The :ref:`build` package knows how to invoke your build tool to create one of
+these:
+
+.. code-block:: bash
+
+    python3 -m build --wheel source-tree-directory
+
+Or, your build tool may provide its own interface for creating a wheel.
+
+.. note::
+
+  The default behaviour of :ref:`build` is to make both an sdist and a wheel
+  from the source in the current directory; the above examples are
+  deliberately specific.
+
+Upload to the package distribution service
+==========================================
+
+The :ref:`twine` tool can upload build artifacts to PyPI for distribution,
+using a command like:
+
+.. code-block:: bash
+
+    twine upload dist/package-name-version.tar.gz dist/package-name-version-py3-none-any.whl
+
+Or, your build tool may provide its own interface for uploading.
+
+Download and install
+====================
+
+Now that the package is published, end users can download and install the
+package into their Python environment. Typically this is done with :ref:`pip`,
+using a command like:
+
+.. code-block:: bash
+
+    python3 -m pip install package-name
+
+End users may also use other tools like :ref:`pipenv`, :ref:`poetry`, or
+:ref:`pdm`.

source/flow.rst

@@ -42,7 +42,7 @@ limited resources.
 Public dataset
 ==============
 
-As an alternative, the `Linehaul project <https://github.com/pypa/linehaul>`__
+As an alternative, the `Linehaul project <https://github.com/pypa/linehaul-cloud-function/>`__
 streams download logs from PyPI to `Google BigQuery`_ [#]_, where they are
 stored as a public dataset.
 

source/guides/analyzing-pypi-package-downloads.rst

@@ -542,8 +542,7 @@ work of turning these interfaces into actual scripts [2]_.  The scripts will be
 generated during the install of your :term:`distribution <Distribution
 Package>`.
 
-For more information, see `Automatic Script Creation
-<https://setuptools.readthedocs.io/en/latest/userguide/quickstart.html#entry-points-and-automatic-script-creation>`_
+For more information, see :doc:`Entry Points <setuptools:userguide/entry_point>`
 from the :doc:`setuptools docs <setuptools:index>`.
 
 .. _`Choosing a versioning scheme`:

source/guides/distributing-packages-using-setuptools.rst

@@ -29,12 +29,12 @@ jobs:
         .
     # Actually publish to PyPI/TestPyPI
     - name: Publish distribution 📦 to Test PyPI
-      uses: pypa/gh-action-pypi-publish@master
+      uses: pypa/gh-action-pypi-publish@release/v1
       with:
         password: ${{ secrets.TEST_PYPI_API_TOKEN }}
         repository_url: https://test.pypi.org/legacy/
     - name: Publish distribution 📦 to PyPI
       if: startsWith(github.ref, 'refs/tags')
-      uses: pypa/gh-action-pypi-publish@master
+      uses: pypa/gh-action-pypi-publish@release/v1
       with:
         password: ${{ secrets.PYPI_API_TOKEN }}