purl2src 1.2.3__py3-none-any.whl

purl2src/__init__.py

@@ -0,0 +1,19 @@
+"""Semantic Copycat Purl2Src - Translate PURLs to download URLs."""
+
+import warnings
+
+# Suppress urllib3 OpenSSL warning on macOS
+warnings.filterwarnings("ignore", message="urllib3 v2 only supports OpenSSL 1.1.1+")
+
+from .parser import parse_purl
+from .handlers import get_download_url
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("purl2src")
+except Exception:
+    # Fallback for development installations
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["parse_purl", "get_download_url"]

purl2src/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for CLI execution."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

purl2src/cli.py

@@ -0,0 +1,151 @@
+"""Command-line interface for purl2src."""
+
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+import click
+
+from . import __version__
+from .handlers import get_download_url
+
+
+@click.command()
+@click.version_option(version=__version__, prog_name="purl2src")
+@click.argument("purl", required=False)
+@click.option(
+    "-f",
+    "--file",
+    type=click.Path(exists=True, path_type=Path),
+    help="Read PURLs from file (one per line)",
+)
+@click.option(
+    "-o", "--output", type=click.Path(path_type=Path), help="Write results to file (JSON format)"
+)
+@click.option(
+    "--validate/--no-validate", default=True, help="Validate that download URLs are accessible"
+)
+@click.option(
+    "--format", type=click.Choice(["json", "csv", "plain"]), default="plain", help="Output format"
+)
+@click.option("-v", "--verbose", is_flag=True, help="Verbose output")
+def main(
+    purl: Optional[str],
+    file: Optional[Path],
+    output: Optional[Path],
+    validate: bool,
+    format: str,
+    verbose: bool,
+) -> None:
+    """
+    Translate Package URLs (PURLs) to download URLs.
+
+    Examples:
+
+        purl2src "pkg:npm/express@4.17.1"
+
+        purl2src "pkg:pypi/requests@2.28.0" --validate
+
+        purl2src -f purls.txt --output results.json
+    """
+    # Collect PURLs to process
+    purls: List[str] = []
+
+    if purl:
+        purls.append(purl)
+
+    if file:
+        with open(file, "r") as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    purls.append(line)
+
+    if not purls:
+        click.echo("Error: No PURLs provided. Use --help for usage.", err=True)
+        sys.exit(1)
+
+    # Process PURLs
+    results = []
+    errors = 0
+
+    # Only show progress bar for multiple PURLs in verbose mode
+    if len(purls) > 1 and verbose:
+        with click.progressbar(purls, label="Processing PURLs", show_pos=True) as purl_iter:
+            for purl_str in purl_iter:
+                try:
+                    result = get_download_url(purl_str, validate=validate)
+                    results.append(result.to_dict())
+
+                    if result.status == "failed":
+                        errors += 1
+
+                except Exception as e:
+                    result_dict = {
+                        "purl": purl_str,
+                        "download_url": None,
+                        "status": "failed",
+                        "error": str(e),
+                    }
+                    results.append(result_dict)
+                    errors += 1
+    else:
+        for purl_str in purls:
+            try:
+                result = get_download_url(purl_str, validate=validate)
+                results.append(result.to_dict())
+
+                if result.status == "failed":
+                    errors += 1
+
+            except Exception as e:
+                result_dict = {
+                    "purl": purl_str,
+                    "download_url": None,
+                    "status": "failed",
+                    "error": str(e),
+                }
+                results.append(result_dict)
+                errors += 1
+
+    # Format and output results
+    if format == "json":
+        output_data = json.dumps(results, indent=2)
+    elif format == "csv":
+        # Simple CSV output
+        lines = ["purl,download_url,status,method"]
+        for r in results:
+            lines.append(
+                f"{r['purl']},{r.get('download_url', '')},"
+                f"{r.get('status', 'failed')},{r.get('method', '')}"
+            )
+        output_data = "\n".join(lines)
+    else:  # plain
+        lines = []
+        for r in results:
+            if r.get("download_url"):
+                lines.append(f"{r['purl']} -> {r['download_url']}")
+            else:
+                error_msg = r.get("error", "Failed to resolve")
+                lines.append(f"{r['purl']} -> ERROR: {error_msg}")
+        output_data = "\n".join(lines)
+
+    # Write output
+    if output:
+        with open(output, "w") as f:
+            f.write(output_data)
+        if verbose:
+            click.echo(f"Results written to {output}")
+    else:
+        click.echo(output_data)
+
+    # Exit with error code if any failures
+    if errors > 0:
+        if verbose:
+            click.echo(f"\nCompleted with {errors} error(s)", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

purl2src/handlers/__init__.py

@@ -0,0 +1,85 @@
+"""Package ecosystem handlers."""
+
+from typing import Dict, Optional, Type
+from .base import BaseHandler, HandlerResult
+from .npm import NpmHandler
+from .pypi import PyPiHandler
+from .cargo import CargoHandler
+from .nuget import NuGetHandler
+from .github import GitHubHandler
+from .generic import GenericHandler
+from .conda import CondaHandler
+from .golang import GoLangHandler
+from .rubygems import RubyGemsHandler
+from .maven import MavenHandler
+
+# Registry of all available handlers
+HANDLERS: Dict[str, Type[BaseHandler]] = {
+    "npm": NpmHandler,
+    "pypi": PyPiHandler,
+    "cargo": CargoHandler,
+    "nuget": NuGetHandler,
+    "github": GitHubHandler,
+    "generic": GenericHandler,
+    "conda": CondaHandler,
+    "golang": GoLangHandler,
+    "gem": RubyGemsHandler,
+    "rubygems": RubyGemsHandler,
+    "maven": MavenHandler,
+}
+
+
+def get_download_url(purl: str, validate: bool = True) -> HandlerResult:
+    """
+    Get download URL for a Package URL.
+
+    Args:
+        purl: Package URL string
+        validate: Whether to validate the URL is accessible
+
+    Returns:
+        HandlerResult with download URL and metadata
+    """
+    from ..parser import parse_purl
+    from ..utils import HttpClient, URLCache
+
+    # Check cache first
+    cache = URLCache()
+    cached = cache.get(purl)
+    if cached:
+        return HandlerResult(**cached)
+
+    # Parse PURL
+    parsed = parse_purl(purl)
+
+    # Get appropriate handler
+    handler_class = HANDLERS.get(parsed.ecosystem)
+    if not handler_class:
+        return HandlerResult(
+            purl=purl,
+            download_url=None,
+            validated=False,
+            method="unsupported",
+            error=f"Unsupported ecosystem: {parsed.ecosystem}",
+            status="failed",
+            fallback_available=False,
+        )
+
+    # Create handler and get download URL
+    with HttpClient() as http_client:
+        handler = handler_class(http_client)
+        result = handler.get_download_url(parsed, validate=validate)
+
+    # Cache successful results
+    if result.download_url and result.validated:
+        cache.set(purl, result.to_dict())
+
+    return result
+
+
+__all__ = [
+    "BaseHandler",
+    "HandlerResult",
+    "get_download_url",
+    "HANDLERS",
+]

purl2src/handlers/base.py

@@ -0,0 +1,226 @@
+"""Base handler class for all package ecosystems."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, asdict
+from typing import Optional, Dict, Any, List
+import shutil
+import subprocess
+import shlex
+
+from ..parser import Purl
+from ..utils.http import HttpClient
+
+
+@dataclass
+class HandlerResult:
+    """Result from handler processing."""
+
+    purl: str
+    download_url: Optional[str]
+    validated: bool
+    method: str  # "direct", "api", or "fallback"
+    fallback_command: Optional[str] = None
+    error: Optional[str] = None
+    status: str = "success"  # "success" or "failed"
+    fallback_available: bool = True
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
+class HandlerError(Exception):
+    """Exception raised by handlers."""
+
+    pass
+
+
+class BaseHandler(ABC):
+    """Base class for all ecosystem handlers."""
+
+    def __init__(self, http_client: HttpClient):
+        self.http_client = http_client
+
+    def get_download_url(self, purl: Purl, validate: bool = True) -> HandlerResult:
+        """
+        Get download URL for a package.
+
+        This method implements the three-level resolution strategy:
+        1. Try direct URL construction
+        2. Try API query
+        3. Try package manager fallback
+
+        Args:
+            purl: Parsed PURL object
+            validate: Whether to validate the URL is accessible
+
+        Returns:
+            HandlerResult with download URL and metadata
+        """
+        # Check fallback availability once
+        fallback_cmd = self.get_fallback_cmd(purl)
+        fallback_available = bool(fallback_cmd and self.is_package_manager_available())
+
+        # Level 1: Try direct URL construction
+        try:
+            url = self.build_download_url(purl)
+            if url and (not validate or self.http_client.validate_url(url)):
+                return HandlerResult(
+                    purl=str(purl),
+                    download_url=url,
+                    validated=validate,
+                    method="direct",
+                    fallback_command=fallback_cmd,
+                    fallback_available=fallback_available,
+                )
+        except Exception:
+            pass
+
+        # Level 2: Try API query
+        try:
+            url = self.get_download_url_from_api(purl)
+            if url and (not validate or self.http_client.validate_url(url)):
+                return HandlerResult(
+                    purl=str(purl),
+                    download_url=url,
+                    validated=validate,
+                    method="api",
+                    fallback_command=fallback_cmd,
+                    fallback_available=fallback_available,
+                )
+        except Exception:
+            pass
+
+        # Level 3: Try package manager fallback
+        if fallback_available:
+            try:
+                url = self.execute_fallback_command(purl)
+                if url and (not validate or self.http_client.validate_url(url)):
+                    return HandlerResult(
+                        purl=str(purl),
+                        download_url=url,
+                        validated=validate,
+                        method="fallback",
+                        fallback_command=fallback_cmd,
+                        fallback_available=fallback_available,
+                    )
+            except Exception:
+                pass
+
+        # All methods failed
+        return HandlerResult(
+            purl=str(purl),
+            download_url=None,
+            validated=False,
+            method="none",
+            fallback_command=fallback_cmd,
+            error="Failed to resolve download URL",
+            status="failed",
+            fallback_available=fallback_available,
+        )
+
+    @abstractmethod
+    def build_download_url(self, purl: Purl) -> Optional[str]:
+        """
+        Build direct download URL from PURL components.
+
+        Args:
+            purl: Parsed PURL object
+
+        Returns:
+            Download URL or None if not applicable
+        """
+        pass
+
+    @abstractmethod
+    def get_download_url_from_api(self, purl: Purl) -> Optional[str]:
+        """
+        Query package registry API for download URL.
+
+        Args:
+            purl: Parsed PURL object
+
+        Returns:
+            Download URL or None if not found
+        """
+        pass
+
+    @abstractmethod
+    def get_fallback_cmd(self, purl: Purl) -> Optional[str]:
+        """
+        Get package manager command for fallback.
+
+        Args:
+            purl: Parsed PURL object
+
+        Returns:
+            Command string or None if not available
+        """
+        pass
+
+    @abstractmethod
+    def get_package_manager_cmd(self) -> List[str]:
+        """
+        Get package manager command name(s) to check.
+
+        Returns:
+            List of command names (e.g., ["npm", "yarn"])
+        """
+        pass
+
+    def is_package_manager_available(self) -> bool:
+        """Check if package manager is installed."""
+        for cmd in self.get_package_manager_cmd():
+            if shutil.which(cmd):
+                return True
+        return False
+
+    def execute_fallback_command(self, purl: Purl) -> Optional[str]:
+        """
+        Execute package manager command and parse output.
+
+        Args:
+            purl: Parsed PURL object
+
+        Returns:
+            Download URL extracted from command output
+
+        Raises:
+            HandlerError: If command execution fails
+        """
+        cmd = self.get_fallback_cmd(purl)
+        if not cmd:
+            return None
+
+        try:
+            # Execute command safely
+            result = subprocess.run(
+                shlex.split(cmd),
+                capture_output=True,
+                text=True,
+                timeout=30,
+                check=True,
+            )
+
+            # Parse output - this should be overridden by subclasses
+            return self.parse_fallback_output(result.stdout)
+
+        except subprocess.TimeoutExpired:
+            raise HandlerError(f"Command timed out: {cmd}")
+        except subprocess.CalledProcessError as e:
+            raise HandlerError(f"Command failed: {cmd}\n{e.stderr}")
+
+    def parse_fallback_output(self, output: str) -> Optional[str]:
+        """
+        Parse package manager command output.
+
+        This should be overridden by subclasses to extract the download URL
+        from the specific package manager's output format.
+
+        Args:
+            output: Command stdout
+
+        Returns:
+            Download URL or None if not found
+        """
+        return None

purl2src/handlers/cargo.py

@@ -0,0 +1,40 @@
+"""Cargo (Rust) handler."""
+
+from typing import Optional, List
+from urllib.parse import quote
+
+from ..parser import Purl
+from .base import BaseHandler
+
+
+class CargoHandler(BaseHandler):
+    """Handler for Cargo/Rust packages."""
+
+    def build_download_url(self, purl: Purl) -> Optional[str]:
+        """
+        Build Cargo download URL.
+
+        Format: https://crates.io/api/v1/crates/{name}/{version}/download
+        """
+        if not purl.version:
+            return None
+
+        return f"https://crates.io/api/v1/crates/{purl.name}/{purl.version}/download"
+
+    def get_download_url_from_api(self, purl: Purl) -> Optional[str]:
+        """Cargo doesn't need API query - direct URL works."""
+        return None
+
+    def get_fallback_cmd(self, purl: Purl) -> Optional[str]:
+        """Get cargo command."""
+        return f"cargo search {quote(purl.name)} --limit 1"
+
+    def get_package_manager_cmd(self) -> List[str]:
+        """Cargo command name."""
+        return ["cargo"]
+
+    def parse_fallback_output(self, output: str) -> Optional[str]:
+        """Parse cargo search output."""
+        # Cargo search doesn't directly provide download URLs
+        # This would need more complex handling
+        return None

purl2src/handlers/conda.py

@@ -0,0 +1,75 @@
+"""Conda handler."""
+
+from typing import Optional, List
+
+from ..parser import Purl
+from .base import BaseHandler, HandlerError
+
+
+class CondaHandler(BaseHandler):
+    """Handler for Conda packages."""
+
+    def build_download_url(self, purl: Purl) -> Optional[str]:
+        """
+        Build Conda download URL.
+
+        Requires qualifiers: build, channel, subdir
+        Format depends on channel:
+        - main/defaults: repo.anaconda.com/pkgs/main/{subdir}/{pkg}-{ver}-{build}.tar.bz2
+        - others: anaconda.org/{ch}/{pkg}/{ver}/download/{subdir}/{pkg}-{ver}-{build}.tar.bz2
+        """
+        if not purl.version:
+            return None
+
+        # Check required qualifiers
+        required = ["build", "channel", "subdir"]
+        for qual in required:
+            if qual not in purl.qualifiers:
+                raise HandlerError(f"Missing required qualifier: {qual}")
+
+        build = purl.qualifiers["build"]
+        channel = purl.qualifiers["channel"]
+        subdir = purl.qualifiers["subdir"]
+
+        # Handle different channel types
+        if channel in ["main", "defaults"]:
+            # Main/defaults channel uses repo.anaconda.com
+            return (
+                f"https://repo.anaconda.com/pkgs/main/{subdir}/"
+                f"{purl.name}-{purl.version}-{build}.tar.bz2"
+            )
+        else:
+            # Community channels (conda-forge, bioconda, etc.) use anaconda.org
+            return (
+                f"https://anaconda.org/{channel}/{purl.name}/{purl.version}/"
+                f"download/{subdir}/{purl.name}-{purl.version}-{build}.tar.bz2"
+            )
+
+    def get_download_url_from_api(self, purl: Purl) -> Optional[str]:
+        """Query Anaconda API."""
+        # Could implement Anaconda API query here
+        return None
+
+    def get_fallback_cmd(self, purl: Purl) -> Optional[str]:
+        """Get conda command."""
+        if not purl.version:
+            return None
+
+        channel = purl.qualifiers.get("channel", "conda-forge")
+        return f"conda search -c {channel} {purl.name}={purl.version} --info"
+
+    def get_package_manager_cmd(self) -> List[str]:
+        """Conda command names."""
+        return ["conda", "mamba", "micromamba"]
+
+    def parse_fallback_output(self, output: str) -> Optional[str]:
+        """Parse conda search output."""
+        # Look for "url" line with various formatting
+        import re
+
+        for line in output.split("\n"):
+            # Look for pattern: url (spaces) : (spaces) http...
+            match = re.search(r"url\s*:\s*(https?://\S+)", line, re.IGNORECASE)
+            if match:
+                return match.group(1)
+        return None

purl2src/handlers/generic.py

@@ -0,0 +1,94 @@
+"""Generic handler using qualifiers."""
+
+import re
+from typing import Optional, List
+
+from ..parser import Purl
+from .base import BaseHandler, HandlerResult
+
+
+class GenericHandler(BaseHandler):
+    """Handler for generic packages using qualifiers."""
+
+    def build_download_url(self, purl: Purl) -> Optional[str]:
+        """Build URL from qualifiers."""
+        # Check for direct download_url qualifier
+        if "download_url" in purl.qualifiers:
+            return purl.qualifiers["download_url"]
+
+        # Check for vcs_url qualifier
+        if "vcs_url" in purl.qualifiers:
+            vcs_url = purl.qualifiers["vcs_url"]
+
+            # Handle git+https:// prefix
+            if vcs_url.startswith("git+"):
+                vcs_url = vcs_url[4:]
+
+            # Extract commit hash if present
+            match = re.match(r"(.+)@([a-f0-9]+)$", vcs_url)
+            if match:
+                repo_url, commit = match.groups()
+                # Store commit for later checkout
+                self._commit = commit
+                return repo_url
+
+            return vcs_url
+
+        return None
+
+    def get_download_url_from_api(self, purl: Purl) -> Optional[str]:
+        """Generic packages don't have a registry API."""
+        return None
+
+    def get_fallback_cmd(self, purl: Purl) -> Optional[str]:
+        """Get git command for VCS URLs."""
+        if "vcs_url" in purl.qualifiers:
+            vcs_url = purl.qualifiers["vcs_url"]
+
+            # Handle git+https:// prefix
+            if vcs_url.startswith("git+"):
+                vcs_url = vcs_url[4:]
+
+            # Extract commit hash if present
+            match = re.match(r"(.+)@([a-f0-9]+)$", vcs_url)
+            if match:
+                repo_url, commit = match.groups()
+                return f"git clone {repo_url} && git checkout {commit}"
+
+            return f"git clone {vcs_url}"
+
+        return None
+
+    def get_package_manager_cmd(self) -> List[str]:
+        """Git is used for VCS URLs."""
+        return ["git"]
+
+    def parse_fallback_output(self, output: str) -> Optional[str]:
+        """Parse git output."""
+        # Git clone doesn't return download URLs
+        return None
+
+    def get_download_url(self, purl: Purl, validate: bool = True) -> "HandlerResult":
+        """Override to handle checksum validation."""
+        result = super().get_download_url(purl, validate)
+
+        # If we have a download URL and checksum, validate it
+        if result.download_url and result.validated and "checksum" in purl.qualifiers:
+            try:
+                # Download and verify checksum
+                checksum = purl.qualifiers["checksum"]
+                # Extract algorithm if specified (e.g., sha256:abc123)
+                if ":" in checksum:
+                    algo, value = checksum.split(":", 1)
+                else:
+                    algo, value = "sha256", checksum
+
+                self.http_client.download_and_verify(
+                    result.download_url, expected_checksum=value, algorithm=algo
+                )
+            except ValueError as e:
+                result.error = str(e)
+                result.status = "failed"
+                result.validated = False
+
+        return result