Consequences of optional-dependencies in pyproject.toml

[buhtz]

From the docs I have this piece of a pyproject.toml

[project.optional-dependencies]
pdf = ["ReportLab>=1.2", "RXP"]
rest = ["docutils>=0.3", "pack ==1.1, ==1.3"]

I understand that pyproject.toml is independent from a build system. My mindset is to divide between release dependencies and build/development dependencies. The latter for example do include all extra packages that are needed to make unittests; e.g. pyfakefs.

The example above has two items pdf and rest. Why? Can I use that string when installing the package via pip install in an extra argument? Or can I do something like pip install --include-optional-dependencies?

[abravalheri]

The example is merely illustrative. It shows a hypothetical package that can create documents using either PDF or reStructuredText. These features are considered "optional" (not part of the package's core: maybe the user does not want to generate documents, or maybe the default is generate .txt documents).

To install these additional features with pip, one can use:

pip install 'my_package[pdf]'
# OR
pip install 'my_package[rest]'
# OR
pip install 'my_package[pdf,rest]' # both

Without the [...] part the package is installed without the additional features.

[buhtz]

That is a very good example you described. Thanks a lot.
I checked to the docu but couldn't find that [...] syntax somewhere else. Can you give me a hint please? I would like to know...

• if I could use pip to "ask" the package which options (in that example pdf and rest) are available before installing
• and if there is something like [all] to install all options no matter how many are there.

[abravalheri]

This is part of pip's own documentation: https://pip.pypa.io/en/stable/reference/requirement-specifiers/?highlight=optional#overview.

As far as I know, for the time being pip does not offer any of the features you are asking about. You have to document the available extras for your users and manually create an all group.