Implement a plugin system

[sdispater]

This PR introduces a plugin system to add commands and features to Poetry more easily.

It uses the standard entrypoints system that exists today and will make it possible to build two kinds of plugins:

• Generic plugins that will make it possible to interact with the Poetry instance created by Poetry. This will be useful to, for instance, implement a plugin that will dynamically set the version of the project based on VCS tags and commits.
• Application plugins that will make it possible to add commands to the Poetry CLI.

This PR also provides three new commands to manage plugins:

• plugin add to install plugins
• plugin remove to uninstall plugins
• plugin show to list currently installed plugins.

Todo

• Tests for the plugin add command
• The plugin remove command
• The plugin show command

Pull Request Check List

Resolves: #693

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

[cognifloyd]

Ooh. This is exciting [WIP] development. Looking forward to it!

Are plugins prohibited with poetry new? Not sure why people would need them in that context, but 🤷.

[cognifloyd]

Plugins can't be used for poetry new calls?

[sdispater]

I think it's a leftover restriction from a previous shot at implementing the plugin system.

The current implementation should not need such restriction.

I'll check and remove it if needed.

[1ace]

I interpret your docs to mean "yes", but can you confirm whether it's possible with this system to have a repo-specific plugin that lives in the repo itself? or does it need to be installed in one of the sites for poetry to see it?

That would be a really useful feature I think :)

[sdispater]

@1ace Plugins will be global and not on a per-project basis.

[sdispater]

@abn Regarding the export command, there are two ways to go:

• Make use of subcommands rather than a --format option.
• Make the export command pluggable so that the --format option can be hooked into.

Once we make it an official plugin we'll see how it goes. For now, I don't have a strong preference even though I feel like keeping the option makes more sense.

As to how sub commands can be added, it's simple since subcommands are nothing more than namespaced commands. So basically, it woould look like this:

from cleo.commands.command import Command
from poetry.plugins.application_plugin import ApplicationPlugin


class ExportRequirementsCommand(Command):

    name = "export requirements.txt"

    def handle(self) -> int:
        # Do the export

        return 0


def export_command_factory():
    return ExportRequirementsCommand()


class ExportApplicationPlugin(ApplicationPlugin):
    def activate(self, application):
        application.command_loader.register_factory(
            "export requirements.txt", export_command_factory
        )

[henryiii]

Just curious, would it be possible to add an extension building system via a plugin? So poetry handles the Python files and CMake (for example) handles the compiling? I assume a little extra work would be needed to ensure wheels has the right names and such, but how close might this be to working?

[abn]

@henryiii If I am understanding you correct, I suspect you can achieve that today using the build script without a plugin. https://github.com/sdispater/pendulum/blob/411d0aa41a5f39c5f4a2f43a3c369c2dd24787db/pyproject.toml#L51-L53

You can add the cmake call into the build.py. If this is not the case, I would suggest you open a discussion.

[henryiii]

Thanks @abn, that's good to know about. (Though, @sdispater, two notes; just to keep in mind, distutils is slated for removal in Python 3.12, and you shouldn't name a top-level file build.py, because then you can't build the project with python -m build, I've had to debug this before).

I'll probably open a discussion, because I'm interested in developing a scikit-build plugin that would integrate CMake with Poetry.

[mpeteuil]

I was wondering if there is a recommended naming pattern for plugins? Like poetry_plugin_X or poetry_X_plugin or something like that. I asked in the Discord and was pointed to Github, although this PR may not be the right place and one of the other plugin-related issues could be a better place for this question.

[github-actions]

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