pkgq 0.1.0__tar.gz

pkgq-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+.eggs/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+
+# System
+.DS_Store
+Thumbs.db
+
+# Local
+*.local.*
+.env

pkgq-0.1.0/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.

pkgq-0.1.0/Makefile

@@ -0,0 +1,37 @@
+# pkgq Makefile
+
+.PHONY: help install test lint build publish clean
+
+# Installation
+help:
+	@echo "pkgq - Package Query"
+	@echo ""
+	@echo "Commands:"
+	@echo "  make install    - Install dependencies"
+	@echo "  make test       - Run tests"
+	@echo "  make lint       - Run linter"
+	@echo "  make build      - Build package"
+	@echo "  make publish    - Publish to PyPI"
+	@echo "  make clean      - Clean build artifacts"
+
+install:
+	uv sync
+
+test:
+	uv run pytest -v
+
+lint:
+	uv run ruff check src/
+	uv run mypy src/
+
+build:
+	uv build
+
+publish: build
+	uv publish
+
+clean:
+	rm -rf dist/
+	rm -rf .venv/
+	find . -type d -name "__pycache__" -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete

pkgq-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,119 @@
+# 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/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pkgq"
+version = "0.1.0"
+description = "Package Query - Find API information for Python packages"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Christophe VG", email = "contact@christophe.vg"}]
+keywords = ["package", "query", "api", "documentation", "mcp", "agent"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+
+dependencies = [
+  "httpx>=0.27.0",
+  "pydantic>=2.0.0",
+  "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+mcp = [
+  "fastmcp>=3.0.0",
+]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+  "pytest-cov>=5.0.0",
+  "mypy>=1.13.0",
+  "ruff>=0.8.0",
+  "build>=1.0.0",
+  "twine>=6.0.0",
+]
+
+[project.scripts]
+pkgq = "pkgq.cli:main"
+pkgq-mcp-server = "pkgq.mcp:run"
+
+[project.urls]
+Homepage = "https://github.com/christophevg/pkgq"
+Documentation = "https://github.com/christophevg/pkgq#readme"
+Repository = "https://github.com/christophevg/pkgq"
+Issues = "https://github.com/christophevg/pkgq/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pkgq"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-v --cov=pkgq --cov-report=term-missing"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+indent-width = 2
+
+[tool.ruff.lint]
+select = [
+  "E",   # pycodestyle errors
+  "W",   # pycodestyle warnings
+  "F",   # pyflakes
+  "I",   # isort
+  "B",   # flake8-bugbear
+  "C4",  # flake8-comprehensions
+  "UP",  # pyupgrade
+]
+ignore = [
+  "E501",  # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pkgq"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "def __repr__",
+  "raise NotImplementedError",
+  "if TYPE_CHECKING:",
+]

pkgq-0.1.0/src/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-0.1.0/src/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()