#!/usr/bin/env python3
"""Application-level process inventory ports."""

from typing import Any, ContextManager, Iterable, Protocol, Sequence


class ProcessInventoryGateway(Protocol):
    """Port for enumerating and resolving system processes."""

    def iter_processes(self, attrs: Sequence[str]) -> Iterable[Any]:
        """Iterate process handles with selected attribute prefetch."""

    def get_process(self, pid: int) -> Any:
        """Resolve a process handle by PID."""

    def list_pids(self) -> list[int]:
        """Return currently visible process IDs."""

    def snapshot_current_pids(self) -> set[int]:
        """Return a current PID snapshot for staleness pruning."""

    def process_errors(self) -> tuple[type[BaseException], ...]:
        """Return recoverable process-access exception types."""

    def process_info_pid(self, proc: Any) -> int:
        """Return PID from prefetched process metadata."""

    def process_info_name(self, proc: Any) -> str:
        """Return process name from prefetched metadata."""

    def process_pid(self, proc: Any) -> int:
        """Return PID from a resolved process handle."""

    def process_name(self, proc: Any) -> str:
        """Return process name from a process handle."""

    def process_cmdline(self, proc: Any) -> list[str]:
        """Return process command line arguments."""

    def process_ppid(self, proc: Any) -> int:
        """Return process parent PID."""

    def process_username(self, proc: Any) -> str:
        """Return process owner name."""

    def process_cpu_percent(self, proc: Any) -> float:
        """Return current process CPU percent."""

    def process_memory_percent(self, proc: Any) -> float:
        """Return current process memory percent."""

    def process_status(self, proc: Any) -> str:
        """Return process status string."""

    def process_create_time(self, proc: Any) -> float:
        """Return process create time."""

    def process_cpu_times(self, proc: Any) -> Any:
        """Return process CPU times payload."""

    def process_memory_info(self, proc: Any) -> Any:
        """Return process memory info payload."""

    def process_num_threads(self, proc: Any) -> int:
        """Return process thread count."""

    def process_io_counters(self, proc: Any) -> Any:
        """Return process IO counters payload."""

    def process_net_connection_count(self, proc: Any) -> int:
        """Return number of active INET connections for process."""

    def process_cpu_affinity(self, proc: Any) -> list[int]:
        """Return process CPU affinity."""

    def process_is_running(self, proc: Any) -> bool:
        """Return whether process is currently running."""

    def process_oneshot(self, proc: Any) -> ContextManager[Any]:
        """Return context manager for batched process reads."""


__all__ = ["ProcessInventoryGateway"]
