[](https://badge.fury.io/py/py-psscriptanalyzer)
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
[](https://pypi.org/project/py-psscriptanalyzer/)
[](https://codecov.io/github/thetestlabs/py-psscriptanalyzer)
[](https://app.codacy.com/gh/thetestlabs/py-psscriptanalyzer/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://readthedocs.org/projects/py-psscriptanalyzer/)
[](https://github.com/thetestlabs/py-psscriptanalyzer/actions/workflows/release.yaml)
# py-psscriptanalyzer
---
<div align="center">
<strong><a href="https://py-psscriptanalyzer.thetestlabs.io">Read the documentation on ReadTheDocs!</a></strong>
</div>
---
A Python wrapper for [PSScriptAnalyzer](https://github.com/PowerShell/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
```bash
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):
```bash
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):
```bash
# 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**:
```bash
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
```bash
# 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
```python
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`:
```yaml
repos:
- repo: https://github.com/thetestlabs/py-psscriptanalyzer
rev: v0.3.1 # Use the latest version
hooks:
- id: py-psscriptanalyzer # Lint your PowerShell
- id: py-psscriptanalyzer-format # Format your PowerShell
```
### GitHub Actions
```yaml
- 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](https://github.com/PowerShell/PowerShell/releases)
- **macOS**: `brew install powershell`
- **Linux**: [Installation guide](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux)
## Documentation
Full documentation available at **[py-psscriptanalyzer.thetestlabs.io](https://py-psscriptanalyzer.thetestlabs.io/)**
## Contributing
Contributions welcome! See our development guide in the documentation.
## License
MIT - see [LICENSE](LICENSE) file.
A tool for linting and formatting PowerShell code using PSScriptAnalyzer.
Raw data
{
"_id": null,
"home_page": null,
"name": "py-psscriptanalyzer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Chris McQuaid <chris@thetestlabs.io>",
"keywords": "automation, ci-cd, code-quality, formatting, linting, powershell, pre-commit, psscriptanalyzer, static-analysis",
"author": null,
"author_email": "Chris McQuaid <chris@thetestlabs.io>",
"download_url": "https://files.pythonhosted.org/packages/8f/80/744f23a269c194ee33a1176c95b9ad38fc965773de79c5f596b4e42dd63e/py_psscriptanalyzer-0.3.1.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/py-psscriptanalyzer)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/astral-sh/ruff)\n[](https://pypi.org/project/py-psscriptanalyzer/)\n[](https://codecov.io/github/thetestlabs/py-psscriptanalyzer)\n[](https://app.codacy.com/gh/thetestlabs/py-psscriptanalyzer/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)\n[](https://readthedocs.org/projects/py-psscriptanalyzer/)\n[](https://github.com/thetestlabs/py-psscriptanalyzer/actions/workflows/release.yaml)\n\n# py-psscriptanalyzer\n\n---\n\n<div align=\"center\">\n <strong><a href=\"https://py-psscriptanalyzer.thetestlabs.io\">Read the documentation on ReadTheDocs!</a></strong>\n</div>\n\n---\n\nA Python wrapper for [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) - bringing cross-platform PowerShell static analysis and formatting to your projects, including a `pre-commit` hook and integration with CI/CD tools\n\n## What it does\n\n\u2705 **Lints PowerShell files** (`.ps1`, `.psm1`, `.psd1`) for code quality issues \n\u2705 **Formats PowerShell code** automatically \n\u2705 **Works everywhere** - Windows, macOS, Linux \n\u2705 **Zero config** - installs PSScriptAnalyzer automatically \n\u2705 **GitHub Actions ready** - with standard error annotations \n\u2705 **CI/CD friendly** - perfect for automation pipelines \n\u2705 **Pre-commit hooks** - catch issues before they hit your repo\n\n## Installation\n\n```bash\npip install py-psscriptanalyzer\n```\n\n### Troubleshooting Installation\n\n#### macOS/Linux: \"externally-managed-environment\" Error\n\nIf you encounter an \"externally-managed-environment\" error, you have several options:\n\n1. **Use a virtual environment** (recommended):\n\n ```bash\n python3 -m venv py-psscriptanalyzer-env\n source py-psscriptanalyzer-env/bin/activate # On Windows: py-psscriptanalyzer-env\\Scripts\\activate\n pip install py-psscriptanalyzer\n ```\n\n2. **Use pipx** (for command-line use):\n\n ```bash\n # Install pipx if not already installed\n brew install pipx # macOS\n # sudo apt install pipx # Ubuntu/Debian\n\n # Install py-psscriptanalyzer with pipx\n pipx install py-psscriptanalyzer\n ```\n\n3. **Install to user directory**:\n ```bash\n pip install --user py-psscriptanalyzer\n ```\n\n**Note**: If you're using the package in a CI/CD environment, virtual environments or containers are typically the best approach.\n\n## Usage\n\n### Command Line\n\n```bash\n# Analyze PowerShell files\npy-psscriptanalyzer script.ps1 module.psm1\n\n# Format PowerShell files\npy-psscriptanalyzer --format script.ps1\n\n# Set severity level (hierarchical: Information > Warning > Error)\npy-psscriptanalyzer --severity Error script.ps1 # Only errors\npy-psscriptanalyzer --severity Warning script.ps1 # Warnings + errors (default)\npy-psscriptanalyzer --severity Information script.ps1 # All issues\n\n# Search recursively for PowerShell files\npy-psscriptanalyzer --recursive\n\n# Use environment variable for default severity\nexport SEVERITY_LEVEL=Error\npy-psscriptanalyzer script.ps1 # Uses Error level\n```\n\n### Python API\n\n```python\nfrom py_psscriptanalyzer import run_script_analyzer, find_powershell\n\n# Find PowerShell installation\npowershell_cmd = find_powershell()\n\n# Analyze files\nexit_code = run_script_analyzer(\n powershell_cmd,\n [\"script.ps1\"],\n severity=\"Warning\"\n)\n\n# Format files\nexit_code = run_script_analyzer(\n powershell_cmd,\n [\"script.ps1\"],\n format_files=True\n)\n```\n\n### Pre-commit Hooks\n\nAdd this to your `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n - repo: https://github.com/thetestlabs/py-psscriptanalyzer\n rev: v0.3.1 # Use the latest version\n hooks:\n - id: py-psscriptanalyzer # Lint your PowerShell\n - id: py-psscriptanalyzer-format # Format your PowerShell\n```\n\n### GitHub Actions\n\n```yaml\n- name: Analyze PowerShell\n run: |\n pip install py-psscriptanalyzer\n py-psscriptanalyzer --severity Error **/*.ps1\n```\n\n## Prerequisites\n\n- Python 3.9+\n- PowerShell (any version - we'll find it!)\n\nNeed PowerShell? Get it here:\n\n- **Windows**: Already installed, or get [PowerShell Core](https://github.com/PowerShell/PowerShell/releases)\n- **macOS**: `brew install powershell`\n- **Linux**: [Installation guide](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux)\n\n## Documentation\n\nFull documentation available at **[py-psscriptanalyzer.thetestlabs.io](https://py-psscriptanalyzer.thetestlabs.io/)**\n\n## Contributing\n\nContributions welcome! See our development guide in the documentation.\n\n## License\n\nMIT - see [LICENSE](LICENSE) file.\n\nA tool for linting and formatting PowerShell code using PSScriptAnalyzer.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python wrapper for PowerShell PSScriptAnalyzer - static analysis and formatting for PowerShell scripts",
"version": "0.3.1",
"project_urls": {
"Changelog": "https://github.com/thetestlabs/py-psscriptanalyzer/blob/main/CHANGELOG.md",
"Documentation": "https://py-psscriptanalyzer.thetestlabs.io/",
"Homepage": "https://github.com/thetestlabs/py-psscriptanalyzer",
"Issues": "https://github.com/thetestlabs/py-psscriptanalyzer/issues",
"Repository": "https://github.com/thetestlabs/py-psscriptanalyzer"
},
"split_keywords": [
"automation",
" ci-cd",
" code-quality",
" formatting",
" linting",
" powershell",
" pre-commit",
" psscriptanalyzer",
" static-analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "839d79fdb86e6d874bcf2c980f954f1a7404c11461f5295820029fee8cc4753a",
"md5": "612557f722017cfdb2beafde95565e50",
"sha256": "50dbbfe6e307610c92af65d9127cd9722ea4118b3cba563aeea303edcb7e2035"
},
"downloads": -1,
"filename": "py_psscriptanalyzer-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "612557f722017cfdb2beafde95565e50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17188,
"upload_time": "2025-08-14T17:04:07",
"upload_time_iso_8601": "2025-08-14T17:04:07.741607Z",
"url": "https://files.pythonhosted.org/packages/83/9d/79fdb86e6d874bcf2c980f954f1a7404c11461f5295820029fee8cc4753a/py_psscriptanalyzer-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8f80744f23a269c194ee33a1176c95b9ad38fc965773de79c5f596b4e42dd63e",
"md5": "a6a720d486937785be145efe0c10a132",
"sha256": "f45a1f8328a1e6189aaaa992648eecf031111d3eb611e341a7d949a4422869c5"
},
"downloads": -1,
"filename": "py_psscriptanalyzer-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "a6a720d486937785be145efe0c10a132",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 126830,
"upload_time": "2025-08-14T17:04:09",
"upload_time_iso_8601": "2025-08-14T17:04:09.385843Z",
"url": "https://files.pythonhosted.org/packages/8f/80/744f23a269c194ee33a1176c95b9ad38fc965773de79c5f596b4e42dd63e/py_psscriptanalyzer-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 17:04:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thetestlabs",
"github_project": "py-psscriptanalyzer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "py-psscriptanalyzer"
}
JSON
