ComfyUI-Manager/tests/common/pip_util/DEPENDENCY_TREE_CONTEXT.md

Dependency Tree Context for pip_util Tests

Generated: 2025-10-01 Tool: pip install --dry-run --ignore-installed Python: 3.12.3 pip: 25.2

This document provides detailed dependency tree information for all test packages, verified against real PyPI data. Use this as a reference when extending tests.

---

Table of Contents

1. Current Test Environment
2. Package Dependency Trees
3. Version Analysis
4. Upgrade Scenarios
5. Adding New Test Scenarios

---

Current Test Environment

Base packages installed in test_venv (from requirements-test-base.txt):

urllib3==1.26.15           # Protected from 2.x upgrade
certifi==2023.7.22         # Protected from 2025.x upgrade
charset-normalizer==3.2.0  # Protected from 3.4.x upgrade
six==1.16.0                # For deletion/restore tests
attrs==23.1.0              # Bystander package
packaging==23.1            # Bystander package
pytest==8.4.2              # Test framework

Total environment size: ~913KB (all packages < 1MB)

---

Package Dependency Trees

1. requests → Dependencies

Package: requests==2.32.5 Size: ~100KB Purpose: Main test package for dependency protection

Dependency Tree

requests==2.32.5
├── charset-normalizer<4,>=2
│   └── 3.2.0 (OLD) → 3.4.3 (LATEST)
├── idna<4,>=2.5
│   └── (NOT INSTALLED) → 3.10 (LATEST)
├── urllib3<3,>=1.21.1
│   └── 1.26.15 (OLD) → 2.5.0 (LATEST) ⚠️ MAJOR VERSION JUMP
└── certifi>=2017.4.17
    └── 2023.7.22 (OLD) → 2025.8.3 (LATEST)

Install Scenarios

Scenario A: Without constraints (fresh install)

$ pip install --dry-run --ignore-installed requests

Would install:
  certifi-2025.8.3           # Latest version
  charset-normalizer-3.4.3   # Latest version
  idna-3.10                  # New dependency
  requests-2.32.5            # Target package
  urllib3-2.5.0              # Latest version (2.x!)

Scenario B: With pin constraints

$ pip install --dry-run requests \
    urllib3==1.26.15 \
    certifi==2023.7.22 \
    charset-normalizer==3.2.0

Would install:
  certifi-2023.7.22          # Pinned to OLD version
  charset-normalizer-3.2.0   # Pinned to OLD version
  idna-3.10                  # New dependency (not pinned)
  requests-2.32.5            # Target package
  urllib3-1.26.15            # Pinned to OLD version

Impact Analysis:

• ✅ Pin successfully prevents urllib3 1.x → 2.x major upgrade
• ✅ Pin prevents certifi 2023 → 2025 upgrade (2 years)
• ✅ Pin prevents charset-normalizer minor upgrade
• ⚠️ idna is NEW and NOT pinned (acceptable - new dependency)

---

2. python-dateutil → Dependencies

Package: python-dateutil==2.9.0.post0 Size: ~280KB Purpose: Real dependency chain test (depends on six)

Dependency Tree

python-dateutil==2.9.0.post0
└── six>=1.5
    └── 1.16.0 (OLD) → 1.17.0 (LATEST)

Install Scenarios

Scenario A: Without constraints

$ pip install --dry-run --ignore-installed python-dateutil

Would install:
  python-dateutil-2.9.0.post0  # Target package
  six-1.17.0                   # Latest version

Scenario B: With pin constraints

$ pip install --dry-run python-dateutil six==1.16.0

Would install:
  python-dateutil-2.9.0.post0  # Target package
  six-1.16.0                   # Pinned to OLD version

Impact Analysis:

• ✅ Pin successfully prevents six 1.16.0 → 1.17.0 upgrade
• ✅ Real dependency relationship (verified via PyPI)

---

3. Other Test Packages (No Dependencies)

These packages have no dependencies or only have dependencies already in the test environment:

