"""
Type stubs for the sh module.

sh replaces itself in sys.modules with a SelfWrapper instance at import time,
so all attribute lookups (e.g. ``sh.ls``) are resolved dynamically and return
Command objects.  The module-level ``__getattr__`` below is the PEP 562
mechanism that tells type checkers about this dynamic resolution, enabling
patterns like ``from sh import ls`` to type-check cleanly.
"""

import threading
from contextlib import contextmanager
from queue import Queue
from typing import (
    Any,
    AsyncIterator,
    Dict,
    Generator,
    Generic,
    Iterator,
    List,
    Literal,
    Optional,
    Tuple,
    overload,
)

from typing_extensions import TypeVar as _TypeVarExt

# ---------------------------------------------------------------------------
# Version / metadata
# ---------------------------------------------------------------------------

__version__: str
__project_url__: str
DEFAULT_ENCODING: str

# ---------------------------------------------------------------------------
# Exceptions
# ---------------------------------------------------------------------------

class ForkException(Exception):
    def __init__(self, orig_exc: str) -> None: ...

class ErrorReturnCode(Exception):
    exit_code: int
    full_cmd: str
    stdout: bytes
    stderr: bytes
    truncate: bool
    truncate_cap: int
    def __init__(
        self,
        full_cmd: str,
        stdout: bytes,
        stderr: bytes,
        truncate: bool = ...,
    ) -> None: ...

class SignalException(ErrorReturnCode): ...
class CommandNotFound(AttributeError): ...

