From 522850384ea92208116d6f2bab6db48042e34b16 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 28 Jun 2022 09:25:51 +0100 Subject: [Docs:discovery] Attempt to clarify include/exclude --- docs/userguide/package_discovery.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index 93419a24..6770833f 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -319,8 +319,7 @@ in ``src`` that start with the name ``pkg`` and not ``additional``: [options.packages.find] where = src - include = pkg* - exclude = additional + include = pkg* # alternatively: `exclude = additional*` .. note:: ``pkg`` does not contain an ``__init__.py`` file, therefore @@ -334,8 +333,7 @@ in ``src`` that start with the name ``pkg`` and not ``additional``: # ... packages=find_packages( where='src', - include=['pkg*'], - exclude=['additional'], + include=['pkg*'], # alternatively: `exclude=['additional*']` ), package_dir={"": "src"} # ... @@ -353,8 +351,7 @@ in ``src`` that start with the name ``pkg`` and not ``additional``: [tool.setuptools.packages.find] where = ["src"] - include = ["pkg*"] - exclude = ["additional"] + include = ["pkg*"] # alternatively: `exclude = ["additional*"]` namespaces = false .. note:: -- cgit v1.2.1 From ba909ad632859ee8a71effef637976501e1e81a0 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 28 Jun 2022 09:46:07 +0100 Subject: Avoid inline comments in INI files --- docs/userguide/package_discovery.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index 6770833f..856d2f30 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -319,7 +319,8 @@ in ``src`` that start with the name ``pkg`` and not ``additional``: [options.packages.find] where = src - include = pkg* # alternatively: `exclude = additional*` + include = pkg* + # alternatively: `exclude = additional*` .. note:: ``pkg`` does not contain an ``__init__.py`` file, therefore -- cgit v1.2.1 From 41e2d7221fdcc20db4134b2ac181745da3118af5 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Tue, 28 Jun 2022 09:50:04 +0100 Subject: [Docs:discovery] Update examples to consider setup.cfg/setup.py optional --- docs/userguide/package_discovery.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index 856d2f30..2efc62b9 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -156,8 +156,7 @@ all modules and packages meant for distribution are placed inside this directory:: project_root_directory - ├── pyproject.toml - ├── setup.cfg # or setup.py + ├── pyproject.toml # AND/OR setup.cfg, setup.py ├── ... └── src/ └── mypkg/ @@ -190,8 +189,7 @@ flat-layout The package folder(s) are placed directly under the project root:: project_root_directory - ├── pyproject.toml - ├── setup.cfg # or setup.py + ├── pyproject.toml # AND/OR setup.cfg, setup.py ├── ... └── mypkg/ ├── __init__.py @@ -240,8 +238,7 @@ A standalone module is placed directly under the project root, instead of inside a package folder:: project_root_directory - ├── pyproject.toml - ├── setup.cfg # or setup.py + ├── pyproject.toml # AND/OR setup.cfg, setup.py ├── ... └── single_file_lib.py @@ -293,7 +290,7 @@ then returns a list of ``str`` representing the packages it could find. To use it, consider the following directory:: mypkg - ├── setup.cfg # and/or setup.py, pyproject.toml + ├── pyproject.toml # AND/OR setup.cfg, setup.py └── src ├── pkg1 │   └── __init__.py @@ -410,7 +407,7 @@ Now, suppose you decide to package the ``foo`` part for distribution and start by creating a project directory organized as follows:: foo - ├── setup.cfg # and/or setup.py, pyproject.toml + ├── pyproject.toml # AND/OR setup.cfg, setup.py └── src └── timmins └── foo @@ -515,7 +512,7 @@ to `PEP 420 `_. It used to be more cumbersome to accomplish the same result. Historically, there were two methods to create namespace packages. One is the ``pkg_resources`` style supported by ``setuptools`` and the other one being ``pkgutils`` style offered by -``pkgutils`` module in Python. Both are now considered deprecated despite the +``pkgutils`` module in Python. Both are now considered *deprecated* despite the fact they still linger in many existing packages. These two differ in many subtle yet significant aspects and you can find out more on `Python packaging user guide `_. @@ -555,7 +552,7 @@ And your directory should look like this .. code-block:: bash foo - ├── setup.cfg # and/or setup.py, pyproject.toml + ├── pyproject.toml # AND/OR setup.cfg, setup.py └── src └── timmins ├── __init__.py @@ -575,7 +572,7 @@ file contains the following: __path__ = __import__('pkgutil').extend_path(__path__, __name__) -The project layout remains the same and ``setup.cfg`` remains the same. +The project layout remains the same and ``pyproject.toml/setup.cfg`` remains the same. ---- -- cgit v1.2.1