extras_require¶

Display a warning at the top of module documentation that it has additional requirements.

Docs
Tests
PyPI
Anaconda
Activity
QA
Other

Overview¶

This extension assumes you have a repository laid out like this:

.
├── chemistry_tools
│   ├── __init__.py
│   ├── formulae
│   │   ├── __init__.py
│   │   ├── compound.py
│   │   ├── formula.py
│   │   ├── parser.py
│   │   └── requirements.txt
│   ├── constants.py
│   └── utils.py
├── doc-source
│   ├── api
│   │   ├── chemistry_tools.rst
│   │   ├── elements.rst
│   │   ├── formulae.rst
│   │   └── pubchem.rst
│   ├── conf.py
│   ├── index.rst
│   └── requirements.txt
├── LICENSE
├── README.rst
├── requirements.txt
├── setup.py
└── tox.ini

The file ./chemistry_tools/formulae/requirements.txt contains the additional requirements to run the formulae subpackage. These would be defined in setup.py like this:

setup(
        extras_require={
                "formulae": [
                        "mathematical>=0.1.7",
                        "pandas>=1.0.1",
                        "pyparsing>=2.2.0",
                        "tabulate>=0.8.3",
                        "cawdrey>=0.1.2",
                        "quantities>=0.12.4",
                        ],
                }
        )

A message can be displayed in the documentation to indicate that the subpackage has these additional requirements that must be installed.

For instance, this:

.. extras-require:: formulae
    :file: formulae/requirements.txt

will produce this:

Attention

This module has the following additional requirements:

cawdrey>=0.1.2
mathematical>=0.1.7
pandas>=1.0.1
pyparsing>=2.2.0
quantities>=0.12.4
tabulate>=0.8.3

These can be installed as follows:

python -m pip install chemistry_tools[formulae]

The path given in :file: is relative to the package_root variable given in conf.py, which in turn is relative to the parent directory of the sphinx documentation. For example, this line:.

package_root = "chemistry_tools"

points to ./chemistry_tools, and therefore :file: formulae/requirements.txt points to ./chemistry_tools/formulae/requirements.txt.

Requirements can also be specified in pyproject.toml (using the option :pyproject:), setup.cfg (using the option :setup.cfg::), or by typing in the requirements manually, one per line.

The :scope: option can be used to specify a different scope for additional requirements, such as package, module, class or function. Any string value can be supplied here.

Installation¶

python3 -m pip install extras_require --user

First add the required channels

conda config --add channels https://conda.anaconda.org/domdfcoding
conda config --add channels https://conda.anaconda.org/conda-forge

Then install

conda install extras_require

python3 -m pip install git+https://github.com/sphinx-toolbox/extras_require@master --user

Enable extras_require by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx-prompt',
    'sphinxcontrib.extras_require',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Configuration¶

package_root¶

Type: str

Required: True

For example,

package_root = "chemistry_tools"

points to ./chemistry_tools.

pypi_name¶: Type: str

Required: False

This is the name provided to pip install. Defaults to the name of the project in the Sphinx configuration.

New in version 0.4.0.

Directive¶

.. extras-require::¶

The requirements can be specified in several ways:

:file: requirements_file (string)¶

Shows the requirements from the given file. The file must contain a list of PEP 508 requirements, one per line.

The path is relative to the package_root variable given in conf.py, which in turn is relative to the parent directory of the sphinx documentation.

:__pkginfo__: (flag)¶

Flag to indicate the requirements should be obtained from __pkginfo__.py.

This looks in the parent directory of the sphinx documentation for a file named __pkginfo__.py. The requirements are imported as the variable extras_require, which must be a dictionary mapping extras to a list of requirements.

Example:

extras_require = {
        "extra_b": [
                "flask>=1.1.2",
                "click<7.1.2",
                "sphinx==3.0.3",
                ],
        }

The requirements can be generated programmatically in the __pkginfo__.py file during the import process.

:setup.cfg: (flag)¶

Flag to indicate the requirements should be obtained from setup.cfg.

This looks in the parent directory of the sphinx documentation for a file named setup.cfg. This file must be readable by Python’s configparser module, and contain the section [options.extras_require].

Example:

[options.extras_require]
extra_c = faker; pytest; tox