# Concrete ErrorReturnCode subclasses for exit codes 0-255
class ErrorReturnCode_0(ErrorReturnCode): ...
class ErrorReturnCode_1(ErrorReturnCode): ...
class ErrorReturnCode_2(ErrorReturnCode): ...
class ErrorReturnCode_3(ErrorReturnCode): ...
class ErrorReturnCode_4(ErrorReturnCode): ...
class ErrorReturnCode_5(ErrorReturnCode): ...
class ErrorReturnCode_6(ErrorReturnCode): ...
class ErrorReturnCode_7(ErrorReturnCode): ...
class ErrorReturnCode_8(ErrorReturnCode): ...
class ErrorReturnCode_9(ErrorReturnCode): ...
class ErrorReturnCode_10(ErrorReturnCode): ...
class ErrorReturnCode_11(ErrorReturnCode): ...
class ErrorReturnCode_12(ErrorReturnCode): ...
class ErrorReturnCode_13(ErrorReturnCode): ...
class ErrorReturnCode_14(ErrorReturnCode): ...
class ErrorReturnCode_15(ErrorReturnCode): ...
class ErrorReturnCode_16(ErrorReturnCode): ...
class ErrorReturnCode_17(ErrorReturnCode): ...
class ErrorReturnCode_18(ErrorReturnCode): ...
class ErrorReturnCode_19(ErrorReturnCode): ...
class ErrorReturnCode_20(ErrorReturnCode): ...
class ErrorReturnCode_21(ErrorReturnCode): ...
class ErrorReturnCode_22(ErrorReturnCode): ...
class ErrorReturnCode_23(ErrorReturnCode): ...
class ErrorReturnCode_24(ErrorReturnCode): ...
class ErrorReturnCode_25(ErrorReturnCode): ...
class ErrorReturnCode_26(ErrorReturnCode): ...
class ErrorReturnCode_27(ErrorReturnCode): ...
class ErrorReturnCode_28(ErrorReturnCode): ...
class ErrorReturnCode_29(ErrorReturnCode): ...
class ErrorReturnCode_30(ErrorReturnCode): ...
class ErrorReturnCode_31(ErrorReturnCode): ...
class ErrorReturnCode_32(ErrorReturnCode): ...
class ErrorReturnCode_33(ErrorReturnCode): ...
class ErrorReturnCode_34(ErrorReturnCode): ...
class ErrorReturnCode_35(ErrorReturnCode): ...
class ErrorReturnCode_36(ErrorReturnCode): ...
class ErrorReturnCode_37(ErrorReturnCode): ...
class ErrorReturnCode_38(ErrorReturnCode): ...
class ErrorReturnCode_39(ErrorReturnCode): ...
class ErrorReturnCode_40(ErrorReturnCode): ...
class ErrorReturnCode_41(ErrorReturnCode): ...
class ErrorReturnCode_42(ErrorReturnCode): ...
class ErrorReturnCode_43(ErrorReturnCode): ...
class ErrorReturnCode_44(ErrorReturnCode): ...
class ErrorReturnCode_45(ErrorReturnCode): ...
class ErrorReturnCode_46(ErrorReturnCode): ...
class ErrorReturnCode_47(ErrorReturnCode): ...
class ErrorReturnCode_48(ErrorReturnCode): ...
class ErrorReturnCode_49(ErrorReturnCode): ...
class ErrorReturnCode_50(ErrorReturnCode): ...
class ErrorReturnCode_51(ErrorReturnCode): ...
class ErrorReturnCode_52(ErrorReturnCode): ...
class ErrorReturnCode_53(ErrorReturnCode): ...
class ErrorReturnCode_54(ErrorReturnCode): ...
class ErrorReturnCode_55(ErrorReturnCode): ...
class ErrorReturnCode_56(ErrorReturnCode): ...
class ErrorReturnCode_57(ErrorReturnCode): ...
class ErrorReturnCode_58(ErrorReturnCode): ...
class ErrorReturnCode_59(ErrorReturnCode): ...
class ErrorReturnCode_60(ErrorReturnCode): ...
class ErrorReturnCode_61(ErrorReturnCode): ...
class ErrorReturnCode_62(ErrorReturnCode): ...
class ErrorReturnCode_63(ErrorReturnCode): ...
class ErrorReturnCode_64(ErrorReturnCode): ...
class ErrorReturnCode_65(ErrorReturnCode): ...
class ErrorReturnCode_66(ErrorReturnCode): ...
class ErrorReturnCode_67(ErrorReturnCode): ...
class ErrorReturnCode_68(ErrorReturnCode): ...
class ErrorReturnCode_69(ErrorReturnCode): ...
class ErrorReturnCode_70(ErrorReturnCode): ...
class ErrorReturnCode_71(ErrorReturnCode): ...
class ErrorReturnCode_72(ErrorReturnCode): ...
class ErrorReturnCode_73(ErrorReturnCode): ...
class ErrorReturnCode_74(ErrorReturnCode): ...
class ErrorReturnCode_75(ErrorReturnCode): ...
class ErrorReturnCode_76(ErrorReturnCode): ...
class ErrorReturnCode_77(ErrorReturnCode): ...
class ErrorReturnCode_78(ErrorReturnCode): ...
class ErrorReturnCode_79(ErrorReturnCode): ...
class ErrorReturnCode_80(ErrorReturnCode): ...
class ErrorReturnCode_81(ErrorReturnCode): ...
class ErrorReturnCode_82(ErrorReturnCode): ...
class ErrorReturnCode_83(ErrorReturnCode): ...
class ErrorReturnCode_84(ErrorReturnCode): ...
class ErrorReturnCode_85(ErrorReturnCode): ...
class ErrorReturnCode_86(ErrorReturnCode): ...
class ErrorReturnCode_87(ErrorReturnCode): ...
class ErrorReturnCode_88(ErrorReturnCode): ...
class ErrorReturnCode_89(ErrorReturnCode): ...
class ErrorReturnCode_90(ErrorReturnCode): ...
class ErrorReturnCode_91(ErrorReturnCode): ...
class ErrorReturnCode_92(ErrorReturnCode): ...
class ErrorReturnCode_93(ErrorReturnCode): ...
class ErrorReturnCode_94(ErrorReturnCode): ...
class ErrorReturnCode_95(ErrorReturnCode): ...
class ErrorReturnCode_96(ErrorReturnCode): ...
class ErrorReturnCode_97(ErrorReturnCode): ...
class ErrorReturnCode_98(ErrorReturnCode): ...
class ErrorReturnCode_99(ErrorReturnCode): ...
class ErrorReturnCode_100(ErrorReturnCode): ...
class ErrorReturnCode_101(ErrorReturnCode): ...
class ErrorReturnCode_102(ErrorReturnCode): ...
class ErrorReturnCode_103(ErrorReturnCode): ...
class ErrorReturnCode_104(ErrorReturnCode): ...
class ErrorReturnCode_105(ErrorReturnCode): ...
class ErrorReturnCode_106(ErrorReturnCode): ...
class ErrorReturnCode_107(ErrorReturnCode): ...
class ErrorReturnCode_108(ErrorReturnCode): ...
class ErrorReturnCode_109(ErrorReturnCode): ...
class ErrorReturnCode_110(ErrorReturnCode): ...
class ErrorReturnCode_111(ErrorReturnCode): ...
class ErrorReturnCode_112(ErrorReturnCode): ...
class ErrorReturnCode_113(ErrorReturnCode): ...
class ErrorReturnCode_114(ErrorReturnCode): ...
class ErrorReturnCode_115(ErrorReturnCode): ...
class ErrorReturnCode_116(ErrorReturnCode): ...
class ErrorReturnCode_117(ErrorReturnCode): ...
class ErrorReturnCode_118(ErrorReturnCode): ...
class ErrorReturnCode_119(ErrorReturnCode): ...
class ErrorReturnCode_120(ErrorReturnCode): ...
class ErrorReturnCode_121(ErrorReturnCode): ...
class ErrorReturnCode_122(ErrorReturnCode): ...
class ErrorReturnCode_123(ErrorReturnCode): ...
class ErrorReturnCode_124(ErrorReturnCode): ...
class ErrorReturnCode_125(ErrorReturnCode): ...
class ErrorReturnCode_126(ErrorReturnCode): ...
class ErrorReturnCode_127(ErrorReturnCode): ...
class ErrorReturnCode_128(ErrorReturnCode): ...
class ErrorReturnCode_129(ErrorReturnCode): ...
class ErrorReturnCode_130(ErrorReturnCode): ...
class ErrorReturnCode_131(ErrorReturnCode): ...
class ErrorReturnCode_132(ErrorReturnCode): ...
class ErrorReturnCode_133(ErrorReturnCode): ...
class ErrorReturnCode_134(ErrorReturnCode): ...
class ErrorReturnCode_135(ErrorReturnCode): ...
class ErrorReturnCode_136(ErrorReturnCode): ...
class ErrorReturnCode_137(ErrorReturnCode): ...
class ErrorReturnCode_138(ErrorReturnCode): ...
class ErrorReturnCode_139(ErrorReturnCode): ...
class ErrorReturnCode_140(ErrorReturnCode): ...
class ErrorReturnCode_141(ErrorReturnCode): ...
class ErrorReturnCode_142(ErrorReturnCode): ...
class ErrorReturnCode_143(ErrorReturnCode): ...
class ErrorReturnCode_144(ErrorReturnCode): ...
class ErrorReturnCode_145(ErrorReturnCode): ...
class ErrorReturnCode_146(ErrorReturnCode): ...
class ErrorReturnCode_147(ErrorReturnCode): ...
class ErrorReturnCode_148(ErrorReturnCode): ...
class ErrorReturnCode_149(ErrorReturnCode): ...
class ErrorReturnCode_150(ErrorReturnCode): ...
class ErrorReturnCode_151(ErrorReturnCode): ...
class ErrorReturnCode_152(ErrorReturnCode): ...
class ErrorReturnCode_153(ErrorReturnCode): ...
class ErrorReturnCode_154(ErrorReturnCode): ...
class ErrorReturnCode_155(ErrorReturnCode): ...
class ErrorReturnCode_156(ErrorReturnCode): ...
class ErrorReturnCode_157(ErrorReturnCode): ...
class ErrorReturnCode_158(ErrorReturnCode): ...
class ErrorReturnCode_159(ErrorReturnCode): ...
class ErrorReturnCode_160(ErrorReturnCode): ...
class ErrorReturnCode_161(ErrorReturnCode): ...
class ErrorReturnCode_162(ErrorReturnCode): ...
class ErrorReturnCode_163(ErrorReturnCode): ...
class ErrorReturnCode_164(ErrorReturnCode): ...
class ErrorReturnCode_165(ErrorReturnCode): ...
class ErrorReturnCode_166(ErrorReturnCode): ...
class ErrorReturnCode_167(ErrorReturnCode): ...
class ErrorReturnCode_168(ErrorReturnCode): ...
class ErrorReturnCode_169(ErrorReturnCode): ...
class ErrorReturnCode_170(ErrorReturnCode): ...
class ErrorReturnCode_171(ErrorReturnCode): ...
class ErrorReturnCode_172(ErrorReturnCode): ...
class ErrorReturnCode_173(ErrorReturnCode): ...
class ErrorReturnCode_174(ErrorReturnCode): ...
class ErrorReturnCode_175(ErrorReturnCode): ...
class ErrorReturnCode_176(ErrorReturnCode): ...
class ErrorReturnCode_177(ErrorReturnCode): ...
class ErrorReturnCode_178(ErrorReturnCode): ...
class ErrorReturnCode_179(ErrorReturnCode): ...
class ErrorReturnCode_180(ErrorReturnCode): ...
class ErrorReturnCode_181(ErrorReturnCode): ...
class ErrorReturnCode_182(ErrorReturnCode): ...
class ErrorReturnCode_183(ErrorReturnCode): ...
class ErrorReturnCode_184(ErrorReturnCode): ...
class ErrorReturnCode_185(ErrorReturnCode): ...
class ErrorReturnCode_186(ErrorReturnCode): ...
class ErrorReturnCode_187(ErrorReturnCode): ...
class ErrorReturnCode_188(ErrorReturnCode): ...
class ErrorReturnCode_189(ErrorReturnCode): ...
class ErrorReturnCode_190(ErrorReturnCode): ...
class ErrorReturnCode_191(ErrorReturnCode): ...
class ErrorReturnCode_192(ErrorReturnCode): ...
class ErrorReturnCode_193(ErrorReturnCode): ...
class ErrorReturnCode_194(ErrorReturnCode): ...
class ErrorReturnCode_195(ErrorReturnCode): ...
class ErrorReturnCode_196(ErrorReturnCode): ...
class ErrorReturnCode_197(ErrorReturnCode): ...
class ErrorReturnCode_198(ErrorReturnCode): ...
class ErrorReturnCode_199(ErrorReturnCode): ...
class ErrorReturnCode_200(ErrorReturnCode): ...
class ErrorReturnCode_201(ErrorReturnCode): ...
class ErrorReturnCode_202(ErrorReturnCode): ...
class ErrorReturnCode_203(ErrorReturnCode): ...
class ErrorReturnCode_204(ErrorReturnCode): ...
class ErrorReturnCode_205(ErrorReturnCode): ...
class ErrorReturnCode_206(ErrorReturnCode): ...
class ErrorReturnCode_207(ErrorReturnCode): ...
class ErrorReturnCode_208(ErrorReturnCode): ...
class ErrorReturnCode_209(ErrorReturnCode): ...
class ErrorReturnCode_210(ErrorReturnCode): ...
class ErrorReturnCode_211(ErrorReturnCode): ...
class ErrorReturnCode_212(ErrorReturnCode): ...
class ErrorReturnCode_213(ErrorReturnCode): ...
class ErrorReturnCode_214(ErrorReturnCode): ...
class ErrorReturnCode_215(ErrorReturnCode): ...
class ErrorReturnCode_216(ErrorReturnCode): ...
class ErrorReturnCode_217(ErrorReturnCode): ...
class ErrorReturnCode_218(ErrorReturnCode): ...
class ErrorReturnCode_219(ErrorReturnCode): ...
class ErrorReturnCode_220(ErrorReturnCode): ...
class ErrorReturnCode_221(ErrorReturnCode): ...
class ErrorReturnCode_222(ErrorReturnCode): ...
class ErrorReturnCode_223(ErrorReturnCode): ...
class ErrorReturnCode_224(ErrorReturnCode): ...
class ErrorReturnCode_225(ErrorReturnCode): ...
class ErrorReturnCode_226(ErrorReturnCode): ...
class ErrorReturnCode_227(ErrorReturnCode): ...
class ErrorReturnCode_228(ErrorReturnCode): ...
class ErrorReturnCode_229(ErrorReturnCode): ...
class ErrorReturnCode_230(ErrorReturnCode): ...
class ErrorReturnCode_231(ErrorReturnCode): ...
class ErrorReturnCode_232(ErrorReturnCode): ...
class ErrorReturnCode_233(ErrorReturnCode): ...
class ErrorReturnCode_234(ErrorReturnCode): ...
class ErrorReturnCode_235(ErrorReturnCode): ...
class ErrorReturnCode_236(ErrorReturnCode): ...
class ErrorReturnCode_237(ErrorReturnCode): ...
class ErrorReturnCode_238(ErrorReturnCode): ...
class ErrorReturnCode_239(ErrorReturnCode): ...
class ErrorReturnCode_240(ErrorReturnCode): ...
class ErrorReturnCode_241(ErrorReturnCode): ...
class ErrorReturnCode_242(ErrorReturnCode): ...
class ErrorReturnCode_243(ErrorReturnCode): ...
class ErrorReturnCode_244(ErrorReturnCode): ...
class ErrorReturnCode_245(ErrorReturnCode): ...
class ErrorReturnCode_246(ErrorReturnCode): ...
class ErrorReturnCode_247(ErrorReturnCode): ...
class ErrorReturnCode_248(ErrorReturnCode): ...
class ErrorReturnCode_249(ErrorReturnCode): ...
class ErrorReturnCode_250(ErrorReturnCode): ...
class ErrorReturnCode_251(ErrorReturnCode): ...
class ErrorReturnCode_252(ErrorReturnCode): ...
class ErrorReturnCode_253(ErrorReturnCode): ...
class ErrorReturnCode_254(ErrorReturnCode): ...
class ErrorReturnCode_255(ErrorReturnCode): ...

