fancy-subprocess 2.3__tar.gz → 3.0__tar.gz

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/.gitignore

@@ -122,6 +122,7 @@ celerybeat.pid
 # Environments
 .env
 .venv
+.just_venv_*
 env/
 venv/
 ENV/

fancy_subprocess-3.0/Justfile

@@ -0,0 +1,29 @@
+default:
+    just --list --justfile "{{justfile()}}"
+
+[private]
+verify_with_impl python_minor_version $UV_PROJECT_ENVIRONMENT:
+    @echo UV_PROJECT_ENVIRONMENT=${UV_PROJECT_ENVIRONMENT}
+    uv sync --python 3.{{python_minor_version}}
+
+    uv run -m mypy .
+    uv run ty check .
+    uv run ruff check --target-version py3{{python_minor_version}}
+    uv run ruff format --check --target-version py3{{python_minor_version}}
+    uv run -m pytest
+
+verify_with python_minor_version="14": (verify_with_impl python_minor_version ".just_venv_3_"+python_minor_version)
+
+verify: (verify_with "10") (verify_with "11") (verify_with "12") (verify_with "13") (verify_with "14")
+
+format:
+    uv run ruff check --select I --fix
+    uv run ruff format
+
+build_no_verify:
+    uv build
+
+build: verify build_no_verify
+
+publish: build
+    uv publish

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fancy-subprocess
-Version: 2.3
+Version: 3.0
 Summary: subprocess.run() with formatted output, detailed error messages and retry capabilities
 Project-URL: Homepage, https://github.com/petamas/python-fancy-subprocess
 Project-URL: Bug Tracker, https://github.com/petamas/python-fancy-subprocess/issues
@@ -17,12 +17,13 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
 Requires-Dist: ntstatus<3,>=2.0
-Requires-Dist: oslex<2,>=0.1.3
+Requires-Dist: oslex<3,>=2.0
 Requires-Dist: pathext<2,>=1.5
-Requires-Dist: typeguard<5,>=4.4.2
-Requires-Dist: typing-extensions<5,>=4.14
+Requires-Dist: typeguard<5,>=4.5.2
+Requires-Dist: typing-extensions<5,>=4.15
 Description-Content-Type: text/markdown
 
 # fancy-subprocess
@@ -55,7 +56,7 @@ Arguments (all of them except `cmd` are optional):
     - The type of this argument is also aliased as `fancy_subprocess.Success`.
 - `flush_before_subprocess: bool` - If `True`, flushes both the standard output and error streams before running the command. If unspecified or set to `None`, defaults to `True`.
 - `trim_output_lines: bool` - If `True`, remove trailing whitespace from the lines of the output of the command before calling `print_output` and adding them to the `output` field of `RunResult`. If unspecified or set to `None`, defaults to `True`.
-- `max_output_size: int` - Maximum number of characters to be recorded in the `output` field of `RunResult`. If the command produces more than `max_output_size` characters, only the last `max_output_size` will be recorded. If unspecified or set to `None`, defaults to 10,000,000.
+- `max_output_size: int | NoLimit` - Maximum number of characters to be recorded in the `output` field of `RunResult`. If the command produces more than `max_output_size` characters, only the last `max_output_size` will be recorded. If set to `fancy_subprocess.NO_LIMIT`, then the full output will be recorded. If unspecified or set to `None`, defaults to 10,000,000.
 - `retry: int` - Number of times to retry running the command on failure. Note that the total number of attempts is one greater than what's specified. (I.e. `retry=2` attempts to run the command 3 times.) If unspecified or set to `None`, defaults to 0.
 - `retry_initial_sleep_seconds: float` - Number of seconds to wait before retrying for the first time. If unspecified or set to `None`, defaults to 10.
 - `retry_backoff: float` - Factor used to increase wait times before subsequent retries. If unspecified or set to `None`, defaults to 2.
@@ -282,6 +283,17 @@ Exception FileNotFoundError with message "[Errno 2] No such file or directory: '
 
 Calls `sys.stdout.reconfigure()` and `sys.stderr.reconfigure()` with the provided parameters. Raises `TypeError` if either `sys.stdout` or `sys.stderr` is not an instance of `io.TextIOWrapper`.
 
