From 44510d2d10b351818e51e04b2343d013f06d012c Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 10 Jun 2022 13:07:36 +0100 Subject: [PATCH 1/7] Clarify the package_dir configuration --- docs/references/keywords.rst | 41 +++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index d36630000f..76fb014ac4 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -194,7 +194,46 @@ extensions). .. _keyword/package_dir: ``package_dir`` - A dictionary providing a mapping of package to directory names. + A dictionary that maps package names (as the developer wishes they would be + imported by the end-users) into directory paths (that actually exist in the + project's source tree). This configuration can be used with 2 main objectives: + + 1. To effectively "rename" paths when building your package. + For example, ``package_dir={"mypkg": "dir1/dir2/code_for_mypkg"}`` + will instruct setuptools to copy the ``dir1/dir2/code_for_mypkg/...`` files + as ``mypkg/...`` when building the final :term:`wheel distribution `. + + .. attention:: + While it is *possible* to specify arbitrary mappings, developers are + **STRONGLY ADVISED AGAINST** that. They should try as much as possible + to keep the directory names and structure identical to as they would + appear in the final wheel, only deviating when absolutely necessary. + + 2. To indicate that the code corresponding to a package implementation is + entirely contained inside a specific directory. + In this case, a special key is required (the empty string, ``""``), + for example: ``package_dir={"": ""}``. + All the directories inside the container directory will be copied + directly into the final :term:`wheel distribution `, but the + container directory itself will not. + + This practice is very common in the community, to help separating the + package implementation from auxiliary files (e.g. CI configuration files), + and is referred as :ref:`src-layout`, because traditionally the + container directory is named ``src``. + + All paths in ``package_dir`` must be relative to the project root directory + and use a forward slash (``/``) as path separator (regardless of the + operating system). + + .. tip:: + When using :doc:`package discovery ` + together with :doc:`setup.cfg ` or + :doc:`pyproject.toml `, it is very likely + that you don't need to specify a value for ``package_dir``. Please have + a look on the definitions of :ref:`src-layout` and :ref:`flat-layout` to + learn common practices on how to design a project's directory structure + and minimise the amount of configuration that is needed. .. _keyword/requires: From a78cc892073be1b8b694eb9586c79533042b2190 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 10 Jun 2022 13:13:47 +0100 Subject: [PATCH 2/7] Add news fragment --- changelog.d/3358.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/3358.doc.rst diff --git a/changelog.d/3358.doc.rst b/changelog.d/3358.doc.rst new file mode 100644 index 0000000000..f88898642d --- /dev/null +++ b/changelog.d/3358.doc.rst @@ -0,0 +1 @@ +Clarify the role of the ``package_dir`` configuration. From 4a32c2f4d7dca2be1ff82d14759d6e257d75ecdb Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 10 Jun 2022 13:24:39 +0100 Subject: [PATCH 3/7] Improve choice of words --- docs/references/keywords.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index 76fb014ac4..0b8c0c57a1 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -196,7 +196,7 @@ extensions). ``package_dir`` A dictionary that maps package names (as the developer wishes they would be imported by the end-users) into directory paths (that actually exist in the - project's source tree). This configuration can be used with 2 main objectives: + project's source tree). This configuration can be used with 2 main purposes: 1. To effectively "rename" paths when building your package. For example, ``package_dir={"mypkg": "dir1/dir2/code_for_mypkg"}`` @@ -206,11 +206,11 @@ extensions). .. attention:: While it is *possible* to specify arbitrary mappings, developers are **STRONGLY ADVISED AGAINST** that. They should try as much as possible - to keep the directory names and structure identical to as they would + to keep the directory names and hierarchy identical to as they would appear in the final wheel, only deviating when absolutely necessary. - 2. To indicate that the code corresponding to a package implementation is - entirely contained inside a specific directory. + 2. To indicate that the relevant code is entirely contained inside + a specific directory (instead of directly placed under the project's root). In this case, a special key is required (the empty string, ``""``), for example: ``package_dir={"": ""}``. All the directories inside the container directory will be copied From 0d45acaaeae9db4adef4f450429b12bfc974cb13 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 10 Jun 2022 16:36:05 +0100 Subject: [PATCH 4/7] Add clarifications to setup.cfg guides --- docs/userguide/declarative_config.rst | 37 ++++++++++++++++++++------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/docs/userguide/declarative_config.rst b/docs/userguide/declarative_config.rst index 2a65e6e367..4778dcf8b0 100644 --- a/docs/userguide/declarative_config.rst +++ b/docs/userguide/declarative_config.rst @@ -62,8 +62,8 @@ boilerplate code in some cases. Metadata and options are set in the config sections of the same name. -* Keys are the same as the keyword arguments one provides to the ``setup()`` - function. +* Keys are the same as the :doc:`keyword arguments ` one + provides to the ``setup()`` function. * Complex values can be written comma-separated or placed one per line in *dangling* config values. The following are equivalent: @@ -90,7 +90,7 @@ Metadata and options are set in the config sections of the same name. Using a ``src/`` layout ======================= -One commonly used package configuration has all the module source code in a +One commonly used configuration has all the Python source code in a subdirectory (often called the ``src/`` layout), like this:: ├── src @@ -101,7 +101,7 @@ subdirectory (often called the ``src/`` layout), like this:: └── setup.cfg You can set up your ``setup.cfg`` to automatically find all your packages in -the subdirectory like this: +the subdirectory, using :ref:`package_dir `, like this: .. code-block:: ini @@ -116,6 +116,22 @@ the subdirectory like this: [options.packages.find] where=src +In this example, the value for the :ref:`package_dir ` +configuration (i.e. ``=src``) is parsed as ``{"": "src"}``. +The ``""`` key has a special meaning in this context, and indicates that all the +packages are contained inside the given directory. +Also note that the value for ``[options.packages.find] where`` matches to the +value associated with ``""`` in the ``package_dir`` dictionary. + +.. + TODO: Add the following tip once the auto-discovery is no longer experimental: + + Starting in version 61, ``setuptools`` can automatically infer the + configurations for both ``packages`` and ``package_dir`` for projects using + a ``src/`` layout (as long as no value is specified for ``py_modules``). + Please see :doc:`package discovery ` for more + details. + Specifying values ================= @@ -127,7 +143,10 @@ Type names used below: * ``list-comma`` - dangling list or string of comma-separated values * ``list-semi`` - dangling list or string of semicolon-separated values * ``bool`` - ``True`` is 1, yes, true -* ``dict`` - list-comma where keys are separated from values by ``=`` +* ``dict`` - list-comma where each entry corresponds to a key/value pair, + with keys separated from values by ``=``. + If an entry starts with ``=``, the key is assumed to be an empty string + (e.g. ``=src`` is parsed into ``{"": "src"}``). * ``section`` - values are read from a dedicated (sub)section @@ -143,15 +162,15 @@ Special directives: * ``file:`` - Value is read from a list of files and then concatenated - .. note:: - The ``file:`` directive is sandboxed and won't reach anything outside - the directory containing ``setup.py``. + .. important:: + The ``file:`` directive is sandboxed and won't reach anything outside the + project directory (i.e. the directory containing ``setup.cfg``/``pyproject.toml``). Metadata -------- -.. note:: +.. attention:: The aliases given below are supported for compatibility reasons, but their use is not advised. From 3820d57c1d8475698f48639a6ebc228d2390fade Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 10 Jun 2022 16:39:40 +0100 Subject: [PATCH 5/7] Apply suggestions from code review --- docs/userguide/declarative_config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/declarative_config.rst b/docs/userguide/declarative_config.rst index 4778dcf8b0..fd866b68b9 100644 --- a/docs/userguide/declarative_config.rst +++ b/docs/userguide/declarative_config.rst @@ -120,7 +120,7 @@ In this example, the value for the :ref:`package_dir ` configuration (i.e. ``=src``) is parsed as ``{"": "src"}``. The ``""`` key has a special meaning in this context, and indicates that all the packages are contained inside the given directory. -Also note that the value for ``[options.packages.find] where`` matches to the +Also note that the value for ``[options.packages.find] where`` matches the value associated with ``""`` in the ``package_dir`` dictionary. .. From 231629732de7077f94eacc2fe5a4619595f86be2 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Sat, 11 Jun 2022 10:21:28 +0100 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: cdfarrow --- docs/references/keywords.rst | 16 ++++++++-------- docs/userguide/declarative_config.rst | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index 0b8c0c57a1..8c11d3aca0 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -194,9 +194,9 @@ extensions). .. _keyword/package_dir: ``package_dir`` - A dictionary that maps package names (as the developer wishes they would be + A dictionary that maps package names (as they will be imported by the end-users) into directory paths (that actually exist in the - project's source tree). This configuration can be used with 2 main purposes: + project's source tree). This configuration has two main purposes: 1. To effectively "rename" paths when building your package. For example, ``package_dir={"mypkg": "dir1/dir2/code_for_mypkg"}`` @@ -206,7 +206,7 @@ extensions). .. attention:: While it is *possible* to specify arbitrary mappings, developers are **STRONGLY ADVISED AGAINST** that. They should try as much as possible - to keep the directory names and hierarchy identical to as they would + to keep the directory names and hierarchy identical to the way they will appear in the final wheel, only deviating when absolutely necessary. 2. To indicate that the relevant code is entirely contained inside @@ -217,21 +217,21 @@ extensions). directly into the final :term:`wheel distribution `, but the container directory itself will not. - This practice is very common in the community, to help separating the + This practice is very common in the community to help separate the package implementation from auxiliary files (e.g. CI configuration files), - and is referred as :ref:`src-layout`, because traditionally the + and is referred to as :ref:`src-layout`, because traditionally the container directory is named ``src``. All paths in ``package_dir`` must be relative to the project root directory - and use a forward slash (``/``) as path separator (regardless of the - operating system). + and use a forward slash (``/``) as path separator regardless of the + operating system. .. tip:: When using :doc:`package discovery ` together with :doc:`setup.cfg ` or :doc:`pyproject.toml `, it is very likely that you don't need to specify a value for ``package_dir``. Please have - a look on the definitions of :ref:`src-layout` and :ref:`flat-layout` to + a look at the definitions of :ref:`src-layout` and :ref:`flat-layout` to learn common practices on how to design a project's directory structure and minimise the amount of configuration that is needed. diff --git a/docs/userguide/declarative_config.rst b/docs/userguide/declarative_config.rst index fd866b68b9..aa8bc7ea16 100644 --- a/docs/userguide/declarative_config.rst +++ b/docs/userguide/declarative_config.rst @@ -146,7 +146,7 @@ Type names used below: * ``dict`` - list-comma where each entry corresponds to a key/value pair, with keys separated from values by ``=``. If an entry starts with ``=``, the key is assumed to be an empty string - (e.g. ``=src`` is parsed into ``{"": "src"}``). + (e.g. ``=src`` is parsed as ``{"": "src"}``). * ``section`` - values are read from a dedicated (sub)section From 712a5b46627055d744d7f350f1f5d167ce04ba3c Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Sat, 11 Jun 2022 10:31:09 +0100 Subject: [PATCH 7/7] Use 'commonly' instead of 'traditionally' --- docs/references/keywords.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index 8c11d3aca0..a66d503ea6 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -219,8 +219,8 @@ extensions). This practice is very common in the community to help separate the package implementation from auxiliary files (e.g. CI configuration files), - and is referred to as :ref:`src-layout`, because traditionally the - container directory is named ``src``. + and is referred to as :ref:`src-layout`, because the container + directory is commonly named ``src``. All paths in ``package_dir`` must be relative to the project root directory and use a forward slash (``/``) as path separator regardless of the