# Concrete SignalException subclasses for all known POSIX signals
class SignalException_SIGHUP(SignalException): ...
class SignalException_SIGINT(SignalException): ...
class SignalException_SIGQUIT(SignalException): ...
class SignalException_SIGILL(SignalException): ...
class SignalException_SIGTRAP(SignalException): ...
class SignalException_SIGIOT(SignalException): ...
class SignalException_SIGABRT(SignalException): ...
class SignalException_SIGBUS(SignalException): ...
class SignalException_SIGFPE(SignalException): ...
class SignalException_SIGKILL(SignalException): ...
class SignalException_SIGUSR1(SignalException): ...
class SignalException_SIGSEGV(SignalException): ...
class SignalException_SIGUSR2(SignalException): ...
class SignalException_SIGPIPE(SignalException): ...
class SignalException_SIGALRM(SignalException): ...
class SignalException_SIGTERM(SignalException): ...
class SignalException_SIGSTKFLT(SignalException): ...
class SignalException_SIGCLD(SignalException): ...
class SignalException_SIGCHLD(SignalException): ...
class SignalException_SIGCONT(SignalException): ...
class SignalException_SIGSTOP(SignalException): ...
class SignalException_SIGTSTP(SignalException): ...
class SignalException_SIGTTIN(SignalException): ...
class SignalException_SIGTTOU(SignalException): ...
class SignalException_SIGURG(SignalException): ...
class SignalException_SIGXCPU(SignalException): ...
class SignalException_SIGXFSZ(SignalException): ...
class SignalException_SIGVTALRM(SignalException): ...
class SignalException_SIGPROF(SignalException): ...
class SignalException_SIGWINCH(SignalException): ...
class SignalException_SIGIO(SignalException): ...
class SignalException_SIGPOLL(SignalException): ...
class SignalException_SIGPWR(SignalException): ...
class SignalException_SIGSYS(SignalException): ...
class SignalException_SIGRTMIN(SignalException): ...
class SignalException_SIGRTMAX(SignalException): ...

