ewoks install: support the poetry package manager

.github/workflows/test.yml

@@ -32,7 +32,7 @@ jobs:
         ${{ matrix.extra-pytest-warnings }}
       enable-coverage: ${{ matrix.enable-coverage }}
       jupyter-platform-dirs: "1"
-      package-managers: "uv pixi conda"
+      package-managers: "uv poetry pixi conda"
       codecov-flags: "unit"
     strategy:
       fail-fast: false

doc/howtoguides/requirements.rst

@@ -19,8 +19,8 @@ What is stored
   :term:`package manager` can recreate the environment from this list.
 * ``manager``: the :term:`package manager` that generated the requirements, with the content
   of the files it needs to recreate the environment: ``requirements.txt`` for pip-venv,
-  ``pyproject.toml`` and ``uv.lock`` for uv, ``environment.yml`` for conda, ``pixi.toml``
-  and ``pixi.lock`` for pixi.
+  ``pyproject.toml`` and ``uv.lock`` for uv, ``pyproject.toml`` and ``poetry.lock`` for
+  poetry, ``environment.yml`` for conda, ``pixi.toml`` and ``pixi.lock`` for pixi.
 
 Use ``--exclude-requirements`` to store nothing.
 
@@ -88,32 +88,34 @@ content.
 
 Without ``--env-root`` the :term:`package manager` decides where the environment goes: conda
 creates it in its own environment directory (``conda config --show envs_dirs``), so
-``conda activate <name>`` finds it. venv, uv and pixi create an environment wherever they are
-told to, so for those ewoks uses ``~/.ewoks/envs``.
+``conda activate <name>`` finds it, and poetry in the directory it creates project
+environments in (``poetry config virtualenvs.path``). venv, uv and pixi create an environment
+wherever they are told to, so for those ewoks uses ``~/.ewoks/envs``.
 
 An environment that already exists is installed in, which adds the requirements to what is
 already there. Use ``--clean`` to remove it first. Only a directory that contains a python
 environment is removed.
 
 The environment of a :term:`workflow` is a directory. For pip-venv and conda it is a python
-environment, for uv it is a project with the environment in ``.venv`` and for pixi it is a
-workspace with the environment in ``.pixi/envs/default``. ``ewoks execute --env`` takes that
-directory, not the python interpreter inside it.
+environment, for uv and poetry it is a project with the environment in ``.venv`` and for pixi
+it is a workspace with the environment in ``.pixi/envs/default``. ``ewoks execute --env`` takes
+that directory, not the python interpreter inside it.
 
 Limitations
 -----------
 
 * ``--in-place`` is only supported by pip-venv and uv. The other package managers only install
   in an environment they created themselves.
 * ``--python-version`` is a request: uv can provide any python version, conda and pixi provide
-  the patch versions built by their channel and pip-venv can only use the version of the python
-  interpreter that creates the environment. A warning is emitted when the version cannot be
-  provided.
-* uv and pixi resolve the ``distributions`` into a lock file, which requires access to the
-  package index. When that fails, a warning is emitted and the requirements are stored without
-  files: the environment is then recreated from the ``distributions`` list.
+  the patch versions built by their channel, and pip-venv and poetry can only use the version of
+  the python interpreter that creates the environment. A warning is emitted when the version
+  cannot be provided.
+* uv, poetry and pixi resolve the ``distributions`` into a lock file, which requires access to
+  the package index. When that fails, a warning is emitted and the requirements are stored
+  without files: the environment is then recreated from the ``distributions`` list.
 * A lock file is only read by a :term:`package manager` that understands its format version, so
   reproducing an environment can require a version of the tool that is at least as recent as
   the one that generated the requirements.
+* poetry 1.8 or later is required. Older versions are reported as not available.
 * A package installed from a local directory cannot be recreated elsewhere. This is reported as
   a warning when the requirements are generated.

doc/reference/glossary.rst

@@ -29,7 +29,7 @@ Glossary
         An execution engine is the underlying software used to execute the :term:`workflow`. :term:`Ewoks` supports multiple execution engines: pypushflow, orange, dask and the ewoks internal excution engine.
 
     Package manager
-        A package manager creates python environments and installs packages in them. :term:`Ewoks` uses package managers to store the environment in which a :term:`workflow` was created and to recreate it: pip with venv, uv, conda and pixi.
+        A package manager creates python environments and installs packages in them. :term:`Ewoks` uses package managers to store the environment in which a :term:`workflow` was created and to recreate it: pip with venv, uv, poetry, conda and pixi.
 
     blissdata
         `Blissdata <https://bliss.gitlab-pages.esrf.fr/blissdata>`_ is an API for accessing data from BLISS in memory.

doc/tutorials/install.rst

@@ -22,6 +22,7 @@ of the supported ones
 
     install/pip_venv
     install/uv
+    install/poetry
     install/conda
     install/pixi
 

doc/tutorials/install/poetry.rst

