pkgq 0.1.0__py3-none-any.whl

pkgq/__init__.py

@@ -0,0 +1,11 @@
+"""
+pkgq - Package Query
+
+Find API information for Python packages.
+"""
+
+__version__ = "0.1.0"
+
+from pkgq.find import FindResult, find
+
+__all__ = ["find", "FindResult"]

pkgq/cli.py

@@ -0,0 +1,155 @@
+"""
+pkgq CLI - Command line interface for package query.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.markdown import Markdown
+
+from pkgq import find
+from pkgq.find import get_cache_dir
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="pkgq",
+        description="Package Query - Find API information for Python packages",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # find command
+    find_parser = subparsers.add_parser("find", help="Find package documentation")
+    find_parser.add_argument("package", help="Package name")
+    find_parser.add_argument(
+        "--version", "-v", help="Desired version (default: latest)"
+    )
+    find_parser.add_argument(
+        "--from-version", "-f", help="Current cached version (for update check)"
+    )
+    find_parser.add_argument(
+        "--cache-dir", "-c", type=Path, help="Cache directory"
+    )
+    find_parser.add_argument(
+        "--save", "-s", action="store_true", help="Save to cache"
+    )
+    find_parser.add_argument(
+        "--json", "-j", action="store_true", help="Output as JSON"
+    )
+    find_parser.add_argument(
+        "--verbose", "-V", action="store_true", help="Verbose output"
+    )
+
+    # cache command
+    cache_parser = subparsers.add_parser("cache", help="Manage cache")
+    cache_parser.add_argument(
+        "--clear", action="store_true", help="Clear cache"
+    )
+    cache_parser.add_argument(
+        "--list", action="store_true", help="List cached packages"
+    )
+    cache_parser.add_argument(
+        "--dir", action="store_true", help="Show cache directory"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "find":
+        cmd_find(args)
+    elif args.command == "cache":
+        cmd_cache(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+def cmd_find(args):
+    """Handle find command."""
+    console = Console()
+
+    try:
+        result = find(
+            package=args.package,
+            version=args.version,
+            from_version=args.from_version,
+            cache_dir=args.cache_dir,
+            verbose=args.verbose,
+        )
+
+        if args.save:
+            cache_path = result.save_to_cache(args.cache_dir)
+            console.print(f"[green]Saved to:[/green] {cache_path}")
+
+        if args.json:
+            print(json.dumps(result.to_dict(), indent=2))
+        else:
+            # Print version info
+            status = "[green]cached[/green]" if result.cached else "[blue]fetched[/blue]"
+            console.print(f"[bold]{result.package}[/bold] {result.version} ({status})")
+            console.print(f"[dim]Source: {result.source}[/dim]")
+            console.print()
+
+            # Print content as markdown
+            md = Markdown(result.content)
+            console.print(md)
+
+    except Exception as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(1)
+
+
+def cmd_cache(args):
+    """Handle cache command."""
+    console = Console()
+    cache_dir = get_cache_dir()
+
+    if args.dir:
+        console.print(str(cache_dir))
+        return
+
+    if args.clear:
+        import shutil
+        if cache_dir.exists():
+            shutil.rmtree(cache_dir)
+            console.print(f"[green]Cleared cache:[/green] {cache_dir}")
+        else:
+            console.print("[yellow]Cache is empty[/yellow]")
+        return
+
+    if args.list:
+        if not cache_dir.exists():
+            console.print("[yellow]Cache is empty[/yellow]")
+            return
+
+        packages = sorted(cache_dir.iterdir())
+        if not packages:
+            console.print("[yellow]Cache is empty[/yellow]")
+            return
+
+        console.print(f"[bold]Cached packages ({len(packages)}):[/bold]")
+        for pkg_dir in packages:
+            metadata_file = pkg_dir / "metadata.json"
+            if metadata_file.exists():
+                metadata = json.loads(metadata_file.read_text())
+                version = metadata.get("version", "?")
+                source = metadata.get("source", "?")
+                console.print(f"  {pkg_dir.name} {version} ({source})")
+            else:
+                console.print(f"  {pkg_dir.name} (no metadata)")
+        return
+
+    # Default: show cache info
+    console.print(f"Cache directory: {cache_dir}")
+    if cache_dir.exists():
+        packages = list(cache_dir.iterdir())
+        console.print(f"Cached packages: {len(packages)}")
+    else:
+        console.print("Cache is empty")
+
+
+if __name__ == "__main__":
+    main()

pkgq/find.py

@@ -0,0 +1,352 @@
+"""
+Package Query - Find package documentation.
+
+This module provides the find() function to query Python package information
+from various sources (GitHub, PyPI, etc.).
+"""
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+
+@dataclass
+class FindResult:
+    """Result of a package find operation."""
+
+    package: str
+    version: str
+    source: str
+    content: str
+    cached: bool = False
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        return {
+            "package": self.package,
+            "version": self.version,
+            "source": self.source,
+            "content": self.content,
+            "cached": self.cached,
+        }
+
+    def save_to_cache(self, cache_dir: Path | None = None) -> Path:
+        """Save result to cache directory."""
+        if cache_dir is None:
+            cache_dir = get_cache_dir()
+
+        package_dir = cache_dir / self.package
+        package_dir.mkdir(parents=True, exist_ok=True)
+
+        # Save PACKAGE.md
+        package_file = package_dir / "PACKAGE.md"
+        package_file.write_text(self.content)
+
+        # Save metadata
+        metadata = {
+            "package": self.package,
+            "version": self.version,
+            "source": self.source,
+            "cached": True,
+        }
+        metadata_file = package_dir / "metadata.json"
+        metadata_file.write_text(json.dumps(metadata, indent=2))
+
+        return package_dir
+
+
+def get_cache_dir() -> Path:
+    """Get the cache directory for package information."""
+    # Check environment variable first
+    cache_env = os.environ.get("PKGQ_CACHE")
+    if cache_env:
+        return Path(cache_env)
+
+    # Default to ~/.cache/pkgq/packages
+    cache_dir = Path.home() / ".cache" / "pkgq" / "packages"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def check_cached(package: str, cache_dir: Path | None = None) -> FindResult | None:
+    """Check if package is cached locally.
+
+    Args:
+        package: Package name
+        cache_dir: Cache directory (default: ~/.cache/pkgq/packages)
+
+    Returns:
+        FindResult if cached, None if not
+    """
+    if cache_dir is None:
+        cache_dir = get_cache_dir()
+
+    package_dir = cache_dir / package
+    package_file = package_dir / "PACKAGE.md"
+    metadata_file = package_dir / "metadata.json"
+
+    if not package_file.exists():
+        return None
+
+    if not metadata_file.exists():
+        return None
+
+    try:
+        metadata = json.loads(metadata_file.read_text())
+        content = package_file.read_text()
+
+        return FindResult(
+            package=metadata["package"],
+            version=metadata["version"],
+            source=metadata["source"],
+            content=content,
+            cached=True,
+        )
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+
+def get_pypi_info(package: str) -> dict:
+    """Get package info from PyPI.
+
+    Args:
+        package: Package name
+
+    Returns:
+        Package metadata from PyPI
+    """
+    url = f"https://pypi.org/pypi/{package}/json"
+
+    with httpx.Client() as client:
+        response = client.get(url)
+        response.raise_for_status()
+        return response.json()
+
+
+def extract_github_url(pypi_info: dict) -> str | None:
+    """Extract GitHub URL from PyPI info.
+
+    Args:
+        pypi_info: PyPI package info
+
+    Returns:
+        GitHub URL or None
+    """
+    info = pypi_info.get("info", {})
+    project_urls = info.get("project_urls") or {}
+
+    # Check project_urls for GitHub
+    for _key, url in project_urls.items():
+        if "github.com" in url.lower():
+            return url
+
+    # Check home_page
+    home_page = info.get("home_page", "")
+    if "github.com" in home_page.lower():
+        return home_page
+
+    return None
+
+
+def parse_github_url(url: str) -> tuple[str, str]:
+    """Parse GitHub URL to owner and repo.
+
+    Args:
+        url: GitHub URL
+
+    Returns:
+        Tuple of (owner, repo)
+    """
+    # Handle various GitHub URL formats
+    # https://github.com/owner/repo
+    # https://github.com/owner/repo.git
+    # https://github.com/owner/repo/
+    # https://github.com/owner/repo#readme
+
+    # Remove URL fragment (e.g., #readme)
+    if "#" in url:
+        url = url.split("#")[0]
+
+    url = url.rstrip("/")
+    if url.endswith(".git"):
+        url = url[:-4]
+
+    parts = url.split("/")
+    if len(parts) >= 5 and "github.com" in parts[2]:
+        return parts[3], parts[4]
+
+    raise ValueError(f"Invalid GitHub URL: {url}")
+
+
+def fetch_package_md_from_github(
+    owner: str, repo: str, branch: str = "main"
+) -> str | None:
+    """Fetch PACKAGE.md from GitHub repository.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+        branch: Branch name (default: main)
+
+    Returns:
+        PACKAGE.md content or None
+    """
+    url = f"https://raw.githubusercontent.com/{owner}/{repo}/{branch}/PACKAGE.md"
+
+    with httpx.Client() as client:
+        response = client.get(url)
+        if response.status_code == 200:
+            return response.text
+        return None
+
+
+def get_default_branch(owner: str, repo: str) -> str:
+    """Get default branch from GitHub API.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+
+    Returns:
+        Default branch name
+    """
+    url = f"https://api.github.com/repos/{owner}/{repo}"
+
+    with httpx.Client() as client:
+        response = client.get(url)
+        if response.status_code == 200:
+            data = response.json()
+            return data.get("default_branch", "main")
+        return "main"
+
+
+def find(
+    package: str,
+    version: str | None = None,
+    from_version: str | None = None,
+    cache_dir: Path | None = None,
+    verbose: bool = False,
+) -> FindResult:
+    """Find package documentation.
+
+    Queries multiple sources in order:
+    1. Local cache (if from_version is provided)
+    2. GitHub repository (PACKAGE.md)
+    3. Generate from PyPI docs
+
+    Args:
+        package: Package name
+        version: Desired version (default: latest)
+        from_version: Current cached version (for update check)
+        cache_dir: Cache directory (default: ~/.cache/pkgq/packages)
+        verbose: Print source information during lookup
+
+    Returns:
+        FindResult with package information
+
+    Raises:
+        ValueError: If package not found
+    """
+    if cache_dir is None:
+        cache_dir = get_cache_dir()
+
+    # Step 1: Check local cache
+    cached = check_cached(package, cache_dir)
+    if cached and from_version:
+        # Check if we need to update
+        if cached.version == from_version:
+            # Same version, return cached
+            return cached
+        # Different version, need to fetch
+    elif cached and not from_version:
+        # No version specified, use cached
+        return cached
+
+    # Step 2: Get PyPI info
+    pypi_info = get_pypi_info(package)
+    info = pypi_info.get("info", {})
+    latest_version = info.get("version", "unknown")
+
+    if version is None:
+        version = latest_version
+
+    # Step 3: Try GitHub
+    github_url = extract_github_url(pypi_info)
+    github_error = None
+    if github_url:
+        try:
+            owner, repo = parse_github_url(github_url)
+            default_branch = get_default_branch(owner, repo)
+
+            # Try common branches
+            branches_tried = []
+            for branch in [default_branch, "main", "master"]:
+                if branch in branches_tried:
+                    continue
+                branches_tried.append(branch)
+                content = fetch_package_md_from_github(owner, repo, branch)
+                if content:
+                    if verbose:
+                        print(f"Found PACKAGE.md on GitHub ({owner}/{repo}, branch: {branch})")
+                    return FindResult(
+                        package=package,
+                        version=version,
+                        source=f"github:{owner}/{repo}",
+                        content=content,
+                        cached=False,
+                    )
+
+            # GitHub URL found but no PACKAGE.md in any branch
+            github_error = f"GitHub repo found ({owner}/{repo}) but no PACKAGE.md found in branches: {', '.join(branches_tried)}"
+        except ValueError as e:
+            github_error = f"Invalid GitHub URL: {e}"
+
+    # Step 4: Generate basic info from PyPI
+    if verbose and github_error:
+        print(f"Warning: {github_error}")
+        print("Falling back to PyPI-generated documentation")
+
+    summary = info.get("summary", "No summary available")
+    author = info.get("author", "Unknown")
+    home_page = info.get("home_page", "")
+    project_urls = info.get("project_urls") or {}
+
+    content = f"""# {package}
+
+> {summary}
+
+## Overview
+
+Package: **{package}**
+Version: **{version}**
+Author: **{author}**
+
+## Installation
+
+```
+pip install {package}
+```
+
+## References
+
+"""
+
+    if home_page:
+        content += f"- Homepage: {home_page}\n"
+
+    for key, url in project_urls.items():
+        content += f"- {key}: {url}\n"
+
+    if github_error:
+        content += f"\n---\n\n_Note: {github_error}_\n"
+
+    return FindResult(
+        package=package,
+        version=version,
+        source="pypi",
+        content=content,
+        cached=False,
+    )

pkgq/mcp.py

@@ -0,0 +1,62 @@
+"""
+pkgq MCP Server - Model Context Protocol server for package query.
+
+Provides a simple tool to find package documentation.
+"""
+
+from typing import Annotated
+
+from fastmcp import FastMCP
+
+from pkgq import find
+
+# Create MCP server
+mcp = FastMCP(
+    name="pkgq",
+    version="0.1.0",
+)
+
+
+@mcp.tool()
+def find_package(
+    package: Annotated[str, "Package name to find"],
+    version: Annotated[str | None, "Desired version (default: latest)"] = None,
+    from_version: Annotated[str | None, "Current cached version (for update check)"] = None,
+) -> str:
+    """Find package documentation.
+
+    Queries multiple sources in order:
+    1. Local cache (if from_version is provided)
+    2. GitHub repository (PACKAGE.md)
+    3. Generate from PyPI docs
+
+    Args:
+        package: Package name (e.g., "yoker", "httpx")
+        version: Desired version (default: latest)
+        from_version: Current cached version (for update check)
+
+    Returns:
+        Package documentation in PACKAGE.md format
+    """
+    result = find(
+        package=package,
+        version=version,
+        from_version=from_version,
+        verbose=True,  # Include source information
+    )
+
+    # Return formatted result
+    status = "cached" if result.cached else "fetched"
+    header = f"# {result.package} (v{result.version}) [{status}]\n\n"
+    header += f"Source: {result.source}\n\n---\n\n"
+
+    return header + result.content
+
+
+def run():
+    """Run the MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    run()