# Numeric aliases — SignalException_N mirrors the named form for the same signal
class SignalException_1(SignalException): ...  # SIGHUP
class SignalException_2(SignalException): ...  # SIGINT
class SignalException_3(SignalException): ...  # SIGQUIT
class SignalException_4(SignalException): ...  # SIGILL
class SignalException_5(SignalException): ...  # SIGTRAP
class SignalException_6(SignalException): ...  # SIGABRT / SIGIOT
class SignalException_7(SignalException): ...  # SIGBUS
class SignalException_8(SignalException): ...  # SIGFPE
class SignalException_9(SignalException): ...  # SIGKILL
class SignalException_10(SignalException): ...  # SIGUSR1
class SignalException_11(SignalException): ...  # SIGSEGV
class SignalException_12(SignalException): ...  # SIGUSR2
class SignalException_13(SignalException): ...  # SIGPIPE
class SignalException_14(SignalException): ...  # SIGALRM
class SignalException_15(SignalException): ...  # SIGTERM
class SignalException_16(SignalException): ...  # SIGSTKFLT
class SignalException_17(SignalException): ...  # SIGCHLD / SIGCLD
class SignalException_18(SignalException): ...  # SIGCONT
class SignalException_19(SignalException): ...  # SIGSTOP
class SignalException_20(SignalException): ...  # SIGTSTP
class SignalException_21(SignalException): ...  # SIGTTIN
class SignalException_22(SignalException): ...  # SIGTTOU
class SignalException_23(SignalException): ...  # SIGURG
class SignalException_24(SignalException): ...  # SIGXCPU
class SignalException_25(SignalException): ...  # SIGXFSZ
class SignalException_26(SignalException): ...  # SIGVTALRM
class SignalException_27(SignalException): ...  # SIGPROF
class SignalException_28(SignalException): ...  # SIGWINCH
class SignalException_29(SignalException): ...  # SIGIO / SIGPOLL
class SignalException_30(SignalException): ...  # SIGPWR
class SignalException_31(SignalException): ...  # SIGSYS
class SignalException_34(SignalException): ...  # SIGRTMIN
class SignalException_64(SignalException): ...  # SIGRTMAX

