You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Upgrade from poetry 1.7 to poetry 2.3, including conforming to PEP 621. Updated all documentation to remove references to Poetry 1 and include more information for Poetry 2. Co-authored with Claude.
* Add python version placeholder file for documentation generation
* Updating docs, fixing python version
* Downgrading packages to avoid test failures
* Adding documentation on upgrading poetry
Copy file name to clipboardExpand all lines: docs/source/development/getting-started.rst
+73-12Lines changed: 73 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,15 +9,15 @@ Installing requirements
9
9
Poetry Installation and Setup
10
10
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11
11
12
-
``imap-processing`` uses :ref:`poetry-link` for dependency management. Check out our :ref:`style guide <poetry-environment>` for more information on specific IMAP Poetry usage.
12
+
``imap-processing`` uses :ref:`poetry-link` for dependency management. Check out our :ref:`style guide <poetry-environment>` for more information on specific IMAP Poetry usage. If you are upgrading from Poetry 1.x, see :ref:`upgrading-poetry`.
13
13
14
14
If you're running locally, you can install the Python requirements with Poetry.
15
15
16
16
To setup versioning *(recommended for developers)*
This will install the dependencies from `poetry.lock`, ensuring that consistent versions are used. Poetry also provides a virtual environment, which you will have to activate.
34
+
This will install the dependencies from `poetry.lock`, ensuring that consistent versions are used.
35
+
Poetry manages a virtual environment for the project, which you will need to activate.
35
36
36
-
.. code-block:: bash
37
+
.. note::
38
+
39
+
``poetry shell`` was removed in Poetry 2. Use one of the following to activate
40
+
the virtual environment instead:
41
+
42
+
.. code-block:: bash
43
+
44
+
# Activate via Poetry (outputs the activation command)
45
+
source$(poetry env info --path)/bin/activate
46
+
47
+
# Or on Windows (PowerShell)
48
+
& (poetry env info --path)\Scripts\activate.ps1
49
+
50
+
Alternatively, you can use the ``venv`` module to create and manage your
51
+
own virtual environment independently:
52
+
53
+
.. code-block:: bash
54
+
55
+
python3 -m venv .venv
56
+
source .venv/bin/activate
57
+
pip install -e ".[dev,test,tools]"
58
+
59
+
.. note::
60
+
61
+
Some dependencies include compiled extensions and require system libraries
62
+
if no pre-built wheel is available for your platform. If installation fails
63
+
with a PEP 517 build error, install the relevant system libraries below and
64
+
then re-run the install command.
65
+
66
+
**netcdf4** requires the NetCDF-C and HDF5 libraries:
67
+
68
+
.. code-block:: bash
69
+
70
+
# Debian/Ubuntu
71
+
sudo apt-get install -y libnetcdf-dev libhdf5-dev
37
72
38
-
poetry shell
73
+
# macOS (Homebrew)
74
+
brew install netcdf hdf5
39
75
76
+
**scipy** provides pre-built wheels for Python 3.10–3.13. If you are using
77
+
Python 3.14 or later, no wheel is available yet and scipy must be compiled
78
+
from source, which requires a Fortran compiler and BLAS/LAPACK. The
79
+
simplest fix is to use Python 3.12 or 3.13.
80
+
81
+
If you need to build from source, install the following:
Copy file name to clipboardExpand all lines: docs/source/development/poetry.rst
+60-28Lines changed: 60 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,7 @@ These advantages ensure that we can all install the same versions of tools, that
20
20
21
21
Poetry also provides tools for automatically bumping dependency versions only where it makes sense. You can specify when a dependency should get a version change using Poetry's extensive `dependency specification <https://python-poetry.org/docs/dependency-specification/>`_ formatting.
22
22
23
-
Finally, Poetry provides a :ref:`shell <poetry-shell-link>`, which you can use as a virtual environment. This shell is automatically tied to the project directory, and allows developers to install dependency versions in an isolated environment. This means that, for example, if you have a different project using the same package with a different version, you can have each project with it's own version kept separate from conflicts.
23
+
Finally, Poetry manages a virtual environmenttied to the project directory, which allows developers to install dependency versions in an isolated environment. This means that, for example, if you have a different project using the same package with a different version, you can have each project with its own version kept separate from conflicts. See :ref:`poetry-shell-link` for how to activate it.
24
24
25
25
We have a :ref:`Poetry style guide<poetry-environment>` for specific recommendations about using Poetry in these projects.
26
26
@@ -52,7 +52,7 @@ Poetry has a command to `add a new dependency <https://python-poetry.org/docs/ma
52
52
# Add a new dependency with default latest version
53
53
poetry add pendulum
54
54
55
-
These dependencies are then added automatically to the ``pyproject.toml`` file. The overall project dependencies go under ``[tool.poetry.dependencies]``. The main project dependencies are always installed.
55
+
These dependencies are then added automatically to the ``pyproject.toml`` file. The main project dependencies go under the ``[project]`` table as a ``dependencies`` list, using `PEP 508 <https://peps.python.org/pep-0508/>`_ version specifiers (e.g. ``numpy>=1.24,<2``). Dependencies in ``[tool.poetry.group.*]`` sections continue to use Poetry's caret notation. The main project dependencies are always installed.
56
56
57
57
You can also update the ``pyproject.toml`` file directly, using the existing formatting or the `Poetry documentation on it <https://python-poetry.org/docs/pyproject/>`_ as a guide.
58
58
@@ -63,52 +63,84 @@ This will create a new version of the ``poetry.lock`` file, which should be comm
63
63
64
64
.. _poetry-dependency-groups-link:
65
65
66
-
Dependency groups
67
-
^^^^^^^^^^^^^^^^^^
66
+
Optional extras
67
+
^^^^^^^^^^^^^^^
68
68
69
-
Poetry also provides dependency groups for separating dependencies into logical separations. If you are installing the project as an end user, you do not need the development tools. The testing environment does not need the documentation generation dependencies. In our case, the AWS Lambda environment does not need the same dependencies as the CDK deployment. Before you add a dependency to the main group, ask yourself if it would make more sense in one of the other existing dependency groups.
69
+
This project uses PEP 621 optional dependencies (extras) to separate dependencies into logical groups. If you are installing the project as an end user, you do not need the development tools. The testing environment does not need the documentation generation dependencies. Before you add a dependency to the main dependencies, ask yourself if it would make more sense in one of the existing extras (``dev``, ``test``, ``doc``, ``tools``, ``map_visualization``).
70
70
71
-
To add a dependency to an existing group, you can use the ``--group`` flag::
72
-
73
-
poetry add mkdocs --group docs
74
-
75
-
These groups can be made optional as well, meaning they will not be installed by default when the user runs ``poetry install``. You can specify what groups to install using the ``--with`` or ``--without`` flags.
76
-
77
-
Pip also provides a standard for optional dependencies. These can be installed when using ``pip`` instead of Poetry to install the dependencies. This goes under the ``[tool.poetry.extras]`` section in ``pyproject.toml``. These are separate, but similar to the optional dependencies. They can only be all installed or all not installed, with no splitting out into specific groups like the dependency groups.
71
+
To add a dependency to an existing extra, update the ``[project.optional-dependencies]`` section in ``pyproject.toml`` directly using PEP 508 version specifiers. These extras can be installed selectively when running ``poetry install`` or ``pip install``.
78
72
79
73
.. _poetry-shell-link:
80
74
81
-
Installing and the Poetry Shell
82
-
--------------------------------
75
+
Installing and Activating the Virtual Environment
76
+
-------------------------------------------------
83
77
84
78
To install the Poetry project, you can use the `install <https://python-poetry.org/docs/cli/#install>`_ command::
85
79
86
80
# We use dynamic versioning, which requires a plugin to be installed first
# Install main dependencies and any dependency groups which are installed by default
83
+
# Install main dependencies only
90
84
poetry install
91
85
92
-
# Install all extras
86
+
# Install all extras (dev, test, doc, tools, map_visualization)
93
87
poetry install --all-extras
94
88
95
-
# install without specific dependency groups
96
-
poetry install --without test,docs
89
+
# Install with specific extras
90
+
poetry install --extras "test doc"
91
+
92
+
By default, this command will install dependencies out of the ``poetry.lock`` file.
93
+
94
+
.. note::
95
+
96
+
``poetry shell`` was removed in Poetry 2. To activate the Poetry-managed
97
+
virtual environment, use:
98
+
99
+
.. code-block:: bash
100
+
101
+
source$(poetry env info --path)/bin/activate
102
+
103
+
# To exit the virtual environment
104
+
deactivate
97
105
98
-
# Install with optional dependency groups
99
-
poetry install --with lambda_dev
106
+
On Windows (PowerShell):
100
107
101
-
By default, this command will install dependencies out of the ``poetry.lock`` file. This will also install into your Poetry shell for the project.
108
+
.. code-block:: powershell
102
109
103
-
The Poetry shell is a virtual environment tool provided by Poetry. To start the Poetry shell, with your dependencies installed, you can use the poetry `shell <https://python-poetry.org/docs/cli/#shell>`_ command::
110
+
& (poetry env info --path)\Scripts\activate.ps1
104
111
105
-
poetry shell
112
+
You can also run a single command inside the environment without activating
113
+
it using ``poetry run``::
114
+
115
+
poetry run pytest
116
+
117
+
.. _venv-alternative-link:
118
+
119
+
Using a plain ``venv`` instead of Poetry's virtual environment
#Or install directly with pip using the pyproject.toml extras
139
+
pip install -e ".[dev,test,tools]"
109
140
110
-
However, you are not required to use the Poetry shell as your virtual environment manager if you have another tool you prefer.
141
+
The ``venv`` approach avoids the need for ``poetry shell`` entirely: your
142
+
shell is already in the virtual environment after running ``source .venv/bin/activate``.
111
143
112
-
Poetry will, by default, not create a new virtual environment if it detects that it is running in a virtual environment already. So, for example, you can use a `Conda environment <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_ by activating the environment first, and then running `poetry install`.
144
+
Poetry will, by default, not create a new virtual environment if it detects that it is running in a virtual environment already. So, for example, you can use a `Conda environment <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_ by activating the environment first, and then running ``poetry install``.
113
145
114
146
There are also `settings <https://python-poetry.org/docs/configuration/#virtualenvscreate>`_ surrounding the virtual environment that you can change to suit your workflow.
0 commit comments