purl2repo

purl2repo resolves Package URLs (PURLs) to canonical repositories and optional version references. It is built for automation that needs a clear answer plus confidence, evidence, warnings, and candidate details.

Repositories are not assumed to be GitHub projects. A result can point to source code, a VCS URL, a generic URL, or an artifact hub such as Hugging Face.

Features

• Python API and purl2repo CLI.
• Typed dataclass results with stable JSON serialization.
• Evidence, warnings, confidence, and candidate scoring.
• Repository URL validation when network is available.
• Conservative release, tag, source, package, and revision links.
• Structured metadata first, deps.dev third-party fallback second, bounded HTML fallback only when needed.

Supported PURL Types

Full metadata-backed resolution:

• pkg:pypi
• pkg:npm
• pkg:cargo
• pkg:maven
• pkg:nuget
• pkg:golang

Direct or explicit repository resolution:

• pkg:github
• pkg:bitbucket
• pkg:generic
• pkg:huggingface
• pkg:mlflow

See docs/ecosystems.md for exact behavior by ecosystem and PURL type.

Installation

pip install purl2repo

Requires Python 3.11 or newer.

Quickstart

from purl2repo import resolve

result = resolve("pkg:pypi/requests@2.31.0")

print(result.repository_url)
print(result.repository_kind)
print(result.confidence)
print(result.evidence)

Reusable resolver:

from purl2repo import Resolver

with Resolver(timeout=15.0, use_cache=True) as resolver:
    results = list(
        resolver.resolve_many(
            [
                "pkg:pypi/requests@2.31.0",
                "pkg:npm/react@18.2.0",
                "pkg:huggingface/distilbert-base-uncased@043235d6088ecd3dd5fb5ca3592b6913fd516027",
            ]
        )
    )

    parallel_results = list(
        resolver.resolve_many(
            [
                "pkg:pypi/requests@2.31.0",
                "pkg:npm/react@18.2.0",
            ],
            max_workers=4,
        )
    )

CLI

purl2repo parse pkg:pypi/requests@2.31.0
purl2repo resolve pkg:pypi/requests@2.31.0
purl2repo resolve pkg:huggingface/distilbert-base-uncased@043235d6088ecd3dd5fb5ca3592b6913fd516027
purl2repo repo pkg:npm/react
purl2repo release pkg:cargo/rand@0.8.5
purl2repo supports
purl2repo version

JSON and trace output:

purl2repo resolve pkg:pypi/requests@2.31.0 --json --pretty
purl2repo resolve pkg:npm/react@18.2.0 --trace

See docs/cli.md for all commands, flags, and exit codes.

Output

resolve() returns a ResolutionResult.

The main fields are:

• canonical_repository: full RepositoryRef with URL, kind, platform, host, namespace, name, confidence, and reasons.
• repository_url: convenience URL for the canonical repository.
• repository_kind: source_code, artifact_hub, vcs, generic, or related repository class.
• version_reference: verified or inferred version-specific link when available.
• repository_validated and repository_validation_status: whether the selected repository URL was checked, skipped, inconclusive, or not applicable.
• confidence, evidence, warnings, and repository_candidates.

See docs/api.md, docs/scoring.md, and docs/architecture.md for the full contract.

Examples

Hugging Face resolves to Hugging Face as the canonical artifact hub, even when a PURL qualifier points elsewhere:

purl2repo resolve 'pkg:huggingface/microsoft/deberta-v3-base@559062ad13d311b87b2c455e67dcd5f1c8f65111?repository_url=https://hub-ci.huggingface.co'

Generic PURLs use explicit qualifiers:

purl2repo resolve 'pkg:generic/example@1.0.0?vcs_url=git+https://github.com/org/repo.git'

MLflow PURLs need an explicit registry or tracking endpoint:

purl2repo resolve 'pkg:mlflow/trafficsigns@10?repository_url=https://adb-5245952564735461.0.azuredatabricks.net/api/2.0/mlflow'

Versionless PURLs are valid:

purl2repo resolve pkg:pypi/requests

Documentation

• Architecture
• API
• CLI
• Ecosystems
• PURL support
• Scoring
• Migration from v1
• Development
• Release process

Development

python3.11 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/mypy
.venv/bin/pytest --cov=purl2repo --cov-report=term-missing --cov-fail-under=90

Live integration tests are separate:

.venv/bin/pytest tests/integration -m integration

See CONTRIBUTING.md and docs/development.md for contributor guidance.

License

Apache-2.0. See LICENSE.