pydocq

pydocq is a command-line interface tool for querying Python package documentation, specifically designed for AI agents. It provides structured, machine-readable JSON metadata about Python packages, classes, functions, and methods.

Features

Core Functionality

• Path Resolution: Query any Python element using dot notation (e.g., pandas.DataFrame.merge)
• Runtime Introspection: Extract signatures, docstrings, and source locations using Python's inspect module
• Member Discovery: List and categorize all members of modules and classes
• Type Annotation Parsing: Parse and analyze complex type annotations (Optional, Union, generics)
• AST Static Analysis: Analyze Python source code without importing it
• Search Functionality: Search elements by name pattern, docstring content, type, or metadata

SDK Decorators

Add custom metadata to your code using decorators:

• @metadata(**kwargs): Add arbitrary metadata
• @example(code, description): Add code examples
• @deprecated(reason, since, version): Mark as deprecated
• @param(name, **info): Document parameters
• @returns(**info): Document return values
• @category(*categories): Categorize elements
• @tag(*tags): Add tags
• @when(version, condition): Add version information
• @note(text): Add notes
• @author(name, email): Add author information
• @see_also(*references): Add cross-references

Output Formats

• json: Structured, machine-readable JSON (default)
• raw: Human-readable text format
• signature: Minimal signature-only output
• markdown: Markdown documentation format
• yaml: YAML structure

Installation

pip install pydocq

Usage

Basic Query

# Query a module
pydocq json

# Query a function
pydocq json.dumps

# Query a class
pydocq pandas.DataFrame

# Query a method
pydocq pandas.DataFrame.merge

Output Options

# Verbose output (includes SDK metadata)
pydocq --verbose my_package.MyClass

# Compact output (only path, type, module_path)
pydocq --compact json.dumps

# Include source location
pydocq --include-source os.path.join

# Include SDK metadata
pydocq --include-metadata my_module.my_func

# Exclude docstring or signature
pydocq --no-docstring json.dumps
pydocq --no-signature json.dumps

Output Formats

# JSON (default)
pydocq --format json json.dumps

# Raw text format
pydocq --format raw json.dumps

# Signature only
pydocq --format signature json.dumps

# Markdown format
pydocq --format markdown pandas.DataFrame

# YAML format
pydocq --format yaml json.dumps

Member Discovery

# List all members of a module
pydocq --list-members json

# List all members including private ones
pydocq --list-members --include-private json

# List class members
pydocq --list-members builtins.str

# List class members including inherited
pydocq --list-members --include-inherited my_package.MyClass

Using SDK Decorators

from pydocq import metadata, example, deprecated, tag

@metadata(category="api", version="1.0")
@tag("important", "stable")
@example("result = my_function(42)", "Basic usage")
@deprecated("Use new_function instead", since="1.0", version="2.0")
def my_function(x: int) -> int:
    """Process an integer value.

    Args:
        x: The input value

    Returns:
        The processed value
    """
    return x * 2

Query with metadata:

pydocq --include-metadata my_module.my_function

Output:

{
  "path": "my_module.my_function",
  "type": "function",
  "module_path": "my_module",
  "signature": {
    "parameters": [
      {
        "name": "x",
        "kind": "POSITIONAL_OR_KEYWORD",
        "annotation": "int",
        "default": null
      }
    ],
    "return_type": "int"
  },
  "docstring": {
    "docstring": "Process an integer value...",
    "length": 123
  },
  "sdk_metadata": {
    "category": "api",
    "version": "1.0",
    "tags": ["important", "stable"],
    "example": {"code": "result = my_function(42)", "description": "Basic usage"},
    "deprecated": {"reason": "Use new_function instead", "since": "1.0", "version": "2.0"}
  }
}

Development

Setup

# Clone the repository
git clone https://github.com/yourusername/pydocq.git
cd pydocq

# Install with uv
uv pip install -e .

# Or with pip
pip install -e .

Running Tests

# Install development dependencies
uv pip install pytest pytest-cov

# Run tests
pytest

# Run tests with coverage
pytest --cov=pydocq --cov-report=html

Building for Distribution

# Build with uv
uv build

# Or with pip
python -m build

# The built package will be in dist/

Project Structure

pydocq/
├── pydocq/
│   ├── __init__.py
│   ├── cli.py              # CLI interface
│   ├── analyzer/
│   │   ├── resolver.py      # Path resolution
│   │   ├── inspector.py     # Runtime introspection
│   │   ├── formatter.py     # JSON formatting
│   │   ├── discovery.py     # Member discovery
│   │   ├── errors.py        # Error handling
│   │   ├── type_parser.py   # Type annotation parsing
│   │   ├── ast_analyzer.py  # AST static analysis
│   │   ├── output_formats.py # Output formatters
│   │   └── search.py        # Search functionality
│   └── sdk/
│       ├── __init__.py
│       └── decorators.py     # SDK decorators
├── tests/
│   ├── test_cli.py
│   ├── test_resolver.py
│   ├── test_inspector.py
│   ├── test_formatter.py
│   ├── test_discovery.py
│   ├── test_errors.py
│   ├── test_type_parser.py
│   ├── test_ast_analyzer.py
│   ├── test_output_formats.py
│   ├── test_sdk_decorators.py
│   └── test_search.py
├── docs/                    # Internal documentation
├── README.md
├── LICENSE
├── pyproject.toml
└── .python-version

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with:

• Typer for CLI interface
• Python's inspect module for runtime introspection
• Python's AST module for static analysis
• pytest for testing

Changelog

0.1.0 (Unreleased)

• Initial release
• Path resolution for Python packages
• Runtime introspection with inspect module
• Member discovery for modules and classes
• Type annotation parsing
• AST static analysis
• SDK decorators for custom metadata
• Search functionality
• Multiple output formats (JSON, raw, signature, markdown, YAML)
• Comprehensive test coverage (178 tests)