pwshpy 1.0.0__py3-none-any.whl

pwshpy/__init__.py

@@ -0,0 +1,144 @@
+"""Public package surface for pwshpy.
+
+A genuinely Pythonic PowerShell: typed records and a fluent, lazy pipeline over
+native Windows bindings (native), with an in-process PowerShell 7.6 SDK fallback
+(.NET) — never a ``pwsh.exe`` subprocess.
+
+Typical use::
+
+    from pwshpy import ps
+    for proc in ps.get_process().where(lambda p: p.name == "python").take(5):
+        print(proc.pid, proc.name)
+
+This module re-exports the stable public API, routing through the proper
+architectural layers (domain records/pipeline/errors, the wired ``ps`` facade,
+and package metadata).
+"""
+
+from __future__ import annotations
+
+# Metadata
+from .__init__conf__ import print_info
+
+# Composition exports (wired adapters + the ps facade)
+from .composition import Ps, build_ps, get_config, ps
+
+# Domain object model
+from .domain.enums import (
+    AceType,
+    AddressFamily,
+    ConnectionState,
+    EventLevel,
+    ProcessStatus,
+    RegistryHive,
+    RegistryValueType,
+    ServiceKind,
+    ServiceStartType,
+    ServiceState,
+    TaskState,
+    TransportProtocol,
+    WellKnownSid,
+)
+from .domain.errors import (
+    ConfigurationError,
+    ElevationRequiredError,
+    FeatureUnavailableError,
+    NativeCallError,
+    PlatformUnsupportedError,
+    PowerShellError,
+    PwshPyError,
+)
+from .domain.pipeline import Pipeline
+from .domain.records import (
+    AclEntry,
+    CimInstance,
+    CommandInfo,
+    CommandParameter,
+    ComputerInfo,
+    ConnectionTest,
+    Credential,
+    DiskUsage,
+    DnsRecord,
+    EnvVar,
+    EventLogEntry,
+    FileSystemItem,
+    Hotfix,
+    LocalGroup,
+    LocalUser,
+    NetAdapter,
+    NetConnection,
+    NetIpAddress,
+    ProcessInfo,
+    ProcessResult,
+    PSInvocationResult,
+    PSObjectRecord,
+    PSRecord,
+    RegistryKey,
+    RegistryValue,
+    ScheduledTaskInfo,
+    ServiceInfo,
+    SystemUptime,
+    WebResponse,
+)
+
+__all__ = [
+    # Facade
+    "ps",
+    "Ps",
+    "build_ps",
+    # Object model
+    "Pipeline",
+    "PSRecord",
+    "ProcessInfo",
+    "ProcessResult",
+    "NetAdapter",
+    "NetConnection",
+    "NetIpAddress",
+    "DiskUsage",
+    "SystemUptime",
+    "WebResponse",
+    "DnsRecord",
+    "ComputerInfo",
+    "ConnectionTest",
+    "Credential",
+    "FileSystemItem",
+    "Hotfix",
+    "EnvVar",
+    "RegistryKey",
+    "RegistryValue",
+    "ServiceInfo",
+    "EventLogEntry",
+    "CimInstance",
+    "CommandInfo",
+    "CommandParameter",
+    "ScheduledTaskInfo",
+    "LocalUser",
+    "LocalGroup",
+    "AclEntry",
+    "PSObjectRecord",
+    "PSInvocationResult",
+    "ProcessStatus",
+    "ConnectionState",
+    "TransportProtocol",
+    "AddressFamily",
+    "RegistryHive",
+    "RegistryValueType",
+    "ServiceState",
+    "ServiceStartType",
+    "ServiceKind",
+    "EventLevel",
+    "TaskState",
+    "WellKnownSid",
+    "AceType",
+    # Errors
+    "PwshPyError",
+    "NativeCallError",
+    "PowerShellError",
+    "FeatureUnavailableError",
+    "PlatformUnsupportedError",
+    "ElevationRequiredError",
+    "ConfigurationError",
+    # Config + metadata
+    "get_config",
+    "print_info",
+]

