pypi

Documentation

Overview

Package pypi provides an HTTP client for the Python Package Index API.

Overview

This package fetches package metadata from PyPI (https://pypi.org), the official repository for Python packages.

Usage

client, err := pypi.NewClient(24 * time.Hour)  // Cache TTL
if err != nil {
    log.Fatal(err)
}

pkg, err := client.FetchPackage(ctx, "fastapi", false)  // false = use cache
if err != nil {
    log.Fatal(err)
}

fmt.Println(pkg.Name, pkg.Version)
fmt.Println("Dependencies:", pkg.Dependencies)

PackageInfo

[FetchPackage] returns a PackageInfo containing:

• Name, Version: Package identity
• Dependencies: Direct runtime dependencies (extras/dev filtered out)
• Summary: Package description
• License, Author: Package metadata
• ProjectURLs, HomePage: Links for enrichment

Caching

Responses are cached to reduce load on PyPI and speed up repeated requests. The cache TTL is set when creating the client. Pass refresh=true to [FetchPackage] to bypass the cache.

Dependency Filtering

Dependencies are extracted from requires_dist, filtering out:

• Optional extras (extra markers)
• Development dependencies (dev markers)
• Test dependencies (test markers)

Package names are normalized following PEP 503.

Index

• Constants
• func CheckPythonVersion(pythonVersion, requiresPython string) bool
• type Client
  • func NewClient(backend cache.Cache, cacheTTL time.Duration, pythonVersion string) *Client
  • func (c *Client) FetchPackage(ctx context.Context, pkg string, refresh bool) (*PackageInfo, error)
  • func (c *Client) FetchPackageVersion(ctx context.Context, pkg, version string, refresh bool) (*PackageInfo, error)
  • func (c *Client) ListVersions(ctx context.Context, pkg string, refresh bool) ([]string, error)
  • func (c *Client) ListVersionsWithConstraints(ctx context.Context, pkg string, refresh bool) (map[string]string, error)
• type Dependency
• type PackageInfo
  • func (p *PackageInfo) IsCompatibleWith(pythonVersion string) bool

Constants

const DefaultPythonVersion = "3.11"

DefaultPythonVersion is the default assumed Python version for marker evaluation. Dependencies with markers like `python_version < "3.11"` are skipped.

Functions

func CheckPythonVersion

func CheckPythonVersion(pythonVersion, requiresPython string) bool

CheckPythonVersion checks if a Python version satisfies a requires_python constraint. This is a convenience wrapper around constraints.CheckVersionConstraint.

Types

type Client

type Client struct {
	*integrations.Client
	// contains filtered or unexported fields
}

Client provides access to the PyPI package registry API. It handles HTTP requests with caching and automatic retries.

All methods are safe for concurrent use by multiple goroutines.

func NewClient

func NewClient(backend cache.Cache, cacheTTL time.Duration, pythonVersion string) *Client

NewClient creates a PyPI client with the given cache backend.

Parameters:

• backend: Cache backend for HTTP response caching (use storage.NullBackend{} for no caching)
• cacheTTL: How long responses are cached (typical: 1-24 hours)
• pythonVersion: Target Python version for marker evaluation (e.g., "3.11"); empty uses default

The returned Client is safe for concurrent use.

func (*Client) FetchPackage

func (c *Client) FetchPackage(ctx context.Context, pkg string, refresh bool) (*PackageInfo, error)

FetchPackage retrieves metadata for a Python package from PyPI (latest version).

The pkg parameter is normalized automatically (case-insensitive, underscores→hyphens). Package name cannot be empty; an empty string will result in an API error.

If refresh is true, the cache is bypassed and a fresh API call is made. If refresh is false, cached data is returned if available and not expired.

Returns:

• PackageInfo populated with metadata on success
• integrations.ErrNotFound if the package doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)
• Other errors for JSON decoding failures

The returned PackageInfo pointer is never nil if err is nil. This method is safe for concurrent use.

func (*Client) FetchPackageVersion

func (c *Client) FetchPackageVersion(ctx context.Context, pkg, version string, refresh bool) (*PackageInfo, error)

FetchPackageVersion retrieves metadata for a specific version of a Python package.

The pkg parameter is normalized automatically. The version must be an exact version string (e.g., "2.31.0").

If refresh is true, the cache is bypassed and a fresh API call is made.

Returns:

• PackageInfo populated with metadata on success
• integrations.ErrNotFound if the package or version doesn't exist
• integrations.ErrNetwork for HTTP failures (timeout, 5xx, etc.)

This method is safe for concurrent use.

func (*Client) ListVersions

func (c *Client) ListVersions(ctx context.Context, pkg string, refresh bool) ([]string, error)

ListVersions returns all available versions for a package. Versions are sorted lexicographically (not by PEP 440), so "1.10.0" sorts before "1.2.0". Pre-release versions are included in the list. Callers that need proper version ordering should sort the result with a PEP 440 comparator.

func (*Client) ListVersionsWithConstraints

func (c *Client) ListVersionsWithConstraints(ctx context.Context, pkg string, refresh bool) (map[string]string, error)

ListVersionsWithConstraints returns all versions and their runtime constraints in a single API call. This is more efficient than calling FetchPackageVersion for each version individually. Returns a map of version -> requires_python constraint (empty string if not specified).

type Dependency

type Dependency struct {
	Name       string // Normalized package name
	Constraint string // Version constraint (e.g., ">=1.0,<2.0"), empty for no constraint
}

Dependency represents a package dependency with version constraint.

type PackageInfo

type PackageInfo struct {
	Name           string            // Normalized package name (e.g., "fastapi", never empty in valid info)
	Version        string            // Version string (e.g., "0.104.1", never empty in valid info)
	RequiresPython string            // Python version constraint (e.g., ">=3.8", may be empty)
	Dependencies   []Dependency      // Direct runtime dependencies with constraints (nil or empty if none)
	ProjectURLs    map[string]string // Project URLs from metadata (e.g., "Homepage", "Repository", may be nil)
	HomePage       string            // Homepage URL (may be empty)
	Summary        string            // Short package description (may be empty)
	License        string            // License name or expression (may be empty)
	LicenseText    string            // Full raw license text for custom/proprietary licenses (may be empty)
	Author         string            // Author name (may be empty)
}

PackageInfo holds metadata for a Python package from PyPI.

Package names are normalized following PEP 503 (lowercase, underscores→hyphens). Dependencies list only runtime dependencies; extras, dev, and test deps are excluded.

Zero values: All string fields are empty, Dependencies is nil. A nil Dependencies slice is valid and indicates no dependencies or failed dependency fetch. This struct is safe for concurrent reads after construction.

func (*PackageInfo) IsCompatibleWith

func (p *PackageInfo) IsCompatibleWith(pythonVersion string) bool

IsCompatibleWith checks if this package is compatible with the given Python version. Returns true if compatible (or if requires_python is not specified), false otherwise.