API Reference

py-psscriptanalyzer Module

The py_psscriptanalyzer package provides the core functionality for PowerShell static analysis and formatting.

Main Module Functions

main(argv=None)

Main entry point for the py-psscriptanalyzer CLI tool.

Parameters:

  • argv (list, optional): Command line arguments. If None, uses sys.argv[1:]

Returns:

  • int: Exit code (0 for success, non-zero for failure)

Example:

from py_psscriptanalyzer import main

# Analyze a file programmatically
result = main(['script.ps1'])

run_script_analyzer(files, format_mode=False, severity='All')

Run PSScriptAnalyzer on the specified PowerShell files.

Parameters:

  • files (list[str]): List of PowerShell file paths to analyze

  • format_mode (bool, optional): If True, format files instead of analyzing. Defaults to False

  • severity (str, optional): Severity level to filter results. Options: ‘Error’, ‘Warning’, ‘Information’, ‘All’. Defaults to ‘All’

Returns:

  • int: Exit code (0 for success, non-zero for issues found or errors)

Example:

from py_psscriptanalyzer import run_script_analyzer

# Analyze files
result = run_script_analyzer(['script1.ps1', 'script2.ps1'], severity='Warning')

# Format files
result = run_script_analyzer(['script.ps1'], format_mode=True)

Core Module (py_psscriptanalyzer.core)

Functions

parse_arguments(args)

Parse command line arguments for the CLI tool.

Parameters:

  • args (list[str]): Command line arguments

Returns:

  • argparse.Namespace: Parsed arguments

filter_powershell_files(files)

Filter input files to only include PowerShell files.

Parameters:

  • files (list[str]): List of file paths

Returns:

  • list[str]: List of PowerShell file paths only

PowerShell Module (py_psscriptanalyzer.powershell)

Functions

find_powershell()

Find an available PowerShell executable on the system.

Returns:

  • str | None: Path to PowerShell executable, or None if not found

Example:

from py_psscriptanalyzer.powershell import find_powershell

pwsh_path = find_powershell()
if pwsh_path:
    print(f"Found PowerShell at: {pwsh_path}")
else:
    print("PowerShell not found")

check_psscriptanalyzer_installed(powershell_exe)

Check if the PSScriptAnalyzer module is installed.

Parameters:

  • powershell_exe (str): Path to PowerShell executable

Returns:

  • bool: True if PSScriptAnalyzer is installed, False otherwise

install_psscriptanalyzer(powershell_exe)

Install the PSScriptAnalyzer PowerShell module.

Parameters:

  • powershell_exe (str): Path to PowerShell executable

Returns:

  • bool: True if installation succeeded, False otherwise

Scripts Module (py_psscriptanalyzer.scripts)

Functions

build_powershell_file_array(files)

Build a PowerShell array string for the given files.

Parameters:

  • files (list[str]): List of file paths

Returns:

  • str: PowerShell array string

escape_powershell_path(path)

Escape a file path for use in PowerShell commands.

Parameters:

  • path (str): File path to escape

Returns:

  • str: Escaped file path

generate_analysis_script(files, severity)

Generate a PowerShell script for analyzing files.

Parameters:

  • files (list[str]): List of PowerShell file paths

  • severity (str): Severity level to filter results

Returns:

  • str: PowerShell script content

generate_format_script(files)

Generate a PowerShell script for formatting files.

Parameters:

  • files (list[str]): List of PowerShell file paths

Returns:

  • str: PowerShell script content

Constants Module (py_psscriptanalyzer.constants)

Constants

POWERSHELL_EXECUTABLES

List of PowerShell executable names to search for:

POWERSHELL_EXECUTABLES = ["pwsh", "powershell"]

POWERSHELL_FILE_EXTENSIONS

Set of PowerShell file extensions:

POWERSHELL_FILE_EXTENSIONS = {".ps1", ".psm1", ".psd1"}

SEVERITY_LEVELS

Valid PSScriptAnalyzer severity levels:

SEVERITY_LEVELS = ["Error", "Warning", "Information", "All"]

ANALYSIS_TIMEOUT

Timeout for PowerShell analysis operations (in seconds):

ANALYSIS_TIMEOUT = 300  # 5 minutes

Error Handling

The package provides comprehensive error handling for common scenarios:

PowerShell Not Found

from py_psscriptanalyzer.powershell import find_powershell

if not find_powershell():
    print("❌ PowerShell not found. Please install PowerShell Core.")

PSScriptAnalyzer Module Missing

from py_psscriptanalyzer.powershell import check_psscriptanalyzer_installed, install_psscriptanalyzer

pwsh = find_powershell()
if not check_psscriptanalyzer_installed(pwsh):
    if install_psscriptanalyzer(pwsh):
        print("✅ PSScriptAnalyzer installed successfully")
    else:
        print("❌ Failed to install PSScriptAnalyzer")

Type Hints

The package is fully type-annotated for better IDE support and development experience. All public functions include proper type hints for parameters and return values.

Compatibility

  • Python: 3.9+

  • PowerShell: Core 7.0+ or Windows PowerShell 5.1+

  • Operating Systems: Windows, macOS, Linux