# PyEnvSearch
🔍 **Python library navigation tool for developers and AI agents**
A powerful command-line tool designed for the modern Python ecosystem (uv/uvx) that combines traditional code search with AI-powered package analysis.
## ✨ Key Features
### 🔍 **Code Discovery & Navigation**
- **Virtual Environment Detection**: Automatically finds and analyzes virtual environments
- **Package Location Discovery**: Locates exact paths for installed packages
- **Semantic Code Search**: Find classes, methods, enums with AST-aware search
- **High-Performance Search**: Uses ast-grep and ripgrep when available for blazing-fast search
- **Code Structure Navigation**: Generate beautiful table of contents for any package
### 🤖 **AI-Powered Analysis**
- **Package Summaries**: Get concise overviews of any Python package
- **Technical Explanations**: Deep dive into package architecture and design
- **Step-by-Step Tutorials**: Generate how-to guides for specific tasks
- **API References**: Comprehensive usage patterns and best practices
- **Multi-LLM Support**: Works with Claude, Gemini, Codex, and Goose
### 🛠️ **Developer Experience**
- **JSON Output**: Perfect for programmatic usage and tool integration
- **LLM-Friendly Documentation**: Finds AI-optimized docs (llms.txt, ai.txt)
- **Zero Heavy Dependencies**: Minimal footprint with graceful degradation
- **uv/uvx Native**: Built for the modern Python toolchain
## 🚀 Installation
### Prerequisites
**Core functionality works with Python standard library only.** For enhanced features:
#### Optional: Performance Tools
```bash
# For blazing-fast search (highly recommended)
# macOS
brew install ripgrep ast-grep
# Ubuntu/Debian
sudo apt install ripgrep
cargo install ast-grep-cli
# Windows
winget install BurntSushi.ripgrep.MSVC
cargo install ast-grep-cli
```
#### Optional: AI-Powered Analysis
For AI features, install at least one LLM CLI tool:
```bash
# Claude (best results) - requires subscription
npm install -g @anthropic-ai/claude
# Gemini (free tier available)
npm install -g @google/generative-ai-cli
# Codex (OpenAI account required)
# See: https://github.com/microsoft/codex-cli
# Goose (multi-provider support)
pipx install goose-ai
```
### Install PyEnvSearch
```bash
# With uv tool (recommended for CLI usage)
uv tool install pyenvsearch
# With performance tools for blazing-fast search
uv tool install "pyenvsearch[performance]"
# With pipx (alternative CLI installer)
pipx install pyenvsearch
pipx install "pyenvsearch[performance]"
# For one-time usage (no installation)
uvx pyenvsearch --help
# Or install as regular package
uv add pyenvsearch
uv add "pyenvsearch[performance]" # With fast search tools
pip install pyenvsearch
pip install "pyenvsearch[performance]"
```
## 📖 Usage Guide
### 🔍 Environment & Discovery
**Understand your Python environment and locate packages**
```bash
# Show virtual environment info
pyenvsearch venv
# Find where a package is installed
pyenvsearch find httpx
# Find LLM-optimized documentation
pyenvsearch docs requests
```
### 🔎 Code Navigation & Search
**Navigate and search through package code**
```bash
# Generate package table of contents
pyenvsearch toc fastapi --depth 3
# Search for code patterns
pyenvsearch search "class.*Http" --type regex
pyenvsearch search "async def" --package httpx
# Find specific classes and methods
pyenvsearch class HttpClient
pyenvsearch method get --class HttpClient
# List all classes, methods, or enums in a package
pyenvsearch list-classes requests
pyenvsearch list-methods httpx --include-private
pyenvsearch list-enums enum --enum-type IntEnum
```
### 🤖 AI-Powered Analysis
**Get intelligent insights about any Python package**
```bash
# Quick package overview
pyenvsearch summarize requests
# Deep technical explanation
pyenvsearch explain fastapi --tool claude
# Step-by-step tutorials
pyenvsearch howto pandas --task "data cleaning"
pyenvsearch howto sqlalchemy
# Comprehensive API guides
pyenvsearch api-guide httpx --tool gemini
# Check available AI tools
pyenvsearch llm-tools
```
### 💾 JSON Output
**Perfect for scripts and tool integration**
```bash
# Any command with --json flag
pyenvsearch find httpx --json
pyenvsearch summarize requests --json | jq '.content'
pyenvsearch list-classes fastapi --json
```
## 🎯 Real-World Examples
### 🧪 Exploring a New Package
```bash
# Just installed a new package? Get oriented quickly:
pyenvsearch find fastapi # Where is it?
pyenvsearch summarize fastapi # What does it do?
pyenvsearch toc fastapi --depth 2 # How is it structured?
pyenvsearch list-classes fastapi # What are the main classes?
```
### 🔍 Debugging & Investigation
```bash
# Looking for specific functionality:
pyenvsearch search "ValidationError" --package pydantic
pyenvsearch method validate --package pydantic
pyenvsearch class BaseModel --package pydantic
# Need usage examples:
pyenvsearch howto pydantic --task "custom validators"
pyenvsearch api-guide pydantic
```
### 🤖 AI Agent Workflows
```bash
# Perfect for AI agents exploring codebases:
pyenvsearch venv --json | jq '.packages[]'
pyenvsearch docs requests --json # Find AI-friendly docs
pyenvsearch explain httpx --json # Get structured analysis
pyenvsearch search "async.*client" --json --package httpx
```
### 📊 Package Analysis Scripts
```bash
#!/bin/bash
# Analyze all installed packages
for pkg in $(pyenvsearch venv --json | jq -r '.packages[].name'); do
echo "=== $pkg ==="
pyenvsearch summarize "$pkg" --json | jq -r '.content'
done
```
## 🏗️ Architecture
**Built for Performance & Developer Experience:**
- **🪶 Minimal Dependencies**: Python standard library + optional performance tools
- **⚡ High Performance**: Leverages ast-grep, ripgrep when available
- **🔄 Graceful Degradation**: Works with or without external tools
- **🎯 uv/uvx Native**: Designed for modern Python workflows
- **🤖 LLM Integration**: Multi-provider AI analysis with automatic fallback
- **📊 Structured Output**: JSON support for programmatic usage
## 🛠️ Development
### Setup
```bash
git clone <repository-url>
cd pyenvsearch
uv sync --dev
```
### Testing
```bash
# Run all tests
uv run pytest
# With coverage
uv run pytest --cov=src --cov-report=html
# Test specific functionality
uv run pytest tests/test_llm.py -v
```
### Code Quality
```bash
# Lint and fix issues
uvx ruff check --fix
uvx ruff format
# Type checking
uvx mypy src/
# Run all quality checks
uvx ruff check --fix && uvx ruff format && uvx mypy src/
```
### Manual Testing
```bash
# Test basic functionality
uv run python -m pyenvsearch venv
uv run python -m pyenvsearch find requests
uv run python -m pyenvsearch summarize requests
# Test with different LLM tools
uv run python -m pyenvsearch llm-tools
uv run python -m pyenvsearch summarize requests --tool claude
```
## 📋 Requirements
### Core Requirements
- **Python 3.13+** (uses modern Python features)
- **uv/uvx** (recommended package manager)
### Optional Performance Tools
- **ripgrep** (`rg`) - Blazing fast text search
- **ast-grep** - Semantic code search and analysis
```bash
# Install performance tools (optional but recommended)
# macOS
brew install ripgrep ast-grep
# Ubuntu/Debian
sudo apt install ripgrep
cargo install ast-grep-cli
# Windows
winget install BurntSushi.ripgrep.MSVC
cargo install ast-grep-cli
```
### LLM Tools (for AI features)
- **Claude CLI** - Best results, requires subscription
- **Gemini CLI** - Good free tier
- **Codex CLI** - OpenAI integration
- **Goose** - Multi-provider support
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
---
**Made with ❤️ for the Python community and AI agents everywhere** 🐍🤖
Raw data
{
"_id": null,
"home_page": null,
"name": "pyenvsearch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ai, development, documentation, llm, navigation, packages, python, search, uv, uvx, virtual-environment",
"author": null,
"author_email": "Michael Bommarito <michael.bommarito@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/11/3b/afa0aa6bd9693ee45d05fb7835cb36115973feec9c1d51e2a548d137ad2d/pyenvsearch-0.4.0.tar.gz",
"platform": null,
"description": "# PyEnvSearch\n\n\ud83d\udd0d **Python library navigation tool for developers and AI agents**\n\nA powerful command-line tool designed for the modern Python ecosystem (uv/uvx) that combines traditional code search with AI-powered package analysis.\n\n## \u2728 Key Features\n\n### \ud83d\udd0d **Code Discovery & Navigation**\n- **Virtual Environment Detection**: Automatically finds and analyzes virtual environments\n- **Package Location Discovery**: Locates exact paths for installed packages \n- **Semantic Code Search**: Find classes, methods, enums with AST-aware search\n- **High-Performance Search**: Uses ast-grep and ripgrep when available for blazing-fast search\n- **Code Structure Navigation**: Generate beautiful table of contents for any package\n\n### \ud83e\udd16 **AI-Powered Analysis** \n- **Package Summaries**: Get concise overviews of any Python package\n- **Technical Explanations**: Deep dive into package architecture and design\n- **Step-by-Step Tutorials**: Generate how-to guides for specific tasks\n- **API References**: Comprehensive usage patterns and best practices\n- **Multi-LLM Support**: Works with Claude, Gemini, Codex, and Goose\n\n### \ud83d\udee0\ufe0f **Developer Experience**\n- **JSON Output**: Perfect for programmatic usage and tool integration\n- **LLM-Friendly Documentation**: Finds AI-optimized docs (llms.txt, ai.txt)\n- **Zero Heavy Dependencies**: Minimal footprint with graceful degradation\n- **uv/uvx Native**: Built for the modern Python toolchain\n\n## \ud83d\ude80 Installation\n\n### Prerequisites\n**Core functionality works with Python standard library only.** For enhanced features:\n\n#### Optional: Performance Tools\n```bash\n# For blazing-fast search (highly recommended)\n# macOS\nbrew install ripgrep ast-grep\n\n# Ubuntu/Debian \nsudo apt install ripgrep\ncargo install ast-grep-cli\n\n# Windows\nwinget install BurntSushi.ripgrep.MSVC\ncargo install ast-grep-cli\n```\n\n#### Optional: AI-Powered Analysis\nFor AI features, install at least one LLM CLI tool:\n```bash\n# Claude (best results) - requires subscription\nnpm install -g @anthropic-ai/claude\n\n# Gemini (free tier available) \nnpm install -g @google/generative-ai-cli\n\n# Codex (OpenAI account required)\n# See: https://github.com/microsoft/codex-cli\n\n# Goose (multi-provider support)\npipx install goose-ai\n```\n\n### Install PyEnvSearch\n```bash\n# With uv tool (recommended for CLI usage)\nuv tool install pyenvsearch\n\n# With performance tools for blazing-fast search\nuv tool install \"pyenvsearch[performance]\"\n\n# With pipx (alternative CLI installer)\npipx install pyenvsearch\npipx install \"pyenvsearch[performance]\"\n\n# For one-time usage (no installation)\nuvx pyenvsearch --help\n\n# Or install as regular package\nuv add pyenvsearch\nuv add \"pyenvsearch[performance]\" # With fast search tools\npip install pyenvsearch\npip install \"pyenvsearch[performance]\"\n```\n\n## \ud83d\udcd6 Usage Guide\n\n### \ud83d\udd0d Environment & Discovery\n**Understand your Python environment and locate packages**\n\n```bash\n# Show virtual environment info\npyenvsearch venv\n\n# Find where a package is installed\npyenvsearch find httpx\n\n# Find LLM-optimized documentation\npyenvsearch docs requests\n```\n\n### \ud83d\udd0e Code Navigation & Search\n**Navigate and search through package code**\n\n```bash\n# Generate package table of contents \npyenvsearch toc fastapi --depth 3\n\n# Search for code patterns\npyenvsearch search \"class.*Http\" --type regex\npyenvsearch search \"async def\" --package httpx\n\n# Find specific classes and methods\npyenvsearch class HttpClient\npyenvsearch method get --class HttpClient\n\n# List all classes, methods, or enums in a package\npyenvsearch list-classes requests\npyenvsearch list-methods httpx --include-private\npyenvsearch list-enums enum --enum-type IntEnum\n```\n\n### \ud83e\udd16 AI-Powered Analysis\n**Get intelligent insights about any Python package**\n\n```bash\n# Quick package overview\npyenvsearch summarize requests\n\n# Deep technical explanation \npyenvsearch explain fastapi --tool claude\n\n# Step-by-step tutorials\npyenvsearch howto pandas --task \"data cleaning\"\npyenvsearch howto sqlalchemy \n\n# Comprehensive API guides\npyenvsearch api-guide httpx --tool gemini\n\n# Check available AI tools\npyenvsearch llm-tools\n```\n\n### \ud83d\udcbe JSON Output\n**Perfect for scripts and tool integration**\n\n```bash\n# Any command with --json flag\npyenvsearch find httpx --json\npyenvsearch summarize requests --json | jq '.content'\npyenvsearch list-classes fastapi --json\n```\n\n## \ud83c\udfaf Real-World Examples\n\n### \ud83e\uddea Exploring a New Package\n```bash\n# Just installed a new package? Get oriented quickly:\npyenvsearch find fastapi # Where is it?\npyenvsearch summarize fastapi # What does it do?\npyenvsearch toc fastapi --depth 2 # How is it structured?\npyenvsearch list-classes fastapi # What are the main classes?\n```\n\n### \ud83d\udd0d Debugging & Investigation \n```bash\n# Looking for specific functionality:\npyenvsearch search \"ValidationError\" --package pydantic\npyenvsearch method validate --package pydantic\npyenvsearch class BaseModel --package pydantic\n\n# Need usage examples:\npyenvsearch howto pydantic --task \"custom validators\"\npyenvsearch api-guide pydantic\n```\n\n### \ud83e\udd16 AI Agent Workflows\n```bash\n# Perfect for AI agents exploring codebases:\npyenvsearch venv --json | jq '.packages[]'\npyenvsearch docs requests --json # Find AI-friendly docs\npyenvsearch explain httpx --json # Get structured analysis\npyenvsearch search \"async.*client\" --json --package httpx\n```\n\n### \ud83d\udcca Package Analysis Scripts\n```bash\n#!/bin/bash\n# Analyze all installed packages\nfor pkg in $(pyenvsearch venv --json | jq -r '.packages[].name'); do\n echo \"=== $pkg ===\"\n pyenvsearch summarize \"$pkg\" --json | jq -r '.content'\ndone\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\n**Built for Performance & Developer Experience:**\n- **\ud83e\udeb6 Minimal Dependencies**: Python standard library + optional performance tools\n- **\u26a1 High Performance**: Leverages ast-grep, ripgrep when available \n- **\ud83d\udd04 Graceful Degradation**: Works with or without external tools\n- **\ud83c\udfaf uv/uvx Native**: Designed for modern Python workflows\n- **\ud83e\udd16 LLM Integration**: Multi-provider AI analysis with automatic fallback\n- **\ud83d\udcca Structured Output**: JSON support for programmatic usage\n\n## \ud83d\udee0\ufe0f Development\n\n### Setup\n```bash\ngit clone <repository-url>\ncd pyenvsearch\nuv sync --dev\n```\n\n### Testing\n```bash\n# Run all tests\nuv run pytest\n\n# With coverage\nuv run pytest --cov=src --cov-report=html\n\n# Test specific functionality\nuv run pytest tests/test_llm.py -v\n```\n\n### Code Quality\n```bash\n# Lint and fix issues\nuvx ruff check --fix\nuvx ruff format\n\n# Type checking\nuvx mypy src/\n\n# Run all quality checks\nuvx ruff check --fix && uvx ruff format && uvx mypy src/\n```\n\n### Manual Testing\n```bash\n# Test basic functionality\nuv run python -m pyenvsearch venv\nuv run python -m pyenvsearch find requests\nuv run python -m pyenvsearch summarize requests\n\n# Test with different LLM tools\nuv run python -m pyenvsearch llm-tools\nuv run python -m pyenvsearch summarize requests --tool claude\n```\n\n## \ud83d\udccb Requirements\n\n### Core Requirements\n- **Python 3.13+** (uses modern Python features)\n- **uv/uvx** (recommended package manager)\n\n### Optional Performance Tools \n- **ripgrep** (`rg`) - Blazing fast text search\n- **ast-grep** - Semantic code search and analysis\n\n```bash\n# Install performance tools (optional but recommended)\n# macOS\nbrew install ripgrep ast-grep\n\n# Ubuntu/Debian \nsudo apt install ripgrep\ncargo install ast-grep-cli\n\n# Windows\nwinget install BurntSushi.ripgrep.MSVC\ncargo install ast-grep-cli\n```\n\n### LLM Tools (for AI features)\n- **Claude CLI** - Best results, requires subscription\n- **Gemini CLI** - Good free tier\n- **Codex CLI** - OpenAI integration \n- **Goose** - Multi-provider support\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**Made with \u2764\ufe0f for the Python community and AI agents everywhere** \ud83d\udc0d\ud83e\udd16",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library navigation and AI-powered analysis tool for developers and AI agents. Combines traditional code search with LLM-powered package insights.",
"version": "0.4.0",
"project_urls": {
"Changelog": "https://github.com/mjbommar/pyenvsearch/releases",
"Documentation": "https://github.com/mjbommar/pyenvsearch#readme",
"Homepage": "https://github.com/mjbommar/pyenvsearch",
"Issues": "https://github.com/mjbommar/pyenvsearch/issues",
"Repository": "https://github.com/mjbommar/pyenvsearch.git"
},
"split_keywords": [
"ai",
" development",
" documentation",
" llm",
" navigation",
" packages",
" python",
" search",
" uv",
" uvx",
" virtual-environment"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "66524270ff6f625cf8a70716310b195943e98197e20865bdb1796d792c7476f4",
"md5": "2b66d3f4fd99bb5270ebfb212ae1feec",
"sha256": "84f891d07981b49315f54b98629f8112dd4db8c58bb701c8f5c93bcccb0bf37d"
},
"downloads": -1,
"filename": "pyenvsearch-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b66d3f4fd99bb5270ebfb212ae1feec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 36031,
"upload_time": "2025-08-25T02:15:11",
"upload_time_iso_8601": "2025-08-25T02:15:11.343431Z",
"url": "https://files.pythonhosted.org/packages/66/52/4270ff6f625cf8a70716310b195943e98197e20865bdb1796d792c7476f4/pyenvsearch-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "113bafa0aa6bd9693ee45d05fb7835cb36115973feec9c1d51e2a548d137ad2d",
"md5": "3e73d9a56aa8c94e03c69c07b17dbc3e",
"sha256": "e92277bc2630c624eefd2c425d7eb682ab739e848b774e5b64ddf480b07ab4bf"
},
"downloads": -1,
"filename": "pyenvsearch-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "3e73d9a56aa8c94e03c69c07b17dbc3e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 39740,
"upload_time": "2025-08-25T02:15:12",
"upload_time_iso_8601": "2025-08-25T02:15:12.821939Z",
"url": "https://files.pythonhosted.org/packages/11/3b/afa0aa6bd9693ee45d05fb7835cb36115973feec9c1d51e2a548d137ad2d/pyenvsearch-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 02:15:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mjbommar",
"github_project": "pyenvsearch",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyenvsearch"
}
JSON
