feat: type safety

.github/workflows/ci.yml

@@ -12,30 +12,57 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  pyright:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv run pyright --verbose
+
   test:
-    name: Test ${{ matrix.os }} py${{ matrix.python-version }} java${{ matrix.java-version }}
+    name: ${{ matrix.os }} py${{ matrix.python-version }} j${{ matrix.java-version }} bf${{ matrix.bioformats-version }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
         os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
         java-version: ["11"]
+        bioformats-version: [""]
         include:
+          # older java
           - os: ubuntu-latest
             python-version: "3.9"
             java-version: "8"
+          - os: windows-latest
+            python-version: "3.10"
+            java-version: "8"
+          # older bio-formats version
+          - os: ubuntu-latest
+            python-version: "3.9"
+            java-version: "8"
+            bioformats-version: "6.0.1"
+          # newer java
           - os: ubuntu-latest
             python-version: "3.11"
             java-version: "21"
+          # no java at all!
           - os: windows-latest
-            python-version: "3.10"
-            java-version: "8"
+            python-version: "3.13"
+            java-version: ""
+          - os: macos-latest
+            python-version: "3.12"
+            java-version: ""
+          - os: ubuntu-latest
+            python-version: "3.11"
+            java-version: ""
+
     env:
       UV_FROZEN: "1"
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
+        if: matrix.java-version != ''
         with:
           distribution: temurin
           java-version: ${{ matrix.java-version }}
@@ -44,6 +71,9 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Test
         run: uv run --group test --no-dev pytest -v --color yes --cov --cov-report=xml
+        env:
+          BIOFORMATS_VERSION: ${{matrix.bioformats-version}}
+
       - uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -110,4 +110,6 @@ ENV/
 .vscode/
 .idea/
 tests/data/
-bioformats/
+bioformats/
+stubs/
+uv.lock

.pre-commit-config.yaml

@@ -30,3 +30,5 @@ repos:
         # you have to add the things you want to type check against here
         additional_dependencies:
           - numpy
+          - git+https://github.com/tlambert03/scyjava-stubs#subdirectory=packages/ome-formats-gpl-stubs
+          - ome-types

README.md

@@ -2,23 +2,22 @@
 
 [![License](https://img.shields.io/pypi/l/bffile.svg?color=green)](https://github.com/tlambert03/bffile/raw/main/LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/bffile.svg?color=green)](https://pypi.org/project/bffile)
-[![Python Version](https://img.shields.io/pypi/pyversions/bffile.svg?color=green)](https://python.org)
+[![Python
+Version](https://img.shields.io/pypi/pyversions/bffile.svg?color=green)](https://python.org)
 [![CI](https://github.com/tlambert03/bffile/actions/workflows/ci.yml/badge.svg)](https://github.com/tlambert03/bffile/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/tlambert03/bffile/branch/main/graph/badge.svg)](https://codecov.io/gh/tlambert03/bffile)
 
-Yet another Bio-Formats wrapper for python
+Yet another [Bio-Formats](https://github.com/ome/bioformats) wrapper for python
+
+Bio-Formats is a Java library for reading and writing data in life sciences
+image file formats. This library provides a python interface to Bio-Formats.
 
 ## Installation
 
 ```bash
 pip install git+https://github.com/tlambert03/bffile
 ```
 
-### Install Java ...
-
-This package requires that you have java installed.  
-[INSERT GUIDELINES HERE]
-
 ## Usage
 
 ```python
@@ -30,3 +29,54 @@ with BioFile("tests/data/ND2_dims_p4z5t3c2y32x32.nd2") as bf:
     data = bf.to_numpy(series=1)
     print(data.shape, data.dtype)
 ```
+
+## Notes on Java, Maven, and Bio-Formats
+
+Because this library wraps the Java-based Bio-Formats library, it does require a
+JVM at runtime.
+
+> [!TIP]
+> Every attempt is made to make that as easy (and customizable) as possible.
+> **no additional action should be required by the user to use this package**.
+>
+> `pip install bffile` should be sufficient.
+
+Here's how it works:
+
+1. If you have Java installed, it will be detected and used.  This respects
+   standard environment variables like `JAVA_HOME` and `PATH`.
+2. If you don't have Java installed, the library will download a
+   [JRE](https://en.wikipedia.org/wiki/Java_Runtime_Environment) using the
+   [cjdk](https://pypi.org/project/cjdk/) package, and use it.
+   - By default, it will use [zulu-jre](https://www.azul.com/downloads/) version
+     11, but this can be customized by using the `JAVA_VENDOR` environment
+     variable to specify a different vendor, and/or the `JAVA_VERSION`
+     environment variable to specify a different version:
+
+        ```sh
+        export JAVA_VENDOR=temurin
+        export JAVA_VERSION=17
+        ```
+
+3. [`jgo`](https://github.com/scijava/jgo) is used to fetch java dependencies at
+   runtime.  This requires that `maven` is installed and on the `PATH`.  If you
+   don't already have `maven` installed, `cjdk` will be used to download it as
+   well.
+   - If you would like to customize the version of `maven` that is fetched, you
+   may use the `MAVEN_URL` and `MAVEN_SHA` variables.  for example:
+
+        ```sh
+        export MAVEN_URL = "https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz"
+        export MAVEN_SHA = "a555254d6b53d267965a3404ecb14e53c3827c09c3b94b5678835887ab404556bfaf78dcfe03ba76fa2508649dca8531c74bca4d5846513522404d48e8c4ac8b"
+        ```
+
+4. By default, the latest version of Bio-Formats (GPL) is fetched from maven
+   [maven](https://mvnrepository.com/artifact/ome/formats-gpl).  This
+   can also be customized by using the `BIOFORMATS_VERSION` environment variable
+   to specify a different version or license.  For example
+
+    ```sh
+    export BIOFORMATS_VERSION="6.13.0"
+    # or
+    export BIOFORMATS_VERSION="ome:formats-bsd:8.1"
+    ```

justfile

@@ -0,0 +1,2 @@
+build-stubs:
+    uv run scripts/stubgen.py 'ome:formats-gpl:RELEASE' --prefix loci --prefix ome --prefix java.io

pyproject.toml

@@ -13,14 +13,13 @@ name = "bffile"
 dynamic = ["version"]
 description = "Yet another Bio-Formats wrapper for python"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 license = { text = "BSD-3-Clause" }
 authors = [{ name = "Talley Lambert", email = "talley.lambert@gmail.com" }]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "License :: OSI Approved :: BSD License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -29,10 +28,11 @@ classifiers = [
 ]
 dependencies = [
     "numpy>=2.0.2",
-    "ome-types>=0.6.1",
+    "ome-types[pint,lxml]>=0.6.1",
     "scyjava>=1.10.2",
     "dask[array]>=2024.8.0",
     "resource-backed-dask-array>=0.1.0",
+    "cjdk>=0.3.0",
 ]
 
 [project.urls]
@@ -49,15 +49,16 @@ dev = [
     "mypy>=1.15.0",
     "pdbpp>=0.11.6 ; sys_platform != 'win32'",
     "pre-commit>=4.2.0",
-    "pyright>=1.1.399",
+    "pyright>=1.1.408",
     "rich>=14.0.0",
     "ruff>=0.11.6",
+    "types-requests>=2.32.0.20250328",
 ]
 
 # https://docs.astral.sh/ruff
 [tool.ruff]
 line-length = 88
-target-version = "py39"
+target-version = "py310"
 src = ["src"]
 
 # https://docs.astral.sh/ruff/rules
@@ -91,18 +92,31 @@ skip-magic-trailing-comma = false # default is false
 
 # https://mypy.readthedocs.io/en/stable/config_file.html
 [tool.mypy]
+mypy_path = "$MYPY_CONFIG_FILE_DIR/typings"
 files = "src/**/"
 strict = true
 disallow_any_generics = false
 disallow_subclassing_any = false
 show_error_codes = true
 pretty = true
 
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.10"
+enableExperimentalFeatures = true
+verboseOutput = true
+venv = ".venv"
+reportMissingModuleSource = "none"
+
 # https://docs.pytest.org/
 [tool.pytest.ini_options]
 minversion = "7.0"
 testpaths = ["tests"]
-filterwarnings = ["error"]
+filterwarnings = [
+    "error",
+    "ignore:Failing to pass a value to the 'type_params' parameter",
+    "ignore:Failed to retrieve OME XML:RuntimeWarning",
+]
 
 # https://coverage.readthedocs.io/
 [tool.coverage.report]
@@ -125,3 +139,6 @@ ignore = [".pre-commit-config.yaml", ".ruff_cache/**/*", "tests/**/*"]
 
 [tool.typos.default]
 extend-ignore-identifiers-re = ["(?i)nd2?.*", "(?i)ome", "AIMD"]
+
+[tool.uv.sources]
+ome-formats-gpl-stubs = { git = "https://github.com/tlambert03/scyjava-stubs", subdirectory = "packages/ome-formats-gpl-stubs" }