Configuration

Comprehensive configuration system that handles command-line arguments, profiles, tool settings, and environment detection. The ProspectorConfig class is the central configuration management system for Prospector.

Capabilities

ProspectorConfig Class

Main configuration class that aggregates settings from command-line arguments, configuration files, and profiles.

class ProspectorConfig:
    def __init__(self, workdir: Optional[Path] = None) -> None

Creates a new configuration instance by processing command-line arguments and loading profiles.

Parameters:

• workdir: Optional[Path] - Working directory for analysis (defaults to current directory)

Properties:

• paths: list[Path] - Paths to analyze (files or directories)
• workdir: Path - Working directory for the analysis
• profile: ProspectorProfile - Active configuration profile
• tools_to_run: list[str] - List of tool names to execute
• libraries: list[str] - Detected/configured libraries (Django, Flask, etc.)
• messages: list[Message] - Configuration-related messages and warnings
• explicit_file_mode: bool - True if analyzing specific files rather than directories
• ignores: list[re.Pattern[str]] - Compiled regex patterns for ignoring files/paths
• configured_by: dict[str, Optional[Union[str, Path]]] - Track how each tool was configured

Tool Management

def get_tools(self, found_files: FileFinder) -> list[tools.ToolBase]

Creates and configures all enabled analysis tools.

Parameters:

• found_files: FileFinder - File discovery object for tool configuration

Returns:

• list[tools.ToolBase] - List of configured and ready-to-run tools

Side Effects:

• Updates configured_by dictionary with tool configuration sources
• Adds configuration messages to messages list

def replace_deprecated_tool_names(self) -> list[str]

Replaces deprecated tool names (pep8→pycodestyle, pep257→pydocstyle) with current names.

Returns:

• list[str] - List of deprecated tool names that were found and replaced

File Filtering

def make_exclusion_filter(self) -> Callable[[Path], bool]

Creates a filter function for excluding files and directories from analysis.

Returns:

• Callable[[Path], bool] - Filter function that returns True if path should be excluded

The filter checks against:

• Ignore patterns from configuration and profiles
• Ignore paths from configuration and profiles
• Library-specific ignore patterns (e.g., Django migrations)

Output Configuration

def get_output_report(self) -> list[tuple[str, list[str]]]

Gets the configured output format and target files.

Returns:

• list[tuple[str, list[str]]] - List of (format_name, target_files) tuples

Defaults to ("grouped", []) if no specific format is configured.

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

Gets summary information about the configuration for reporting.

Returns:

• dict[str, Any] - Dictionary containing:
  • libraries: list[str] - Detected libraries
  • strictness: Optional[str] - Strictness level
  • profiles: str - Comma-separated profile names
  • tools: list[str] - Tools to be run

Tool Configuration Access

def get_disabled_messages(self, tool_name: str) -> list[str]

Gets list of message codes disabled for a specific tool.

Parameters:

• tool_name: str - Name of the tool

Returns:

• list[str] - List of disabled message codes

def get_enabled_messages(self, tool_name: str) -> list[str]

Gets list of message codes enabled for a specific tool.

Parameters:

• tool_name: str - Name of the tool

Returns:

• list[str] - List of enabled message codes

def tool_options(self, tool_name: str) -> dict[str, Any]

Gets tool-specific configuration options.

Parameters:

• tool_name: str - Name of the tool

Returns:

• dict[str, Any] - Tool-specific options dictionary

def external_config_location(self, tool_name: str) -> Optional[Path]

Gets the path to external configuration file for a tool.

Parameters:

• tool_name: str - Name of the tool

Returns:

• Optional[Path] - Path to external config file, or None if not configured

def use_external_config(self, _: Any) -> bool

Determines whether to use external configuration files for tools.

Returns:

• bool - True if external config should be used

Exit Behavior

def exit_with_zero_on_success(self) -> bool

Determines whether to exit with code 0 even when issues are found.

Returns:

• bool - True if --zero-exit flag was provided

Configuration Properties

The ProspectorConfig class provides numerous boolean and scalar properties for accessing configuration settings:

@property
def die_on_tool_error(self) -> bool

Whether to exit immediately if a tool encounters an error.

@property
def summary_only(self) -> bool

Whether to output only summary information.

@property
def messages_only(self) -> bool

Whether to output only messages (no summary).

@property
def quiet(self) -> bool

Whether to suppress normal output.

@property
def blending(self) -> bool

Whether to blend/deduplicate similar messages from different tools.

@property
def absolute_paths(self) -> bool

Whether to use absolute paths in output.

@property
def max_line_length(self) -> int

Maximum line length setting for tools that support it.

@property
def include_tool_stdout(self) -> bool

Whether to include tool stdout/stderr in messages.

@property
def direct_tool_stdout(self) -> bool

Whether to pass tool output directly to console.

@property
def show_profile(self) -> bool

Whether to include profile information in output.

@property
def legacy_tool_names(self) -> bool

Whether to use legacy tool names in output.

Usage Examples

Basic Configuration

from prospector.config import ProspectorConfig
from pathlib import Path

# Default configuration using current directory
config = ProspectorConfig()

# Configuration with specific working directory
config = ProspectorConfig(workdir=Path("/path/to/project"))

# Access configuration properties
print(f"Tools to run: {config.tools_to_run}")
print(f"Libraries detected: {config.libraries}")
print(f"Blending enabled: {config.blending}")

Working with Tools

from prospector.config import ProspectorConfig
from prospector.finder import FileFinder
from pathlib import Path

config = ProspectorConfig()

# Discover files
paths = [Path(".")]
found_files = FileFinder(*paths, exclusion_filters=[config.make_exclusion_filter()])

# Get configured tools
tools = config.get_tools(found_files)

# Check how tools were configured
for tool_name, config_source in config.configured_by.items():
    if config_source:
        print(f"{tool_name} configured from: {config_source}")
    else:
        print(f"{tool_name} using default configuration")

Tool-Specific Configuration

from prospector.config import ProspectorConfig

config = ProspectorConfig()

# Get tool options
pylint_options = config.tool_options("pylint")
print(f"Pylint options: {pylint_options}")

# Check disabled messages
disabled = config.get_disabled_messages("pylint")
print(f"Disabled pylint messages: {disabled}")

# Check if external config should be used
if config.use_external_config("pylint"):
    external_config = config.external_config_location("pylint")
    if external_config:
        print(f"Using external pylint config: {external_config}")

File Filtering

from prospector.config import ProspectorConfig
from pathlib import Path

config = ProspectorConfig()

# Create exclusion filter
exclusion_filter = config.make_exclusion_filter()

# Test paths
test_paths = [
    Path("src/main.py"),
    Path("migrations/0001_initial.py"),
    Path("__pycache__/cache.py"),
    Path(".git/config")
]

for path in test_paths:
    if exclusion_filter(path):
        print(f"Excluding: {path}")
    else:
        print(f"Including: {path}")