Dependency Deprecation Pattern

Experiment Overview

Context

KINTSUGI originally depended on Java/Maven for PyImageJ and CLIJ2 GPU processing. This created installation friction and cross-platform issues. The goal was to replace these with pure Python implementations (CuPy/NumPy) while allowing legacy users to continue using Java if needed.

Verified Workflow

Step 1: Identify all dependency touchpoints

Search for all references to the dependency:

# Search code
grep -r "java\|Java\|FIJI\|fiji\|clij\|CLIJ\|maven\|Maven\|ImageJ\|imagej" src/ notebooks/

# Check configuration files
grep -r "java\|openjdk\|maven" envs/ pyproject.toml

Files typically affected:

• pyproject.toml - optional dependencies
• envs/*.yml - conda environment files
• src/*/deps.py - dependency checker
• docs/*.md - documentation
• Core modules using the dependency

Step 2: Update the core module with deprecation

# Example: edf.py - deprecating CLIJ2 backend

import warnings
from typing import Literal

BackendType = Literal["auto", "cupy", "numpy", "clij2"]

def _detect_backend(self, requested: BackendType) -> str:
    """Detect best available backend."""
    if requested == "clij2":
        warnings.warn(
            "CLIJ2 backend is deprecated and will be removed in v2.0. "
            "Use 'cupy' or 'numpy' instead.",
            DeprecationWarning,
            stacklevel=2
        )
        # Still allow it to work for now
        if self._check_clij2_available():
            return "clij2"
        else:
            warnings.warn("CLIJ2 not available, falling back to cupy")
            requested = "auto"

    if requested == "auto":
        # NEW priority order: CuPy > NumPy (CLIJ2 excluded from auto)
        if self._check_cupy_available():
            return "cupy"
        return "numpy"

    return requested

Step 3: Update dependency checker

# deps.py - mark as deprecated but keep functional

def _check_java(self, verbose: bool):
    """Check Java installation.

    .. deprecated::
        Java/Maven dependencies are no longer required for core functionality.
        Kept for backward compatibility with legacy CLIJ2 workflows.
    """
    if verbose:
        print("\n[Java/Maven] (DEPRECATED - no longer required)")

    # Still check and report, but don't fail
    try:
        # ... existing check code ...
        if verbose:
            print(f"  [OK]       java v{version} (optional)")
    except Exception as e:
        if verbose:
            print(f"  [SKIP]     java (optional, not required)")

Step 4: Update pyproject.toml

[project.optional-dependencies]
# Keep the optional group but exclude from [full]
java = [
    "JPype1>=1.5.0",
    "scyjava>=1.0.0",
    "pyimagej>=1.4.0",
]

# Remove java from full install
full = [
    "kintsugi[gpu,viz,dl,analysis,bio]",  # Note: java excluded
]

Step 5: Update environment files

# envs/env-*.yml - comment out with deprecation note

# Java/ImageJ Integration (DEPRECATED - no longer required)
# Uncomment if you need legacy CLIJ2 support:
# - openjdk=11
# - maven
# - jpype1

Step 6: Update documentation

Add deprecation notices to all relevant docs:

> **Note:** Java, Maven, and FIJI are no longer required. KINTSUGI now uses
> pure Python implementations (CuPy/NumPy) for all processing including EDF.

For historical documents, add a header:

> **DEPRECATION NOTICE (2025):** This document is historical. Java/Maven/FIJI
> dependencies have been removed. See `src/kintsugi/edf.py` for current implementation.

Failed Attempts (Critical)

Key Insights

• Gradual deprecation: Mark as deprecated first, remove in next major version
• Keep it working: Deprecated doesn't mean broken - users need time to migrate
• Clear warnings: Use Python's warnings.warn() with DeprecationWarning
• Document the alternative: Every deprecation notice should say what to use instead
• Update ALL touchpoints: Code, configs, docs, environment files, README
• Test both paths: Verify deprecated code still works AND new code works

Checklist for Dependency Deprecation

• Search entire codebase for dependency references
• Add deprecation warnings to code using the dependency
• Update auto-detection to prefer new implementation
• Keep optional dependency group but exclude from [full]
• Comment out in environment files with explanation
• Update installation documentation
• Add deprecation notices to historical docs
• Update CLAUDE.md / project documentation
• Test deprecated path still works
• Test new path works
• Update changelog/release notes

References

• Python deprecation warnings: https://docs.python.org/3/library/warnings.html
• Semantic versioning for breaking changes: https://semver.org/
• PEP 387 - Backwards Compatibility Policy: https://peps.python.org/pep-0387/