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

{fancy_subprocess-2.4 → fancy_subprocess-3.0}/Justfile

@@ -3,12 +3,14 @@ default:
 
 [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)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fancy-subprocess
-Version: 2.4
+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
@@ -20,10 +20,10 @@ 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
@@ -56,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.

{fancy_subprocess-2.4 → 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.

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

@@ -13,6 +13,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
+import oslex
 from typing_extensions import Unpack
 
 from fancy_subprocess._exit_code import stringify_exit_code
@@ -20,10 +21,12 @@ 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 oslex_join
 from fancy_subprocess._utils import value_or
 
 
@@ -41,7 +44,6 @@ class RunResult:
     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`:
@@ -62,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()
 
@@ -74,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:
@@ -98,14 +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],
     *,
@@ -135,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.
@@ -148,92 +234,28 @@ 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())
+        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:
@@ -242,6 +264,6 @@ def run(
                 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.4 → fancy_subprocess-3.0}/fancy_subprocess/_run_param.py

@@ -5,6 +5,9 @@ __all__ = [
     'check_run_params',
     'EnvOverrides',
     'force_run_params',
+    'MaxOutputSize',
+    'NO_LIMIT',
+    'NoLimit',
     'RunParams',
     'Success',
 ]
@@ -31,6 +34,19 @@ 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]
 
 
@@ -41,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]

{fancy_subprocess-2.4 → fancy_subprocess-3.0}/fancy_subprocess/_utils.py

@@ -2,12 +2,8 @@ __all__ = [
     'value_or',
 ]
 
-from collections.abc import Sequence
-from pathlib import Path
 from typing import TypeVar
 
-import oslex
-
 T = TypeVar('T')
 U = TypeVar('U')
 
@@ -17,7 +13,3 @@ def value_or(value: T | None, default: U) -> T | U:
         return default
     else:
         return value
-
-
-def oslex_join(cmd: Sequence[str | Path]) -> str:
-    return oslex.join([str(arg) for arg in cmd])

{fancy_subprocess-2.4 → fancy_subprocess-3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fancy-subprocess"
-version = "2.4"
+version = "3.0"
 authors = [
     { name="Tamás PEREGI", email="petamas@gmail.com" },
 ]
@@ -28,10 +28,10 @@ license = "MIT"
 license-files = ["LICENSE"]
 dependencies = [
     "ntstatus>=2.0,<3",
-    "oslex>=0.1.3,<2",
+    "oslex>=2.0,<3",
     "pathext>=1.5,<2",
-    "typeguard>=4.4.2,<5",
-    "typing_extensions>=4.14,<5",
+    "typeguard>=4.5.2,<5",
+    "typing_extensions>=4.15,<5",
 ]
 
 [project.urls]
@@ -41,6 +41,7 @@ dependencies = [
 [dependency-groups]
 dev = [
     "mypy>=1.14.1,<1.15",
+    "pytest>=8.3.5,<9",
     "ruff>=0.15.12,<0.16",
     "ty>=0.0.34,<0.1",
 ]

fancy_subprocess-3.0/tests/test_runerror_bugs.py

@@ -0,0 +1,38 @@
+import pickle
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import pytest
+
+from fancy_subprocess import RunError
+from fancy_subprocess import RunResult
+
+
+def test_runerror_picklable() -> None:
+    """
+    There are certain exceptions that cannot be pickled, see:
+    - https://github.com/python/cpython/issues/101159 (original issue with long discussion)
+    - https://github.com/python/cpython/issues/44791 (closed issue linking various related issues)
+    - https://github.com/python/cpython/issues/87626 (open issue that actually matches ours)
+    RunError's previous implementation (using @dataclass(kw_only=True)) was like that.
+    This test guards against the class becoming unpicklable again.
+    """
+    original_error = RunError(['notepad.exe'], RunResult(exit_code=0))
+    pickled_error = pickle.loads(pickle.dumps(original_error))
+    assert original_error.cmd == pickled_error.cmd
+    assert original_error.result == pickled_error.result
+
+
+def test_runerror_is_contextlib_contextmanager_compatible() -> None:
+    """
+    On Python 3.11+, RunError's previous implementation (using @dataclass(frozen=True)) caused contextmanager() to raise an exception:
+    > dataclasses.FrozenInstanceError: cannot assign to field '__traceback__'
+    """
+
+    @contextmanager
+    def manager() -> Iterator[int]:
+        yield 3
+
+    with pytest.raises(RunError):
+        with manager() as exit_code:
+            raise RunError(['notepad.exe'], RunResult(exit_code=exit_code))