From 31ef8d781607505d9bd581647df056a1a637ddea Mon Sep 17 00:00:00 2001 From: Bartosz Sokorski Date: Sat, 24 Sep 2022 15:33:10 +0200 Subject: [PATCH] docs: rephrase plugin configuration in docs (#6557) Co-authored-by: Bjorn Neergaard Co-authored-by: Mathieu Kniewallner --- docs/plugins.md | 8 ++++---- docs/pyproject.md | 22 +++++++++++++++++----- 2 files changed, 21 insertions(+), 9 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index d9eee07a8ad..7fc8bfe081b 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -50,7 +50,7 @@ demo = "poetry_demo_plugin.plugin:MyPlugin" Every plugin has to supply a class which implements the `poetry.plugins.Plugin` interface. The `activate()` method of the plugin is called after the plugin is loaded -and receives an instance of `Poetry` as well as an instance of `cleo.io.IO`. +and receives an instance of `Poetry` as well as an instance of `cleo.io.io.IO`. Using these two objects all configuration can be read and all public internal objects and state can be manipulated as desired. @@ -78,7 +78,7 @@ If you want to add commands or options to the `poetry` script you need to create an application plugin which implements the `poetry.plugins.ApplicationPlugin` interface. The `activate()` method of the application plugin is called after the plugin is loaded -and receives an instance of `console.Application`. +and receives an instance of `poetry.console.Application`. ```python from cleo.commands.command import Command @@ -119,7 +119,7 @@ This will help keep the performances of Poetry good. {{% /note %}} The plugin also must be declared in the `pyproject.toml` file of the plugin package -as an `application.plugin` plugin: +as a `poetry.application.plugin` plugin: ```toml [tool.poetry.plugins."poetry.application.plugin"] @@ -135,7 +135,7 @@ A plugin **must not** remove or modify in any way the core commands of Poetry. Plugins can also listen to specific events and act on them if necessary. -These events are fired by [Cleo](https://github.com/sdispater/cleo) +These events are fired by [Cleo](https://github.com/python-poetry/cleo) and are accessible from the `cleo.events.console_events` module. - `COMMAND`: this event allows attaching listeners before any command is executed. diff --git a/docs/pyproject.md b/docs/pyproject.md index 55004615ccb..955c64d4c6a 100644 --- a/docs/pyproject.md +++ b/docs/pyproject.md @@ -414,15 +414,27 @@ Dependencies listed in [dependency groups]({{< relref "managing-dependencies#dep ## `plugins` -Poetry supports arbitrary plugins which work similarly to -[setuptools entry points](http://setuptools.readthedocs.io/en/latest/setuptools.html). -To match the example in the setuptools documentation, you would use the following: +Poetry supports arbitrary plugins, which are exposed as the ecosystem-standard [entry points](https://packaging.python.org/en/latest/specifications/entry-points/) and discoverable using `importlib.metadata`. This is similar to (and compatible with) the entry points feature of `setuptools`. +The syntax for registering a plugin is: ```toml [tool.poetry.plugins] # Optional super table -[tool.poetry.plugins."blogtool.parsers"] -".rst" = "some_module:SomeClass" +[tool.poetry.plugins."A"] +"B" = "C:D" +``` +Which are: + +- `A` - type of the plugin, for example `poetry.plugin` or `flake8.extension` +- `B` - name of the plugin +- `C` - python module import path +- `D` - the entry point of the plugin (a function or class) + +Example (from [`poetry-plugin-export`](http://github.com/python-poetry/poetry-plugin-export)): + +```toml +[tool.poetry.plugins."poetry.application.plugin"] +export = "poetry_plugin_export.plugins:ExportApplicationPlugin" ``` ## `urls`