purl2meta

Resolve Package URLs (purl) to registry metadata API URLs.

Given a purl like pkg:pypi/requests@2.28.0, purl2meta returns the corresponding registry API endpoint — https://pypi.org/pypi/requests/2.28.0/json — so you can fetch package metadata without hardcoding registry-specific URL patterns.

Installation

pip install purl2meta

To also fetch metadata over HTTP (installs httpx):

pip install purl2meta[fetch]

Quick start

Get a metadata URL

from purl2meta import get_metadata_url

get_metadata_url("pkg:pypi/requests@2.28.0")
# => "https://pypi.org/pypi/requests/2.28.0/json"

get_metadata_url("pkg:npm/express@4.18.2")
# => "https://registry.npmjs.org/express/4.18.2"

get_metadata_url("pkg:maven/org.apache.commons/commons-io@1.3.2")
# => "https://repo.maven.apache.org/maven2/org/apache/commons/commons-io/1.3.2/commons-io-1.3.2.pom"

get_metadata_url("pkg:cargo/serde@1.0.193")
# => "https://crates.io/api/v1/crates/serde/1.0.193"

Returns None for unsupported types or purls missing required fields.

Fetch metadata directly

Requires the [fetch] extra.

from purl2meta import get_metadata

data = get_metadata("pkg:pypi/requests@2.28.0")
# => {"info": {"name": "requests", "version": "2.28.0", ...}, "urls": [...], ...}

data = get_metadata("pkg:npm/express@4.18.2")
# => {"name": "express", "version": "4.18.2", "dependencies": {...}, ...}

get_metadata resolves the URL, sends an HTTP GET, and returns parsed JSON (or raw text for non-JSON responses like Maven POM files). Returns None if the purl type is unsupported.

Supported package types

API reference

get_metadata_url(purl: str) -> str | None

Return the metadata API URL for the given purl string, or None if the type is unsupported or required fields are missing.

get_metadata(purl: str) -> dict | str | None

Fetch metadata from the registry. Returns parsed JSON as a dict, raw text for non-JSON responses (e.g. Maven POM XML), or None if unsupported. Requires httpx.

metadata_router

The underlying Router instance. Use it to register custom routes:

from packageurl import PackageURL
from purl2meta import metadata_router

@metadata_router.route("pkg:custom/.*")
def build_custom_metadata_url(purl):
    purl_data = PackageURL.from_string(purl)
    return f"https://my-registry.example.com/api/{purl_data.name}"

Development

git clone <repo-url>
cd purl2meta

# Run tests
uv run --with pytest --with httpx python -m pytest tests/ -v

License

MIT