@@ -0,0 +1,153 @@
+.. _install_poetry:
+
+poetry
+======
+
+End-to-end walk-through with `poetry <https://python-poetry.org/>`_ 1.8 or later. Poetry works
+with projects instead of environments: its commands need a directory with a
+``pyproject.toml`` file, selected with ``-C``.
+
+Install poetry
+--------------
+
+.. tabs::
+
+    .. group-tab:: Linux
+
+        .. code-block:: bash
+
+            export POETRY_HOME=$HOME/.local/poetry
+            curl -sSL https://install.python-poetry.org | python3 -
+            export PATH=$POETRY_HOME/bin:$PATH
+
+    .. group-tab:: macOS
+
+        .. code-block:: bash
+
+            export POETRY_HOME=$HOME/.local/poetry
+            curl -sSL https://install.python-poetry.org | python3 -
+            export PATH=$POETRY_HOME/bin:$PATH
+
+    .. group-tab:: Windows
+
+        .. code-block:: powershell
+
+            $env:POETRY_HOME = "$env:USERPROFILE\.local\poetry"
+            (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
+            $env:PATH = "$env:POETRY_HOME\bin;$env:PATH"
+
+Producer side
+-------------
+
+Create a project, install :term:`ewoks` in it and store a :term:`workflow` with the packages
+of that project as its ``requirements``
+
+.. tabs::
+
+    .. group-tab:: Linux
+
+        .. code-block:: bash
+
+            poetry new ewoks_producer
+            poetry -C ewoks_producer add ewoks
+            poetry -C ewoks_producer run ewoks convert demo "$PWD/demo.json" --test
+
+    .. group-tab:: macOS
+
+        .. code-block:: bash
+
+            poetry new ewoks_producer
+            poetry -C ewoks_producer add ewoks
+            poetry -C ewoks_producer run ewoks convert demo "$PWD/demo.json" --test
+
+    .. group-tab:: Windows
+
+        .. code-block:: powershell
+
+            poetry new ewoks_producer
+            poetry -C ewoks_producer add ewoks
+            poetry -C ewoks_producer run ewoks convert demo "$PWD\demo.json" --test
+
+Install any package that provides :term:`tasks <Task>` instead of
+``ewoks`` for a real :term:`workflow`. Poetry 2 resolves the arguments of ``poetry run``
+relative to the project directory, so the workflow paths are absolute.
+
+Re-producer side
+----------------
+
+Only ``ewoks`` itself is needed to recreate the environment of ``demo.json``
+
+.. tabs::
+
+    .. group-tab:: Linux
+
+        .. code-block:: bash
+
+            poetry new ewoks_reproducer
+            poetry -C ewoks_reproducer add ewoks
+            poetry -C ewoks_reproducer run ewoks install "$PWD/demo.json" --yes --env-root "$PWD/ewoks_envs"
+
+    .. group-tab:: macOS
+
+        .. code-block:: bash
+
+            poetry new ewoks_reproducer
+            poetry -C ewoks_reproducer add ewoks
+            poetry -C ewoks_reproducer run ewoks install "$PWD/demo.json" --yes --env-root "$PWD/ewoks_envs"
+
+    .. group-tab:: Windows
+
+        .. code-block:: powershell
+
+            poetry new ewoks_reproducer
+            poetry -C ewoks_reproducer add ewoks
+            poetry -C ewoks_reproducer run ewoks install "$PWD\demo.json" --yes --env-root "$PWD\ewoks_envs"
+
+The environment of the :term:`workflow` is a poetry project in ``ewoks_envs/demo`` with the
+virtual environment in its ``.venv`` directory.
+
+Execute the workflow
+--------------------
+
+.. tabs::
+
+    .. group-tab:: Linux
+
+        .. code-block:: bash
+
+            poetry -C ewoks_reproducer run ewoks execute --env "$PWD/ewoks_envs/demo" "$PWD/demo.json" --outputs=all
+
+    .. group-tab:: macOS
+
+        .. code-block:: bash
+
+            poetry -C ewoks_reproducer run ewoks execute --env "$PWD/ewoks_envs/demo" "$PWD/demo.json" --outputs=all
+
+    .. group-tab:: Windows
+
+        .. code-block:: powershell
+
+            poetry -C ewoks_reproducer run ewoks execute --env "$PWD\ewoks_envs\demo" "$PWD\demo.json" --outputs=all
+
+Clean up
+--------
+
+.. tabs::
+
+    .. group-tab:: Linux
+
+        .. code-block:: bash
+
+            rm -rf ewoks_producer ewoks_reproducer ewoks_envs demo.json
+
+    .. group-tab:: macOS
+
+        .. code-block:: bash
+
+            rm -rf ewoks_producer ewoks_reproducer ewoks_envs demo.json
+
+    .. group-tab:: Windows
+
+        .. code-block:: powershell
+
+            Remove-Item -Recurse -Force ewoks_producer, ewoks_reproducer, ewoks_envs, demo.json