Poetry: Document difference between poetry plugins and entrypoints.

[brennie]

• [x] I have searched the issues of this repo and believe that this is not a duplicate.

Issue

From a cursory glance, it looks like plugins are converted to entrypoints, but it would be good to clarify this in the documentation because it reads as if they are different:

Poetry supports arbitrary plugins which work similarly to setuptools entry points. (2)

[cjw296]

@sdispater - I don't want to open a new issue, so I'll comment here. I'm a little confused, because https://github.com/sdispater/poetry/issues/693 would seem to be the right place but that issue has become muddied with discussions around cleo, python version specification, etc.

This issue asks a specific question, but mine is a little broader: It appears that poetry has documentation for its own plugins along with a way of specifying plugins for your own projects. However, it doesn't have any examples/documentation about how to use the latter.

As a concrete example, how would I replace this specification and use of entrypoints if I moved that project to poetry?

[orlnub123]

I'm not sure why poetry specific plugins are documented since they don't seem to be implemented yet although I might be wrong since I just did a simple grep search.

As @brennie said plugins are simply a way to specify entry points so you wouldn't need to change anything to use them. I'd imagine you'd specify them similarly:

[tool.poetry.scripts]
archivist = "archivist.main:main"

[tool.poetry.plugins."archivist.repo"]
git = "archivist.main:main"

[tool.poetry.plugins."archivist.source"]
crontab = "archivist.sources.crontab:Plugin"
jenkins = "archivist.sources.jenkins:Plugin"
packages = "archivist.sources.packages:Plugin"
paths = "archivist.sources.paths:Plugin"

[tool.poetry.plugins."archivist.notification"]
email = "archivist.notifications.email:Plugin"
stream = "archivist.notifications.stream:Plugin"

[cjw296]

@orlnub123 - great, so this is just a documentation issue.
Related question: Should I specify any dependency to make sure the pkg_resources package is available? I seem to remember that comes from setuptools, so curious about whether that'll "always" be available across virtualenvs, conda environments, etc?

[orlnub123]

@cjw296 It's probably possible to have an environment where setuptools isn't available at runtime so I'd say it's a good idea to declare it as a dependency.

[stale[bot]]

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

[cjw296]

not stale

[mfriedenhagen]

I still do not get it. What is the difference between tool.poetry.script and the stuff you declare beneath tool.poetry.plugins? Scripts I may invoke with "poetry run SCRIPT_NAME".

[sinoroc]

@mfriedenhagen

As far as I understood it is a taken out of the _entry points_ feature from _setuptools_:

• https://setuptools.readthedocs.io/en/latest/userguide/entry_point.html

Basically you have named entry points in different categories. The most common category is console_scripts. If you add an entry point in that category, then an executable of the same name is created. The executable will be created so that it runs the function specified as value for the entry point.

In _setuptools_ setup.cfg you might have:

[options.entry_points]
console_scripts =
    mycommand = mypackage.mymodule:my_function

This should result in a mycommand executable that when called, runs the function my_function from mypackage.mymodule. So more or less:

#!/usr/bin/env python

if __name__ == '__main__':
    import mypackage
    mypackage.mymodule.my_function()

In _poetry_ you would write in pyproject.toml either one of the following two:

[tool.poetry.scripts]
mycommand = "mypackage.mymodule:my_function"

[tool.poetry.plugins."console_scripts"]
"mycommand" = "mypackage.mymodule:my_function"

As far as I know they should be the same. Except maybe that first notation also allows to do poetry run mycommand (I am not sure).

---

As for the more general "_plug-ins_" side of this, I find it a bit hard to explain...

First I am a bit conflicted on the divide that was created in _poetry_ between _scripts_ and _plugins_. In both cases these are _entry points_, true they might be used for console scripts or plug-ins, but maybe for other things as well.

Basically you could write a pluggable application, that will look for any entry point registered in the specific category of your application (you define the name yourself, and it could look like awesomeapplication_plugin_category for example), and then your application can decide to call the associated functions to enhance the features of your pluggable application with plug-ins. So once your pluggable application is published and documented, I could write a plug-in for it:

[tool.poetry.plugins."awesomeapplication_plugin_category"]
"myawesomeplugin_entry_point" = "myawesomeplugin.mymodule:my_function"

So console_scripts is just one category of _entry points_ and [tool.poetry.scripts] is in a way some kind of a shortcut for [tool.poetry.plugins."console_scripts"].

[mfriedenhagen]

Thanks a lot @sinoroc. That now makes sense somehow. So poetry currently does not allow to extend itself with plugins but provides a means to build a package which enhances other software like e.g. pytest, so I the following sample of https://docs.pytest.org/en/stable/writing_plugins.html#setuptools-entry-points could probably be written as

[tool.poetry.plugins."pytest11"]
name_of_plugin = "myproject.pluginmodule"

[sinoroc]

poetry currently _does not_ allow to extend itself with plugins but provides a means to build a package which enhances other software like e.g. pytest

Exactly.

the following sample of https://docs.pytest.org/en/stable/writing_plugins.html#setuptools-entry-points could probably be written as

[tool.poetry.plugins."pytest11"]
name_of_plugin = "myproject.pluginmodule"

Yes, seems right.

Poetry's own plug-in system is scheduled for _v1.2_. The way this future plug-in system is drafted now, if you were to write a plug-in for poetry in the future, it might look like this in your pyroject.toml:

[tool.poetry.plugins."poetry.plugin"]
demo = "poetry_demo_plugin.plugin:MyPlugin"

-- https://github.com/python-poetry/poetry/blame/605d786a942301374309d67c09d6579bf9165d75/docs/docs/plugins.md#L31-L32