tessl/pypi-pdoc

API Documentation for Python Projects with focus on simplicity and automatic HTML generation from docstrings

—

Pending

Overview

Eval results

Files

Module Extraction and Loading

Name: tessl/pypi-pdoc
Author: tessl

Utilities for discovering, loading, and walking Python modules with error handling and import safety. These functions handle the complex process of safely importing Python modules for documentation generation.

Capabilities

Module Specification Processing

Parse and process module specifications from command line arguments or API calls.

def walk_specs(specs: Sequence[Path | str]) -> list[str]:
    """
    Process module specifications and return module names.
    
    Parameters:
    - specs: Sequence of module names (str) or file paths (Path)
    
    Returns:
    - list[str]: Module names ready for import
    
    Handles:
    - File path to module name conversion
    - Negative patterns for exclusion (!pattern)
    - Package discovery and filtering
    - Submodule collection
    """

def parse_spec(spec: Path | str) -> str:
    """
    Parse individual module specification.
    
    Parameters:
    - spec: Path | str - Module specification (name or file path)
    
    Returns:
    - str: Resolved module name
    
    Side Effects:
    - May modify sys.path for file-based modules
    - Sets up module search paths
    """

Safe Module Loading

Load Python modules with error handling and side effect management.

def load_module(module: str) -> types.ModuleType:
    """
    Safely load a Python module for documentation.
    
    Parameters:
    - module: str - Dotted module name to load
    
    Returns:
    - ModuleType: The loaded Python module object
    
    Raises:
    - ImportError: If module cannot be imported
    - RuntimeError: If module has import-time side effects
    """

@contextmanager
def mock_some_common_side_effects():
    """
    Mock common side effects that may occur during module import.
    
    Prevents modules from performing unwanted actions during documentation generation.
    
    Effects:
    - Patches common side-effect functions
    - Prevents GUI dialogs and interactive prompts
    - Disables network connections where possible
    """

Module Discovery

Advanced module and package discovery utilities.

def iter_modules2(module: types.ModuleType) -> dict[str, pkgutil.ModuleInfo]:
    """
    Iterate over all modules in a package.
    
    Parameters:
    - module: types.ModuleType - Package module to iterate
    
    Returns:
    - dict[str, pkgutil.ModuleInfo]: Module info by name
    """

def walk_packages2(modules: Iterable[pkgutil.ModuleInfo]) -> Iterator[pkgutil.ModuleInfo]:
    """
    Walk all packages and subpackages from given module info.
    
    Parameters:
    - modules: Iterable[pkgutil.ModuleInfo] - Module info objects to traverse
    
    Yields:
    - pkgutil.ModuleInfo: Information about each discovered module
    """

Module Metadata

Utilities for extracting module metadata and managing import caches.

def module_mtime(modulename: str) -> float | None:
    """
    Get modification time of module source file.
    
    Parameters:
    - modulename: str - Dotted module name
    
    Returns:
    - float | None: Modification timestamp or None if not available
    """

def invalidate_caches(module_name: str) -> None:
    """
    Clear import caches for a module.
    
    Parameters:
    - module_name: str - Module name to invalidate
    
    Effects:
    - Clears importlib caches
    - Removes module from sys.modules if present
    - Forces fresh import on next load
    """

Install with Tessl CLI