Use poetry instead of venv

.github/actions/setup-poetry/action.yml

@@ -0,0 +1,46 @@
+name: Setup the dependencies
+description: Check out the repo, install pinned Python and Poetry version, make deps
+
+inputs:
+  python-version:
+    description: Python version to install
+    required: false
+    default: "3.11"
+  poetry-version:
+    description: Poetry version to install
+    required: false
+    default: "2.3.3"
+
+runs:
+  using: composite
+  steps:
+    - name: Install python
+      id: setup-python
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ inputs.python-version }}
+    - name: Install poetry
+      id: setup-poetry
+      shell: sh
+      run: |
+        printf "\033[34;1m%s\033[0m: %s\n" "Python location" "$(command -v python)"
+        pipx install --python python poetry==${{ inputs.poetry-version }}
+        printf "\033[34;1m%s\033[0m: %s\n" "Poetry location" "$(command -v poetry)"
+        # Configure dependencies to install in venv
+        poetry config --no-interaction virtualenvs.create true
+        poetry config --no-interaction virtualenvs.in-project true
+    - name: Cache venv for OS, python, lockfile
+      id: cached-venv
+      uses: actions/cache@v5
+      with:
+        path: .venv
+        key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('poetry.lock') }}
+    - name: Install dependencies when uncached
+      if: ${{steps.cached-venv.outputs.cache-hit != 'true'}} # inexact = false
+      shell: sh
+      run: poetry -v install --no-interaction --no-root --with test --without dev
+    - name: Install project
+      shell: sh
+      run: poetry -v install --no-interaction --only-root
+
+# vim: set nowrap tw=100:

.github/workflows/lockfiles.yml

@@ -14,19 +14,20 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
-      - uses: actions/setup-python@v5
-        with:
-          python-version-file: .python-version
+      - uses: ./.github/actions/setup-poetry
 
-      - name: "Update Lockfiles and Open PR"
-        uses: tedivm/action-python-lockfile-update@v2
-        with:
-          pip_extras: "dev"
-          # This key will bypass workflow limitations to ensure tests are run.
-          # deploy_key: ${{ secrets.WRITEABLE_DEPLOY_KEY }}
+      - name: Update Lockfile
+        run: poetry update
 
+      - name: Open PR with updated lockfile
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "Update poetry.lock"
+          branch: chore/update-lockfile
+          title: "Update poetry.lock"
+          body: "Automated dependency update via `poetry update`."
+          delete-branch: true
         env:
-          # Needed to open pull request- automatically set for all actions.
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/push.yml

@@ -11,12 +11,12 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  pypi:
-    uses: ./.github/workflows/pypi.yml
-      #  doc:
-      #    uses: ./.github/workflows/doc.yml
+  test:
+    uses: ./.github/workflows/test.yml
+#  doc:
+#    uses: ./.github/workflows/doc.yml
   all:
-    needs: [pypi]
+    needs: [test]
     runs-on: ubuntu-latest
     steps:
       - name: Success

.github/workflows/test.yml

@@ -12,25 +12,26 @@ env:
 
 jobs:
   test:
-    name: ${{matrix.target}}
+    name: ${{matrix.python-version}}/${{matrix.target}}
     strategy:
       fail-fast: false
       matrix:
+        python-version: ["3.11"]
         target:
-          - black
           - mypy
           - pytest
-          - ruff
-          - tomlsort
+        include:
+          - target: pytest-cov
+            python-version: "3.14"
 
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - name: "Checkout repo"
+        uses: actions/checkout@v5
+      - name: "Set up dependencies and install"
+        uses: ./.github/actions/setup-poetry
         with:
-          python-version-file: .python-version
-      - name: Install Dependencies
-        run: make install
+          python-version: ${{matrix.python-version}}
       - name: Test
         run: make test/${{matrix.target}}
 

.gitignore

@@ -95,13 +95,6 @@ ipython_config.py
 #   install all needed dependencies.
 Pipfile.lock
 
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
 # pdm
 #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
 #pdm.lock

.pre-commit-config.yaml

@@ -4,6 +4,7 @@ repos:
     hooks:
       - id: check-added-large-files
         args: ['--maxkb=100']
+        exclude: '^poetry.lock$'
       - id: check-case-conflict
       - id: check-merge-conflict
       - id: check-shebang-scripts-are-executable

README.md

@@ -12,45 +12,35 @@ postprocessing utilities.
 
 # Development
 
