Skip to content

Commit

Permalink
docs: Reorder example tabs
Browse files Browse the repository at this point in the history
  • Loading branch information
@abravalheri
abravalheri committed Jun 16, 2022
1 parent 9c7163b commit 9d48703
Show file tree
Hide file tree
Showing 3 changed files with 150 additions and 150 deletions.
115 changes: 57 additions & 58 deletions docs/userguide/dependency_management.rst
View file
Expand Up @@ -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
Expand All @@ -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),
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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`.

Expand All @@ -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
Expand All @@ -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::
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
68 changes: 34 additions & 34 deletions docs/userguide/entry_point.rst
View file
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -150,7 +157,7 @@ Then, we can add a GUI script entry point:
.. tab:: setup.py

.. code-block:: python
from setuptools import setup
setup(
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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``.
Expand Down Expand Up @@ -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
Expand All @@ -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:

Expand Down

0 comments on commit 9d48703

Please sign in to comment.