Skip to content

Add mechanism for comparison of setup.py and its equivalent setup.cfg #2584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 5, 2021
Merged

Add mechanism for comparison of setup.py and its equivalent setup.cfg #2584

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
666f444
Add sphinx-inline-tabs extension
amy-lei Mar 1, 2021
474f833
Replace adjacent code blocks with tabbed containers
amy-lei Mar 1, 2021
c88c4e8
Add changelog
amy-lei Mar 1, 2021
265fb0e
Extend extensions later in the file. Fixes flake8 failure and isolate…
jaraco Mar 5, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/2584.doc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Added ``sphinx-inline-tabs`` extension to allow for comparison of ``setup.py`` and its equivalent ``setup.cfg`` -- by :user:`amy-lei`
3 changes: 3 additions & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,3 +93,6 @@
html_theme = 'alabaster'
templates_path = ['_templates']
html_sidebars = {'index': ['tidelift-sidebar.html']}

# Add support for inline tabs
extensions += ['sphinx_inline_tabs']
1 change: 1 addition & 0 deletions docs/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,6 @@ sphinx
jaraco.packaging>=6.1
rst.linker>=1.9
pygments-github-lexers==0.0.5
sphinx-inline-tabs

setuptools>=34
228 changes: 128 additions & 100 deletions docs/userguide/dependency_management.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,23 +49,27 @@ be able to run. ``setuptools`` support automatically download and install
these dependencies when the package is installed. Although there is more
finess to it, let's start with a simple example.

.. code-block:: ini
.. tab:: setup.cfg

[options]
#...
install_requires =
docutils
BazSpam ==1.1
.. code-block:: ini

[options]
#...
install_requires =
docutils
BazSpam ==1.1

.. tab:: setup.py

.. code-block:: python
.. code-block:: python

setup(
#...,
install_requires = [
'docutils',
'BazSpam ==1.1'
]
)
setup(
#...,
install_requires = [
'docutils',
'BazSpam ==1.1'
]
)


When your project is installed (e.g. using pip), all of the dependencies not
Expand All @@ -82,41 +86,49 @@ 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

.. code-block:: ini

[options]
#...
install_requires =
enum34;python_version<'3.4'
.. tab:: setup.cfg

.. code-block:: python
.. code-block:: ini

setup(
[options]
#...
install_requires=[
"enum34;python_version<'3.4'",]
)
install_requires =
enum34;python_version<'3.4'

.. tab:: setup.py

.. code-block:: python

setup(
#...
install_requires=[
"enum34;python_version<'3.4'",]
)

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:

.. code-block:: ini

[options]
#...
install_requires =
enum34;python_version<'3.4'
pywin32 >= 1.0;platform_system=='Windows'
.. tab:: setup.cfg

.. code-block:: python
.. code-block:: ini

setup(
[options]
#...
install_requires=[
"enum34;python_version<'3.4'",
"pywin32 >= 1.0;platform_system=='Windows'"
]
)
install_requires =
enum34;python_version<'3.4'
pywin32 >= 1.0;platform_system=='Windows'

.. tab:: setup.py

.. code-block:: python

setup(
#...
install_requires=[
"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 <https://www.python.org/dev/peps/pep-0508/>`_.
Expand Down Expand Up @@ -181,20 +193,24 @@ The ``dependency_links`` option takes the form of a list of URL strings. For
example, this will cause a search of the specified page for eggs or source
distributions, if the package's dependencies aren't already installed:

.. code-block:: ini

[options]
#...
dependency_links = http://peak.telecommunity.com/snapshots/
.. tab:: setup.cfg

.. code-block:: python
.. code-block:: ini

setup(
[options]
#...
dependency_links=[
"http://peak.telecommunity.com/snapshots/"
],
)
dependency_links = http://peak.telecommunity.com/snapshots/

.. tab:: setup.py

.. code-block:: python

setup(
#...
dependency_links=[
"http://peak.telecommunity.com/snapshots/"
],
)


Optional dependencies
Expand All @@ -211,56 +227,64 @@ ancillary functions such as "tests" and "docs".
For example, Package-A offers optional PDF support and requires two other
dependencies for it to work:

.. code-block:: ini
.. tab:: setup.cfg

[metadata]
name = Package-A
.. code-block:: ini

[options.extras_require]
PDF = ReportLab>=1.2; RXP
[metadata]
name = Package-A

[options.extras_require]
PDF = ReportLab>=1.2; RXP

.. code-block:: python

setup(
name="Project-A",
#...
extras_require={
"PDF": ["ReportLab>=1.2", "RXP"],
}
)
.. tab:: setup.py

.. code-block:: python

setup(
name="Project-A",
#...
extras_require={
"PDF": ["ReportLab>=1.2", "RXP"],
}
)

The name ``PDF`` is an arbitary identifier of such a list of dependencies, to
which other components can refer and have them installed. There are two common
use cases.

First is the console_scripts entry point:

.. code-block:: ini
.. tab:: setup.cfg

[metadata]
name = Project A
#...
.. code-block:: ini

[options]
#...
entry_points=
[console_scripts]
rst2pdf = project_a.tools.pdfgen [PDF]
rst2html = project_a.tools.htmlgen

.. code-block:: python

setup(
name = "Project-A"
#...,
entry_points={
"console_scripts": [
"rst2pdf = project_a.tools.pdfgen [PDF]",
"rst2html = project_a.tools.htmlgen",
],
}
)
[metadata]
name = Project A
#...

[options]
#...
entry_points=
[console_scripts]
rst2pdf = project_a.tools.pdfgen [PDF]
rst2html = project_a.tools.htmlgen

.. tab:: setup.py

.. code-block:: python

setup(
name = "Project-A"
#...,
entry_points={
"console_scripts": [
"rst2pdf = project_a.tools.pdfgen [PDF]",
"rst2html = project_a.tools.htmlgen",
],
}
)

This syntax indicates that the entry point (in this case a console script)
is only valid when the PDF extra is installed. It is up to the installer
Expand All @@ -273,24 +297,28 @@ The second use case is that other package can use this "extra" for their
own dependencies. For example, if "Project-B" needs "project A" with PDF support
installed, it might declare the dependency like this:

.. code-block:: ini
.. tab:: setup.cfg

[metadata]
name = Project-B
#...
.. code-block:: ini

[options]
#...
install_requires =
Project-A[PDF]
[metadata]
name = Project-B
#...

[options]
#...
install_requires =
Project-A[PDF]

.. tab:: setup.py

.. code-block:: python
.. code-block:: python

setup(
name="Project-B",
install_requires=["Project-A[PDF]"],
...
)
setup(
name="Project-B",
install_requires=["Project-A[PDF]"],
...
)

This will cause ReportLab to be installed along with project A, if project B is
installed -- even if project A was already installed. In this way, a project
Expand Down
Loading