-Development is a little weird if you're not used to modern python projects,
-especially because [python development and packaging evolves so
-quickly](https://dev.to/farcellier/i-migrate-to-poetry-in-2023-am-i-right--115).
-To isolate the development environment, `pyenv` and `pip`
-install a toolchain locally.
-
-## Setting up
-
-External dependencies (easily installed through [Homebrew](https://brew.sh/) or
-another package manager):
-- [pyenv](https://github.com/pyenv/pyenv), which will install its own python versions in an isolated environment
-
-After cloning the repository, run `make pre-commit` to:
-- Install the development version of python specified in `.python-version` to
-  your `pyenv` prefix (default: `~/.pyenv`, configurable with the `PYENV_ROOT`
-  variable)
-- Set up a virtual environment in `.venv` that will contain all the development
-  dependencies, including a `celerpy` symlink in its environment that will
-  point to your working copy
-- Install pre-commit hooks that use the tools just installed in your virtual
-  environment.
-
-## Testing and committing
-
-At this point you can modify the python code and run tests *without* having to
-reinstall the dependencies, and every `git commit` will run the tests
-automatically. (Use `git commit --no-verify` to disable.)
-
-The makefile specifies a few useful targets:
-- `style`: apply style fixups to all the python files in development
-- `test`: run tests
-- `pip`: reinstall all the dependencies in your virtual environment
-- `rebuild_dependencies`: update the `requirements` file if you add a new
-  dependency to `pyproject.toml`
-
-You can also test independently once your virtual environment is set up. For
-example, to run a single python test function from a single python test, with
-the most verbose output and sending stdout/stderr to the console, run:
+To isolate the development environment, this project uses
+[Poetry](https://python-poetry.org/) to manage dependencies, virtual
+environments, and lockfiles. A persistent development+CI environment is encoded
+into the distributed `poetry.lock` file. A simple `makefile` is included to
+configure and run for those not familiar with a Poetry envirnment workflow.
+
+## Setting up the first time
+
+Install Poetry using [Homebrew](https://brew.sh/) or [pipx](https://pipx.pypa.io/stable/how-to/install-pipx/).
+
+After cloning the celerpy repository and installing poetry, run `make setup` to:
+- install all project and development dependencies from `poetry.lock`, and
+- install pre-commit hooks.
+
+## Development and testing
+
+Activating the poetry environment will load the python version and all development dependencies. It is faster than manually invoking `poetry run` or using the included makefile.
+
 ```console
-$ . .venv/bin/activate
-$ pytest -vv -s test/test_process.py -k test_context
+$ eval $(poetry env activate)
+$ pytest test/
+$ mypy celerpy
+$ poetry run pytest -vv -s test/test_process.py -k test_context
 ```
+
+## Pre-commit hooks
+
+Style and linting should be performed automatically at every `git commit` after you run `make pre-commit`. They can also be invoked manually with `pre-commit run`. Use `git commit --no-verify` to disable temporarily for a particular commit. Pull requests automatically have their style checked and fixed via `pre-commit.ci`.
+
+## Release/versioning
+
+Not yet implemented:

celerpy/__init__.py

@@ -1,11 +1,11 @@
 # Copyright 2024 UT-Battelle, LLC, and other Celeritas developers.
 # See the top-level LICENSE file for details.
 # SPDX-License-Identifier: Apache-2.0
-try:
-    from . import _version  # type: ignore[attr-defined]
+from importlib.metadata import PackageNotFoundError, version
 
-    __version__ = _version.__version__
-except:  # noqa: E722
+try:
+    __version__ = version("celerpy")
+except PackageNotFoundError:
     __version__ = "0.0.0-dev"
 
 # Expose __version__ for type checkers

celerpy/cli.py

@@ -22,9 +22,9 @@ def load_settings():
 
 def print_version(value: bool):
     if value:
-        from . import _version
+        from . import __version__
 
-        typer.echo(_version.version)
+        typer.echo(__version__)
         raise typer.Exit()
 
 

celerpy/visualize.py

@@ -39,7 +39,7 @@ class WrappingListedColormap(ListedColormap):
     through the available colors and emit a warning.
     """
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
         self._warned: bool = False
 
@@ -87,8 +87,8 @@ class IdMapper:
     (so that new volumes "appear").
     """
 
-    def __init__(self):
-        self.id_to_volume = []
+    def __init__(self) -> None:
+        self.id_to_volume: list[str] = []
         self.volume_to_id = ReverseIndexDict(self.id_to_volume)
 
     def clear(self):