API Reference

depwhy can be used as a Python library. The main entry point is depwhy.analyze().

Import

python
import depwhy
# or
from depwhy import analyze

Function Signature

python
def analyze(
  source: str | list[str] | os.PathLike[str],
  *,
  python_version: str | None = None,
  platform: str | None = None,
  offline: bool = False,
  cache_ttl_hours: int = 24,
  max_concurrency: int = 10,
) -> ConflictReport:

Parameters

source

The dependency source. Can be:

  • A list[str] of PEP 508 requirement strings (e.g., ["requests>=2.28", "urllib3==1.26.0"])
  • A str path to a requirements.txt file
  • A str or os.PathLike path to a pyproject.toml file

python_version (keyword-only)

Target Python version for marker evaluation, e.g. "3.11". Defaults to the running interpreter.

platform (keyword-only)

Target platform for marker evaluation, e.g. "linux". Defaults to the current platform.

offline (keyword-only)

If True, only use cached metadata. No network requests will be made.

cache_ttl_hours (keyword-only)

Hours before cached PyPI metadata is considered stale. Default: 24.

max_concurrency (keyword-only)

Max concurrent HTTP requests to PyPI. Default: 10.

Returns

A ConflictReport object containing detected conflicts, warnings, and fix suggestions.

Raises

  • FileNotFoundError — If source is a file path that doesn't exist.
  • ValueError — If the source file can't be parsed.

Usage Examples

Analyze a requirements file

python
import depwhy

report = depwhy.analyze("requirements.txt")

if report.has_conflicts:
  for conflict in report.conflicts:
      print(conflict.package)
      print(f"  Problem:     {conflict.problem}")
      print(f"  Solution:    {conflict.solution.description}")
      print(f"               {conflict.solution.pip_command}")
      if conflict.alternative:
          print(f"  Alternative: {conflict.alternative.description}")
          print(f"               {conflict.alternative.pip_command}")
else:
  print(f"No conflicts found ({report.analyzed_packages} packages checked)")

Analyze a list of requirements

python
report = depwhy.analyze(["django>=4.0", "celery==5.2", "kombu==5.3"])

With Python version and platform

python
report = depwhy.analyze(
  "requirements.txt",
  python_version="3.11",
  platform="linux",
)

Offline mode

python
report = depwhy.analyze("requirements.txt", offline=True)

The analyze() function is synchronous but internally uses asyncio for parallel PyPI fetches.

offline=True requires a warm cache from a previous online run.