CLI argument to `poetry add` to add the dependency to `[tool.poetry.extras]`

[AliSot2000]

Issue Kind

Brand new capability

Description

• Add an info to the poetry add help that states that dependency groups aren't equivalent to groups of extras and have no parallel in pip.

• Add an argument to poetry add which requires --optional let's say for the sake of argument -i --include-in. Providing that argument, adds the dependency into the list of dependencies of an extra:

So doing something like poetry add --optional -i cuda cupy would now additionally:

1. Add the section [tool.poetry.extras] if it doesn't exist.
2. Add the extra cuda if it doesn't exits.
3. Add cupy into the dependency list of cuda if it doesn't exist. So you end up with:

[tool.poetry.extras]
cuda = ["cupy"]

• Maybe add a command to edit, remove, add, list the extras of the project you're working on.

Impact

How it should affect other users

• The improved documentation for the dependency groups as well as potentially highlighting the word "dependency" in the poetry add help should reduce frustration for new users of poetry which also primarily look at the help of commands and not the docs online. (Also poetry doesn't have a man page you could consult).
• Adding the option to add a dependency to the pip extras of the package you're currently working on gives you the changes in the pyproject.toml that you could figure out afterwards how to change the config manually. (So once again, no requirement to read the docs online)
• Adding commands to edit the [tool.poetry.extras] would seem to be inline with the purpose of poetry which is, as far as I understand: Managing / Resolving Dependencies and Facilitating easier Packaging for Python Projects.

Lastly, it's my conviction that cli tools should contain everything needed to operate them in their help section. And not require the user to leave the shell and look up the docs in a browser.

---

How it affected me

I've sadly spent an entire day trying to get my package to have an optional dependency. It also may be very well possible that I'm stupid and just didn't read the docs and only referred to the help of poetry in the cli.

It firstly took me some time to figure out that if you poetry add -E some-extra package will add some-package[some-extra] to your install dependencies. That's my bad for not reading the documentation closely enough. Tho maybe the formulation of the help could be improved or the word "dependency" could be highlighted?

Another thing that took me for a ride were the dependency groups. I thought they were equivalent to the extras you can define for your package.

Since, when not using poetry, you have something like:

[project.optional-dependencies]
gui = ["PyQt5"]
cli = [
  "rich",
  "click",
]

I accidentally equated the poetry dependency groups to the project.optional-dependencies. I was mostly looking at the output of poetry [build, add, install] --help for information. I think it might be useful to put in the note that dependency groups are something unique to poetry and they have no parallel with pip / pypi.

(It would be also a cool idea to have dependency groups be marked as an extra for pip but I think that diverges too much from the established ux that poetry has)

After figuring out that dependency groups and the -E flag for poetry add weren't the right way to go, I finally left my terminal and looked at the docs to finally learn that you can only add extras to your package the following way:

1. Add the dependency as optional to the main group so poetry add --optional some-package
2. Modify the pyproject.toml to contain the following:

[tool.poetry.extras]
extra_name = ["list-of-extra-deps-in-main-section"]

I had the preconceived notion that everything regarding configs with poetry is only handled through the shell. I was not expecting to manually edit config files. Now this can be argued as an me issue and being an new poetry user.

Workarounds

1. Add the dependency as optional to the main group so poetry add --optional some-package
2. Modify the pyproject.toml to contain the following:

[tool.poetry.extras]
extra_name = ["list-of-extra-deps-in-main-section"]

The somewhat confusing part is having to edit the pyproject.toml yourself.

[dimbleby]

The requested CLI argument is redundant in the PEP621 world of the main branch, and there already is a warning for those who do not make the switch

the best way to improve either docs or CLI help text is to submit a merge request

[CesarArroyo09]

@dimbleby Maybe the feature in the way suggested by @AliSot2000 is redundant, but it seems necessary. I don't think anybody would expect to manually change pyproject.toml when using poetry.

The workaround only works for poetry < 2.0.0. And for poetry >= 2.0.0 the documentation only explains that tool.poetry.extras is deprecated and project.optional-dependencies should be used instead but it does not specify how to do this using poetry.

It is not clear that the management of this section is within the scope of poetry. I would gladly provide a merge request for the documentation if I knew if what we want to do is even possible. This is: managing optional and grouped optional dependencies with poetry.

[dimbleby]

this issue is already redundant now that poetry 2.0 is released

poetry add --help tells you how to use the --optional option

if that's missing from the docs then I expect a merge request would be welcome