attrs==23.1.0         # No dependencies
packaging==23.1       # No dependencies (standalone)
six==1.16.0           # No dependencies (pure Python)

---

Version Analysis

urllib3: Major Version Jump (1.x → 2.x)

Current: 1.26.15 (2023) Latest: 2.5.0 (2025) Breaking Changes: YES - urllib3 2.0 removed deprecated APIs

Available versions:

2.x series: 2.5.0, 2.4.0, 2.3.0, 2.2.3, 2.2.2, 2.2.1, 2.2.0, 2.1.0, 2.0.7, ...
1.26.x:     1.26.20, 1.26.19, 1.26.18, 1.26.17, 1.26.16, 1.26.15, ...
1.25.x:     1.25.11, 1.25.10, 1.25.9, ...

Why test with 1.26.15?

• ✅ Real-world scenario: Many projects pin urllib3<2 to avoid breaking changes
• ✅ Meaningful test: 1.x → 2.x is a major API change
• ✅ Compatibility: requests accepts both 1.x and 2.x (urllib3<3,>=1.21.1)

Breaking changes in urllib3 2.0:

• Removed urllib3.contrib.pyopenssl
• Removed urllib3.contrib.securetransport
• Changed import paths for some modules
• Updated connection pooling behavior

---

certifi: Long-Term Version Gap (2023 → 2025)

Current: 2023.7.22 (July 2023) Latest: 2025.8.3 (August 2025) Gap: ~2 years of SSL certificate updates

Available versions:

2025: 2025.8.3, 2025.7.14, 2025.7.9, 2025.6.15, 2025.4.26, ...
2024: 2024.12.25, 2024.11.28, 2024.10.29, 2024.9.19, ...
2023: 2023.11.17, 2023.7.22, 2023.5.7, ...

Why test with 2023.7.22?

• ✅ Real-world scenario: Older environments with outdated SSL certificates
• ✅ Meaningful test: 2-year gap shows protection of older versions
• ✅ Safety: Still compatible with requests (certifi>=2017.4.17)

---

charset-normalizer: Minor Version Updates

Current: 3.2.0 (2023) Latest: 3.4.3 (2025) Breaking Changes: NO - only minor/patch updates

Available versions:

3.4.x: 3.4.3, 3.4.2, 3.4.1, 3.4.0
3.3.x: 3.3.2, 3.3.1, 3.3.0
3.2.x: 3.2.0

Why test with 3.2.0?

• ✅ Demonstrates protection of minor version updates
• ✅ Compatible with requests (charset-normalizer<4,>=2)

---

six: Stable Version Update

Current: 1.16.0 (2021) Latest: 1.17.0 (2024) Breaking Changes: NO - six is very stable

Available versions:

1.17.0, 1.16.0, 1.15.0, 1.14.0, 1.13.0, 1.12.0, ...

Why test with 1.16.0?

• ✅ Real dependency of python-dateutil
• ✅ Small size (11KB) - lightweight for tests
• ✅ Demonstrates protection of stable packages

---

idna: New Dependency

Not pre-installed - Added by requests

Version: 3.10 Size: ~69KB Dependency spec: idna<4,>=2.5 (from requests)

Why NOT pre-installed?

• ✅ Tests that new dependencies are correctly added
• ✅ Tests that pins only affect specified packages
• ✅ Real-world scenario: new dependency introduced by package update

---

Upgrade Scenarios

Scenario Matrix

Package	Initial	Without Pin	With Pin	Change Type
urllib3	1.26.15	2.5.0 ❌	1.26.15 ✅	Major (breaking)
certifi	2023.7.22	2025.8.3 ❌	2023.7.22 ✅	2-year gap
charset-normalizer	3.2.0	3.4.3 ❌	3.2.0 ✅	Minor update
six	1.16.0	1.17.0 ❌	1.16.0 ✅	Stable update
idna	(none)	3.10 ✅	3.10 ✅	New dependency
requests	(none)	2.32.5 ✅	2.32.5 ✅	Target package
python-dateutil	(none)	2.9.0 ✅	2.9.0 ✅	Target package

