From 24dbaab1fde00a673351b63991df4f0ea0b14a30 Mon Sep 17 00:00:00 2001 From: Bartek Sokorski Date: Sun, 18 Sep 2022 23:01:49 +0200 Subject: [PATCH 1/3] Rephrase plugin configuration in docs --- docs/plugins.md | 8 ++++---- docs/pyproject.md | 15 ++++++++++----- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index d9eee07a8ad..9ebae1269c4 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 an `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..ffb08f4cdd1 100644 --- a/docs/pyproject.md +++ b/docs/pyproject.md @@ -414,16 +414,21 @@ 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 work similarly to `setuptools` entry points. +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` - pythonic path to module containing plugin class +- `D` - name of plugin class ## `urls` From b0a1144548aba0a7dae23809b81b81f92eb53514 Mon Sep 17 00:00:00 2001 From: Bartosz Sokorski Date: Mon, 19 Sep 2022 10:00:45 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Bjorn Neergaard --- docs/plugins.md | 2 +- docs/pyproject.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index 9ebae1269c4..7fc8bfe081b 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -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 `poetry.application.plugin` plugin: +as a `poetry.application.plugin` plugin: ```toml [tool.poetry.plugins."poetry.application.plugin"] diff --git a/docs/pyproject.md b/docs/pyproject.md index ffb08f4cdd1..74eaf9073cb 100644 --- a/docs/pyproject.md +++ b/docs/pyproject.md @@ -414,7 +414,7 @@ Dependencies listed in [dependency groups]({{< relref "managing-dependencies#dep ## `plugins` -Poetry supports arbitrary plugins which work similarly to `setuptools` entry points. +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 @@ -427,8 +427,8 @@ Which are: - `A` - type of the plugin, for example `poetry.plugin` or `flake8.extension` - `B` - name of the plugin -- `C` - pythonic path to module containing plugin class -- `D` - name of plugin class +- `C` - python module import path +- `D` - the entry point of the plugin (a function or class) ## `urls` From 19c07d327e6cee565c92ab9d49f80699ee86fe34 Mon Sep 17 00:00:00 2001 From: Bartek Sokorski Date: Fri, 23 Sep 2022 21:40:27 +0200 Subject: [PATCH 3/3] Add real world example of plugin config --- docs/pyproject.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/pyproject.md b/docs/pyproject.md index 74eaf9073cb..955c64d4c6a 100644 --- a/docs/pyproject.md +++ b/docs/pyproject.md @@ -430,6 +430,13 @@ Which are: - `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` In addition to the basic urls (`homepage`, `repository` and `documentation`), you can specify