class TimeoutException(Exception):
    exit_code: Optional[int]
    full_cmd: str
    def __init__(self, exit_code: Optional[int], full_cmd: str) -> None: ...

# Internal exceptions exposed via the allowlist
class DoneReadingForever(Exception): ...
class NotYetReadyToRead(Exception): ...

class OProc:
    """Manages fork/exec and I/O wiring for a child process (Open Process).

    Instantiated internally by RunningCommand; accessible via
    ``RunningCommand.process``.
    """

    # Redirect sentinels — pass as ``stderr`` to merge stderr into stdout, or
    # as the ``pipe`` argument to select which stream is piped.
    STDOUT: int  # -1
    STDERR: int  # -2

    # -- populated in the parent process after fork() --
    pid: int
    sid: int
    pgid: int
    cmd: List[str]
    call_args: Dict[str, Any]
    exit_code: Optional[int]
    timed_out: bool
    started: float
    ctty: Optional[str]
    stdin: Any  # file-like object, Queue, or None

    def __init__(
        self,
        command: Any,  # RunningCommand (forward ref avoided to keep stub simple)
        parent_log: Any,
        cmd: List[str],
        stdin: Any,
        stdout: Any,
        stderr: Any,
        call_args: Dict[str, Any],
        pipe: int,
        process_assign_lock: threading.Lock,
    ) -> None: ...
    def __repr__(self) -> str: ...

    # -- aggregated output (bytes) --
    @property
    def stdout(self) -> bytes: ...
    @property
    def stderr(self) -> bytes: ...

    # -- process group / session helpers --
    def get_pgid(self) -> int:
        """Return the *current* process group ID (may differ from self.pgid)."""
        ...
    def get_sid(self) -> int:
        """Return the *current* session ID (may differ from self.sid)."""
        ...

    # -- signal helpers --
    def signal(self, sig: int) -> None: ...
    def signal_group(self, sig: int) -> None: ...
    def kill(self) -> None: ...
    def kill_group(self) -> None: ...
    def terminate(self) -> None: ...

    # -- lifecycle --
    def is_alive(self) -> Tuple[bool, Optional[int]]:
        """Poll the child without blocking.

        Returns ``(alive, exit_code)``.  ``exit_code`` is ``None`` while the
        process is still running.
        """
        ...
    def wait(self) -> int:
        """Block until the process exits and return its exit code."""
        ...

    # -- buffering controls --
    def change_in_bufsize(self, buf: int) -> None: ...
    def change_out_bufsize(self, buf: int) -> None: ...
    def change_err_bufsize(self, buf: int) -> None: ...

    # some private properties accessed by the tests
    _pipe_queue: Queue

