Analysis Runner

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

Capabilities

Prospector Class

Main orchestrator class that coordinates the execution of multiple static analysis tools and aggregates their results.

class Prospector:
    def __init__(self, config: ProspectorConfig) -> None

Creates a new Prospector instance with the provided configuration.

Parameters:

• config: ProspectorConfig - Configuration object containing analysis settings

Properties:

• config: ProspectorConfig - The configuration object
• summary: Optional[dict[str, Any]] - Analysis summary information
• messages: list[Message] - Collection of analysis messages

def execute(self) -> None

Executes the analysis by running all configured tools and processing their results. This method:

1. Discovers files to analyze using FileFinder
2. Runs each enabled tool on the discovered files
3. Processes and filters the resulting messages
4. Generates summary information

def get_messages(self) -> list[Message]

Returns all analysis messages found during execution.

Returns:

• list[Message] - List of all messages from analysis tools

def get_summary(self) -> Optional[dict[str, Any]]

Returns summary information about the analysis run.

Returns:

• Optional[dict[str, Any]] - Dictionary containing:
  • started: datetime - When analysis started
  • completed: datetime - When analysis completed
  • time_taken: str - Duration in seconds
  • message_count: int - Total number of messages
  • libraries: list[str] - Detected libraries
  • strictness: Optional[str] - Strictness level used
  • profiles: str - Comma-separated list of profiles
  • tools: list[str] - Tools that were run
  • formatter: str - Output formatter used
  • external_config: str - External config files used (if any)

def print_messages(self) -> None

Prints analysis results using the configured output formatters. Handles multiple output formats and files as specified in configuration.

def write_to(self, formatter: Formatter, target: TextIO) -> None

Writes formatted output to a specific target.

Parameters:

• formatter: Formatter - The formatter to use for output
• target: TextIO - The target stream to write to

def process_messages(self, found_files: FileFinder, messages: list[Message], 
                    tools: dict[str, ToolBase]) -> list[Message]

Processes raw messages from tools by applying blending and filtering.

Parameters:

• found_files: FileFinder - File discovery object
• messages: list[Message] - Raw messages from tools
• tools: dict[str, ToolBase] - Dictionary of tools that were run

Returns:

• list[Message] - Processed and filtered messages

Main Entry Point

def main() -> None

Main entry point function for the prospector command-line tool. This function:

1. Creates a ProspectorConfig from command-line arguments
2. Validates input paths (multi-path mode requires files, not directories)
3. Creates and executes a Prospector instance
4. Prints results and exits with appropriate code

Exit Codes:

• 0 - Success (no issues found or --zero-exit flag used)
• 1 - Analysis completed but issues were found
• 2 - Fatal error or invalid arguments

Parser Access

def get_parser() -> argparse.ArgumentParser

Returns the argparse parser used by prospector. This is primarily used for documentation generation with Sphinx.

Returns:

• argparse.ArgumentParser - The argument parser with all prospector options

Usage Examples

Basic Programmatic Usage

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

# Create default configuration
config = ProspectorConfig()

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

# Process results
messages = prospector.get_messages()
for message in messages:
    print(f"{message.source}: {message.message}")

# Get summary
summary = prospector.get_summary()
print(f"Analysis took {summary['time_taken']} seconds")
print(f"Found {summary['message_count']} issues")

Custom Configuration

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

# Create configuration with custom working directory
workdir = Path("/path/to/project")
config = ProspectorConfig(workdir=workdir)

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

# Print results using configured formatters
prospector.print_messages()

Error Handling

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

try:
    config = ProspectorConfig()
    prospector = Prospector(config)
    prospector.execute()
    
    messages = prospector.get_messages()
    if messages:
        print(f"Found {len(messages)} issues")
    else:
        print("No issues found!")
        
except FatalProspectorException as e:
    print(f"Fatal error: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")