Coding Python Pwshpy

using-pwsh

pwshpy is a genuinely Pythonic PowerShell: typed records + a lazy pipeline over native OS bindings (win32 / wmi / winreg / psutil / socket / systemd / pwd), never a pwsh.exe subprocess and never text parsing. When you are about to write a PowerShell command or a .ps1, shell out to pwsh / wevtutil / sc, or hand-roll pywin32 / win32evtlog with manual XML - reach for pwshpy instead. Source and full docs: https://github.com/bitranox/pwshpy (this repo is itself a Claude Code plugin/marketplace: install anywhere with /plugin marketplace add bitranox/pwshpy then /plugin install pwshpy).

When to use

• About to issue or run any PowerShell command - a Get-* / Set-* cmdlet, a pwsh one-liner, or a .ps1 - for OS/admin work (processes, services, event log, registry, scheduled tasks, ACLs, local accounts, files, network, credentials). Prefer pwshpy even for a single one-off command.
• Want better error handling and reporting: a failed command should raise / exit non-zero with a clear message, not be silently swallowed. PowerShell's default is a non-terminating error you must remember -ErrorAction Stop (or $?/$LASTEXITCODE) to catch; pwshpy failures are real Python exceptions (PwshPyError and subtypes) in the library and a real non-zero exit with a message on the CLI - nothing quietly skipped.
• About to shell out to pwsh / powershell / wevtutil / sc, or hand-roll pywin32 / wmi / win32evtlog with manual XML parsing.
• Want typed objects instead of text you re-parse; a memory-bounded read of a huge event log; or one script that runs on Windows AND Linux.
• On the command line: clean JSON + a real exit code instead of Get-* | ConvertTo-Json (and its single-item-collapse quirk).
• Need to hand a Python script to a machine with no Python (a Windows admin, a colleague): pwshpy pack tool.py makes one self-extracting file that installs uv and runs it - a .ps1 for Windows or a .sh for any POSIX /bin/sh (not only bash). Declare third-party deps in a PEP 723 block or with --with.

Not installed? pwshpy is one uv tool install pwshpy away (or run ad-hoc with uvx pwshpy ...), so reach for it rather than falling back to raw pwsh.

When NOT: a PowerShell module-only cmdlet with no pwshpy wrapper -> still use pwshpy via ps.cmdlet("Verb-Noun", **params) (needs the [full] extra). A genuinely interactive PowerShell TUI is out of scope.

Core idea

Typed Pydantic records stream through a lazy Pipeline (.where(pred).select(fn).take(n).first() / .to_list()) over native bindings. Two backends, same records: native (win32/wmi/winreg/psutil/socket/systemd/pwd - fast, the default) and .NET (the real PowerShell 7 SDK hosted in-process, behind pip install "pwshpy[full]", for the AD/Exchange/Azure long tail and running any .ps1). Never spawns pwsh.exe; never parses text.

Library - from pwshpy import ps

from pwshpy import ps
from pwshpy.domain.enums import ServiceState

# running services whose name contains "sql" -> one JSON line each
for s in ps.get_service().where(lambda s: s.status is ServiceState.RUNNING and "sql" in s.name.lower()):
    print(s.model_dump_json())

ps.get_service() returns a lazy Pipeline[ServiceInfo]; filter and shape in Python, not with cmdlet switches. Records are Pydantic (.model_dump() / .model_dump_json() for free). Status/level fields are canonical English str enums (locale-independent), never a localized OS string.

CLI - prefer pwshpy over pwsh (even for one-liners)

pwshpy get_service --jsonl | jq -c 'select(.status == "Running" and (.name | test("sql"; "i")))'

--jsonl streams one record per line (lazy end to end); --json emits a single array; the default is a human table. Why prefer it over pwsh: typed JSON (no ConvertTo-Json single-item-collapse quirk), a real process exit code, UTF-8 with no BOM, memory-bounded streaming, and real errors (a failure exits non-zero with a message, not a swallowed non-terminating error). See pwshpy --help and pwshpy <command> --help.

Enum fields in the JSON are the capitalized enum name, not upper-cased - filter on the exact string: service status "Running" / "Stopped", event level "Error" / "Warning" / "Information" / "Verbose". So the jq above uses .status == "Running", not "RUNNING". In Python compare the enum member directly (s.status is ServiceState.RUNNING).

Translate a cmdlet / .ps1

Method: replace each cmdlet with its ps.* verb; filter/shape in Python (or jq over --jsonl); anything without a wrapper -> ps.cmdlet("Verb-Noun", **params). pwshpy removes these PowerShell traps for free: single-item collapse, $null-operand order, a forgotten -ErrorAction Stop (every failure raises), the $x = Get-WinEvent memory blow-up (reads stream, memory-bounded), Out-File UTF-16/BOM, and localized Administrators / SID (records key on SID / uid, not a translated name).