# ---------------------------------------------------------------------------
# RunningCommand — returned when a Command is called
#
# Inherits from str in this stub (not at runtime) so that type checkers
# expose the full str interface — e.g. .split(), .strip(), .startswith() —
# matching the dynamic delegation in RunningCommand.__getattr__.
# ---------------------------------------------------------------------------

class RunningCommand(str):
    ran: str
    call_args: Dict[str, Any]
    cmd: List[str]
    process: OProc

    @property
    def stdout(self) -> bytes: ...
    @property
    def stderr(self) -> bytes: ...
    @property
    def exit_code(self) -> int: ...
    @property
    def pid(self) -> int: ...
    def wait(self, timeout: Optional[float] = ...) -> "RunningCommand": ...
    def is_alive(self) -> bool: ...
    def kill(self) -> None: ...
    def kill_group(self) -> None: ...
    def terminate(self) -> None: ...
    def signal(self, sig: int) -> None: ...
    def signal_group(self, sig: int) -> None: ...
    def __int__(self) -> int: ...
    def __float__(self) -> float: ...
    def __long__(self) -> int: ...
    def __await__(self) -> Generator[Any, None, "RunningCommand"]: ...
    def __aiter__(self) -> AsyncIterator[str]: ...
    def __enter__(self) -> None: ...
    def __exit__(self, *args: Any) -> None: ...
    def __next__(self) -> str: ...

