or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

analysis-runner.mdconfiguration.mdexceptions.mdfile-finding.mdformatters.mdindex.mdmessages.mdprofiles.mdtools.md
tile.json

tessl/pypi-prospector

Prospector is a tool to analyse Python code by aggregating the result of other tools.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/prospector@1.17.x

To install, run

npx @tessl/cli install tessl/pypi-prospector@1.17.0

index.mddocs/

Prospector

Prospector is a comprehensive Python code analysis tool that aggregates results from multiple static analysis tools including Pylint, pycodestyle, pyflakes, mccabe complexity checker, pydocstyle, and others into a unified report. It provides intelligent defaults and profiles that adapt to different coding styles and frameworks, automatically detecting project dependencies to configure appropriate analysis rules.

Package Information

  • Package Name: prospector
  • Language: Python
  • Installation: pip install prospector
  • Optional Dependencies: prospector[with_bandit], prospector[with_mypy], prospector[with_pyright], prospector[with_pyroma], prospector[with_ruff], prospector[with_vulture], prospector[with_everything]

Core Imports

from prospector.run import Prospector, main
from prospector.config import ProspectorConfig
from prospector.message import Message, Location
from prospector.finder import FileFinder

For accessing tools and formatters:

from prospector import tools
from prospector.formatters import FORMATTERS
from prospector.tools.base import ToolBase

Basic Usage

Command Line Usage

# Analyze current directory
prospector

# Analyze specific path
prospector path/to/code

# Use specific tools
prospector --tool pylint --tool pyflakes

# Use specific profile
prospector --profile my_profile

# Output as JSON
prospector --output-format json

Programmatic Usage

from prospector.config import ProspectorConfig
from prospector.run import Prospector

# Create configuration
config = ProspectorConfig()

# Run analysis
prospector = Prospector(config)
prospector.execute()

# Get results
messages = prospector.get_messages()
summary = prospector.get_summary()

# Print results
prospector.print_messages()

Architecture

Prospector follows a plugin-based architecture with several key components:

  • Prospector: Main orchestrator that coordinates tool execution and message processing
  • ProspectorConfig: Configuration management system that handles command-line arguments, profiles, and tool settings
  • Tools: Plugin system where each static analysis tool (pylint, pyflakes, etc.) implements the ToolBase interface
  • Messages: Standardized representation of analysis results with Location information
  • Formatters: Output formatting system supporting multiple formats (JSON, text, XML, etc.)
  • Profiles: Configuration profiles that define tool settings and enable/disable rules
  • FileFinder: File discovery system that identifies Python modules and packages to analyze

This modular design allows Prospector to integrate diverse analysis tools while providing a consistent interface and unified output format.

Capabilities

Main Analysis Runner

Core functionality for running code analysis with the main Prospector class. This handles tool orchestration, configuration management, and result aggregation.

class Prospector:
    def __init__(self, config: ProspectorConfig) -> None: ...
    def execute(self) -> None: ...
    def get_messages(self) -> list[Message]: ...
    def get_summary(self) -> Optional[dict[str, Any]]: ...
    def print_messages(self) -> None: ...

def main() -> None: ...

Analysis Runner

Configuration Management

Comprehensive configuration system that handles command-line arguments, profiles, tool settings, and environment detection.

class ProspectorConfig:
    def __init__(self, workdir: Optional[Path] = None): ...
    def get_tools(self, found_files: FileFinder) -> list[tools.ToolBase]: ...
    def make_exclusion_filter(self) -> Callable[[Path], bool]: ...
    def get_output_report(self) -> list[tuple[str, list[str]]]: ...

Configuration

Message and Location System

Standardized data structures for representing analysis results and source code locations.

class Message:
    def __init__(self, source: str, code: str, location: Location, message: str, 
                 doc_url: Optional[str] = None, is_fixable: bool = False): ...

class Location:
    def __init__(self, path: Optional[Union[Path, str]], module: Optional[str], 
                 function: Optional[str], line: Optional[int], character: Optional[int],
                 line_end: Optional[int] = None, character_end: Optional[int] = None): ...

Messages

File Discovery

File and module discovery system that identifies Python code to be analyzed.

class FileFinder:
    def __init__(self, *provided_paths: Path, 
                 exclusion_filters: Optional[Iterable[Callable[[Path], bool]]] = None): ...
    @property
    def python_modules(self) -> list[Path]: ...
    @property  
    def python_packages(self) -> list[Path]: ...
    @property
    def files(self) -> set[Path]: ...
    def make_syspath(self) -> list[Path]: ...

File Finding

Tool Framework

Plugin system for integrating static analysis tools with base classes and tool registry.

class ToolBase(ABC):
    @abstractmethod
    def configure(self, prospector_config: "ProspectorConfig", found_files: FileFinder) -> Optional[tuple]: ...
    @abstractmethod  
    def run(self, found_files: FileFinder) -> list[Message]: ...

TOOLS: dict[str, type[ToolBase]]
DEFAULT_TOOLS: tuple[str, ...]

Tools

Output Formatters

Output formatting system supporting multiple formats including JSON, text, XML, and IDE integrations.

class Formatter(ABC):
    @abstractmethod
    def render(self, summary: bool = True, messages: bool = True, profile: bool = False) -> str: ...

FORMATTERS: dict[str, type[Formatter]]

Formatters

Profile Management

Configuration profile system for managing tool settings, rules, and project-specific configurations.

class ProspectorProfile:
    @staticmethod
    def load(name: Union[str, Path], profile_path: list[Path], 
             forced_inherits: Optional[list[str]] = None) -> ProspectorProfile: ...
    def is_tool_enabled(self, tool_name: str) -> Optional[bool]: ...

Profiles

Exceptions

Custom exception classes for error handling and diagnostics.

class FatalProspectorException(Exception):
    def __init__(self, message: str): ...

class CouldNotHandleEncoding(Exception):
    def __init__(self, path: Path): ...

class PermissionMissing(Exception):
    def __init__(self, path: Path): ...

Exceptions