Upgrade from poetry 1.7 to poetry 2.3

[maxinelasp]

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.

Change Summary

Now that we're expecting more external people to use our project, we should use the latest version of Poetry.

Benefits:

• Correct version of Poetry installs when you run pip install poetry
• Conforms with latest Python standards, making pip work better
• Better/cleaner organization
• Plugins are fixed - no longer do we need to run poetry self add, as the required plugins will install automatically
• More compatibility with venv

Changes from Poetry 1 to Poetry 2:
poetry shell is gone

• Removed from core Poetry 2.x
• Use poetry env activate to print the activation command, then run it manually
• Or install the poetry-plugin-shell plugin to restore the old behavior: poetry self add poetry-plugin-shell
  Lock file

Lock file format changed — not backwards compatible with Poetry 1.x

• poetry lock --no-update is gone; just use poetry lock
• poetry lock by default no longer upgrades pinned versions, just reconciles with pyproject.toml
• pyproject.toml validation is stricter

Poetry 2.x fully adopts PEP 621 ([project] table) alongside [tool.poetry]

• [tool.poetry] must now either have a version field or rely on a plugin via [tool.poetry.requires-plugins] for dynamic versioning
• Plugin dependencies declared in [tool.poetry.requires-plugins] are automatically installed when running poetry install

File changes

The main changes are in pyproject.toml. No dependencies were changed, this is just a reorganization. Once everyone upgrades to Poetry 2, the main changes will be that you no longer use poetry shell. This is documented.

There were a few other updates removing some of the hacks around the dynamic versioning. We are now on the latest version of that plugin.

Testing

I would appreciate if reviewers would clone this branch, install Poetry 2, and verify that everything installs successfully.

[Copilot]

Pull request overview

Upgrades the repository’s packaging and developer workflow to Poetry 2.3, including a migration toward PEP 621 [project] metadata and corresponding documentation/CI updates to reflect Poetry 2 behaviors (notably removal of poetry shell).

Changes:

• Migrates package metadata/dependencies/scripts in pyproject.toml to PEP 621 ([project], dependencies, optional-dependencies, [project.scripts]) while keeping Poetry dynamic versioning.
• Updates developer documentation to describe Poetry 2 installation and virtual environment activation workflows.
• Updates tooling configs (pre-commit Poetry hook + GitHub Actions Poetry setup) to use Poetry 2.3.4.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
pyproject.toml	Moves metadata/deps to PEP 621, adds Poetry 2 plugin requirements, and adjusts Python requirement.
docs/source/development/poetry.rst	Updates Poetry usage docs (deps layout + virtualenv activation) for Poetry 2.
docs/source/development/git-workflow-and-style-guide/poetry-environment.rst	Updates dependency-spec guidance to distinguish PEP 508 vs Poetry group syntax.
docs/source/development/getting-started.rst	Updates setup instructions for Poetry 2 and adds troubleshooting/install notes.
.pre-commit-config.yaml	Bumps Poetry hook to 2.3.4 and removes deprecated lock args; normalizes quoting/formatting.
.gitignore	Removes obsolete commented Poetry lock guidance.
.github/workflows/test.yml	Updates CI to install Poetry 2.3.4 via setup-poetry@v9 and adjusts install steps.

Comments suppressed due to low confidence (1)

.github/workflows/test.yml:41

• CI installs the dynamic versioning plugin via poetry self add before poetry install. With the new [tool.poetry.requires-plugins] config, this step may be unnecessary and it mutates Poetry’s global environment (which can be brittle across runners/caches). Consider removing the explicit self add and relying on requires-plugins (or, if self add is still required in CI, document why and consider dropping requires-plugins to avoid duplicated/conflicting mechanisms).

      - name: Install dependencies and app
        run: |
          # Need to install extra plugins first
          poetry self add "poetry-dynamic-versioning[plugin]"
          poetry install --extras "test"

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[laspsandoval]

Take a look at my comments. I'll try to install it now.

[laspsandoval]

After checking out your branch:
gh pr checkout 3084
I did:
poetry self update 2.3.4
poetry install --all-extras
And everything looked in order.

[laspsandoval]

Thanks for the updates, Maxine. Nice!

[vmartinez-cu]

After checking out your branch: gh pr checkout 3084 I did: poetry self update 2.3.4 poetry install --all-extras And everything looked in order.

I tried to run poetry self update and it failed so I re-installed poetry to get version 2.3.4. I then ran pytest on all tests to see if anything fails due to a missing dependency somewhere and got 6 failed Hi tests. I'm not sure if or how these failures could be related since the error messages don't mention a dependency issue. Are you seeing these too?

FAILED hi/test_hi_l2.py::test_hi_l2[h90-ena-h-sf-nsp-full-hae-4deg-3mo] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_hi_l2[h90-ena-h-hf-nsp-ram-gcs-6deg-3mo] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_create_sky_map_from_psets[h90-ena-h-sf-nsp-full-gcs-6deg-3mo-expected_keys0] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_create_sky_map_from_psets[h90-ena-h-sf-nsp-ram-gcs-6deg-3mo-expected_keys1] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_create_sky_map_from_psets[h90-ena-h-hf-nsp-ram-gcs-6deg-3mo-expected_keys2] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_create_sky_map_from_psets[h90-ena-h-hf-nsp-full-gcs-6deg-3mo-expected_keys3] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"

[vmartinez-cu]

After checking out your branch: gh pr checkout 3084 I did: poetry self update 2.3.4 poetry install --all-extras And everything looked in order.

I tried to run poetry self update and it failed so I re-installed poetry to get version 2.3.4. I then ran pytest on all tests to see if anything fails due to a missing dependency somewhere and got 6 failed Hi tests. I'm not sure if or how these failures could be related since the error messages don't mention a dependency issue. Are you seeing these too?

FAILED hi/test_hi_l2.py::test_hi_l2[h90-ena-h-sf-nsp-full-hae-4deg-3mo] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_hi_l2[h90-ena-h-hf-nsp-ram-gcs-6deg-3mo] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_create_sky_map_from_psets[h90-ena-h-sf-nsp-full-gcs-6deg-3mo-expected_keys0] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_create_sky_map_from_psets[h90-ena-h-sf-nsp-ram-gcs-6deg-3mo-expected_keys1] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_create_sky_map_from_psets[h90-ena-h-hf-nsp-ram-gcs-6deg-3mo-expected_keys2] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"
FAILED hi/test_hi_l2.py::test_create_sky_map_from_psets[h90-ena-h-hf-nsp-full-gcs-6deg-3mo-expected_keys3] - KeyError: "No variable named 'epoch_delta'. Did you mean one of ('epoch',)?"

I reverted to poetry 1.8.0 and still see these failed Hi tests so it seems unrelated to this poetry upgrade

[maxinelasp]

@vmartinez-cu I did see some failing tests, but those ones seem unrelated. Mine were mostly unit conversion failures related to numpy 1 vs numpy 2. Once I pinned numpy at >2 they were fixed. I believe those are unrelated to the upgrade.

[tech3371]

I didn't try the new doc steps but thank you for updating those and adding steps for updating as well!