woolly 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

woolly/http.py

@@ -0,0 +1,34 @@
+"""
+Shared HTTP client configuration for API requests.
+
+This module provides centralized HTTP configuration including
+the User-Agent header and common request settings.
+"""
+
+import httpx
+from importlib.metadata import version
+
+# Version identifier for the User-Agent
+VERSION = version("woolly")
+PROJECT_URL = "https://github.com/r0x0d/woolly"
+
+# Shared headers for all API requests
+DEFAULT_HEADERS = {
+    "User-Agent": f"woolly/{VERSION} ({PROJECT_URL})",
+}
+
+
+def get(url: str, **kwargs) -> httpx.Response:
+    """
+    Make a GET request with default headers.
+
+    Args:
+        url: The URL to request.
+        **kwargs: Additional arguments passed to httpx.get().
+
+    Returns:
+        httpx.Response object.
+    """
+    headers = kwargs.pop("headers", {})
+    merged_headers = {**DEFAULT_HEADERS, **headers}
+    return httpx.get(url, headers=merged_headers, **kwargs)

woolly/languages/__init__.py

@@ -0,0 +1,102 @@
+"""
+Language providers registry.
+
+This module provides automatic discovery and registration of language providers.
+To add a new language, create a module in this directory that defines a class
+inheriting from LanguageProvider and add it to PROVIDERS dict.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from woolly.languages.base import LanguageProvider
+from woolly.languages.python import PythonProvider
+from woolly.languages.rust import RustProvider
+
+
+class ProviderInfo(BaseModel):
+    """Information about an available language provider."""
+
+    language_id: str
+    display_name: str
+    aliases: list[str] = Field(default_factory=list)
+
+
+# Registry of available language providers
+# Key: language identifier (used in CLI)
+# Value: Provider class
+PROVIDERS: dict[str, type[LanguageProvider]] = {
+    "rust": RustProvider,
+    "python": PythonProvider,
+}
+
+# Aliases for convenience
+ALIASES: dict[str, str] = {
+    "rs": "rust",
+    "crate": "rust",
+    "crates": "rust",
+    "py": "python",
+    "pypi": "python",
+}
+
+
+def get_provider(language: str) -> Optional[LanguageProvider]:
+    """
+    Get an instantiated provider for the specified language.
+
+    Args:
+        language: Language identifier or alias (e.g., "rust", "python", "rs", "py")
+
+    Returns:
+        Instantiated LanguageProvider, or None if not found.
+    """
+    # Resolve aliases
+    language = language.lower()
+    if language in ALIASES:
+        language = ALIASES[language]
+
+    provider_class = PROVIDERS.get(language)
+    if provider_class is None:
+        return None
+
+    return provider_class()
+
+
+def list_providers() -> list[ProviderInfo]:
+    """
+    List all available providers.
+
+    Returns:
+        List of ProviderInfo objects with language details.
+    """
+    result = []
+    for lang_id, provider_class in PROVIDERS.items():
+        # Find aliases for this language
+        aliases = [alias for alias, target in ALIASES.items() if target == lang_id]
+        result.append(
+            ProviderInfo(
+                language_id=lang_id,
+                display_name=provider_class.display_name,
+                aliases=aliases,
+            )
+        )
+    return result
+
+
+def get_available_languages() -> list[str]:
+    """Get list of available language identifiers."""
+    return list(PROVIDERS.keys())
+
+
+__all__ = [
+    "LanguageProvider",
+    "ProviderInfo",
+    "PythonProvider",
+    "RustProvider",
+    "get_provider",
+    "list_providers",
+    "get_available_languages",
+    "PROVIDERS",
+    "ALIASES",
+]

woolly/languages/base.py

@@ -0,0 +1,374 @@
+"""
+Base abstract class defining the contract for language package providers.
+
+To add support for a new language, create a new module in the `languages/` directory
+that implements a class inheriting from `LanguageProvider`. The class must implement
+all abstract methods defined here.
+
+Example:
+    class GoProvider(LanguageProvider):
+        name = "go"
+        display_name = "Go"
+        registry_name = "Go Modules"
+        fedora_provides_prefix = "golang"
+        cache_namespace = "go"
+
+        def fetch_package_info(self, package_name: str) -> Optional[PackageInfo]:
+            # Fetch from proxy.golang.org or pkg.go.dev
+            ...
+
+        def fetch_dependencies(self, package_name: str, version: str) -> list[Dependency]:
+            # Fetch dependencies from go.mod
+            ...
+"""
+
+import re
+import subprocess
+from abc import ABC, abstractmethod
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from woolly.cache import FEDORA_CACHE_TTL, read_cache, write_cache
+from woolly.debug import log_cache_hit, log_cache_miss, log_command_output
+
+
+class PackageInfo(BaseModel):
+    """Information about a package from an upstream registry."""
+
+    name: str
+    latest_version: str
+    description: Optional[str] = None
+    homepage: Optional[str] = None
+    repository: Optional[str] = None
+
+
+class Dependency(BaseModel):
+    """A package dependency."""
+
+    name: str
+    version_requirement: str
+    optional: bool = False
+    kind: Literal["normal", "dev", "build"] = "normal"
+
+
+class FedoraPackageStatus(BaseModel):
+    """Status of a package in Fedora repositories."""
+
+    is_packaged: bool
+    versions: list[str] = Field(default_factory=list)
+    package_names: list[str] = Field(default_factory=list)
+
+
+class LanguageProvider(ABC):
+    """
+    Abstract base class for language package providers.
+
+    Each language (Rust, Python, Go, etc.) must implement this interface
+    to enable checking its packages against Fedora repositories.
+
+    Attributes:
+        name: Short identifier for the language (e.g., "rust", "python")
+        display_name: Human-readable name (e.g., "Rust", "Python")
+        registry_name: Name of the package registry (e.g., "crates.io", "PyPI")
+        fedora_provides_prefix: Prefix used in Fedora provides (e.g., "crate", "python3dist")
+        cache_namespace: Namespace for caching upstream registry data
+    """
+
+    # Class attributes that must be defined by subclasses
+    name: str
+    display_name: str
+    registry_name: str
+    fedora_provides_prefix: str
+    cache_namespace: str
+
+    # ----------------------------------------------------------------
+    # Abstract methods - MUST be implemented by subclasses
+    # ----------------------------------------------------------------
+
+    @abstractmethod
+    def fetch_package_info(self, package_name: str) -> Optional[PackageInfo]:
+        """
+        Fetch package information from the upstream registry.
+
+        Args:
+            package_name: The name of the package to look up.
+
+        Returns:
+            PackageInfo if the package exists, None otherwise.
+        """
+        pass
+
+    @abstractmethod
+    def fetch_dependencies(self, package_name: str, version: str) -> list[Dependency]:
+        """
+        Fetch dependencies for a specific package version.
+
+        Args:
+            package_name: The name of the package.
+            version: The specific version to get dependencies for.
+
+        Returns:
+            List of Dependency objects.
+        """
+        pass
+
+    # ----------------------------------------------------------------
+    # Concrete methods - shared implementation for all providers
+    # ----------------------------------------------------------------
+
+    def get_latest_version(self, package_name: str) -> Optional[str]:
+        """
+        Get the latest version of a package.
+
+        Args:
+            package_name: The name of the package.
+
+        Returns:
+            Version string if package exists, None otherwise.
+        """
+        info = self.fetch_package_info(package_name)
+        if info is None:
+            return None
+        return info.latest_version
+
+    def get_normal_dependencies(
+        self,
+        package_name: str,
+        version: Optional[str] = None,
+        include_optional: bool = False,
+    ) -> list[tuple[str, str, bool]]:
+        """
+        Get runtime dependencies for a package.
+
+        This method filters dependencies to only include normal (runtime)
+        dependencies. By default, optional dependencies are excluded.
+
+        Args:
+            package_name: The name of the package.
+            version: Specific version, or None for latest.
+            include_optional: If True, include optional dependencies.
+
+        Returns:
+            List of tuples: (dependency_name, version_requirement, is_optional)
+        """
+        if version is None:
+            version = self.get_latest_version(package_name)
+            if version is None:
+                return []
+
+        deps = self.fetch_dependencies(package_name, version)
+        return [
+            (d.name, d.version_requirement, d.optional)
+            for d in deps
+            if d.kind == "normal" and (include_optional or not d.optional)
+        ]
+
+    def get_fedora_provides_pattern(self, package_name: str) -> str:
+        """
+        Get the Fedora provides pattern for this package.
+
+        Uses the `fedora_provides_prefix` attribute to construct the pattern.
+        Override if your language needs special handling.
+
+        Args:
+            package_name: The name of the package.
+
+        Returns:
+            Provides pattern string (e.g., "crate(serde)" or "python3dist(requests)")
+        """
+        normalized = self.normalize_package_name(package_name)
+        return f"{self.fedora_provides_prefix}({normalized})"
+
+    def normalize_package_name(self, package_name: str) -> str:
+        """
+        Normalize a package name to its canonical form.
+
+        Override this method if the language has specific naming conventions
+        that differ between the upstream registry and Fedora.
+
+        Args:
+            package_name: The package name to normalize.
+
+        Returns:
+            Normalized package name.
+        """
+        return package_name
+
+    def get_alternative_names(self, package_name: str) -> list[str]:
+        """
+        Get alternative names to try when looking up a package in Fedora.
+
+        Some packages may be named differently in Fedora than in the upstream
+        registry. Override this method to provide alternatives to try.
+
+        Args:
+            package_name: The original package name.
+
+        Returns:
+            List of alternative names to try.
+        """
+        return []
+
+    # ----------------------------------------------------------------
+    # Fedora repository query methods - shared implementation
+    # ----------------------------------------------------------------
+
+    def _repoquery_package(
+        self, package_name: str
+    ) -> tuple[bool, list[str], list[str]]:
+        """
+        Query Fedora for a package using the virtual provides pattern.
+
+        Args:
+            package_name: The name of the package to query.
+
+        Returns:
+            Tuple of (is_packaged, versions_list, package_names)
+        """
+        cache_key = f"repoquery:{self.name}:{package_name}"
+        cached = read_cache("fedora", cache_key, FEDORA_CACHE_TTL)
+        if cached is not None:
+            log_cache_hit("fedora", cache_key)
+            return tuple(cached)
+
+        log_cache_miss("fedora", cache_key)
+        provide_pattern = self.get_fedora_provides_pattern(package_name)
+        cmd = [
+            "dnf",
+            "repoquery",
+            "--whatprovides",
+            provide_pattern,
+            "--queryformat",
+            "%{NAME}|%{VERSION}",
+        ]
+
+        try:
+            out = (
+                subprocess.check_output(
+                    cmd,
+                    stdin=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+                .decode()
+                .strip()
+            )
+
+            log_command_output(" ".join(cmd), out, exit_code=0)
+
+            if not out:
+                result = (False, [], [])
+                write_cache("fedora", cache_key, list(result))
+                return result
+
+            versions = set()
+            packages = set()
+            for line in out.split("\n"):
+                if "|" in line:
+                    pkg, ver = line.split("|", 1)
+                    packages.add(pkg)
+                    versions.add(ver)
+
+            result = (True, sorted(versions), sorted(packages))
+            write_cache("fedora", cache_key, [result[0], result[1], result[2]])
+            return result
+        except subprocess.CalledProcessError as e:
+            log_command_output(" ".join(cmd), "", exit_code=e.returncode)
+            result = (False, [], [])
+            write_cache("fedora", cache_key, list(result))
+            return result
+
+    def _get_provides_version(self, package_name: str) -> list[str]:
+        """
+        Get the actual package version provided by Fedora packages.
+
+        Args:
+            package_name: The name of the package.
+
+        Returns:
+            List of version strings provided by Fedora packages.
+        """
+        cache_key = f"provides:{self.name}:{package_name}"
+        cached = read_cache("fedora", cache_key, FEDORA_CACHE_TTL)
+        if cached is not None:
+            log_cache_hit("fedora", cache_key)
+            return cached
+
+        log_cache_miss("fedora", cache_key)
+        provide_pattern = self.get_fedora_provides_pattern(package_name)
+        normalized = self.normalize_package_name(package_name)
+        cmd = ["dnf", "repoquery", "--provides", "--whatprovides", provide_pattern]
+
+        try:
+            out = (
+                subprocess.check_output(
+                    cmd,
+                    stdin=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+                .decode()
+                .strip()
+            )
+
+            log_command_output(" ".join(cmd), out, exit_code=0)
+
+            if not out:
+                write_cache("fedora", cache_key, [])
+                return []
+
+            versions = set()
+            # Build pattern: prefix(normalized_name) = version
+            pattern = re.compile(
+                rf"{re.escape(self.fedora_provides_prefix)}\({re.escape(normalized)}\)\s*=\s*([\d.]+)"
+            )
+            for line in out.split("\n"):
+                match = pattern.search(line)
+                if match:
+                    versions.add(match.group(1))
+
+            result = sorted(versions)
+            write_cache("fedora", cache_key, result)
+            return result
+        except subprocess.CalledProcessError as e:
+            log_command_output(" ".join(cmd), "", exit_code=e.returncode)
+            write_cache("fedora", cache_key, [])
+            return []
+
+    def check_fedora_packaging(self, package_name: str) -> FedoraPackageStatus:
+        """
+        Check if a package is available in Fedora repositories.
+
+        This method queries Fedora repositories to determine if the
+        package is packaged and what versions are available.
+
+        Args:
+            package_name: The name of the package.
+
+        Returns:
+            FedoraPackageStatus with packaging information.
+        """
+        normalized = self.normalize_package_name(package_name)
+        is_packaged, pkg_versions, packages = self._repoquery_package(normalized)
+
+        # Try alternative names if not found
+        if not is_packaged:
+            for alt_name in self.get_alternative_names(package_name):
+                is_packaged, pkg_versions, packages = self._repoquery_package(alt_name)
+                if is_packaged:
+                    break
+
+        if is_packaged:
+            provided_versions = self._get_provides_version(normalized)
+            if not provided_versions:
+                provided_versions = pkg_versions
+            return FedoraPackageStatus(
+                is_packaged=True,
+                versions=provided_versions,
+                package_names=packages,
+            )
+
+        return FedoraPackageStatus(
+            is_packaged=False,
+            versions=[],
+            package_names=[],
+        )

woolly/languages/python.py

@@ -0,0 +1,200 @@
+"""
+Python/PyPI language provider.
+
+This provider fetches package information from PyPI and checks
+Fedora repositories for Python packages.
+"""
+
+import re
+from typing import Optional
+
+from woolly import http
+from woolly.cache import DEFAULT_CACHE_TTL, read_cache, write_cache
+from woolly.debug import (
+    log_api_request,
+    log_api_response,
+    log_cache_hit,
+    log_cache_miss,
+)
+from woolly.languages.base import Dependency, LanguageProvider, PackageInfo
+
+PYPI_API = "https://pypi.org/pypi"
+
+
+class PythonProvider(LanguageProvider):
+    """Provider for Python packages via PyPI."""
+
+    name = "python"
+    display_name = "Python"
+    registry_name = "PyPI"
+    fedora_provides_prefix = "python3dist"
+    cache_namespace = "pypi"
+
+    def fetch_package_info(self, package_name: str) -> Optional[PackageInfo]:
+        """Fetch package information from PyPI."""
+        cache_key = f"info:{package_name}"
+        cached = read_cache(self.cache_namespace, cache_key, DEFAULT_CACHE_TTL)
+        if cached is not None:
+            log_cache_hit(self.cache_namespace, cache_key)
+            if cached is False:  # Explicit "not found" cache
+                return None
+            return PackageInfo(
+                name=cached["info"]["name"],
+                latest_version=cached["info"]["version"],
+                description=cached["info"].get("summary"),
+                homepage=cached["info"].get("home_page"),
+                repository=cached["info"].get("project_url"),
+            )
+
+        log_cache_miss(self.cache_namespace, cache_key)
+        url = f"{PYPI_API}/{package_name}/json"
+        log_api_request("GET", url)
+        r = http.get(url)
+        log_api_response(r.status_code, r.text[:500] if r.text else None)
+
+        if r.status_code == 404:
+            write_cache(self.cache_namespace, cache_key, False)
+            return None
+        if r.status_code != 200:
+            raise RuntimeError(
+                f"Failed to fetch metadata for package {package_name}: {r.status_code}"
+            )
+
+        data = r.json()
+        write_cache(self.cache_namespace, cache_key, data)
+
+        return PackageInfo(
+            name=data["info"]["name"],
+            latest_version=data["info"]["version"],
+            description=data["info"].get("summary"),
+            homepage=data["info"].get("home_page"),
+            repository=data["info"].get("project_url"),
+        )
+
+    def fetch_dependencies(self, package_name: str, version: str) -> list[Dependency]:
+        """
+        Fetch dependencies for a specific package version.
+
+        PyPI provides dependencies in the `requires_dist` field.
+        """
+        cache_key = f"deps:{package_name}:{version}"
+        cached = read_cache(self.cache_namespace, cache_key, DEFAULT_CACHE_TTL)
+        if cached is not None:
+            log_cache_hit(self.cache_namespace, cache_key)
+            return [
+                Dependency(
+                    name=d["name"],
+                    version_requirement=d["version_requirement"],
+                    optional=d.get("optional", False),
+                    kind=d.get("kind", "normal"),
+                )
+                for d in cached
+            ]
+
+        log_cache_miss(self.cache_namespace, cache_key)
+        url = f"{PYPI_API}/{package_name}/{version}/json"
+        log_api_request("GET", url)
+        r = http.get(url)
+        log_api_response(r.status_code, r.text[:500] if r.text else None)
+
+        if r.status_code != 200:
+            write_cache(self.cache_namespace, cache_key, [])
+            return []
+
+        data = r.json()
+        requires_dist = data["info"].get("requires_dist") or []
+
+        deps = []
+        for req in requires_dist:
+            parsed = self._parse_requirement(req)
+            if parsed:
+                deps.append(parsed)
+
+        # Cache as dicts
+        cache_data = [
+            {
+                "name": d.name,
+                "version_requirement": d.version_requirement,
+                "optional": d.optional,
+                "kind": d.kind,
+            }
+            for d in deps
+        ]
+        write_cache(self.cache_namespace, cache_key, cache_data)
+
+        return deps
+
+    def _parse_requirement(self, req_string: str) -> Optional[Dependency]:
+        """
+        Parse a PEP 508 requirement string.
+
+        Examples:
+            "requests>=2.20.0"
+            "typing-extensions; python_version < '3.8'"
+            "pytest; extra == 'testing'"
+        """
+        # Check if this is an optional/extra dependency
+        is_optional = False
+        kind = "normal"
+
+        if "extra ==" in req_string or "extra==" in req_string:
+            is_optional = True
+            # Keep kind as "normal" so optional dependencies can be included
+            # when --optional flag is used
+
+        # Extract the package name and version requirement
+        # Handle environment markers (everything after ';')
+        if ";" in req_string:
+            req_string = req_string.split(";")[0].strip()
+
+        # Match package name and optional version specifier
+        # Package names can contain letters, numbers, hyphens, underscores, and dots
+        match = re.match(r"^([A-Za-z0-9][-A-Za-z0-9._]*)\s*(.*)$", req_string.strip())
+
+        if not match:
+            return None
+
+        name = match.group(1)
+        version_req = match.group(2).strip()
+
+        # Handle extras in package name (e.g., "package[extra1,extra2]")
+        if "[" in name:
+            name = name.split("[")[0]
+
+        return Dependency(
+            name=self.normalize_package_name(name),
+            version_requirement=version_req or "*",
+            optional=is_optional,
+            kind=kind,
+        )
+
+    def normalize_package_name(self, package_name: str) -> str:
+        """
+        Normalize a Python package name according to PEP 503.
+
+        Package names are case-insensitive and treat hyphens,
+        underscores, and dots as equivalent.
+        """
+        return re.sub(r"[-_.]+", "-", package_name).lower()
+
+    def get_alternative_names(self, package_name: str) -> list[str]:
+        """
+        Get alternative names to try for package lookup.
+
+        Python package names can use hyphens, underscores, or dots
+        interchangeably.
+        """
+        alternatives = []
+        normalized = self.normalize_package_name(package_name)
+
+        # Try with underscores instead of hyphens
+        alt_underscore = normalized.replace("-", "_")
+        if alt_underscore != normalized:
+            alternatives.append(alt_underscore)
+
+        # Try with dots instead of hyphens
+        alt_dot = normalized.replace("-", ".")
+        if alt_dot != normalized:
+            alternatives.append(alt_dot)
+
+        return alternatives