shellcheck-py

Warnings

• gotcha The `shellcheck-py` package installs the `shellcheck` binary to your environment's PATH, rather than providing Python functions for direct linting. Interaction with the linter is typically done by executing the `shellcheck` command via `subprocess` or as a pre-commit hook.
  Fix: Use `subprocess.run(['shellcheck', ...])` to invoke the installed binary or integrate it as a pre-commit hook. Consult `shellcheck`'s official documentation for command-line arguments and output formats.
• breaking Older Python versions (e.g., 3.10/3.11) may encounter installation failures due to `shellcheck-py` using the deprecated `setup.py install` method, especially if the `wheel` package is not installed. `pip` versions 23.1 and above are enforcing stricter build standards (PEP 517).
  Fix: Upgrade to Python 3.12 or newer. Ensure your `pip` is up-to-date (`pip install --upgrade pip`) and the `wheel` package is installed (`pip install wheel`). If issues persist, consider installing `shellcheck` directly via your system's package manager if `shellcheck-py` isn't strictly required for its bundling capabilities.
• gotcha While `shellcheck-py` aims to make `shellcheck` easily installable, it still relies on platform-specific pre-built binaries. Issues related to binary compatibility with highly specific or unusual system architectures might occur, though less common for mainstream OSes.
  Fix: For highly custom environments or if encountering binary execution issues, verify the `shellcheck` binary itself is compatible with your system architecture. In such rare cases, installing `shellcheck` via its source or alternative distribution methods might be necessary. Refer to the official `shellcheck` project's installation instructions.

Install

• pip install shellcheck-py Install latest version

Imports

• shellcheck binary

  import subprocess
  subprocess.run(["shellcheck", "myscript.sh"])

  The primary interaction with `shellcheck-py` is not through direct Python imports for linting functions, but by invoking the `shellcheck` binary that the package installs onto your PATH. There is no public Python API for the linter functionality itself.

Quickstart

This quickstart demonstrates how to programmatically use the `shellcheck` binary installed by `shellcheck-py` via Python's `subprocess` module. It creates a simple shell script with a known `shellcheck` warning (SC2034) and then invokes `shellcheck` to analyze it, printing the JSON output and exit code.

import subprocess
import os

# Create a dummy shell script for demonstration
script_content = '''#!/bin/bash

# SC2034: foo appears unused. Verify use (or export if used externally).
foo="bar"

echo $foo
'''

with open("test_script.sh", "w") as f:
    f.write(script_content)

os.chmod("test_script.sh", 0o755) # Make it executable

print("Running shellcheck on test_script.sh:")
try:
    # Run shellcheck, capturing output. -f json for machine-readable output
    result = subprocess.run(
        ['shellcheck', '-f', 'json', 'test_script.sh'],
        capture_output=True,
        text=True,
        check=False # Don't raise an exception for non-zero exit codes (warnings/errors)
    )
    print("Standard Output:")
    print(result.stdout)
    if result.stderr:
        print("Standard Error:")
        print(result.stderr)
    print(f"Exit Code: {result.returncode}")
except FileNotFoundError:
    print("Error: 'shellcheck' command not found. Ensure shellcheck-py is installed correctly.")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the dummy script
    if os.path.exists("test_script.sh"):
        os.remove("test_script.sh")