---

Adding New Test Scenarios

Step 1: Identify Candidate Package

Use pip install --dry-run to analyze dependencies:

# Analyze package dependencies
./test_venv/bin/pip install --dry-run --ignore-installed PACKAGE

# Check what changes with current environment
./test_venv/bin/pip install --dry-run PACKAGE

# List available versions
./test_venv/bin/pip index versions PACKAGE

Step 2: Verify Real Dependencies

Good candidates:

• ✅ Has 2+ dependencies
• ✅ Dependencies have version upgrades available
• ✅ Total size < 500KB (all packages combined)
• ✅ Real-world use case (popular package)

Examples:

# flask → click, werkzeug, jinja2 (good: multiple dependencies)
$ pip install --dry-run --ignore-installed flask
Would install: Flask-3.1.2 Jinja2-3.1.6 MarkupSafe-3.0.3 Werkzeug-3.1.3 blinker-1.9.0 click-8.3.0 itsdangerous-2.2.0

# pytest-cov → pytest, coverage (good: popular testing tool)
$ pip install --dry-run --ignore-installed pytest-cov
Would install: coverage-7.10.7 pytest-8.4.2 pytest-cov-7.0.0

Bad candidates:

• ❌ click → colorama (no real dependency - colorama is optional/Windows-only)
• ❌ pandas → numpy (too large - numpy is 50MB+)
• ❌ torch → ... (too large - 800MB+)

Step 3: Document Dependencies

Add to this file:

### Package: PACKAGE_NAME → Dependencies

**Package**: `PACKAGE==VERSION`
**Size**: ~XXXKB
**Purpose**: Brief description

#### Dependency Tree
(Use tree format)

#### Install Scenarios
(Show with/without pin)

#### Impact Analysis
(What does pin protect?)

Step 4: Update Test Files

1. Add package to requirements-test-base.txt (if pre-installation needed)
2. Create policy fixture in test file
3. Write test function using reset_test_venv fixture
4. Update TEST_SCENARIOS.md with detailed scenario

---

Maintenance Notes

Updating This Document

Re-run analysis when:

• ✅ PyPI releases major version updates (e.g., urllib3 3.0)
• ✅ Adding new test packages
• ✅ Test environment base packages change
• ✅ Every 6 months (to catch version drift)

Verification Commands

# Regenerate dependency tree
./test_venv/bin/pip install --dry-run --ignore-installed requests
./test_venv/bin/pip install --dry-run --ignore-installed python-dateutil

# Check current environment
./test_venv/bin/pip freeze

# Verify test packages still available on PyPI
./test_venv/bin/pip index versions urllib3
./test_venv/bin/pip index versions certifi
./test_venv/bin/pip index versions six

---

Quick Reference: Package Specs

From actual package metadata:

# requests dependencies (from requests==2.32.5)
install_requires = [
    "charset_normalizer<4,>=2",
    "idna<4,>=2.5",
    "urllib3<3,>=1.21.1",
    "certifi>=2017.4.17"
]

# python-dateutil dependencies (from python-dateutil==2.9.0)
install_requires = [
    "six>=1.5"
]

# six dependencies
install_requires = []  # No dependencies

# attrs dependencies
install_requires = []  # No dependencies

# packaging dependencies
install_requires = []  # No dependencies

---

Version Compatibility Table

Package	Minimum	Maximum	Current Test	Latest	Notes
urllib3	1.21.1	<3.0	1.26.15	2.5.0	Major version jump possible
certifi	2017.4.17	(none)	2023.7.22	2025.8.3	Always backward compatible
charset-normalizer	2.0	<4.0	3.2.0	3.4.3	Within major version
six	1.5	(none)	1.16.0	1.17.0	Very stable
idna	2.5	<4.0	(new)	3.10	Added by requests

---

See Also

• DEPENDENCY_ANALYSIS.md - Detailed analysis methodology
• TEST_SCENARIOS.md - Complete test scenario specifications
• requirements-test-base.txt - Base environment packages
• README.md - Test suite overview and usage