sparse documentation about "extras" attribute

[devkral]

It would be helpful to have some documentation/tutorials about the dependencies "extras" attribute and its syntax. I found it only by searching the issues.

Can you please add an example in the documentation of the pyproject.toml (or document the single attributes (option, extras, version)).
Something like
pendelum = {version = "*", extras=["mooncalendar"]}

[chrahunt]

It is mentioned in the README. Including in the dependencies and dev dependencies section would probably be good.

[devkral]

it would be super. Anyway thanks for writing this tool. It is really nice to use.

[esciara]

There is an extras section in the pyproject.toml file page of the docs... Isn't this what you are looking for ? Although it looks like it might be incorrect (see #1339)

[stale]

Is this still relevant? If so, what is blocking it? Is there anything you can do to help move it forward?

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[matthijskooijman]

I also ran into this, extras is quite unclear. It seems there might be two different kinds of extras, also specified by https://python-poetry.org/docs/pyproject/#extras:

1. optional dependencies, which enhance a package, but are not required; and
2. clusters of optional dependencies.

Extras as in 1. can be specified when adding dependencies, as documented here, e.g.

poetry add requests[security,socks]

Extras as in 2. can maybe be manually specified in the pyproject.toml project, as suggested here, but you would expect that you could also pass the extra "cluster" as an option to poetry add when adding a dependency, also to update the lock file. Discussion in #1145 suggests that there is no CLI way for this, so you should manually add extras to pyproject.toml and then run poetry lock to add them to poetry.lock?

There's also some indications that 2. might not be currently working? e.g #2073 and #1145

I also wonder if these two usecases might not actually be two faces of the same thing? E.g. 2. might be considered "extras" of the current package, such that poetry install -E foo would be somewhat equivalent to pip install .[foo]? This is what the reporter of #1145 seems to imply as well.

For clarity, it might be worthwile to use different terminology for 1. and 2. Since setuptools already uses "extras" for 1., perhaps 2. should be renamed to something else? Especially since --extras for poetry add might already refer to 1. (suggested at #1145 (comment), though I could not find anything docs for this).

Also note #1463 which fixes an extras-related link in the docs.

[matthijskooijman]

For clarity, it might be worthwile to use different terminology for 1. and 2.

This might also be sidestepped by replacing 2. with "dependency groups", as suggested in #1644.

[aalok-sathe]

Whereas poetry documentation mentions the support for "optional dependency clusters", there is no example of it. I am inferring that it is specified as a extra_name = [list, of, packages, that, are, clustered], but the documentation doesn't say so.

It is also unclear if the extras should be specified either in the [tool.poetry.dependencies] section as ... optional = true, or in the [tool.poetry.extras] section, or both.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.