+### `fancy_subprocess.stringify_exit_code()`
+
+Takes an exit code, and tries to format it in a way to help users understand what went wrong. If it succeeds, returns the explanation as a string. If not, returns `None`.
+
+Some examples:
+- On POSIX platforms, decodes signals to their string representation.
+- On Windows, if the code matches an NTSTATUS error, it returns the name of the NTSTATUS.
+- On Windows, if it is a 32-bit value, returns it as a hex number (because that's usually how you can find them on Google).
+
+Used as part of the error message in `RunError`.
+
 ## Licensing
 
 This library is licensed under the MIT license.

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/README.md

@@ -28,7 +28,7 @@ Arguments (all of them except `cmd` are optional):
     - The type of this argument is also aliased as `fancy_subprocess.Success`.
 - `flush_before_subprocess: bool` - If `True`, flushes both the standard output and error streams before running the command. If unspecified or set to `None`, defaults to `True`.
 - `trim_output_lines: bool` - If `True`, remove trailing whitespace from the lines of the output of the command before calling `print_output` and adding them to the `output` field of `RunResult`. If unspecified or set to `None`, defaults to `True`.
-- `max_output_size: int` - Maximum number of characters to be recorded in the `output` field of `RunResult`. If the command produces more than `max_output_size` characters, only the last `max_output_size` will be recorded. If unspecified or set to `None`, defaults to 10,000,000.
+- `max_output_size: int | NoLimit` - Maximum number of characters to be recorded in the `output` field of `RunResult`. If the command produces more than `max_output_size` characters, only the last `max_output_size` will be recorded. If set to `fancy_subprocess.NO_LIMIT`, then the full output will be recorded. If unspecified or set to `None`, defaults to 10,000,000.
 - `retry: int` - Number of times to retry running the command on failure. Note that the total number of attempts is one greater than what's specified. (I.e. `retry=2` attempts to run the command 3 times.) If unspecified or set to `None`, defaults to 0.
 - `retry_initial_sleep_seconds: float` - Number of seconds to wait before retrying for the first time. If unspecified or set to `None`, defaults to 10.
 - `retry_backoff: float` - Factor used to increase wait times before subsequent retries. If unspecified or set to `None`, defaults to 2.
@@ -255,6 +255,17 @@ Exception FileNotFoundError with message "[Errno 2] No such file or directory: '
 
 Calls `sys.stdout.reconfigure()` and `sys.stderr.reconfigure()` with the provided parameters. Raises `TypeError` if either `sys.stdout` or `sys.stderr` is not an instance of `io.TextIOWrapper`.
 
+### `fancy_subprocess.stringify_exit_code()`
+
+Takes an exit code, and tries to format it in a way to help users understand what went wrong. If it succeeds, returns the explanation as a string. If not, returns `None`.
+
+Some examples:
+- On POSIX platforms, decodes signals to their string representation.
+- On Windows, if the code matches an NTSTATUS error, it returns the name of the NTSTATUS.
+- On Windows, if it is a 32-bit value, returns it as a hex number (because that's usually how you can find them on Google).
+
+Used as part of the error message in `RunError`.
+
 ## Licensing
 
 This library is licensed under the MIT license.

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/fancy_subprocess/__init__.py

@@ -1,4 +1,5 @@
 from fancy_subprocess._compat import *
+from fancy_subprocess._exit_code import *
 from fancy_subprocess._print import *
 from fancy_subprocess._reconfigure import *
 from fancy_subprocess._run_core import *

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/fancy_subprocess/_compat.py

@@ -6,13 +6,16 @@ __all__ = [
     'which',
 ]
 
-from pathext import checked_which, which
+from pathext import checked_which
+from pathext import which
 
-from fancy_subprocess._run_core import RunError, RunResult
+from fancy_subprocess._run_core import RunError
+from fancy_subprocess._run_core import RunResult
 
 RunProcessError = RunError
 RunProcessResult = RunResult
 
+
 def SILENCE(msg: str) -> None:
     """
     Helper function that takes a string, and does nothing with it. Meant to be passed as the print_message or print_output argument of run() and related functions to silence the corresponding output stream.

fancy_subprocess-3.0/fancy_subprocess/_exit_code.py

@@ -0,0 +1,53 @@
+__all__ = [
+    'stringify_exit_code',
+]
+
+import sys
+from typing import Optional
+
+if sys.platform == 'win32':
+    from ntstatus import NtStatus
+    from ntstatus import NtStatusSeverity
+    from ntstatus import ThirtyTwoBits
+else:
+    import signal
+
+    def _signal_name(signal_value: int) -> Optional[str]:
+        try:
+            return signal.Signals(signal_value).name
+        except ValueError:
+            return None
+
+
+def stringify_exit_code(exit_code: int) -> Optional[str]:
+    if sys.platform == 'win32':
+        # Windows
+        if exit_code == 3:
+            # abort() results in exit code 3: https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/abort
+            # While exit code 3 does not necessarily mean aborted (because applications may use it as a generic error code),
+            # it's common enough to be worth handling. "?" included to signal the uncertainty.
+            return 'aborted?'
+
+        if not ThirtyTwoBits.check(exit_code):
+            return None
+
+        try:
+            status = NtStatus.decode(exit_code)
+            if NtStatus.severity(status) != NtStatusSeverity.STATUS_SEVERITY_SUCCESS:
+                return status.name
+        except ValueError:
+            pass
+
+        return f'0x{ThirtyTwoBits(exit_code).unsigned_value:08X}'
+    else:
+        # POSIX
+        if exit_code < 0:
+            return _signal_name(-exit_code) or 'unknown signal'
+        elif exit_code == 126:
+            return 'COULD_NOT_EXECUTE'
+        elif exit_code == 127:
+            return 'COMMAND_NOT_FOUND'
+        elif exit_code in range(129, 160):
+            return _signal_name(exit_code - 128) or 'unknown signal'
+
+    return None

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/fancy_subprocess/_print.py

@@ -16,24 +16,29 @@ PrintFunction = Callable[[str], None]
 
 Indent = int | str
 
+
 def silenced_print(line: str) -> None:
     pass
 
+
 def indented_print(line: str, indent: Optional[Indent] = None) -> None:
     if indent is None:
-        real_indent = 4*' '
+        real_indent = 4 * ' '
     elif isinstance(indent, int):
-        real_indent = indent*' '
+        real_indent = indent * ' '
     else:
         real_indent = indent
 
     print(f'{real_indent}{line}', flush=True)
 
+
 def indented_print_factory(indent: Optional[Indent] = None) -> PrintFunction:
     return lambda line: indented_print(line, indent)
 
+
 def default_print(line: str) -> None:
     indented_print(line, indent='')
 
+
 def error_print(line: str) -> None:
     print(line, file=sys.stderr, flush=True)

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/fancy_subprocess/_reconfigure.py

@@ -4,10 +4,12 @@ __all__ = [
 
 import io
 import sys
-from typing import Optional, TypedDict
+from typing import Optional
+from typing import TypedDict
 
 from typing_extensions import Unpack
 
+
 class ReconfigureParams(TypedDict, total=False):
     encoding: Optional[str]
     errors: Optional[str]
@@ -15,6 +17,7 @@ class ReconfigureParams(TypedDict, total=False):
     line_buffering: Optional[bool]
     write_through: Optional[bool]
 
+
 def _reconfigure_standard_stream(stream: object, name: str, **kwargs: Unpack[ReconfigureParams]) -> None:
     if stream is None:
         raise TypeError(f'{name} is None')
@@ -24,6 +27,7 @@ def _reconfigure_standard_stream(stream: object, name: str, **kwargs: Unpack[Rec
 
     stream.reconfigure(**kwargs)
 
+
 def reconfigure_standard_output_streams(**kwargs: Unpack[ReconfigureParams]) -> None:
     """
     Calls `sys.stdout.reconfigure()` and `sys.stderr.reconfigure()` with the provided parameters. Raises `TypeError` if either `sys.stdout` or `sys.stderr` is not an instance of `io.TextIOWrapper`.

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/fancy_subprocess/_run_core.py

@@ -13,11 +13,22 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
+import oslex
 from typing_extensions import Unpack
 
-from fancy_subprocess._print import default_print, PrintFunction, silenced_print
-from fancy_subprocess._run_param import AnyExitCode, check_run_params, RunParams, Success
-from fancy_subprocess._utils import oslex_join, stringify_exit_code, value_or
+from fancy_subprocess._exit_code import stringify_exit_code
+from fancy_subprocess._print import PrintFunction
+from fancy_subprocess._print import default_print
+from fancy_subprocess._print import silenced_print
+from fancy_subprocess._run_param import AnyExitCode
+from fancy_subprocess._run_param import EnvOverrides
+from fancy_subprocess._run_param import MaxOutputSize
+from fancy_subprocess._run_param import NoLimit
+from fancy_subprocess._run_param import RunParams
+from fancy_subprocess._run_param import Success
+from fancy_subprocess._run_param import check_run_params
+from fancy_subprocess._utils import value_or
+
 
 @dataclass(kw_only=True, frozen=True)
 class RunResult:
@@ -32,7 +43,7 @@ class RunResult:
     exit_code: int = 0
     output: str = ''
 
-@dataclass(kw_only=True, frozen=True)
+
 class RunError(Exception):
     """
     `fancy_subprocess.run()` and similar functions raise `RunError` on error. There are two kinds of errors that result in a `RunError`:
@@ -53,6 +64,11 @@ class RunError(Exception):
     - `oserror: OSError` - The `OSError` raised by `subprocess.Popen()`. Raises `ValueError` if `completed` is `True`.
     """
 
+    # See test_runerror_picklable() in test_runerror_bugs.py for why these arguments are positional only
+    def __init__(self, cmd: Sequence[str | Path], result: RunResult | OSError = RunResult(), /) -> None:
+        self.cmd = cmd
+        self.result = result
+
     cmd: Sequence[str | Path]
     result: RunResult | OSError = RunResult()
 
@@ -65,21 +81,21 @@ class RunError(Exception):
         if isinstance(self.result, RunResult):
             return self.result.exit_code
         else:
-            raise ValueError('...')
+            raise ValueError('"exit_code" can only be queried if "completed" is True')
 
     @property
     def output(self) -> str:
         if isinstance(self.result, RunResult):
             return self.result.output
         else:
-            raise ValueError('...')
+            raise ValueError('"output" can only be queried if "completed" is True')
 
     @property
     def oserror(self) -> OSError:
         if isinstance(self.result, OSError):
             return self.result
         else:
-            raise ValueError('...')
+            raise ValueError('"oserror" can only be queried if "completed" is False')
 
     @property
     def message(self) -> str:
@@ -89,13 +105,93 @@ class RunError(Exception):
                 exit_code_comment = f' ({exit_code_str})'
             else:
                 exit_code_comment = ''
-            return f'Command failed with exit code {self.exit_code}{exit_code_comment}: {oslex_join(self.cmd)}'
+            return f'Command failed with exit code {self.exit_code}{exit_code_comment}: {oslex.join(self.cmd)}'
         else:
-            return f'Exception {type(self.result).__name__} with message "{str(self.result)}" was raised while trying to run command: {oslex_join(self.cmd)}'
+            return f'Exception {type(self.result).__name__} with message "{str(self.result)}" was raised while trying to run command: {oslex.join(self.cmd)}'
 
     def __str__(self) -> str:
         return self.message
 
+
+class _ResolvedRunParams:
+    def __init__(self, cmd: Sequence[str | Path], **kwargs: Unpack[RunParams]) -> None:
+        self.message_quiet: bool = value_or(kwargs.get('message_quiet'), False)
+        self.output_quiet: bool = value_or(kwargs.get('output_quiet'), False)
+        self.default_description: str
+        if self.output_quiet:
+            self.default_description = f'Running command (output silenced): {oslex.join(cmd)}'
+        else:
+            self.default_description = f'Running command: {oslex.join(cmd)}'
+        self.description: str = value_or(kwargs.get('description'), self.default_description)
+        self.success: Success = value_or(kwargs.get('success'), [0])
+        self.flush_before_subprocess: bool = value_or(kwargs.get('flush_before_subprocess'), True)
+        self.trim_output_lines: bool = value_or(kwargs.get('trim_output_lines'), True)
+        self.max_output_size: MaxOutputSize = value_or(kwargs.get('max_output_size'), 10 * 1000 * 1000)
+        self.retry: int = value_or(kwargs.get('retry'), 0)
+        self.retry_initial_sleep_seconds: float = value_or(kwargs.get('retry_initial_sleep_seconds'), 10)
+        self.retry_backoff: float = value_or(kwargs.get('retry_backoff'), 2)
+        self.env_overrides: EnvOverrides = value_or(kwargs.get('env_overrides'), dict())
+        self.cwd: Optional[str | Path] = kwargs.get('cwd')
+        self.encoding: Optional[str] = kwargs.get('encoding')
+        self.errors: str = value_or(kwargs.get('errors'), 'replace')
+        self.replace_fffd_with_question_mark: bool = value_or(kwargs.get('replace_fffd_with_question_mark'), True)
+
+
+def _attempt_run(
+    cmd: Sequence[str | Path],
+    *,
+    print_message: PrintFunction,
+    print_output: PrintFunction,
+    env: dict[str, str],
+    params: _ResolvedRunParams,
+) -> RunResult:
+    print_message(params.description)
+
+    if params.flush_before_subprocess:
+        sys.stdout.flush()
+        sys.stderr.flush()
+
+    output = ''
+    try:
+        with subprocess.Popen(
+            cmd,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+            cwd=params.cwd,
+            env=env,
+            encoding=params.encoding,
+            errors=params.errors,
+        ) as proc:
+            assert proc.stdout is not None  # passing stdout=subprocess.PIPE guarantees this
+
+            for line in iter(proc.stdout.readline, ''):
+                line = line.removesuffix('\n')
+                if params.trim_output_lines:
+                    line = line.rstrip()
+                if params.replace_fffd_with_question_mark:
+                    line = line.replace('\ufffd', '?')
+
+                print_output(line)
+
+                output += line + '\n'
+                if not isinstance(params.max_output_size, NoLimit):
+                    if len(output) > params.max_output_size + 1:
+                        output = output[-params.max_output_size - 1 :]  # drop the beginning of the string
+
+            proc.wait()
+            result = RunResult(exit_code=proc.returncode, output=output.removesuffix('\n'))
+    except OSError as e:
+        raise RunError(cmd, e) from e
+
+    if isinstance(params.success, AnyExitCode) or result.exit_code in params.success:
+        return result
+    else:
+        raise RunError(cmd, result)
+
+
 def run(
     cmd: Sequence[str | Path],
     *,
@@ -125,7 +221,7 @@ def run(
     - `success: Sequence[int] | AnyExitCode` - List of exit codes that should be considered successful. If set to `fancy_subprocess.ANY_EXIT_CODE`, then all exit codes are considered successful. If unspecified or set to `None`, defaults to `[0]`. Note that 0 is not automatically included in the list of successful exit codes, so if a list without 0 is specified, then the function will consider 0 a failure.
     - `flush_before_subprocess: bool` - If `True`, flushes both the standard output and error streams before running the command. If unspecified or set to `None`, defaults to `True`.
     - `trim_output_lines: bool` - If `True`, remove trailing whitespace from the lines of the output of the command before calling `print_output` and adding them to the `output` field of `RunResult`. If unspecified or set to `None`, defaults to `True`.
-    - `max_output_size: int` - Maximum number of characters to be recorded in the `output` field of `RunResult`. If the command produces more than `max_output_size` characters, only the last `max_output_size` will be recorded. If unspecified or set to `None`, defaults to 10,000,000.
+    - `max_output_size: int | NoLimit` - Maximum number of characters to be recorded in the `output` field of `RunResult`. If the command produces more than `max_output_size` characters, only the last `max_output_size` will be recorded. If set to `fancy_subprocess.NO_LIMIT`, then the full output will be recorded. If unspecified or set to `None`, defaults to 10,000,000.
     - `retry: int` - Number of times to retry running the command on failure. Note that the total number of attempts is one greater than what's specified. (I.e. `retry=2` attempts to run the command 3 times.) If unspecified or set to `None`, defaults to 0.
     - `retry_initial_sleep_seconds: float` - Number of seconds to wait before retrying for the first time. If unspecified or set to `None`, defaults to 10.
     - `retry_backoff: float` - Factor used to increase wait times before subsequent retries. If unspecified or set to `None`, defaults to 2.
@@ -138,89 +234,36 @@ def run(
 
     check_run_params(**kwargs)
 
-    message_quiet = value_or(kwargs.get('message_quiet'), False)
-    output_quiet = value_or(kwargs.get('output_quiet'), False)
-    if output_quiet:
-        default_description = f'Running command (output silenced): {oslex_join(cmd)}'
-    else:
-        default_description = f'Running command: {oslex_join(cmd)}'
-    description = value_or(kwargs.get('description'), default_description)
-    success: Success = value_or(kwargs.get('success'), [0])
-    flush_before_subprocess = value_or(kwargs.get('flush_before_subprocess'), True)
-    trim_output_lines = value_or(kwargs.get('trim_output_lines'), True)
-    max_output_size = value_or(kwargs.get('max_output_size'), 10*1000*1000)
-    retry = value_or(kwargs.get('retry'), 0)
-    retry_initial_sleep_seconds = value_or(kwargs.get('retry_initial_sleep_seconds'), 10)
-    retry_backoff = value_or(kwargs.get('retry_backoff'), 2)
-    env_overrides = value_or(kwargs.get('env_overrides'), dict())
-    cwd = kwargs.get('cwd')
-    encoding = kwargs.get('encoding')
-    errors = value_or(kwargs.get('errors'), 'replace')
-    replace_fffd_with_question_mark = value_or(kwargs.get('replace_fffd_with_question_mark'), True)
-
-    if message_quiet:
+    params = _ResolvedRunParams(cmd, **kwargs)
+
+    if params.message_quiet:
         print_message = silenced_print
     else:
         print_message = value_or(print_message, default_print)
 
-    if output_quiet:
+    if params.output_quiet:
         print_output = silenced_print
     else:
         print_output = value_or(print_output, default_print)
 
     env = dict(os.environ)
-    if sys.platform=='win32':
-        env.update((key.upper(), value) for key,value in env_overrides.items())
+    if sys.platform == 'win32':
+        env.update((key.upper(), value) for key, value in params.env_overrides.items())
     else:
-        env.update(env_overrides)
-
-    def attempt_run() -> RunResult:
-        print_message(description)
-
-        if flush_before_subprocess:
-            sys.stdout.flush()
-            sys.stderr.flush()
-
-        output = ''
-        try:
-            with subprocess.Popen(cmd, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, bufsize=1, cwd=cwd, env=env, encoding=encoding, errors=errors) as proc:
-                assert proc.stdout is not None # passing stdout=subprocess.PIPE guarantees this
-
-                for line in iter(proc.stdout.readline, ''):
-                    line = line.removesuffix('\n')
-                    if trim_output_lines:
-                        line = line.rstrip()
-                    if replace_fffd_with_question_mark:
-                        line = line.replace('\ufffd', '?')
-
-                    print_output(line)
-
-                    output += line + '\n'
-                    if len(output)>max_output_size+1:
-                        output = output[-max_output_size-1:] # drop the beginning of the string
-
-                proc.wait()
-                result = RunResult(exit_code=proc.returncode, output=output.removesuffix('\n'))
-        except OSError as e:
-            raise RunError(cmd=cmd, result=e) from e
-
-        if isinstance(success, AnyExitCode) or result.exit_code in success:
-            return result
-        else:
-            raise RunError(cmd=cmd, result=result)
+        env.update(params.env_overrides)
 
-    sleep_seconds = retry_initial_sleep_seconds
-    for attempts_left in range(retry, 0, -1):
+    sleep_seconds = params.retry_initial_sleep_seconds
+    for attempts_left in range(params.retry, 0, -1):
         try:
-            return attempt_run()
+            return _attempt_run(cmd, print_message=print_message, print_output=print_output, env=env, params=params)
         except RunError as e:
             print_message(str(e))
-            if attempts_left!=1:
+            if attempts_left != 1:
                 plural = 's'
             else:
                 plural = ''
             print_message(f'Retrying in {sleep_seconds} seconds ({attempts_left} attempt{plural} left)...')
             time.sleep(sleep_seconds)
-            sleep_seconds *= retry_backoff
+            sleep_seconds *= params.retry_backoff
 
-    return attempt_run()
+    return _attempt_run(cmd, print_message=print_message, print_output=print_output, env=env, params=params)

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/fancy_subprocess/_run_param.py

@@ -5,17 +5,23 @@ __all__ = [
     'check_run_params',
     'EnvOverrides',
     'force_run_params',
+    'MaxOutputSize',
+    'NO_LIMIT',
+    'NoLimit',
     'RunParams',
     'Success',
 ]
 
-from collections.abc import Mapping, Sequence
+from collections.abc import Mapping
+from collections.abc import Sequence
 from pathlib import Path
-from typing import Optional, TypedDict
+from typing import Optional
+from typing import TypedDict
 
 import typeguard
 from typing_extensions import Unpack
 
+
 class AnyExitCode:
     """
     Use an instance of this class (eg. fancy_subprocess.ANY_EXIT_CODE) as the 'success' argument to make run() and related functions treat any exit code as success.
@@ -23,12 +29,27 @@ class AnyExitCode:
 
     pass
 
+
 ANY_EXIT_CODE = AnyExitCode()
 
 Success = Sequence[int] | AnyExitCode
 
+
+class NoLimit:
+    """
+    Use an instance of this class (eg. fancy_subprocess.NO_LIMIT) as the 'max_output_size' argument to make run() and related functions not constrain the size of the output string.
+    """
+
+    pass
+
+
+NO_LIMIT = NoLimit()
+
+MaxOutputSize = int | NoLimit
+
 EnvOverrides = Mapping[str, str]
 
+
 class RunParams(TypedDict, total=False):
     message_quiet: Optional[bool]
     output_quiet: Optional[bool]
@@ -36,7 +57,7 @@ class RunParams(TypedDict, total=False):
     success: Optional[Success]
     flush_before_subprocess: Optional[bool]
     trim_output_lines: Optional[bool]
-    max_output_size: Optional[int]
+    max_output_size: Optional[MaxOutputSize]
     retry: Optional[int]
     retry_initial_sleep_seconds: Optional[float]
     retry_backoff: Optional[float]
@@ -46,11 +67,14 @@ class RunParams(TypedDict, total=False):
     errors: Optional[str]
     replace_fffd_with_question_mark: Optional[bool]
 
+
 def check_run_params(**kwargs: Unpack[RunParams]) -> None:
     try:
         typeguard.check_type(kwargs, RunParams, collection_check_strategy=typeguard.CollectionCheckStrategy.ALL_ITEMS)
     except typeguard.TypeCheckError as e:
-        raise ValueError(str(e)) from None # we don't wanna expose the stacktrace from typeguard to be able to replace it with another library if needed
+        # we don't wanna expose the stacktrace from typeguard to be able to replace it with another library if needed
+        raise ValueError(str(e)) from None
+
 
 def change_default_run_params(params: RunParams, **new_defaults: Unpack[RunParams]) -> None:
     check_run_params(**params)
@@ -59,7 +83,8 @@ def change_default_run_params(params: RunParams, **new_defaults: Unpack[RunParam
     for key in new_defaults.keys():
         if params.get(key) is None:
             # It's safe to ignore the TypedDict-related checks here because of the check_run_params() calls
-            params[key] = new_defaults[key] # type: ignore[literal-required]
+            params[key] = new_defaults[key]  # type: ignore[literal-required] # ty: ignore[invalid-key]
+
 
 def force_run_params(params: RunParams, **forced_values: Unpack[RunParams]) -> None:
     check_run_params(**params)
@@ -70,4 +95,4 @@ def force_run_params(params: RunParams, **forced_values: Unpack[RunParams]) -> N
             raise ValueError(f'Trying to override forced keyword parameter {key} is disallowed')
         else:
             # It's safe to ignore the TypedDict-related checks here because of the check_run_params() calls
-            params[key] = forced_values[key] # type: ignore[literal-required]
+            params[key] = forced_values[key]  # type: ignore[literal-required] # ty: ignore[invalid-key]

{fancy_subprocess-2.3 → fancy_subprocess-3.0}/fancy_subprocess/_run_wrappers.py

@@ -9,10 +9,16 @@ from typing import Optional
 
 from typing_extensions import Unpack
 
-from fancy_subprocess._print import Indent, indented_print_factory, PrintFunction, silenced_print
-from fancy_subprocess._run_core import run, RunResult
-from fancy_subprocess._run_param import check_run_params, force_run_params, RunParams
-from fancy_subprocess._utils import oslex_join
+from fancy_subprocess._print import Indent
+from fancy_subprocess._print import PrintFunction
+from fancy_subprocess._print import indented_print_factory
+from fancy_subprocess._print import silenced_print
+from fancy_subprocess._run_core import RunResult
+from fancy_subprocess._run_core import run
+from fancy_subprocess._run_param import RunParams
+from fancy_subprocess._run_param import check_run_params
+from fancy_subprocess._run_param import force_run_params
+
 
 def run_silenced(
     cmd: Sequence[str | Path],
@@ -42,6 +48,7 @@ def run_silenced(
         **forwarded_args,
     )
 
+
 def run_indented(
     cmd: Sequence[str | Path],
     *,