pkgq-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: pkgq
+Version: 0.1.0
+Summary: Package Query - Find API information for Python packages
+Project-URL: Homepage, https://github.com/christophevg/pkgq
+Project-URL: Documentation, https://github.com/christophevg/pkgq#readme
+Project-URL: Repository, https://github.com/christophevg/pkgq
+Project-URL: Issues, https://github.com/christophevg/pkgq/issues
+Author-email: Christophe VG <contact@christophe.vg>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,api,documentation,mcp,package,query
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: twine>=6.0.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=3.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# pkgq
+
+**PacKaGe Query** - Find API information for Python packages.
+
+A fast, agent-friendly tool for discovering Python package documentation, capabilities, and migration guides.
+
+## Installation
+
+```bash
+# Install with uv
+uv add pkgq
+
+# Or with pip
+pip install pkgq
+
+# For MCP server support
+uv add "pkgq[mcp]"
+```
+
+## Usage
+
+### Python Module
+
+```python
+from pkgq import find
+
+# Find package documentation
+result = find("yoker")
+print(result.content)
+
+# Find specific version
+result = find("yoker", version="2.1.0")
+
+# Check for updates
+result = find("yoker", from_version="1.5.0")
+if result.version != "1.5.0":
+    print(f"Update available: {result.version}")
+
+# Save to cache
+result.save_to_cache()
+```
+
+### Command Line
+
+```bash
+# Find package documentation
+pkgq find yoker
+
+# Find specific version
+pkgq find yoker --version 2.1.0
+
+# Check for updates
+pkgq find yoker --from-version 1.5.0
+
+# Save to cache
+pkgq find yoker --save
+
+# Output as JSON
+pkgq find yoker --json
+
+# Manage cache
+pkgq cache --list
+pkgq cache --clear
+pkgq cache --dir
+```
+
+### MCP Server
+
+```bash
+# Run MCP server
+pkgq-mcp-server
+
+# Or with uvx
+uvx --from pkgq pkgq-mcp-server
+```
+
+The MCP server provides a `find_package` tool for use with Claude Code and other MCP-compatible agents.
+
+## Cache
+
+Package documentation is cached locally:
+
+- Default: `~/.cache/pkgq/packages/`
+- Custom: Set `PKGQ_CACHE` environment variable
+
+Cache structure:
+```
+~/.cache/pkgq/packages/
+├── yoker/
+│   ├── PACKAGE.md      # Package documentation
+│   └── metadata.json   # Version and source info
+└── roomz/
+    ├── PACKAGE.md
+    └── metadata.json
+```
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/christophevg/pkgq.git
+cd pkgq
+
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run linter
+uv run ruff check src/
+
+# Run MCP server
+uv run pkgq-mcp-server
+```
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.

pkgq-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pkgq/__init__.py,sha256=FJDbnF5gs_AsA7LJCsE_h__9mm2g-kVFF9bAs0iTMZ0,169
+pkgq/cli.py,sha256=_Y_VlbV9lXsKH_zylnmFJM7WGGRIQeuodttP8FRe0ro,4564
+pkgq/find.py,sha256=IFdJdx2p5cfVcQLMVhe30XbN7jvQnFnjf71b5JEzmA4,9275
+pkgq/mcp.py,sha256=p52Yjfzjly4ARClnHW6hBlNki7k4W5JnEF8zU5oO9Yw,1504
+pkgq-0.1.0.dist-info/METADATA,sha256=HdOAYUMY3kWKG2y3FKWt-EaDLysva4dVQ5pHrtIRhxY,3412
+pkgq-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pkgq-0.1.0.dist-info/entry_points.txt,sha256=Cist7pDtF1CXo6fgRc0DgHmESMzXD6POYLGlVT8BqZY,70
+pkgq-0.1.0.dist-info/licenses/LICENSE,sha256=fbkavbRGILRFIQKDzdgC-IO9QoSUQ7eNvQcqA6L1cBU,1069
+pkgq-0.1.0.dist-info/RECORD,,

pkgq-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pkgq-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pkgq = pkgq.cli:main
+pkgq-mcp-server = pkgq.mcp:run

pkgq-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Christophe VG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.