pwshpy/__init__conf__.py

@@ -0,0 +1,90 @@
+"""Static package metadata surfaced to CLI commands and documentation.
+
+Purpose
+-------
+Expose the current project metadata as simple constants. These values are kept
+in sync with ``pyproject.toml`` by development automation (tests, push
+pipelines), so runtime code does not query packaging metadata.
+
+Contents
+--------
+* Module-level constants describing the published package.
+* :func:`print_info` rendering the constants for the CLI ``info`` command.
+
+System Role
+-----------
+Lives in the adapters/platform layer; CLI transports import these constants to
+present authoritative project information without invoking packaging APIs.
+"""
+
+from __future__ import annotations
+
+import sys
+
+__all__ = [
+    "name",
+    "title",
+    "version",
+    "homepage",
+    "author",
+    "author_email",
+    "shell_command",
+    "LAYEREDCONF_VENDOR",
+    "LAYEREDCONF_APP",
+    "LAYEREDCONF_SLUG",
+    "print_info",
+]
+
+#: Distribution name declared in ``pyproject.toml``.
+name = "pwshpy"
+#: Human-readable summary shown in CLI help output.
+title = "A Pythonic PowerShell: typed records + a fluent pipeline over native bindings, never a pwsh subprocess."
+#: Current release version pulled from ``pyproject.toml`` by automation.
+version = "1.0.0"
+#: Repository homepage presented to users.
+homepage = "https://github.com/bitranox/pwshpy"
+#: Author attribution surfaced in CLI output.
+author = "bitranox"
+#: Contact email surfaced in CLI output.
+author_email = "bitranox@gmail.com"
+#: Console-script name published by the package.
+shell_command = "pwshpy"
+
+#: Vendor identifier for lib_layered_config paths (macOS/Windows)
+LAYEREDCONF_VENDOR: str = "bitranox"
+#: Application display name for lib_layered_config paths (macOS/Windows)
+LAYEREDCONF_APP: str = "pwshpy"
+#: Configuration slug for lib_layered_config Linux paths and environment variables
+LAYEREDCONF_SLUG: str = "pwshpy"
+
+
+def print_info() -> None:
+    """Print the summarised metadata block used by the CLI ``info`` command.
+
+    Why
+        Provides a single, auditable rendering function so documentation and
+        CLI output always match the system design reference.
+
+    Side Effects
+        Writes to ``stdout``.
+
+    Examples
+    --------
+    >>> print_info()  # doctest: +ELLIPSIS
+    Info for pwshpy:
+    ...
+    """
+
+    fields = [
+        ("name", name),
+        ("title", title),
+        ("version", version),
+        ("homepage", homepage),
+        ("author", author),
+        ("author_email", author_email),
+        ("shell_command", shell_command),
+    ]
+    pad = max(len(label) for label, _ in fields)
+    lines = [f"Info for {name}:", ""]
+    lines.extend(f"    {label.ljust(pad)} = {value}" for label, value in fields)
+    sys.stdout.write("\n".join(lines) + "\n")

pwshpy/__main__.py

@@ -0,0 +1,9 @@
+"""Module entry point for ``python -m pwshpy``."""
+
+from __future__ import annotations
+
+from .adapters.cli.main import main
+from .composition import build_production
+
+if __name__ == "__main__":
+    raise SystemExit(main(services_factory=build_production))

pwshpy/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""Adapters layer - infrastructure and framework integrations.
+
+Contains adapter implementations that connect the application to external
+systems and frameworks (CLI, configuration, logging).
+
+Contents:
+    * :mod:`.config` - Configuration loading, deployment, and display
+    * :mod:`.logging` - Logging setup with lib_log_rich
+    * :mod:`.cli` - Click CLI framework integration
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

pwshpy/adapters/cli/__init__.py