Example - porting $svc = Get-Service Spooler; if ($svc.Status -ne 'Running') { Start-Service Spooler }; Get-WinEvent -LogName System | ? { $_.Level -eq 2 } | Export-Csv report.csv:

from pwshpy import ps
from pwshpy.domain.enums import EventLevel

ps.start_service("Spooler")  # idempotent: a no-op if already running, so the status check is gone
errors = ps.get_win_event("System").where(lambda e: e.level is EventLevel.ERROR)  # Level 2 -> ERROR enum
ps.write_records("report.jsonl", errors, jsonl=True)  # streams record-by-record, memory-bounded

(pwshpy writes JSON/JSONL, not CSV; if you specifically need CSV, use the stdlib csv module inside the for e in errors: loop - it still streams.)

Ship a script to a machine without Python - pwshpy pack

Hand someone a Python tool as ONE self-extracting file: it unpacks itself into a per-user cache, installs uv if the machine has none, runs the script, and returns the script's own exit code, with no Python and nothing pre-installed. Pick the format for the target - a .ps1 for Windows PowerShell 5.1 / pwsh 7, or a .sh for any POSIX /bin/sh, not only bash (dash, busybox ash, macOS sh, ...). unpack is the inverse, so the recipient can read, edit, and repack it.

pwshpy pack tool.py -o tool.ps1          # embeds tool.py + every local module it imports
pwshpy pack tool.py -o tool.sh           # ...as a POSIX shell runner instead (auto-detected from .sh)
pwshpy pack tool.py -o run --format sh   # force the shell runner for a name without a .sh suffix
pwshpy pack tool.py --with rich          # add a dependency at pack time (repeatable)
pwshpy pack tool.py --include data.json  # embed a file no import reveals
pwshpy unpack tool.ps1 -o src/           # restore the sources, then edit and repack (reads .ps1 or .sh)

from pwshpy import ps, PackOptions, RunnerFormat

ps.pack_script("tool.py", "tool.ps1", options=PackOptions(with_packages=["rich"]))
ps.pack_script("tool.py", "tool.sh", options=PackOptions(format=RunnerFormat.SH))
ps.unpack_script("tool.ps1", "src/")  # sniffs zip (.ps1) vs tar (.sh) - never told the format

Pack and unpack are pure Python (zipfile/tarfile + base64), so you can build a .sh on Windows and a .ps1 on Linux, and unpack reads either format on either OS - the format is about the TARGET, not the host you pack on. Only running the artefact needs the matching interpreter.

Declare the packed script's third-party dependencies - they are NEVER guessed from import names (an import name usually is not a package name: yaml is PyYAML, cv2 is opencv-python). Only third-party distributions need it; the standard library and the entry's local modules travel automatically. Two ways:

1. A PEP 723 block at the top of the entry script - uv resolves it and fetches a matching interpreter on the target machine:

   # /// script
   # requires-python = ">=3.12"
   # dependencies = ["rich", "httpx"]
   # ///
   

2. Or at pack time: pwshpy pack tool.py --with rich --with httpx (CLI) / PackOptions(with_packages=["rich", "httpx"]) (library).

The artefact forwards every argument to your script untouched (empty strings, quotes, unicode, -v/-d) and takes its own help/info/clean/no-install-uv/elevate switches - spelled -PwshPyHelp ... on the .ps1, --pwshpy-help ... on the .sh.

Install

uv tool install pwshpy            # the CLI on PATH   (or run once: uvx pwshpy@latest --help)
pip install "pwshpy[full]"        # + the .NET backend for ps.run / ps.cmdlet / module cmdlets

Common mistakes

• Shelling out to pwsh / powershell / wevtutil / sc, or hand-rolling pywin32 / win32evtlog / wmi + XML -> use the ps.* verb.
• Parsing Get-* | Format-* / ConvertTo-Json text -> pwshpy already returns typed records / clean JSON.
• Forgetting --jsonl when piping the CLI to jq / head (the default human table is not for machines).
• Reaching for a PowerShell module cmdlet and giving up -> ps.cmdlet("Verb-Noun", **params) (needs [full]).
• .to_list() on a huge event log -> iterate the pipeline instead (it streams, O(1) memory).
• pwshpy packing a script whose third-party deps are in neither a PEP 723 block nor --with -> the pack warns and the script dies on its first import on the target. Declare them; import names are never auto-guessed into package names.

Further reading

The CLI and library API are discoverable from the INSTALL (always your version): run uvx pwshpy --help (and <subcommand> --help) for per-command flags, and python -c "import pwshpy; help(pwshpy)". The narrative docs below are NOT shipped in the wheel; open each on the default branch (latest, matching your uv-installed version) at https://github.com/bitranox/pwshpy/blob/master/<path>: