From 4fd382d23f43bce178d6b2fb497d876200b3920e Mon Sep 17 00:00:00 2001 From: Rodrigo Mologni Date: Sat, 4 Dec 2021 00:13:41 -0300 Subject: fix: typo 'extras_require' --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 6bf353a0..98e34c19 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -159,7 +159,7 @@ When your project is installed, all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed. This, of course, is a simplified scenarios. ``setuptools`` also provide additional keywords such as ``setup_requires`` that allows you to install -dependencies before running the script, and ``extras_requires`` that take +dependencies before running the script, and ``extras_require`` that take care of those needed by automatically generated scripts. It also provides mechanisms to handle dependencies that are not in PyPI. For more advanced use, see :doc:`dependency_management` -- cgit v1.2.1 From 4834907218be6f104cac123caaf87c5d341e1683 Mon Sep 17 00:00:00 2001 From: eacheson Date: Fri, 24 Dec 2021 12:03:44 +0100 Subject: Update quickstart.rst fix various english issues --- docs/userguide/quickstart.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 98e34c19..da904bab 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -14,9 +14,9 @@ Python packaging at a glance ============================ The landscape of Python packaging is shifting and ``Setuptools`` has evolved to only provide backend support, no longer being the de-facto packaging tool in -the market. All python package must provide a ``pyproject.toml`` and specify +the market. Every python package must provide a ``pyproject.toml`` and specify the backend (build system) it wants to use. The distribution can then -be generated with whatever tools that provides a ``build sdist``-alike +be generated with whatever tool that provides a ``build sdist``-like functionality. While this may appear cumbersome, given the added pieces, it in fact tremendously enhances the portability of your package. The change is driven under :pep:`PEP 517 <517#build-requirements>`. To learn more about Python packaging in general, @@ -76,7 +76,7 @@ This is what your project would look like:: setup.cfg # or setup.py mypackage/__init__.py -Then, you need an builder, such as :std:doc:`PyPA build ` +Then, you need a builder, such as :std:doc:`PyPA build ` which you can obtain via ``pip install build``. After downloading it, invoke the builder:: @@ -89,15 +89,15 @@ Of course, before you release your project to PyPI, you'll want to add a bit more information to your setup script to help people find or learn about your project. And maybe your project will have grown by then to include a few dependencies, and perhaps some data files and scripts. In the next few sections, -we will walk through those additional but essential information you need +we will walk through the additional but essential information you need to specify to properly package your project. Automatic package discovery =========================== For simple projects, it's usually easy enough to manually add packages to -the ``packages`` keyword in ``setup.cfg``. However, for very large projects -, it can be a big burden to keep the package list updated. ``setuptools`` +the ``packages`` keyword in ``setup.cfg``. However, for very large projects, +it can be a big burden to keep the package list updated. ``setuptools`` therefore provides two convenient tools to ease the burden: :literal:`find:\ ` and :literal:`find_namespace:\ `. To use it in your project: @@ -110,11 +110,11 @@ therefore provides two convenient tools to ease the burden: :literal:`find:\ ` a include=pkg1, pkg2 exclude=pk3, pk4 -When you pass the above information, alongside other necessary ones, +When you pass the above information, alongside other necessary information, ``setuptools`` walks through the directory specified in ``where`` (omitted -here as the package reside in current directory) and filters the packages -it can find following the ``include`` (default to none), then remove -those that match the ``exclude`` and return a list of Python packages. Note +here as the package resides in the current directory) and filters the packages +it can find following the ``include`` (defaults to none), then removes +those that match the ``exclude`` and returns a list of Python packages. Note that each entry in the ``[options.packages.find]`` is optional. The above setup also allows you to adopt a ``src/`` layout. For more details and advanced use, go to :ref:`package_discovery` @@ -122,7 +122,7 @@ use, go to :ref:`package_discovery` Entry points and automatic script creation =========================================== -Setuptools support automatic creation of scripts upon installation, that runs +Setuptools supports automatic creation of scripts upon installation, that runs code within your package if you specify them with the ``entry_points`` keyword. This is what allows you to run commands like ``pip install`` instead of having to type ``python -m pip install``. To accomplish this, add the entry_points @@ -157,7 +157,7 @@ operators <, >, <=, >=, == or !=, followed by a version identifier): When your project is installed, all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed. -This, of course, is a simplified scenarios. ``setuptools`` also provide +This, of course, is a simplified scenarios. ``setuptools`` also provides additional keywords such as ``setup_requires`` that allows you to install dependencies before running the script, and ``extras_require`` that take care of those needed by automatically generated scripts. It also provides @@ -207,7 +207,7 @@ associate with your source code. For more information, see :doc:`development_mod Uploading your package to PyPI ============================== -After generating the distribution files, next step would be to upload your +After generating the distribution files, the next step would be to upload your distribution so others can use it. This functionality is provided by `twine `_ and we will only demonstrate the basic use here. -- cgit v1.2.1 From f51935be120c9f5361db02a5df7806b0837913fc Mon Sep 17 00:00:00 2001 From: Ananth Pattabiraman Date: Fri, 7 Jan 2022 19:14:45 +0530 Subject: add resources on packaging Section `Resources on Python packaging` did not point to any resource. Added as discussed on #2674 --- docs/userguide/quickstart.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index da904bab..dc1c9e60 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -225,5 +225,6 @@ parsed by ``setuptool`` to ease the pain of transition. Resources on Python packaging ============================= -Packaging in Python is hard. Here we provide a list of links for those that -want to learn more. +Packaging in Python can be hard and is constantly evolving. +`Python Packaging User Guide `_ has tutorials and +up-to-date references. -- cgit v1.2.1 From 4d36adadc793c28e1df5bbb3a549ea608d55df76 Mon Sep 17 00:00:00 2001 From: Ananth Pattabiraman Date: Fri, 7 Jan 2022 19:59:03 +0530 Subject: Update docs/userguide/quickstart.rst Co-authored-by: Anderson Bravalheri --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index dc1c9e60..4c62c6df 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -227,4 +227,4 @@ Resources on Python packaging ============================= Packaging in Python can be hard and is constantly evolving. `Python Packaging User Guide `_ has tutorials and -up-to-date references. +up-to-date references that can help you when it is time to distribute your work. -- cgit v1.2.1 From b48ef32c926052695008b2f4a8a2c68ca0d88678 Mon Sep 17 00:00:00 2001 From: Julien Palard Date: Mon, 24 Jan 2022 23:47:19 +0100 Subject: doc: Fix trailing spaces, tabs, and missing newlines at end of file. --- docs/userguide/quickstart.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 4c62c6df..28d4ac33 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -96,7 +96,7 @@ to specify to properly package your project. Automatic package discovery =========================== For simple projects, it's usually easy enough to manually add packages to -the ``packages`` keyword in ``setup.cfg``. However, for very large projects, +the ``packages`` keyword in ``setup.cfg``. However, for very large projects, it can be a big burden to keep the package list updated. ``setuptools`` therefore provides two convenient tools to ease the burden: :literal:`find:\ ` and :literal:`find_namespace:\ `. To use it in your project: @@ -189,9 +189,9 @@ Development mode .. tip:: - Prior to :ref:`pip v21.1 `, a ``setup.py`` script was - required to be compatible with development mode. With late - versions of pip, any project may be installed in this mode. + Prior to :ref:`pip v21.1 `, a ``setup.py`` script was + required to be compatible with development mode. With late + versions of pip, any project may be installed in this mode. ``setuptools`` allows you to install a package without copying any files to your interpreter directory (e.g. the ``site-packages`` directory). -- cgit v1.2.1 From f7d30a9529378cf69054b5176249e5457aaf640a Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Thu, 27 Jan 2022 23:00:56 +0100 Subject: Stop mentioning `wheel` in the context of PEP 517 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This dependency is exposed automatically by setuptools and the users do not need to declare it explicitly — it will be installed by PEP 517 front-ends automatically, when building wheels. --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 28d4ac33..203d6204 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -32,7 +32,7 @@ package your project: .. code-block:: toml [build-system] - requires = ["setuptools", "wheel"] + requires = ["setuptools"] build-backend = "setuptools.build_meta" Then, you will need a ``setup.cfg`` or ``setup.py`` to specify your package -- cgit v1.2.1 From e8b418d0b3ccd9b0c70401ef1fe38481980c5578 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 3 Mar 2022 17:41:13 +0000 Subject: Add link to MANIFEST.in in quickstart --- docs/userguide/quickstart.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 203d6204..61ab7f97 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -180,7 +180,9 @@ can simply use the ``include_package_data`` keyword: include_package_data = True This tells setuptools to install any data files it finds in your packages. -The data files must be specified via the distutils' ``MANIFEST.in`` file. +The data files must be specified via the distutils' |MANIFEST.in| file +or automatically added by a :ref:`Revision Control System plugin +`. For more details, see :doc:`datafiles` @@ -228,3 +230,7 @@ Resources on Python packaging Packaging in Python can be hard and is constantly evolving. `Python Packaging User Guide `_ has tutorials and up-to-date references that can help you when it is time to distribute your work. + + +.. |MANIFEST.in| replace:: ``MANIFEST.in`` +.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/ -- cgit v1.2.1 From 580801296f57c829a57567006284d312853b1f2d Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 3 Mar 2022 18:24:10 +0000 Subject: Add missing link to PyPUG MANIFEST.in docs --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 61ab7f97..f3183624 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -180,7 +180,7 @@ can simply use the ``include_package_data`` keyword: include_package_data = True This tells setuptools to install any data files it finds in your packages. -The data files must be specified via the distutils' |MANIFEST.in| file +The data files must be specified via the distutils' |MANIFEST.in|_ file or automatically added by a :ref:`Revision Control System plugin `. For more details, see :doc:`datafiles` -- cgit v1.2.1 From f14200550a97bf3f113a563e3502bc63883b1c6b Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 00:39:39 +0000 Subject: Mention experimental pyproject config in the quickstart --- docs/userguide/quickstart.rst | 44 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 7 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index f3183624..6267fe8b 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -35,9 +35,9 @@ package your project: requires = ["setuptools"] build-backend = "setuptools.build_meta" -Then, you will need a ``setup.cfg`` or ``setup.py`` to specify your package -information, such as metadata, contents, dependencies, etc. Here we demonstrate -the minimum +Then, you will need to specify your package information (either via +``setup.cfg``, ``setup.py`` or ``pyproject.toml``), such as metadata, contents, +dependencies, etc. Here we demonstrate the minimum .. tab:: setup.cfg @@ -51,7 +51,9 @@ the minimum packages = mypackage install_requires = requests - importlib; python_version == "2.6" + importlib-metadata; python_version < "3.8" + + See :doc:`/userguide/declarative_config` for more information. .. tab:: setup.py @@ -65,10 +67,28 @@ the minimum packages=['mypackage'], install_requires=[ 'requests', - 'importlib; python_version == "2.6"', + 'importlib-metadata; python_version == "3.8"', ], ) + See :doc:`/keywords` for more information. + +.. tab:: pyproject.toml + + **EXPERIMENTAL** [#experimental]_ + + .. code-block:: toml + + [project] + name = "mypackage" + version = "0.0.1" + dependencies = [ + "requests", + 'importlib-metadata; python_version<"3.8"', + ] + + See :doc:`/userguide/pyproject_config` for more information. + This is what your project would look like:: ~/mypackage/ @@ -220,8 +240,9 @@ Transitioning from ``setup.py`` to ``setup.cfg`` To avoid executing arbitrary scripts and boilerplate code, we are transitioning into a full-fledged ``setup.cfg`` to declare your package information instead of running ``setup()``. This inevitably brings challenges due to a different -syntax. Here we provide a quick guide to understanding how ``setup.cfg`` is -parsed by ``setuptool`` to ease the pain of transition. +syntax. :doc:`Here ` we provide a quick guide to +understanding how ``setup.cfg`` is parsed by ``setuptool`` to ease the pain of +transition. .. _packaging-resources: @@ -234,3 +255,12 @@ up-to-date references that can help you when it is time to distribute your work. .. |MANIFEST.in| replace:: ``MANIFEST.in`` .. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/ + + +---- + + +.. [#experimental] + Support for specifying package metadata and build configuration options via + ``pyproject.toml`` is experimental and might change (or be completely + removed) in the future. See :doc:`/userguide/pyproject_config`. -- cgit v1.2.1 From 0a754916d77864e5dad08c4b59f60deb97ee200b Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 00:47:01 +0000 Subject: Add some missing references in the quickstart --- docs/userguide/quickstart.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 6267fe8b..dd899428 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -137,7 +137,7 @@ it can find following the ``include`` (defaults to none), then removes those that match the ``exclude`` and returns a list of Python packages. Note that each entry in the ``[options.packages.find]`` is optional. The above setup also allows you to adopt a ``src/`` layout. For more details and advanced -use, go to :ref:`package_discovery` +use, go to :ref:`package_discovery`. Entry points and automatic script creation @@ -182,7 +182,7 @@ additional keywords such as ``setup_requires`` that allows you to install dependencies before running the script, and ``extras_require`` that take care of those needed by automatically generated scripts. It also provides mechanisms to handle dependencies that are not in PyPI. For more advanced use, -see :doc:`dependency_management` +see :doc:`dependency_management`. .. _Including Data Files: @@ -203,7 +203,7 @@ This tells setuptools to install any data files it finds in your packages. The data files must be specified via the distutils' |MANIFEST.in|_ file or automatically added by a :ref:`Revision Control System plugin `. -For more details, see :doc:`datafiles` +For more details, see :doc:`datafiles`. Development mode @@ -231,8 +231,8 @@ Uploading your package to PyPI ============================== After generating the distribution files, the next step would be to upload your distribution so others can use it. This functionality is provided by -`twine `_ and we will only demonstrate the -basic use here. +:pypi:`twine` and is documented in the :doc:`Python packaging tutorial +`. Transitioning from ``setup.py`` to ``setup.cfg`` -- cgit v1.2.1 From 203c2f89d7fd315017c0834f74f5eb7f0f501cc5 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 09:46:01 +0000 Subject: Fix link to keywords --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index dd899428..085e46c0 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -71,7 +71,7 @@ dependencies, etc. Here we demonstrate the minimum ], ) - See :doc:`/keywords` for more information. + See :doc:`/references/keywords` for more information. .. tab:: pyproject.toml -- cgit v1.2.1 From 733c84345904804bf4719b9aa9414018b9ed3057 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 11:04:57 +0000 Subject: Improve discovery section in the quickstart --- docs/userguide/quickstart.rst | 65 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 55 insertions(+), 10 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 085e46c0..6219cd9a 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -118,27 +118,72 @@ Automatic package discovery For simple projects, it's usually easy enough to manually add packages to the ``packages`` keyword in ``setup.cfg``. However, for very large projects, it can be a big burden to keep the package list updated. ``setuptools`` -therefore provides two convenient tools to ease the burden: :literal:`find:\ ` and -:literal:`find_namespace:\ `. To use it in your project: +therefore provides a convenient way to automatically list all the packages in +your project directory: -.. code-block:: ini +.. tab:: setup.cfg - [options] - packages = find: + .. code-block:: ini + + [options] + packages = find: # OR `find_namespaces:` if you want to use namespaces - [options.packages.find] #optional - include=pkg1, pkg2 - exclude=pk3, pk4 + [options.packages.find] (always `find` even if `find_namespaces:` was used before) + # This section is optional + # Each entry in this section is optional, and if not specified, the default values are: + # `where=.`, `include=*` and `exclude=` (empty). + include=mypackage* + exclude=mypackage.tests* + +.. tab:: setup.py + + .. code-block:: python + from setuptools import find_packages # or find_namespace_packages + + setup( + # ... + packages=find_packages( + where='.', + include=['mypackage*'], # ["*"] by default + exclude=['mypackage.tests'], # empty by default + ), + # ... + ) + +.. tab:: pyproject.toml + + **EXPERIMENTAL** [#experimental]_ + + .. code-block:: toml + + # ... + [tool.setuptools.packages] + find = {} # Scan the project directory with the default parameters + + # OR + [tool.setuptools.packages.find] + where = ["src"] # ["."] by default + include = ["mypackage*"] # ["*"] by default + exclude = ["mypackage.tests*"] # empty by default + namespaces = false # true by default When you pass the above information, alongside other necessary information, ``setuptools`` walks through the directory specified in ``where`` (omitted here as the package resides in the current directory) and filters the packages it can find following the ``include`` (defaults to none), then removes -those that match the ``exclude`` and returns a list of Python packages. Note -that each entry in the ``[options.packages.find]`` is optional. The above +those that match the ``exclude`` and returns a list of Python packages. The above setup also allows you to adopt a ``src/`` layout. For more details and advanced use, go to :ref:`package_discovery`. +.. tip:: + Starting with version 60.10.0, setuptools' automatic discovery capabilities + have been improved to detect popular project layouts (such as the + :ref:`flat-layout` and :ref:`src-layout`) without requiring any + special configuration. Check out our :ref:`reference docs ` + for more information, but please keep in mind that this functionality is + still considered **experimental** and might change (or even be removed) in + future releases. + Entry points and automatic script creation =========================================== -- cgit v1.2.1 From 912cb9cbfd677d4ad0de21b16ad9906de9ebef60 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 11:06:34 +0000 Subject: Improve entry-points section in the quickstart --- docs/userguide/quickstart.rst | 48 +++++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 11 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 6219cd9a..13d881cf 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -188,21 +188,47 @@ use, go to :ref:`package_discovery`. Entry points and automatic script creation =========================================== Setuptools supports automatic creation of scripts upon installation, that runs -code within your package if you specify them with the ``entry_points`` keyword. +code within your package if you specify them as :doc:`entry points +`. This is what allows you to run commands like ``pip install`` instead of having -to type ``python -m pip install``. To accomplish this, add the entry_points -keyword in your ``setup.cfg``: +to type ``python -m pip install``. +The following configuration examples show how to accomplish this: -.. code-block:: ini +.. tab:: setup.cfg + + .. code-block:: ini + + [options.entry_points] + console_scripts = + cli-name = mypkg:some_func + +.. tab:: setup.py + + .. code-block:: python + + setup( + # ... + entry_points={ + 'console_scripts': [ + 'cli-name = mypkg:some_func', + ] + } + ) + +.. tab:: pyproject.toml + + **EXPERIMENTAL** [#experimental]_ + + .. code-block:: toml - [options.entry_points] - console_scripts = - main = mypkg:some_func + [project.scripts] + cli-name = mypkg:some_func -When this project is installed, a ``main`` script will be installed and will -invoke the ``some_func`` in the ``__init__.py`` file when called by the user. -For detailed usage, including managing the additional or optional dependencies, -go to :doc:`entry_point`. +When this project is installed, a ``cli-name`` executable will be installed and will +invoke the ``some_func`` in the ``mypkg/__init__.py`` file when called by the user. +Note that you can also use the ``entry-points`` mechanism to advertise +components between installed packages and implement plugin systems. +For detailed usage, go to :doc:`entry_point`. Dependency management -- cgit v1.2.1 From c627a367ea62245631ba203096bd5a961851a42e Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 11:28:38 +0000 Subject: Improve dependencies section in quickstart --- docs/userguide/quickstart.rst | 57 +++++++++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 16 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 13d881cf..7a02d20b 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -233,27 +233,52 @@ For detailed usage, go to :doc:`entry_point`. Dependency management ===================== -``setuptools`` supports automatically installing dependencies when a package is -installed. The simplest way to include requirement specifiers is to use the -``install_requires`` argument to ``setup.cfg``. It takes a string or list of -strings containing requirement specifiers (A version specifier is one of the -operators <, >, <=, >=, == or !=, followed by a version identifier): +Packages built with ``setuptools`` can specify dependencies to be automatically +installed when the package itself is installed. +The example bellow show how to configure this kind of dependencies: -.. code-block:: ini +.. tab:: setup.cfg - [options] - install_requires = - docutils >= 0.3 - requests <= 0.4 + .. code-block:: ini + + [options] + install_requires = + docutils + requests <= 0.4 + +.. tab:: setup.py + + .. code-block:: python + + setup( + # ... + install_requires=["docutils", "requests <= 0.4"], + # ... + ) + +.. tab:: pyproject.toml + + **EXPERIMENTAL** [#experimental]_ + + [project] + # ... + dependencies = [ + "docutils", + "requires <= 0.4", + ] + # ... + +Each dependency is represented a string that can optionally contain version requirements +(e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier), +and/or conditional environment markers, e.g. ``os_name = "windows"`` +(see :doc:`PyPUG:specifications/version-specifiers` for more information). When your project is installed, all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed. -This, of course, is a simplified scenarios. ``setuptools`` also provides -additional keywords such as ``setup_requires`` that allows you to install -dependencies before running the script, and ``extras_require`` that take -care of those needed by automatically generated scripts. It also provides -mechanisms to handle dependencies that are not in PyPI. For more advanced use, -see :doc:`dependency_management`. +This, of course, is a simplified scenarios. You can also specify groups of +extra dependencies that are not strictly required by your package to work, but +that will provide additional functionalities. +For more advanced use, see :doc:`dependency_management`. .. _Including Data Files: -- cgit v1.2.1 From c4c8fd1e5704d22199026be12d4a7fe959295bd6 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 11:32:48 +0000 Subject: Improve data files section in quickstart --- docs/userguide/quickstart.rst | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 7a02d20b..f8e5cc64 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -290,10 +290,34 @@ are placed in a platform-specific location. Setuptools offers three ways to specify data files to be included in your packages. For the simplest use, you can simply use the ``include_package_data`` keyword: -.. code-block:: ini +.. tab:: setup.cfg + + .. code-block:: ini + + [options] + include_package_data = True + +.. tab:: setup.py + + .. code-block:: python + + setup( + # ... + include_package_data=True, + # ... + ) + +.. tab:: pyproject.toml + + **EXPERIMENTAL** [#experimental]_ + + .. code-block:: toml - [options] - include_package_data = True + [tool.setuptools] + include-package-data = true + # This is already the default behaviour if your are using + # pyproject.toml to configure your build. + # You can deactivate that with `include-package-data = false` This tells setuptools to install any data files it finds in your packages. The data files must be specified via the distutils' |MANIFEST.in|_ file -- cgit v1.2.1 From 508ce521dd874c60a1bb440a5a5163ef5060ecdd Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 12:09:22 +0000 Subject: Add note about editable installs in quickstart --- docs/userguide/quickstart.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index f8e5cc64..3075a045 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -331,7 +331,23 @@ Development mode .. tip:: - Prior to :ref:`pip v21.1 `, a ``setup.py`` script was + For the time being you might need to keep a ``setup.py`` + file in your repository if you want to use editable installs + (depending how the project is configured). A simple script will suffice, + for example: + + .. code-block:: python + + from setuptools import setup + + setup() + + You can still keep all the configuration in :doc:`setup.cfg ` + (or :doc:`pyproject.toml `, a ``setup.py`` script was required to be compatible with development mode. With late versions of pip, any project may be installed in this mode. -- cgit v1.2.1 From 630fc123b33eefadcabe005383634a21a6556cd5 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 12:24:25 +0000 Subject: Clarify editable installs note in quickstart --- docs/userguide/quickstart.rst | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 3075a045..f23295aa 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -329,21 +329,16 @@ For more details, see :doc:`datafiles`. Development mode ================ -.. tip:: - - For the time being you might need to keep a ``setup.py`` - file in your repository if you want to use editable installs - (depending how the project is configured). A simple script will suffice, - for example: - - .. code-block:: python - - from setuptools import setup +``setuptools`` allows you to install a package without copying any files +to your interpreter directory (e.g. the ``site-packages`` directory). +This allows you to modify your source code and have the changes take +effect without you having to rebuild and reinstall. +Here's how to do it:: - setup() + pip install --editable . - You can still keep all the configuration in :doc:`setup.cfg ` - (or :doc:`pyproject.toml `, or have version of ``pip`` older than :ref:`v21.1 `, + you might need to keep a ``setup.py`` file in file in your repository if + you want to use editable installs (for the time being). - pip install --editable . + A simple script will suffice, for example: -This creates a link file in your interpreter site package directory which -associate with your source code. For more information, see :doc:`development_mode`. + .. code-block:: python + + from setuptools import setup + + setup() + + You can still keep all the configuration in :doc:`setup.cfg ` + (or :doc:`pyproject.toml Date: Thu, 17 Mar 2022 13:03:30 +0000 Subject: Improve notes on quickstart --- docs/userguide/quickstart.rst | 84 ++++++++++++++++++++++++------------------- 1 file changed, 47 insertions(+), 37 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index f23295aa..9f3288d6 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -35,9 +35,14 @@ package your project: requires = ["setuptools"] build-backend = "setuptools.build_meta" -Then, you will need to specify your package information (either via -``setup.cfg``, ``setup.py`` or ``pyproject.toml``), such as metadata, contents, -dependencies, etc. Here we demonstrate the minimum +Then, you will need to specify your package information such as metadata, +contents, dependencies, etc. + +Setuptools currently support configurations from either ``setup.cfg``, +``setup.py`` or ``pyproject.toml`` [#experimental]_ files, however, configuring new +projects via ``setup.py`` is discouraged [#setup.py]_. + +The following example demonstrates a minimum configuration: .. tab:: setup.cfg @@ -55,7 +60,7 @@ dependencies, etc. Here we demonstrate the minimum See :doc:`/userguide/declarative_config` for more information. -.. tab:: setup.py +.. tab:: setup.py [#setup.py]_ .. code-block:: python @@ -73,9 +78,7 @@ dependencies, etc. Here we demonstrate the minimum See :doc:`/references/keywords` for more information. -.. tab:: pyproject.toml - - **EXPERIMENTAL** [#experimental]_ +.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ .. code-block:: toml @@ -117,9 +120,9 @@ Automatic package discovery =========================== For simple projects, it's usually easy enough to manually add packages to the ``packages`` keyword in ``setup.cfg``. However, for very large projects, -it can be a big burden to keep the package list updated. ``setuptools`` -therefore provides a convenient way to automatically list all the packages in -your project directory: +it can be a big burden to keep the package list updated. +Therefore, ``setuptoops`` provides a convenient way to automatically list all +the packages in your project directory: .. tab:: setup.cfg @@ -135,9 +138,10 @@ your project directory: include=mypackage* exclude=mypackage.tests* -.. tab:: setup.py +.. tab:: setup.py [#setup.py]_ .. code-block:: python + from setuptools import find_packages # or find_namespace_packages setup( @@ -150,9 +154,7 @@ your project directory: # ... ) -.. tab:: pyproject.toml - - **EXPERIMENTAL** [#experimental]_ +.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ .. code-block:: toml @@ -178,7 +180,7 @@ use, go to :ref:`package_discovery`. .. tip:: Starting with version 60.10.0, setuptools' automatic discovery capabilities have been improved to detect popular project layouts (such as the - :ref:`flat-layout` and :ref:`src-layout`) without requiring any + :ref:`flat-layout` and :ref:`src-layout` layouts) without requiring any special configuration. Check out our :ref:`reference docs ` for more information, but please keep in mind that this functionality is still considered **experimental** and might change (or even be removed) in @@ -202,7 +204,7 @@ The following configuration examples show how to accomplish this: console_scripts = cli-name = mypkg:some_func -.. tab:: setup.py +.. tab:: setup.py [#setup.py]_ .. code-block:: python @@ -215,9 +217,7 @@ The following configuration examples show how to accomplish this: } ) -.. tab:: pyproject.toml - - **EXPERIMENTAL** [#experimental]_ +.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ .. code-block:: toml @@ -246,7 +246,7 @@ The example bellow show how to configure this kind of dependencies: docutils requests <= 0.4 -.. tab:: setup.py +.. tab:: setup.py [#setup.py]_ .. code-block:: python @@ -256,17 +256,17 @@ The example bellow show how to configure this kind of dependencies: # ... ) -.. tab:: pyproject.toml +.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ - **EXPERIMENTAL** [#experimental]_ + .. code-block:: toml - [project] - # ... - dependencies = [ - "docutils", - "requires <= 0.4", - ] - # ... + [project] + # ... + dependencies = [ + "docutils", + "requires <= 0.4", + ] + # ... Each dependency is represented a string that can optionally contain version requirements (e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier), @@ -297,7 +297,7 @@ can simply use the ``include_package_data`` keyword: [options] include_package_data = True -.. tab:: setup.py +.. tab:: setup.py [#setup.py]_ .. code-block:: python @@ -307,9 +307,7 @@ can simply use the ``include_package_data`` keyword: # ... ) -.. tab:: pyproject.toml - - **EXPERIMENTAL** [#experimental]_ +.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ .. code-block:: toml @@ -361,7 +359,7 @@ associate with your source code. For more information, see :doc:`development_mod setup() You can still keep all the configuration in :doc:`setup.cfg ` - (or :doc:`pyproject.toml `). Uploading your package to PyPI @@ -396,8 +394,20 @@ up-to-date references that can help you when it is time to distribute your work. ---- +.. rubric:: Notes + +.. [#setup.py] + The ``setup.py`` file should be used only when absolutely necessary. + Examples are kept in this document to help people interested in maintaining or + contributing to existing packages that use ``setup.py``. + Note that you can still keep most of configuration declarative in + :doc:`setup.cfg ` or :doc:`pyproject.toml + ` and use ``setup.py`` only for the parts not + supported in those files (e.g. C extensions). .. [#experimental] - Support for specifying package metadata and build configuration options via - ``pyproject.toml`` is experimental and might change (or be completely - removed) in the future. See :doc:`/userguide/pyproject_config`. + While the ``[build-system]`` table should always be specified in the + ``pyproject.toml`` file, adding package metadata and build configuration + options via the ``[project]`` and ``[tool.setuptools]`` tables is still + experimental and might change (or be completely removed) in future releases. + See :doc:`/userguide/pyproject_config`. -- cgit v1.2.1 From 6f5c5575f6f78bebcdf78a67cc0f05ca999ae45a Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 13:30:13 +0000 Subject: Clarify extras in entry-points are deprecated --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 9f3288d6..3e048574 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -407,7 +407,7 @@ up-to-date references that can help you when it is time to distribute your work. .. [#experimental] While the ``[build-system]`` table should always be specified in the - ``pyproject.toml`` file, adding package metadata and build configuration + ``pyproject.toml`` file, support for adding package metadata and build configuration options via the ``[project]`` and ``[tool.setuptools]`` tables is still experimental and might change (or be completely removed) in future releases. See :doc:`/userguide/pyproject_config`. -- cgit v1.2.1 From 5013bfed2e66c9a7f523da28b8950373666acb81 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 13:56:37 +0000 Subject: Apply suggestions from code review Co-authored-by: Steven Silvester --- docs/userguide/quickstart.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 3e048574..3ddb84aa 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -38,7 +38,7 @@ package your project: Then, you will need to specify your package information such as metadata, contents, dependencies, etc. -Setuptools currently support configurations from either ``setup.cfg``, +Setuptools currently supports configurations from either ``setup.cfg``, ``setup.py`` or ``pyproject.toml`` [#experimental]_ files, however, configuring new projects via ``setup.py`` is discouraged [#setup.py]_. @@ -275,7 +275,7 @@ and/or conditional environment markers, e.g. ``os_name = "windows"`` When your project is installed, all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed. -This, of course, is a simplified scenarios. You can also specify groups of +This, of course, is a simplified scenario. You can also specify groups of extra dependencies that are not strictly required by your package to work, but that will provide additional functionalities. For more advanced use, see :doc:`dependency_management`. @@ -376,7 +376,7 @@ To avoid executing arbitrary scripts and boilerplate code, we are transitioning into a full-fledged ``setup.cfg`` to declare your package information instead of running ``setup()``. This inevitably brings challenges due to a different syntax. :doc:`Here ` we provide a quick guide to -understanding how ``setup.cfg`` is parsed by ``setuptool`` to ease the pain of +understanding how ``setup.cfg`` is parsed by ``setuptools`` to ease the pain of transition. .. _packaging-resources: -- cgit v1.2.1 From 0739ae06e29986bf438c6cd38c8a85fe1d93636c Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 17 Mar 2022 17:55:00 +0000 Subject: Small doc improvements --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 3ddb84aa..276aaf73 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -180,7 +180,7 @@ use, go to :ref:`package_discovery`. .. tip:: Starting with version 60.10.0, setuptools' automatic discovery capabilities have been improved to detect popular project layouts (such as the - :ref:`flat-layout` and :ref:`src-layout` layouts) without requiring any + :ref:`flat-layout` and :ref:`src-layout`) without requiring any special configuration. Check out our :ref:`reference docs ` for more information, but please keep in mind that this functionality is still considered **experimental** and might change (or even be removed) in -- cgit v1.2.1 From 5af72b9c332551756681be31d92a165f737ddf12 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 24 Mar 2022 11:16:03 +0000 Subject: Restore tip about editable installs Experiments with pip 21.1 confirm that it can use editable mode even when `setup.py` is missing. --- docs/userguide/quickstart.rst | 23 +++-------------------- 1 file changed, 3 insertions(+), 20 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 276aaf73..79b5d13e 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -338,28 +338,11 @@ Here's how to do it:: This creates a link file in your interpreter site package directory which associate with your source code. For more information, see :doc:`development_mode`. -.. - TODO: Restore the following note once PEP 660 lands in setuptools. - tip: Prior to :ref:`pip v21.1 `, a ``setup.py`` script was - required to be compatible with development mode. With late - versions of pip, any project may be installed in this mode. - .. tip:: - If you are experimenting with :doc:`configuration using - `, or have version of ``pip`` older than :ref:`v21.1 `, - you might need to keep a ``setup.py`` file in file in your repository if - you want to use editable installs (for the time being). - - A simple script will suffice, for example: - - .. code-block:: python - from setuptools import setup - - setup() - - You can still keep all the configuration in :doc:`setup.cfg ` - (or :doc:`pyproject.toml `). + Prior to :ref:`pip v21.1 `, a ``setup.py`` script was + required to be compatible with development mode. With late + versions of pip, any project may be installed in this mode. Uploading your package to PyPI -- cgit v1.2.1 From e18496d4a58c098f0513f24f52da561f4a93e27b Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 24 Mar 2022 11:44:54 +0000 Subject: Fix example of environment maker for dependencies in quickstart --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 79b5d13e..b363b509 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -270,7 +270,7 @@ The example bellow show how to configure this kind of dependencies: Each dependency is represented a string that can optionally contain version requirements (e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier), -and/or conditional environment markers, e.g. ``os_name = "windows"`` +and/or conditional environment markers, e.g. ``sys_platform == "win32"`` (see :doc:`PyPUG:specifications/version-specifiers` for more information). When your project is installed, all of the dependencies not already installed -- cgit v1.2.1 From 4def932c937ffab43f4a9eea5aa57ad0d1a18272 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 24 Mar 2022 11:50:54 +0000 Subject: Improve text about CLI entry-point in quickstart --- docs/userguide/quickstart.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index b363b509..67c4bc81 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -224,8 +224,9 @@ The following configuration examples show how to accomplish this: [project.scripts] cli-name = mypkg:some_func -When this project is installed, a ``cli-name`` executable will be installed and will -invoke the ``some_func`` in the ``mypkg/__init__.py`` file when called by the user. +When this project is installed, a ``cli-name`` executable will be created. +``cli-name`` will invoke the function ``some_func`` in the +``mypkg/__init__.py`` file when called by the user. Note that you can also use the ``entry-points`` mechanism to advertise components between installed packages and implement plugin systems. For detailed usage, go to :doc:`entry_point`. -- cgit v1.2.1 From 9bc0c4a26f82940c213fb07de5e6ebce0b65dd87 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 24 Mar 2022 11:53:37 +0000 Subject: Add module to entry_point example in quickstart --- docs/userguide/quickstart.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 67c4bc81..4a24f337 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -202,7 +202,7 @@ The following configuration examples show how to accomplish this: [options.entry_points] console_scripts = - cli-name = mypkg:some_func + cli-name = mypkg.mymodule:some_func .. tab:: setup.py [#setup.py]_ @@ -212,7 +212,7 @@ The following configuration examples show how to accomplish this: # ... entry_points={ 'console_scripts': [ - 'cli-name = mypkg:some_func', + 'cli-name = mypkg.mymodule:some_func', ] } ) @@ -222,11 +222,11 @@ The following configuration examples show how to accomplish this: .. code-block:: toml [project.scripts] - cli-name = mypkg:some_func + cli-name = mypkg.mymodule:some_func When this project is installed, a ``cli-name`` executable will be created. ``cli-name`` will invoke the function ``some_func`` in the -``mypkg/__init__.py`` file when called by the user. +``mypkg/mymodule.py`` file when called by the user. Note that you can also use the ``entry-points`` mechanism to advertise components between installed packages and implement plugin systems. For detailed usage, go to :doc:`entry_point`. -- cgit v1.2.1 From 8f4c6e6bb3b23359f63ffeff1974da6a437cca96 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 24 Mar 2022 11:55:01 +0000 Subject: Add missing preposition --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 4a24f337..cfc97758 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -269,7 +269,7 @@ The example bellow show how to configure this kind of dependencies: ] # ... -Each dependency is represented a string that can optionally contain version requirements +Each dependency is represented by a string that can optionally contain version requirements (e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier), and/or conditional environment markers, e.g. ``sys_platform == "win32"`` (see :doc:`PyPUG:specifications/version-specifiers` for more information). -- cgit v1.2.1 From aa33fdce0feb19f25831865daaa2b7c353131f06 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 24 Mar 2022 11:57:58 +0000 Subject: Improve note about setup.py --- docs/userguide/quickstart.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index cfc97758..79cfb2ef 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -381,7 +381,8 @@ up-to-date references that can help you when it is time to distribute your work. .. rubric:: Notes .. [#setup.py] - The ``setup.py`` file should be used only when absolutely necessary. + The ``setup.py`` file should be used only when custom scripting during the + build is necessary. Examples are kept in this document to help people interested in maintaining or contributing to existing packages that use ``setup.py``. Note that you can still keep most of configuration declarative in -- cgit v1.2.1 From bce326f48f2d6e5d5727ee59155212dfedab9b68 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 24 Mar 2022 12:23:06 +0000 Subject: Fix wrong version reference in quickstart --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 79cfb2ef..71d44370 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -178,7 +178,7 @@ setup also allows you to adopt a ``src/`` layout. For more details and advanced use, go to :ref:`package_discovery`. .. tip:: - Starting with version 60.10.0, setuptools' automatic discovery capabilities + Starting with version 61.0.0, setuptools' automatic discovery capabilities have been improved to detect popular project layouts (such as the :ref:`flat-layout` and :ref:`src-layout`) without requiring any special configuration. Check out our :ref:`reference docs ` -- cgit v1.2.1 From 7cd56d3c92be8fc45b029eb4c01b581d8dcf84f0 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Thu, 24 Mar 2022 14:09:51 +0000 Subject: Add back notes about editable install and pyproject metadata On further examination, `pip` seems to fail if `setup.py` is missing. --- docs/userguide/quickstart.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 71d44370..3af8aaa8 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -343,7 +343,23 @@ associate with your source code. For more information, see :doc:`development_mod Prior to :ref:`pip v21.1 `, a ``setup.py`` script was required to be compatible with development mode. With late - versions of pip, any project may be installed in this mode. + versions of pip, ``setup.cfg``-only projects may be installed in this mode. + + If you are experimenting with :doc:`configuration using `, + or have version of ``pip`` older than v21.1, you might need to keep a + ``setup.py`` file in file in your repository if you want to use editable + installs (for the time being). + + A simple script will suffice, for example: + + .. code-block:: python + + from setuptools import setup + + setup() + + You can still keep all the configuration in :doc:`setup.cfg ` + (or :doc:`pyproject.toml `). Uploading your package to PyPI -- cgit v1.2.1 From 135e7d2a491dd68d9be6ac06fc74d4fe727e915d Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Thu, 24 Mar 2022 22:15:29 +0100 Subject: Fix `bellow` typo in docs --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 3af8aaa8..5be1078a 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -236,7 +236,7 @@ Dependency management ===================== Packages built with ``setuptools`` can specify dependencies to be automatically installed when the package itself is installed. -The example bellow show how to configure this kind of dependencies: +The example below show how to configure this kind of dependencies: .. tab:: setup.cfg -- cgit v1.2.1 From 07108bb1793b4049d32c28b381d520f28976bb20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20C=C3=A1rdenas?= Date: Sat, 26 Mar 2022 14:33:27 -0500 Subject: Fix typo in quickstart section The function should be between quotes like a string. cli-name = mypkg.mymodule:some_func => cli-name = "mypkg.mymodule:some_func" --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 5be1078a..c72db26b 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -222,7 +222,7 @@ The following configuration examples show how to accomplish this: .. code-block:: toml [project.scripts] - cli-name = mypkg.mymodule:some_func + cli-name = "mypkg.mymodule:some_func" When this project is installed, a ``cli-name`` executable will be created. ``cli-name`` will invoke the function ``some_func`` in the -- cgit v1.2.1 From a4a7527a61cb81d761c4b117d799f483a833faba Mon Sep 17 00:00:00 2001 From: Vladimir Berlev <1783633+tegoo@users.noreply.github.com> Date: Thu, 14 Apr 2022 16:54:55 +0200 Subject: Fix typo in docs --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index c72db26b..2f778521 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -121,7 +121,7 @@ Automatic package discovery For simple projects, it's usually easy enough to manually add packages to the ``packages`` keyword in ``setup.cfg``. However, for very large projects, it can be a big burden to keep the package list updated. -Therefore, ``setuptoops`` provides a convenient way to automatically list all +Therefore, ``setuptools`` provides a convenient way to automatically list all the packages in your project directory: .. tab:: setup.cfg -- cgit v1.2.1