@@ -0,0 +1,60 @@
+"""CLI package providing the command-line interface.
+
+Re-exports all public symbols from submodules for convenient access.
+
+Contents:
+    * Click context helpers and traceback state management from :mod:`.context`
+    * Root command group from :mod:`.root`
+    * Entry point from :mod:`.main`
+    * All command functions from :mod:`.commands`
+
+System Role:
+    Acts as the public facade for the CLI subsystem. Consumers import from here
+    and remain insulated from internal module boundaries.
+"""
+
+from __future__ import annotations
+
+from .commands import (
+    cli_config,
+    cli_config_deploy,
+    cli_config_generate_examples,
+    cli_fail,
+    cli_info,
+    cli_logdemo,
+)
+from .constants import CLICK_CONTEXT_SETTINGS, TRACEBACK_SUMMARY_LIMIT, TRACEBACK_VERBOSE_LIMIT
+from .context import (
+    TracebackState,
+    apply_traceback_preferences,
+    restore_traceback_state,
+    snapshot_traceback_state,
+    store_cli_context,
+)
+from .main import main
+from .root import cli
+
+__all__ = [
+    # Constants
+    "CLICK_CONTEXT_SETTINGS",
+    "TRACEBACK_SUMMARY_LIMIT",
+    "TRACEBACK_VERBOSE_LIMIT",
+    # Traceback management
+    "TracebackState",
+    "apply_traceback_preferences",
+    "restore_traceback_state",
+    "snapshot_traceback_state",
+    # Context helpers
+    "store_cli_context",
+    # Root command
+    "cli",
+    # Entry point
+    "main",
+    # Commands
+    "cli_config",
+    "cli_config_deploy",
+    "cli_config_generate_examples",
+    "cli_fail",
+    "cli_info",
+    "cli_logdemo",
+]

pwshpy/adapters/cli/commands/__init__.py

@@ -0,0 +1,75 @@
+"""CLI command implementations.
+
+Collects all subcommand functions and re-exports them for registration
+with the root CLI group.
+
+Contents:
+    * Info commands from :mod:`.info`
+    * Config commands from :mod:`.config`
+    * Logging commands from :mod:`.logging`
+"""
+
+from __future__ import annotations
+
+from .acl import cli_acl
+from .cim import cli_cim
+from .config import cli_config, cli_config_deploy, cli_config_generate_examples
+from .connections import cli_connections
+from .credentials import CREDENTIAL_COMMANDS
+from .disks import cli_disks
+from .dns import cli_resolve
+from .dotnet import DOTNET_COMMANDS
+from .elevation import cli_is_elevated
+from .environment import cli_env
+from .event_log import cli_event_log
+from .fileio import FILEIO_COMMANDS
+from .filesystem import FILESYSTEM_COMMANDS
+from .info import cli_fail, cli_info
+from .local_accounts import cli_local_groups, cli_local_users
+from .logging import cli_logdemo
+from .mutating import MUTATING_COMMANDS
+from .netcheck import cli_test_connection
+from .networking import NETWORKING_COMMANDS
+from .proc import PROC_COMMANDS
+from .processes import cli_processes
+from .registry import cli_get_item_property, cli_registry_keys
+from .scheduled_tasks import cli_scheduled_tasks
+from .services import cli_services
+from .system import SYSTEM_COMMANDS
+from .uptime import cli_uptime
+from .web import WEB_COMMANDS
+
+__all__ = [
+    "FILESYSTEM_COMMANDS",
+    "MUTATING_COMMANDS",
+    "NETWORKING_COMMANDS",
+    "CREDENTIAL_COMMANDS",
+    "FILEIO_COMMANDS",
+    "PROC_COMMANDS",
+    "SYSTEM_COMMANDS",
+    "DOTNET_COMMANDS",
+    "WEB_COMMANDS",
+    "cli_acl",
+    "cli_cim",
+    "cli_config",
+    "cli_config_deploy",
+    "cli_config_generate_examples",
+    "cli_connections",
+    "cli_disks",
+    "cli_env",
+    "cli_event_log",
+    "cli_fail",
+    "cli_info",
+    "cli_is_elevated",
+    "cli_local_groups",
+    "cli_local_users",
+    "cli_logdemo",
+    "cli_processes",
+    "cli_get_item_property",
+    "cli_registry_keys",
+    "cli_resolve",
+    "cli_scheduled_tasks",
+    "cli_services",
+    "cli_test_connection",
+    "cli_uptime",
+]