# ---------------------------------------------------------------------------
# Command — represents an un-run system program
# ---------------------------------------------------------------------------

# A Command can return a `str`` or a `Running`` command, depending on if it was
# called with `_return_cmd` or not.
_ReturnT_co = _TypeVarExt(
    "_ReturnT_co", RunningCommand, str, covariant=True, default=str
)

class Command(Generic[_ReturnT_co]):
    def __init__(self, name: str, search_paths: Optional[List[str]] = ...) -> None: ...
    @overload
    def bake(
        self, *args: Any, _bg: Literal[True], **kwargs: Any
    ) -> "Command[RunningCommand]": ...
    @overload
    def bake(
        self, *args: Any, _async: Literal[True], **kwargs: Any
    ) -> "Command[RunningCommand]": ...
    @overload
    def bake(
        self, *args: Any, _return_cmd: Literal[True], **kwargs: Any
    ) -> "Command[RunningCommand]": ...
    @overload
    def bake(
        self, *args: Any, _return_cmd: Literal[False], **kwargs: Any
    ) -> "Command[str]": ...
    @overload
    def bake(self, *args: Any, **kwargs: Any) -> "Command[_ReturnT_co]": ...
    @overload
    def __call__(
        self, *args: Any, _bg: Literal[True], **kwargs: Any
    ) -> RunningCommand: ...
    @overload
    def __call__(
        self, *args: Any, _async: Literal[True], **kwargs: Any
    ) -> RunningCommand: ...
    @overload
    def __call__(
        self, *args: Any, _return_cmd: Literal[True], **kwargs: Any
    ) -> RunningCommand: ...
    @overload
    def __call__(
        self, *args: Any, _return_cmd: Literal[False], **kwargs: Any
    ) -> str: ...
    @overload
    def __call__(self, *args: Any, **kwargs: Any) -> _ReturnT_co: ...
    def __str__(self) -> str: ...
    def __repr__(self) -> str: ...
    def __eq__(self, other: object) -> bool: ...
    def __enter__(self) -> None: ...
    def __exit__(self, *args: Any) -> None: ...
    # sub-command access (e.g. git.log, docker.container.ls)
    def __getattr__(self, name: str) -> "Command[_ReturnT_co]": ...

    # some private properties accessed by the tests
    _path: str
    _call_args: Dict[str, Any]

# ---------------------------------------------------------------------------
# StreamBufferer — exposed via allowlist
# ---------------------------------------------------------------------------

class StreamBufferer:
    type: int
    encoding: str
    decode_errors: str
    def __init__(
        self,
        buffer_type: int,
        encoding: str = ...,
        decode_errors: str = ...,
    ) -> None: ...
    def change_buffering(self, new_type: int) -> None: ...
    def process(self, chunk: bytes) -> List[bytes]: ...
    def flush(self) -> List[bytes]: ...

# ---------------------------------------------------------------------------
# pushd — context manager for temporary directory changes
# ---------------------------------------------------------------------------

@contextmanager
def pushd(path: str) -> Iterator[None]: ...

# ---------------------------------------------------------------------------
# glob — path expansion helper
# ---------------------------------------------------------------------------

def glob(path: str, *args: Any, **kwargs: Any) -> List[str]: ...

# The return value on this technically isn't correct, it should be the type of
# the sh module, but I don't know how to write that. # FIXME
def bake(*args: Any, **kwargs: Any) -> Command[str]: ...
def _aggregate_keywords(*, kwargs: dict, sep: str, prefix: str): ...

# ---------------------------------------------------------------------------
# contrib — namespace of pre-baked command wrappers
# ---------------------------------------------------------------------------

class contrib:
    git: Command[str]
    bash: Command[str]
    sudo: Command[str]
    ssh: Command[str]

# ---------------------------------------------------------------------------
# Module-level __getattr__
#
# This is the PEP 562 hook that tells type checkers (mypy, pyright, …) that
# any name resolved from this module — e.g. ``from sh import ls`` or
# ``sh.grep`` — is a Command object.  Without this, dynamic attribute access
# via SelfWrapper.__getattr__ would be invisible to static analysis.
#
# ErrorReturnCode_N (0-255) and SignalException_SIG* names are declared
# explicitly above (all standard POSIX signals) rather than relying on this fallback.
# ---------------------------------------------------------------------------

def __getattr__(name: str) -> Command[str]: ...
