diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst index f92e22c49f..56fbd0bdd3 100644 --- a/docs/userguide/dependency_management.rst +++ b/docs/userguide/dependency_management.rst @@ -53,6 +53,18 @@ be able to run. ``setuptools`` supports automatically downloading and installing these dependencies when the package is installed. Although there is more finesse to it, let's start with a simple example. +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + # ... + dependencies = [ + "docutils", + "BazSpam == 1.1", + ] + # ... + .. tab:: setup.cfg .. code-block:: ini @@ -75,18 +87,6 @@ finesse to it, let's start with a simple example. ], ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project] - # ... - dependencies = [ - "docutils", - "BazSpam == 1.1", - ] - # ... - When your project is installed (e.g., using :pypi:`pip`), all of the dependencies not already installed will be located (via `PyPI`_), downloaded, built (if necessary), @@ -104,6 +104,17 @@ specific dependencies. For example, the ``enum`` package was added in Python 3.4, therefore, package that depends on it can elect to install it only when the Python version is older than 3.4. To accomplish this +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + # ... + dependencies = [ + "enum34; python_version<'3.4'", + ] + # ... + .. tab:: setup.cfg .. code-block:: ini @@ -124,6 +135,9 @@ the Python version is older than 3.4. To accomplish this ], ) +Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0 +and only install it if the user is using a Windows operating system: + .. tab:: pyproject.toml .. code-block:: toml @@ -132,12 +146,10 @@ the Python version is older than 3.4. To accomplish this # ... dependencies = [ "enum34; python_version<'3.4'", + "pywin32 >= 1.0; platform_system=='Windows'", ] # ... -Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0 -and only install it if the user is using a Windows operating system: - .. tab:: setup.cfg .. code-block:: ini @@ -160,18 +172,6 @@ and only install it if the user is using a Windows operating system: ], ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project] - # ... - dependencies = [ - "enum34; python_version<'3.4'", - "pywin32 >= 1.0; platform_system=='Windows'", - ] - # ... - The environmental markers that may be used for testing platform types are detailed in :pep:`508`. @@ -190,6 +190,16 @@ set of extra functionalities. For example, let's consider a ``Package-A`` that offers optional PDF support and requires two other dependencies for it to work: +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + name = "Package-A" + # ... + [project.optional-dependencies] + PDF = ["ReportLab>=1.2", "RXP"] + .. tab:: setup.cfg .. code-block:: ini @@ -215,16 +225,6 @@ optional PDF support and requires two other dependencies for it to work: }, ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project] - name = "Package-A" - # ... - [project.optional-dependencies] - PDF = ["ReportLab>=1.2", "RXP"] - .. sidebar:: .. tip:: @@ -238,6 +238,17 @@ A use case for this approach is that other package can use this "extra" for thei own dependencies. For example, if ``Package-B`` needs ``Package-B`` with PDF support installed, it might declare the dependency like this: +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + name = "Package-B" + # ... + dependencies = [ + "Package-A[PDF]" + ] + .. tab:: setup.cfg .. code-block:: ini @@ -261,17 +272,6 @@ installed, it might declare the dependency like this: ..., ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project] - name = "Package-B" - # ... - dependencies = [ - "Package-A[PDF]" - ] - This will cause ``ReportLab`` to be installed along with ``Package-A``, if ``Package-B`` is installed -- even if ``Package-A`` was already installed. In this way, a project can encapsulate groups of optional "downstream dependencies" under a feature @@ -338,6 +338,15 @@ Python requirement In some cases, you might need to specify the minimum required python version. This can be configured as shown in the example below. +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + name = "Package-B" + requires-python = ">=3.6" + # ... + .. tab:: setup.cfg .. code-block:: ini @@ -361,14 +370,4 @@ This can be configured as shown in the example below. ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project] - name = "Package-B" - requires-python = ">=3.6" - # ... - - .. _PyPI: https://pypi.org diff --git a/docs/userguide/entry_point.rst b/docs/userguide/entry_point.rst index bad083f490..eff20cf090 100644 --- a/docs/userguide/entry_point.rst +++ b/docs/userguide/entry_point.rst @@ -29,7 +29,7 @@ First consider an example without entry points. Imagine a package defined thus:: project_root_directory - ├── setup.py # and/or setup.cfg, pyproject.toml + ├── pyproject.toml # and/or setup.cfg, setup.py └── src └── timmins ├── __init__.py @@ -69,6 +69,13 @@ In the above example, to create a command ``hello-world`` that invokes ``timmins.hello_world``, add a console script entry point to your configuration: +.. tab:: pyproject.toml + + .. code-block:: toml + + [project.scripts] + hello-world = "timmins:hello_world" + .. tab:: setup.cfg .. code-block:: ini @@ -92,13 +99,6 @@ configuration: } ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project.scripts] - hello-world = "timmins:hello_world" - After installing the package, a user may invoke that function by simply calling ``hello-world`` on the command line: @@ -139,6 +139,13 @@ with an ``__init__.py`` file containing the following: Then, we can add a GUI script entry point: +.. tab:: pyproject.toml + + .. code-block:: toml + + [project.gui-scripts] + hello-world = "timmins:hello_world" + .. tab:: setup.cfg .. code-block:: ini @@ -150,7 +157,7 @@ Then, we can add a GUI script entry point: .. tab:: setup.py .. code-block:: python - + from setuptools import setup setup( @@ -162,13 +169,6 @@ Then, we can add a GUI script entry point: } ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project.gui-scripts] - hello-world = "timmins:hello_world" - .. note:: To be able to import ``PySimpleGUI``, you need to add ``pysimplegui`` to your package dependencies. See :doc:`/userguide/dependency_management` for more information. @@ -236,7 +236,7 @@ corresponding to plugins. Say we have a package ``timmins`` with the following directory structure:: timmins - ├── setup.py # and/or setup.cfg, pyproject.toml + ├── pyproject.toml # and/or setup.cfg, setup.py └── src └── timmins └── __init__.py @@ -328,7 +328,7 @@ which implements the entry point ``timmins.display``. Let us name this plugin ``timmins-plugin-fancy``, and set it up with the following directory structure:: timmins-plugin-fancy - ├── setup.py # and/or setup.cfg, pyproject.toml + ├── pyproject.toml # and/or setup.cfg, setup.py └── src └── timmins_plugin_fancy └── __init__.py @@ -345,6 +345,14 @@ This is the ``display()``-like function that we are looking to supply to the ``timmins`` package. We can do that by adding the following in the configuration of ``timmins-plugin-fancy``: +.. tab:: pyproject.toml + + .. code-block:: toml + + # Note the quotes around timmins.display in order to escape the dot . + [project.entry-points."timmins.display"] + excl = "timmins_plugin_fancy:excl_display" + .. tab:: setup.cfg .. code-block:: ini @@ -368,14 +376,6 @@ of ``timmins-plugin-fancy``: } ) -.. tab:: pyproject.toml - - .. code-block:: toml - - # Note the quotes around timmins.display in order to escape the dot . - [project.entry-points."timmins.display"] - excl = "timmins_plugin_fancy:excl_display" - Basically, this configuration states that we are a supplying an entry point under the group ``timmins.display``. The entry point is named ``excl`` and it refers to the function ``excl_display`` defined by the package ``timmins-plugin-fancy``. @@ -416,6 +416,14 @@ functions, as follows: The configuration of ``timmins-plugin-fancy`` would then change to: +.. tab:: pyproject.toml + + .. code-block:: toml + + [project.entry-points."timmins.display"] + excl = "timmins_plugin_fancy:excl_display" + lined = "timmins_plugin_fancy:lined_display" + .. tab:: setup.cfg .. code-block:: ini @@ -441,14 +449,6 @@ The configuration of ``timmins-plugin-fancy`` would then change to: } ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project.entry-points."timmins.display"] - excl = "timmins_plugin_fancy:excl_display" - lined = "timmins_plugin_fancy:lined_display" - On the ``timmins`` side, we can also use a different strategy of loading entry points. For example, we can search for a specific display style: diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 4e3d73280e..5ee1ce7b14 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -66,6 +66,20 @@ The following example demonstrates a minimum configuration (which assumes the project depends on :pypi:`requests` and :pypi:`importlib-metadata` to be able to run): +.. tab:: pyproject.toml + + .. 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. + .. tab:: setup.cfg .. code-block:: ini @@ -98,20 +112,6 @@ The following example demonstrates a minimum configuration See :doc:`/references/keywords` for more information. -.. tab:: pyproject.toml - - .. 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. - Finally, you will need to organize your Python code to make it ready for distributing into something that looks like the following (optional files marked with ``#``):: @@ -166,6 +166,21 @@ Therefore, ``setuptools`` provides a convenient way to customize which packages should be distributed and in which directory they should be found, as shown in the example below: +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. 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 + .. tab:: setup.cfg .. code-block:: ini @@ -196,21 +211,6 @@ found, as shown in the example below: # ... ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ - - .. 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 @@ -239,6 +239,14 @@ to type ``python -m pip install``. The following configuration examples show how to accomplish this: + +.. tab:: pyproject.toml + + .. code-block:: toml + + [project.scripts] + cli-name = "mypkg.mymodule:some_func" + .. tab:: setup.cfg .. code-block:: ini @@ -260,13 +268,6 @@ The following configuration examples show how to accomplish this: } ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project.scripts] - 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/mymodule.py`` file when called by the user. @@ -281,6 +282,18 @@ Packages built with ``setuptools`` can specify dependencies to be automatically installed when the package itself is installed. The example below show how to configure this kind of dependencies: +.. tab:: pyproject.toml + + .. code-block:: toml + + [project] + # ... + dependencies = [ + "docutils", + "requires <= 0.4", + ] + # ... + .. tab:: setup.cfg .. code-block:: ini @@ -300,18 +313,6 @@ The example below show how to configure this kind of dependencies: # ... ) -.. tab:: pyproject.toml - - .. code-block:: toml - - [project] - # ... - dependencies = [ - "docutils", - "requires <= 0.4", - ] - # ... - 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"`` @@ -332,6 +333,16 @@ Including Data Files 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: +.. tab:: pyproject.toml (**BETA**) [#beta]_ + + .. code-block:: toml + + [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` + .. tab:: setup.cfg .. code-block:: ini @@ -349,16 +360,6 @@ For the simplest use, you can simply use the ``include_package_data`` keyword: # ... ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ - - .. code-block:: toml - - [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 |MANIFEST.in|_ file or automatically added by a :ref:`Revision Control System plugin