pwshpy/adapters/cli/commands/_common.py

@@ -0,0 +1,66 @@
+"""Shared helpers for record-listing CLI commands (processes, connections, ...).
+
+Contents:
+    * :func:`resolve_format` — map the mutually-exclusive output flags to a format.
+    * :func:`parse_pairs` — parse repeatable ``KEY=VALUE`` / ``Name: value`` options.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import rich_click as click
+
+from ..output import RecordFormat
+
+
+def parse_pairs(pairs: Iterable[str], separator: str, label: str, *, strip: bool = False) -> dict[str, str]:
+    """Parse repeatable ``KEY<sep>VALUE`` CLI options into a dict (last wins on a repeated key).
+
+    Used for ``cmdlet -p KEY=VALUE`` and ``invoke_web_request -H 'Name: value'``. A pair with
+    no separator or an empty key raises :class:`click.BadParameter` naming ``label``.
+
+    Example:
+        >>> parse_pairs(["Path=C:/", "Recurse=true"], "=", "KEY=VALUE")
+        {'Path': 'C:/', 'Recurse': 'true'}
+        >>> parse_pairs(["Accept: application/json"], ":", "'Name: value'", strip=True)
+        {'Accept': 'application/json'}
+        >>> parse_pairs(["oops"], "=", "KEY=VALUE")
+        Traceback (most recent call last):
+        click.exceptions.BadParameter: expected KEY=VALUE, got 'oops'
+    """
+    result: dict[str, str] = {}
+    for pair in pairs:
+        key, separator_found, value = pair.partition(separator)
+        clean_key = key.strip() if strip else key
+        if not separator_found or not clean_key:
+            raise click.BadParameter(f"expected {label}, got {pair!r}")
+        result[clean_key] = value.strip() if strip else value
+    return result
+
+
+def resolve_format(as_json: bool, as_jsonl: bool) -> RecordFormat:
+    """Pick the output format from mutually-exclusive flags (default: human table).
+
+    Raises:
+        click.UsageError: If both ``--json`` and ``--jsonl`` are given.
+
+    Example:
+        >>> resolve_format(False, True) is RecordFormat.JSONL
+        True
+        >>> resolve_format(False, False) is RecordFormat.HUMAN
+        True
+        >>> resolve_format(True, True)
+        Traceback (most recent call last):
+        click.exceptions.UsageError: --json and --jsonl are mutually exclusive.
+    """
+    if as_json and as_jsonl:
+        raise click.UsageError("--json and --jsonl are mutually exclusive.")
+    if as_jsonl:
+        return RecordFormat.JSONL
+    if as_json:
+        return RecordFormat.JSON
+    return RecordFormat.HUMAN
+
+
+__all__ = ["parse_pairs", "resolve_format"]

pwshpy/adapters/cli/commands/acl.py

@@ -0,0 +1,51 @@
+"""``pwshpy acl`` - list a path's DACL entries through the pipeline.
+
+A thin front end over the ``ps`` facade (native / win32security), mirroring
+``Get-Acl``.  Emits one :class:`~pwshpy.domain.records.AclEntry` per
+access-control entry, identified by trustee SID (locale-independent).  Filtering
+is done in Python via the pipeline.
+
+Contents:
+    * :func:`cli_acl` - the ``acl`` subcommand.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import lib_log_rich.runtime
+import rich_click as click
+
+from ..constants import CLICK_CONTEXT_SETTINGS
+from ..context import get_cli_context
+from ..output import emit
+from ..typed_click import argument, option
+from ._common import resolve_format
+
+logger = logging.getLogger(__name__)
+
+
+@click.command("get_acl", context_settings=CLICK_CONTEXT_SETTINGS)
+@argument("path")
+@option("--json", "as_json", is_flag=True, default=False, help="Emit records as a JSON array.")
+@option("--jsonl", "as_jsonl", is_flag=True, default=False, help="Stream one JSON record per line.")
+@click.pass_context
+def cli_acl(ctx: click.Context, path: str, as_json: bool, as_jsonl: bool) -> None:
+    """List the ACL entries of PATH - win32 DACLs on Windows, POSIX ACLs on Linux (native; like Get-Acl).
+
+    One record per access-control entry, identified by trustee SID.  Filter in
+    Python via the pipeline, e.g. keep the Deny entries.
+
+    Example:
+        >>> from click.testing import CliRunner
+        >>> CliRunner().invoke(cli_acl, ["--help"]).exit_code
+        0
+    """
+    fmt = resolve_format(as_json, as_jsonl)
+    ps = get_cli_context(ctx).services.ps
+    with lib_log_rich.runtime.bind(job_id="cli-acl", extra={"command": "acl"}):
+        logger.info("Reading ACL")
+        emit(ps.get_acl(path), fmt)
+
+
+__all__ = ["cli_acl"]

