py-psscriptanalyzer 0.3.0

Python wrapper for PowerShell PSScriptAnalyzer - static analysis and formatting for PowerShell scripts

py-psscriptanalyzer

---

Read the documentation on ReadTheDocs!

---

A Python wrapper for PSScriptAnalyzer - bringing cross-platform PowerShell static analysis and formatting to your projects, including a pre-commit hook and integration with CI/CD tools

What it does

✅ Lints PowerShell files (.ps1, .psm1, .psd1) for code quality issues
✅ Formats PowerShell code automatically
✅ Works everywhere - Windows, macOS, Linux
✅ Zero config - installs PSScriptAnalyzer automatically
✅ GitHub Actions ready - with standard error annotations
✅ CI/CD friendly - perfect for automation pipelines
✅ Pre-commit hooks - catch issues before they hit your repo

Installation

pip install py-psscriptanalyzer

Troubleshooting Installation

macOS/Linux: "externally-managed-environment" Error

If you encounter an "externally-managed-environment" error, you have several options:

1. Use a virtual environment (recommended):

   python3 -m venv py-psscriptanalyzer-env
   source py-psscriptanalyzer-env/bin/activate  # On Windows: py-psscriptanalyzer-env\Scripts\activate
   pip install py-psscriptanalyzer
   

2. Use pipx (for command-line use):

   # Install pipx if not already installed
   brew install pipx  # macOS
   # sudo apt install pipx  # Ubuntu/Debian
   
   # Install py-psscriptanalyzer with pipx
   pipx install py-psscriptanalyzer
   

3. Install to user directory:

   pip install --user py-psscriptanalyzer
   

Note: If you're using the package in a CI/CD environment, virtual environments or containers are typically the best approach.

Usage

Command Line

# Analyze PowerShell files
py-psscriptanalyzer script.ps1 module.psm1

# Format PowerShell files
py-psscriptanalyzer --format script.ps1

# Set severity level (hierarchical: Information > Warning > Error)
py-psscriptanalyzer --severity Error script.ps1        # Only errors
py-psscriptanalyzer --severity Warning script.ps1      # Warnings + errors (default)
py-psscriptanalyzer --severity Information script.ps1  # All issues

# Search recursively for PowerShell files
py-psscriptanalyzer --recursive

# Use environment variable for default severity
export SEVERITY_LEVEL=Error
py-psscriptanalyzer script.ps1  # Uses Error level

Python API

from py_psscriptanalyzer import run_script_analyzer, find_powershell

# Find PowerShell installation
powershell_cmd = find_powershell()

# Analyze files
exit_code = run_script_analyzer(
    powershell_cmd,
    ["script.ps1"],
    severity="Warning"
)

# Format files
exit_code = run_script_analyzer(
    powershell_cmd,
    ["script.ps1"],
    format_files=True
)

Pre-commit Hooks

Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/thetestlabs/py-psscriptanalyzer
    rev: v0.3.0 # Use the latest version
    hooks:
      - id: py-psscriptanalyzer # Lint your PowerShell
      - id: py-psscriptanalyzer-format # Format your PowerShell

GitHub Actions

- name: Analyze PowerShell
  run: |
    pip install py-psscriptanalyzer
    py-psscriptanalyzer --severity Error **/*.ps1

Prerequisites

• Python 3.9+
• PowerShell (any version - we'll find it!)

Need PowerShell? Get it here:

• Windows: Already installed, or get PowerShell Core
• macOS: brew install powershell
• Linux: Installation guide

Documentation

Full documentation available at py-psscriptanalyzer.thetestlabs.io

Contributing

Contributions welcome! See our development guide in the documentation.

License

MIT - see LICENSE file.

A tool for linting and formatting PowerShell code using PSScriptAnalyzer.