Merge pull request #42 from AllenCell/feature/example-venv

Example environment with camera-alignment-core 0.6.0

Author: pgarrison

README.md

@@ -137,6 +137,10 @@ see `Makefile` for others or to inspect the underlying scripts run as part of th
     3. make publish: to publish to artifactory.  Requires a ~/.pypirc file with an entry like:
         [release-local]
         repository = https://artifactory.corp.alleninstitute.org/artifactory/api/pypi/pypi-release-local
+    4. Update the example-venv lockfile to use the new release.
+        1. [Install uv](https://docs.astral.sh/uv/getting-started/installation/)
+        2. `cd example-venv && uv lock && uv sync`
+        3. `uv pip list | grep camera-alignment-core` (This should show the new version.)
 
 
 **Allen Institute Software License**

example-venv/.python-version

@@ -0,0 +1 @@
+3.11

example-venv/README.md

@@ -0,0 +1,18 @@
+# An example virtual environment for using camera-alignment-core
+
+## What's here
+This `example-venv` folder contains the following example files.
+* `pyproject.toml`: This is the main definition of the example project, which defines a single dependency, `camera-alignment-core`. The `pyproject.toml` is set up to work with the [uv](https://docs.astral.sh/uv/) package manager.
+* `.python-version`: Tells tools like `uv` or `pyenv` which python version to use. This is different from the `requires-python` line in `pyproject.toml`, which defines the range of versions that are expected to work.
+* `uv.lock`: This uv-specific file defines the exact versions of all dependencies needed for the project (including indirect dependencies). This file is generated by `uv` from the `pyproject.toml` and must be re-generated whenever the `pyproject.toml` changes. This file is what makes the virtual environment reproducible.
+
+## How to use it
+1. Copy the `example-venv` folder somewhere else, let's say `~/my-project`.
+2. [Install uv](https://docs.astral.sh/uv/getting-started/installation/).
+3. Create and test the environment.
+    1. `cd ~/my-project`
+    2. `uv sync`
+    3. `uv run python -c "import camera_alignment_core"`
+4. Add your own dependencies: `uv add pytorch`.
+5. Customize the metadata at the top of `pyproject.toml` for your project.
+6. Put your code in `~/my-project` and run it with `uv run`.

example-venv/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "example-venv"
+version = "0.1.0"
+description = "Virtual environment with camera-alignment-core"
+readme = "README.md"
+requires-python = ">=3.8,<3.12"
+dependencies = [
+    # One main dependency for this example virtual environment
+    "camera-alignment-core",
+    # numcodecs is an indirect dependency of aicsimageio, and recent versions
+    # of numcodecs are incompatible with the version of zarr needed by
+    # aicsimageio. aicsimageio is deprecated, and ultimately this
+    # pin should be made unnecessary by upgrading camera-alignment-core to use
+    # bioio.
+    "numcodecs<=0.15.0",
+]
+license = { text = "BSD-3-Clause" }
+
+[tool.uv.sources]
+# There are two internal-only dependencies: get these from Artifactory
+aicsfiles = { index = "artifactory" }
+camera-alignment-core = { index = "artifactory" }
+
+[[tool.uv.index]]
+name = "artifactory"
+url = "https://artifactory.corp.alleninstitute.org/artifactory/api/pypi/pypi-snapshot-local/simple"
+# The `explicit = true` ensures that the default index (usually PyPi) is used
+# for all packages not explicitly listed in `tool.uv.sources`.
+explicit = true