v2.0.0

UniDep v2.0.0 Release Notes

Breaking Changes

New local_dependencies Schema

The local_dependencies field now supports an enhanced dictionary format with new capabilities for controlling dependency resolution.

Compatibility:

• v2.0.0 is backward compatible: Can read all v1.x requirements.yaml files
• v1.x is NOT forward compatible: Cannot read v2.0.0 files that use the new dictionary format

This means:

• Upgrading from v1.x to v2.0.0 is safe - all existing files will work
• Files using the new dictionary format will cause errors in v1.x
• Simple string format continues to work in both versions

What Changed:

Previously, local_dependencies only accepted simple path strings:

local_dependencies:
  - ../shared-lib
  - ../auth-lib

Now, local_dependencies supports both the simple string format AND a new dictionary format with optional pypi and use fields:

local_dependencies:
  # Simple string format (still supported)
  - ../shared-lib

  # New dictionary format with PyPI alternative
  - local: ../auth-lib
    pypi: company-auth-lib>=1.0

  # New dictionary format with use control
  - local: ../utils
    pypi: company-utils~=2.0
    use: pypi  # Force PyPI even during development

Migration Guide:

No changes required. All existing requirements.yaml and pyproject.toml files will continue to work unchanged in v2.0.0.

New Features

1. PyPI Alternatives for Local Dependencies

Problem Solved: Building portable wheels from monorepos with local dependencies.

Solution: Specify both a local path (for development) and a PyPI package (for distribution):

local_dependencies:
  - local: ../shared-lib
    pypi: company-shared-lib>=1.0

How it works:

• During development (unidep install, pip install -e .): Uses the local path
• When building wheels: Uses the PyPI alternative to create portable packages
• Set UNIDEP_SKIP_LOCAL_DEPS=1 to force PyPI alternatives even during development

Reference: PyPI Alternatives for Local Dependencies

2. Local Dependency Use Modes

Problem Solved: Handling conflicting nested vendor copies in git submodules and controlling dependency resolution.

Solution: The new use field controls how UniDep processes each local dependency:

use value	Behavior	Use case
local (default)	Install from local path with recursion	Normal development
pypi	Force PyPI package, skip local path	Override nested vendor copies
skip	Ignore completely	Temporarily disable dependencies

Example - Overriding nested vendor copies:

local_dependencies:
  # Keep foo editable
  - ./third_party/foo

  # Force YOUR PyPI build of bar (overrides foo's bundled version)
  - local: ./third_party/foo/third_party/bar
    pypi: my-bar>=2.0
    use: pypi

Example - Skipping dependencies:

local_dependencies:
  - ./third_party/foo  # foo has bar in its local_dependencies

  # Skip bar even though foo pins it
  # Prevents bar from being installed despite foo's dependency on it
  - local: ./third_party/foo/third_party/bar
    use: skip

Key feature: Overrides (both pypi and skip) propagate to all nested references of the same path automatically. This is especially useful when a nested dependency pins a package you want to exclude.

Reference: Overriding Nested Vendor Copies

3. Enhanced Documentation

• Build System Differences: Documented how Setuptools and Hatchling handle local dependencies differently
• UNIDEP_SKIP_LOCAL_DEPS: Comprehensive documentation of the environment variable and its use cases
• New FAQ Entries:
  • How to force PyPI instead of local paths
  • How to ignore local dependencies
  • How to handle nested vendor copy conflicts

Bug Fixes

Windows File URI Handling (#262)

Fixed incorrect file URI generation on Windows for local dependencies.

Problem: Local dependencies on Windows were using incorrect URI format (file:///C:/path instead of file:///C:/path).

Impact: Local dependencies failed to install correctly on Windows systems.

Fix: Properly handle Windows path-to-URI conversion following RFC 8089.

Improvements

Hatch Metadata Configuration (#248)

Added missing allow-direct-references configuration for Hatch projects to properly support local dependencies with PyPI alternatives.

[tool.hatch.metadata]
allow-direct-references = true

Testing

• Added 1,900+ lines of new tests covering all PyPI alternatives scenarios
• Added comprehensive integration tests for use field modes
• Added tests for Windows file URI handling
• Test coverage: 97.24%

Documentation Updates

• 200+ lines of new documentation in README
• Added visual examples for nested vendor copy scenarios
• Enhanced FAQ with practical use cases
• Documented migration paths for breaking changes

Upgrade Instructions

From v1.x to v2.0.0

1. Upgrade is safe - no breaking changes for existing files

   • v2.0.0 can read all v1.x requirements.yaml files
   • Simple string paths continue to work unchanged
   • No action required to upgrade

2. Team coordination if using new features

   • If you use the new dictionary format, all team members must upgrade to v2.0.0
   • v1.x cannot read files with {local: ..., pypi: ...} format
   • Consider phased rollout: upgrade everyone before using new features

3. If building wheels for distribution

   • Consider adding pypi alternatives for portable builds
   • See PyPI Alternatives for Local Dependencies

4. If using git submodules with vendored dependencies

   • Use use: pypi to override nested vendor copies
   • See Overriding Nested Vendor Copies

5. Update your build commands (optional)

   • Use UNIDEP_SKIP_LOCAL_DEPS=1 for portable wheel builds
   • See Build System Behavior

Full Changelog

See the full diff for all changes.

---

Note: This is v2.0.0 (major version bump) because:

• The file format schema has changed (old versions cannot read new format)
• This signals to users that team coordination may be needed
• Following semantic versioning: v1.x users must upgrade before using new features
• Even though v2.0.0 is fully backward compatible with v1.x files, the lack of forward compatibility justifies the major version increment