See the setuptools documentation for more information on setup.cfg.

:flit: (flag)¶

Flag to indicate the requirements should be obtained from the [tool.flit.metadata.requires-extra] section of pyproject.toml.

Example:

[tool.flit.metadata.requires-extra]
test = [
    "pytest>=2.7.3",
    "pytest-cov",
]
doc = ["sphinx"]

See the flit documentation for more details.

:pyproject: (flag)¶

Flag to indicate the requirements should be obtained from the [project.optional-dependencies] section of pyproject.toml.

Example:

[project.optional-dependencies]
test = [
  "pytest<5.0.0",
  "pytest-cov[all]"
]

See the PEP 621 section on dependencies/optional-dependencies for more details.

Only one of the above options can be used in each directive.

Manual requirements:

If none of the above options are provided the PEP 508 requirements can instead be provided as the content of the directive. Each requirement must be on its own line, and there must be a blank line between the directive and the list of requirements. e.g.

.. extras-require:: dates

    pytz >=2019.1

Attention

This module has the following additional requirement:

pytz>=2019.1

This can be installed as follows:

python -m pip install chemistry_tools[dates]

Other options:

:scope: (string)¶

Specifies a different scope for additional requirements, such as package, module, class or function.

Any string value can be supplied here.

Example

.. extras-require:: foo
    :scope: class

    bar
    baz

Attention

This class has the following additional requirements:

bar
baz

These can be installed as follows:

python -m pip install chemistry_tools[foo]

`sphinxcontrib.extras_require`¶

A Sphinx directive to specify that a module has extra requirements, and show how to install them.

Functions:

setup(app)

Setup sphinxcontrib.extras_require.

setup(app)[source]¶

Setup sphinxcontrib.extras_require.

Parameters: app (Sphinx) – The Sphinx app.
Return type: Dict[str, Any]

`sphinxcontrib.extras_require.directive`¶

The extras-require directive.

Classes:

ExtrasRequireDirective(name, arguments, …)

Directive to show a notice to users that a module, class or function has additional requirements.

Functions:

`get_requirements`(env, extra, options, content)	Get the requirements for the extras_require node.
`make_node_content`(requirements, …[, scope])	Create the content of an extras_require node.
`validate_requirements`(requirements_list)	Validate a list of PEP 508 requirements and format them consistently.

class ExtrasRequireDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: SphinxDirective

Directive to show a notice to users that a module, class or function has additional requirements.

Attributes:

required_arguments

