Project plugins and forcing a minimum poetry version

[radoering]

Pull Request Check List

Related-to: #5740 (refines the plugin part, omits the tools part)
Resolves: #5729
Resolves: #3316

• Added tests for changed code.
• Updated documentation for changed code.

Introduces tool.poetry.requires-poetry and tool.poetry.requires-plugins.

Example:

[tool.poetry]
requires-poetry = ">=2.0"

[tool.poetry.requires-plugins]
poetry-plugin-bundle = ">=1.3"
poetry-plugin-export = ">=1.7.0"

tool.poetry.requires-poetry enforces a Poetry version and raises an error if the used version is not allowed, e.g.:

This project requires Poetry <2.0, but you are using Poetry 2.0

(Of course, this only works for future Poetry versions because older versions do not know this setting.)

In tool.poetry.requires-plugins you can define plugins that are required for the project. If these plugins are not installed in Poetry's own environment, they are installed only for the project into .poetry/plugins inside the project folder.

rejected first draft

Introduces a `tool.poetry.self` section in pyproject.toml. Example:

[tool.poetry.self]
version = ">=2.0"

[tool.poetry.self.plugins]
poetry-plugin-bundle = ">=1.3"
poetry-plugin-export = ">=1.7.0"

[github-actions]

Deploy preview for website ready!

✅ Preview
https://website-np8dyy7a3-python-poetry.vercel.app

Built with commit 0419d00.
This pull request is being automatically deployed with vercel-action

[Secrus]

Some bikeshedding from my side. I don't like the new self section. When I was working on those issues, I was adding fields directly under the tool.poetry namespace. We already have self referring to the global Poetry installation and IMHO this will be confusing if one self was global and one per project. My proposal would be:
tool.poetry.self.version -> tool.poetry.requires-poetry (mimicking requires-python from PEP 621 spec)
tool.poetry.self.plugins -> tool.poetry.project-plugins

[radoering]

We already have self referring to the global Poetry installation and IMHO this will be confusing if one self was global and one per project.

Yeah, that has already come to my mind, but I couldn't think of anything better. At least, I like the grouping of required version and required plugins into one section.

tool.poetry.self.version -> tool.poetry.requires-poetry (mimicking requires-python from PEP 621 spec)

That is an option. The drawback is that it is not grouped anymore with the required plugins into one section.

tool.poetry.self.plugins -> tool.poetry.project-plugins

Not sure about that because plugins are only installed if they are not available in the global Poetry installation. (I think that makes more sense than just always installing them into the project.) Maybe, requires-plugins? I think it is more like a detail that required plugins that are not available are installed automatically only for the project. We could even introduce a setting to turn this off and just fail if the required plugins are not available (as for the version). (I do not think that we need such a setting but that can change if we get feedback after releasing this into the wild.)

[Secrus]

That is an option. The drawback is that it is not grouped anymore with the required plugins into one section.

Do we need those two features to be grouped together? I don't think so, but maybe you have some good reasons for that

[radoering]

It just belongs together because both are requirements for Poetry itself.

By the way, when running poetry self show plugins, both, global plugins and project plugins will be displayed. Actually, it shouldn't even matter if a plugin is installed globally or in the project folder (except for debugging purposes if something does not work).

Actually, I still think tool.poetry.self.version and tool.poetry.self.plugins is not a bad option. On the other hand, I probably could also get used to tool.poetry.requires-poetry and tool.poetry.requires-plugins.

[radoering]

@johnthagen Since you seem to be interested in this PR and have already given valuable input in various user interfacing issues, I would like to ask for your opinion: self section or requires fields or something else?

(Opinions of others are also welcome, of course.)

self section example

[project]
# ...

[tool.poetry]
# ...

[tool.poetry.self]
version = ">=2.0"

[tool.poetry.self.plugins]
poetry-plugin-bundle = ">=1.3"
poetry-plugin-export = ">=1.7.0"

requires fields example

[project]
# ...

[tool.poetry]
# ...
requires-poetry = ">=2.0"

[tool.poetry.requires-plugins]
poetry-plugin-bundle = ">=1.3"
poetry-plugin-export = ">=1.7.0"

[johnthagen]

@radoering Thanks for the ping.

First, a quick question. Is it assumed that [project] support will be merged as well before this?

• Add support for the project section (PEP 621) #9135

The reason I ask, is that that PR would allow users to move a lot of metadata out of [tool.poetry]. That then makes [tool.poetry] a cleaner space to be able to focus on this kind of internal Poetry-specific metadata (for example package-mode = false etc.) and that could influence my thoughts.

[radoering]

Although this could come before [project] support, I think both will be released together. However, even with [project] support, the fields in [tool.poetry] are still there (although many of them deprecated) so at least we cannot reuse names. (But I understand that there will be less in [tool.poetry] when using the [project] section.)

[johnthagen]

are still there (although many of them deprecated) so at least we cannot reuse names

That is a good point to consider. Are there any fields that we know currently we'd need to use?

I do not have a super strong opinion, but given that package-mode is already under [tool.poetry], I think it is best to go with option #2 requires field

[project]
# ...

[tool.poetry]
# ...
package-mode = false
requires-poetry = ">=2.0"

[tool.poetry.requires-plugins]
poetry-plugin-bundle = ">=1.3"
poetry-plugin-export = ">=1.7.0"

To me this seems like the best long term option.

[radoering]

@johnthagen Thanks for your input. One thing that came to my mind: Is requires-plugins unambiguous enough or is requires-poetry-plugins better?

[johnthagen]

@radoering requires-plugins seems fine to me given that it's already nested inside:

[tool.poetry.requires-plugins]

The .poetry part of that to me implies that we're already talking about poetry-specific configuration (especially once everyone can move all of the wheel metadata out of this into [project]).

[radoering]

I updated the PR from tool.poetry.self.version and tool.poetry.self.plugins to tool.poetry.requires-poetry and tool.poetry.requires-plugins.