pwshpy/adapters/cli/commands/cim.py

@@ -0,0 +1,56 @@
+"""``pwshpy cim`` - query CIM/WMI instances through the pipeline.
+
+A thin front end over the ``ps`` facade (native / WBEM), mirroring
+``Get-CimInstance``.  Streams :class:`~pwshpy.domain.records.CimInstance` records
+lazily (forward-only), so querying an unbounded class and piping to ``head`` stays
+cheap.  CIM instances are open key/value bags - view them with ``--jsonl``.
+
+Contents:
+    * :func:`cli_cim` - the ``cim`` subcommand.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import lib_log_rich.runtime
+import rich_click as click
+
+from ..constants import CLICK_CONTEXT_SETTINGS
+from ..context import get_cli_context
+from ..output import emit
+from ..typed_click import argument, option
+from ._common import resolve_format
+
+logger = logging.getLogger(__name__)
+
+
+@click.command("get_cim_instance", context_settings=CLICK_CONTEXT_SETTINGS)
+@argument("class_name")
+@option("--where", "where", default=None, help='Read-only WQL filter fragment, e.g. "DriveType = 3".')
+@option("--namespace", "namespace", default="root/cimv2", help="WMI namespace (default: root/cimv2).")
+@option("--json", "as_json", is_flag=True, default=False, help="Emit records as a JSON array.")
+@option("--jsonl", "as_jsonl", is_flag=True, default=False, help="Stream one JSON record per line.")
+@click.pass_context
+def cli_cim(
+    ctx: click.Context, class_name: str, where: str | None, namespace: str, as_json: bool, as_jsonl: bool
+) -> None:
+    """Query CIM/WMI class CLASS_NAME as typed records (native; like Get-CimInstance).
+
+    CLASS_NAME is a WMI class, e.g. ``Win32_OperatingSystem``, ``Win32_LogicalDisk``.
+    Streams lazily, so even an unbounded class (``CIM_DataFile``) stays cheap with
+    ``--jsonl | head``.
+
+    Example:
+        >>> from click.testing import CliRunner
+        >>> CliRunner().invoke(cli_cim, ["--help"]).exit_code
+        0
+    """
+    fmt = resolve_format(as_json, as_jsonl)
+    ps = get_cli_context(ctx).services.ps
+    with lib_log_rich.runtime.bind(job_id="cli-cim", extra={"command": "cim"}):
+        logger.info("Querying CIM/WMI")
+        emit(ps.get_cim_instance(class_name, where=where, namespace=namespace), fmt)
+
+
+__all__ = ["cli_cim"]