One argument is required, the name of the extra (e.g.

Methods:

run()

Create the extras_require node.

required_arguments = 1¶

Type: int

One argument is required, the name of the extra (e.g. “testing”, “docs”)

run()[source]¶

Create the extras_require node.

Return type: List[Node]

get_requirements(env, extra, options, content)[source]¶

Get the requirements for the extras_require node.

Parameters

env (BuildEnvironment)
extra (str)
options (Dict[str, Any])
content (Union[Iterable, ViewList])

Return type

List[str]

make_node_content(requirements, package_name, extra, scope='module')[source]¶

Create the content of an extras_require node.

Parameters

requirements (List[str]) – List of additional PEP 508 requirements.
package_name (str) – The name of the module/package on PyPI.
extra (str) – The name of the “extra”.
scope (str) – The scope of the additional requirements, e.g. "module", "package". Default 'module'.

Return type

str

Returns

The content of an extras_require node.

validate_requirements(requirements_list)[source]¶

Validate a list of PEP 508 requirements and format them consistently.

Parameters: requirements_list (List[str]) – List of PEP 508 requirements.
Return type: List[str]
Returns: List of PEP 508 requirements with consistent formatting.

`sphinxcontrib.extras_require.sources`¶

Supported sources for the requirements are implemented here.

Data:

sources

Instance of Sources.

Classes:

Sources([iterable])

Class to store functions that provide requirements sources.

Functions:

`requirements_from_file`(package_root, …)	Load requirements from the specified file.
`requirements_from_flit`(package_root, …)	Load requirements from the `[tool.flit.metadata.requires-extra]` section of a `pyproject.toml` file in the root of the repository.
`requirements_from_pkginfo`(package_root, …)	Load requirements from a `__pkginfo__.py` file in the root of the repository.
`requirements_from_pyproject`(package_root, …)	Load requirements from the `[project.optional-dependencies]` section of a `pyproject.toml` file in the root of the repository.
`requirements_from_setup_cfg`(package_root, …)	Load requirements from a `setup.cfg` file in the root of the repository.

class Sources(iterable=(), /)[source]¶

Bases: List[Tuple[str, Callable, Callable]]

Class to store functions that provide requirements sources.

The syntax of each entry is:

(option_name, getter_function, validator_function)

a string to use in the directive to specify the source to use,
the function that returns the list of additional requirements,
a function to validate the option value provided by the user.

Methods:

register(option_name[, validator])

Decorator to register a function.

register(option_name, validator=<function 'unchanged'>)[source]¶

Decorator to register a function.

The function must have the following signature:

def function(
    package_root: pathlib.Path,
    options: Dict,
    env: sphinx.environment.BuildEnvironment,
    extra: str,
    ) -> List[str]: ...

Parameters

option_name (str) – A string to use in the directive to specify the source to use.
validator (Callable) – A function to validate the option value provided by the user. Default docutils.parsers.rst.directives.unchanged().

Return type

Callable

Returns

The registered function.

Raises

SyntaxError if the decorated function does not take the correct arguments.

requirements_from_file(package_root, options, env, extra)[source]¶

Load requirements from the specified file.

Parameters

package_root (Path) – The path to the package root
options (Dict)
env (BuildEnvironment)
extra (str) – The name of the “extra” that the requirements are for

Return type

List[str]

Returns

List of requirements

requirements_from_flit(package_root, options, env, extra)[source]¶

Load requirements from the [tool.flit.metadata.requires-extra] section of a pyproject.toml file in the root of the repository.

Parameters

package_root (Path) – The path to the package root.
options (Dict)
env (BuildEnvironment)
extra (str) – The name of the “extra” that the requirements are for.

Return type

List[str]

Returns

List of requirements.

requirements_from_pkginfo(package_root, options, env, extra)[source]¶

Load requirements from a __pkginfo__.py file in the root of the repository.

Parameters

package_root (Path) – The path to the package root
options (Dict)
env (BuildEnvironment)
extra (str) – The name of the “extra” that the requirements are for

Return type

List[str]

Returns

List of requirements

requirements_from_pyproject(package_root, options, env, extra)[source]¶

Load requirements from the [project.optional-dependencies] section of a pyproject.toml file in the root of the repository.

Downloading source code¶

The extras_require source code is available on GitHub, and can be accessed from the following URL: https://github.com/sphinx-toolbox/extras_require

If you have git installed, you can clone the repository with the following command:

git clone https://github.com/sphinx-toolbox/extras_require

Cloning into 'extras_require'...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 173 (delta 16), reused 17 (delta 6), pack-reused 126
Receiving objects: 100% (173/173), 126.56 KiB | 678.00 KiB/s, done.
Resolving deltas: 100% (66/66), done.

Alternatively, the code can be downloaded in a ‘zip’ file by clicking:

Clone or download –> Download Zip

Downloading a ‘zip’ file of the source code¶

Building from source¶

The recommended way to build extras_require is to use tox:

tox -e build

The source and wheel distributions will be in the directory dist.

If you wish, you may also use pep517.build or another PEP 517-compatible build tool.

License¶

extras_require is licensed under the BSD 3-Clause “New” or “Revised” License

A permissive license similar to the BSD 2-Clause License, but with a 3rd clause that prohibits others from using the name of the copyright holder or its contributors to promote derived products without written consent.

Permissions	Conditions	Limitations
Commercial use Modification Distribution Private use	License and copyright notice	Liability Warranty

See more information on choosealicense.com ➩

Copyright (c) 2020 by Dominic Davis-Foster <dominic@davis-foster.co.uk>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

View the Function Index or browse the Source Code.

Browse the GitHub Repository

extras_require¶

Overview¶

Installation¶

Configuration¶

Directive¶

sphinxcontrib.extras_require¶

sphinxcontrib.extras_require.directive¶

sphinxcontrib.extras_require.sources¶

Downloading source code¶

Building from source¶

License¶

`sphinxcontrib.extras_require`¶

`sphinxcontrib.extras_require.directive`¶

`sphinxcontrib.extras_require.sources`¶