multiCMD 1.54__tar.gz → 1.56__tar.gz

{multicmd-1.54 → multicmd-1.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multiCMD
-Version: 1.54
+Version: 1.56
 Summary: Run commands simultaneously
 Home-page: https://github.com/yufei-pan/multiCMD
 Author: Yufei Pan
@@ -71,8 +71,8 @@ You can also just drop `multiCMD.py` into your project and import it directly.
 ```bash
 $ mcmd -h
 usage: mcmd [-h] [-p] [-t SECONDS] [-m max_threads] [--sudo] [-q] [-n]
-            [--shell] [-f FILE] [-a FILE] [--summary | --no-summary]
-            [--no-prefix] [--no-color] [--pty | --no-pty] [-V]
+            [--shell] [-e NAME=VALUE] [-f FILE] [-a FILE] [--summary |
+            --no-summary] [--no-prefix] [--no-color] [--pty | --no-pty] [-V]
             [command ...]
 
 Run multiple commands in parallel
@@ -96,6 +96,8 @@ options:
   -n, --dry-run         print each command, quoted, instead of running it
   --shell               run each command through /bin/sh -c ( pipes, ;, > and
                         globs work )
+  -e, --env NAME=VALUE  set NAME to VALUE in the environment of every command
+                        ( repeatable ); NAME alone removes it
   -f, --file FILE       read commands from FILE, one per line ( - for stdin;
                         blank lines and # comments are skipped )
   -a, --arg-file FILE   run each command template once per line of FILE, with
@@ -293,10 +295,47 @@ multiCMD.run_commands(cmds, max_threads=8, color=False)           # never color
 multiCMD.run_command(["python3", "train.py"], pty=True)           # live output, stderr merged
 ```
 
+### Environment per call
+
+```python
+multiCMD.run_command(["xfs_info", "/data"], extra_env={"LC_ALL": "C"})      # add / override variables
+multiCMD.run_command(["env"], extra_env={"HTTP_PROXY": None})               # None removes one
+multiCMD.run_command(["env"], env={"PATH": "/usr/bin", "HOME": "/tmp"})     # the whole environment, as subprocess's env
+```
+
+`env` is the whole environment of the command, as `subprocess`'s `env` ( names and values
+are `str`; on POSIX `bytes` and `os.PathLike` work too ). `extra_env` is applied on top of the
+inherited environment, or of `env` when both are given; a `None` value removes the variable,
+and an empty `extra_env` is the same as none. "Inherited" is `os.environ` as the process holds
+it when the command starts: a variable set behind Python's back ( `os.putenv`, `os.unsetenv`, a
+C library's `setenv` ) reaches commands started without `env` / `extra_env`, not the ones
+given them. An inherited variable with an empty name ( a corrupt `environ` entry such as `=x` ) is left out of the environment of a command given `env` / `extra_env`, and out of an `env` copied from `os.environ`; an empty name in `extra_env` is a `ValueError`. Names are case-insensitive on Windows, so `extra_env={"Path": ...}` replaces `PATH`
+there. On POSIX a command is looked up in the `PATH` of the environment it gets, on every Python
+version; Windows searches the calling process's `PATH` whatever the command's environment says.
+Before Python 3.11 the launcher starts in this process's environment and is handed the command's on
+top of it, so the two together must fit the system's argument limit ( `getconf ARG_MAX`; 2 MiB on Linux
+with the default stack, 128 KiB for one string: before Python 3.11 an entry travels as `_MULTICMD_ENV_<i>=NAME=VALUE`, 15 bytes
+plus the digits of `i` more than its `NAME=VALUE` ); one that does not fit fails with return
+code 126, `Argument list too long`, on every Python.
+On Python 3.7-3.10 a command started with
+neither `env` nor `extra_env` still gets the `LC_CTYPE=C.UTF-8` that interpreter's locale coercion
+sets in a C locale ( as before ); a command given one of them gets exactly the environment described.
+Both are per command: they never change `os.environ` and never reach another command, so
+concurrent commands each see their own. `AsyncExecutor` takes them too, as defaults a call
+overrides. `sudo` resets the environment by default, so with `use_sudo` they may not reach the
+command. On the command line: `mcmd -e LC_ALL=C -e UNSET_ME "cmd"`; `-n` shows them as
+`env LC_ALL=C cmd` ( `env -i ...` for a whole environment ).
+
 `raise_error=True` raises `multiCMD.CommandError`; its `.tasks` holds the failed `Task`
 objects and its message lists each one with its return code and last error line.
 `Task` also records `start_time`, `end_time` and `duration`. With `dry_run=True` nothing
 runs; each command is printed once, quoted so it can be pasted into a shell.
+A command that is not found (return code 127), cannot be executed (126) or that multiCMD
+itself could not run (-1, `task._error`) says why in its `task.stderr`; multiCMD also
+prints a line saying so on stderr, unless `quiet=True`. Before Python 3.11 the exec of a
+command given by its path, or of a file found in `PATH` that may not be executed, happens in
+the launcher's process: it exits 127 / 126 with the reason as the command's own stderr, which
+then shows with the command's output ( unless quiet ) instead of as a line of multiCMD's own.
 
 ### Asynchronous / fire-and-forget
 
@@ -309,7 +348,8 @@ tasks = multiCMD.run_commands(
     max_threads=2, quiet=True,
     wait_for_return=False, return_object=True,
 )
-# tasks[i].returncode is None until that command completes
+# tasks[i].returncode is None until that command completes; tasks[i].thread.join(timeout)
+# waits for one command ( a command whose thread could not start fails with -1, its thread already done )
 
 # Later, block until everything launched this way has finished:
 multiCMD.join_threads()
@@ -336,7 +376,8 @@ executor holds at most one thread per permit plus the dispatcher, however many
 commands are queued. A command's `task.thread` is `None` until it starts, and goes
 back to `None` once it has finished and the executor has joined its thread, so a
 large batch does not keep a `Thread` object per finished command. `stop()` skips
-commands that have not started yet.
+commands that have not started yet, and so does a Ctrl-C ( or an error ) that interrupts
+`run_command(s)`, for that call's commands.
 
 ### Range expansion from Python
 
@@ -370,21 +411,37 @@ default, in the API and on the command line) disables it.
 
 ## Process groups and signals
 
-Every command runs in a process group of its own, so a timeout, `stop()` or Ctrl-C
-reaches the whole process tree, not just the first process. On Python 3.11+ this uses
-`Popen(process_group=0)`; older Pythons start the command through a tiny exec wrapper.
-Commands that try to read the terminal (a password prompt, for example) fail at once
-instead of hanging. The library does this by blocking SIGTTIN/SIGTTOU for the command,
-which covers commands started directly or through bash; `mcmd` also ignores them, which
-every command inherits through any shell.
-
-Because the commands are not in your program's process group, signals sent to that
-group do not reach them. multiCMD handles this for you: a call waiting on the main
-thread that gets Ctrl-C stops its commands before re-raising, `mcmd` stops them on
-SIGTERM / SIGHUP (unless it was started with them ignored, as under `nohup`), and any
-commands still running when the interpreter exits are killed. A program that handles
-SIGTERM itself, or that runs multiCMD from its own threads (where Ctrl-C never
-arrives), can call `multiCMD.kill_all()` from its handler.
+Every command runs in a process group of its own, so a timeout, `stop()` or Ctrl-C reaches the
+whole process tree, not just the first process. On Python 3.11+ this uses `Popen(process_group=0)`;
+older Pythons start the command through a tiny exec wrapper. A command that reads the terminal (a
+password prompt, for example) fails at once instead of hanging: multiCMD blocks SIGTTIN/SIGTTOU for
+it, and `mcmd` also ignores them, which every command inherits through any shell.
+
+Signals sent to your program's group do not reach the commands, so multiCMD stops them itself. One
+Ctrl-C (or a SIGTERM handler's `sys.exit()`) in a call waiting on the main thread, `join_threads()`
+and `AsyncExecutor.wait()` included, stops every command, skips the queued ones and
+re-raises, giving them up to 5 s to exit; a second Ctrl-C ends that wait at once. `mcmd` stops its
+commands on SIGTERM / SIGHUP (unless started with them ignored, as under `nohup`). At interpreter exit
+the commands still running are killed, and a command queued on one of multiCMD's threads fails (-1,
+"not started: the interpreter is exiting") instead of outliving the program; one run from an `atexit`
+handler after that, on the main thread, runs as usual. A program that handles SIGTERM itself, or runs
+multiCMD from its own threads (where Ctrl-C never arrives), can call `multiCMD.kill_all()` from its
+handler. A command not seen to exit a second after SIGKILL is no longer tracked; its pid is named on
+stderr, unless quiet.
+
+multiCMD never touches SIGINT's handler (`mcmd` sets its own SIGTERM / SIGHUP handlers, nothing
+else). What your handler raises while a call waits for its commands is handled as a Ctrl-C.
+
+A command is registered from the moment `Popen` returns it: a Ctrl-C that Python raises inside
+`Popen` as a serial run starts a command (some 50-70 µs each) can leave it running, unknown to
+`kill_all()`. Two Ctrl-Cs microseconds apart can leave a command running, still registered, until
+`kill_all()` or the exit stops it. On Python 3.6-3.9, which raise a Ctrl-C at nearly any instruction,
+even one at a few points between the steps of a run can leave its command registered but not signalled.
+On Python 3.6-3.9 and 3.14 a Ctrl-C at the wrong instruction of a `with` on a lock can leave it held: one of
+`threading`'s can hang the program as its threads end (CPython's own), and one of multiCMD's (an
+`AsyncExecutor`'s queue, the live output) hangs that executor, or the next call that is not quiet, if the
+program keeps going.
+These and the other known limits are in [docs/limitations.md](docs/limitations.md).
 
 ## Key functions and objects
 
@@ -392,12 +449,13 @@ arrives), can call `multiCMD.kill_all()` from its handler.
 run_command(command, timeout=0, max_threads=1, quiet=False, dry_run=False,
             with_stdErr=False, return_code_only=False, return_object=False,
             wait_for_return=True, sem=None, use_sudo=..., raise_error=False,
-            prefix=False, color=None, pty=False, shell=False)
+            prefix=False, color=None, pty=False, shell=False, env=None, extra_env=None)
 
 run_commands(commands, timeout=0, max_threads=1, quiet=False, dry_run=False,
              with_stdErr=False, return_code_only=False, return_object=False,
              parse=False, wait_for_return=True, sem=None, use_sudo=...,
-             raise_error=False, prefix=False, color=None, pty=False, shell=False)
+             raise_error=False, prefix=False, color=None, pty=False, shell=False,
+             env=None, extra_env=None)
 
 ping(hosts, timeout=1, max_threads=0, ...)   # returns True/False reachability
 join_threads(threads=..., timeout=None)      # join fire-and-forget threads
@@ -406,7 +464,8 @@ set_sudo(use_sudo)                           # enable/disable sudo globally
 
 class Task:          # command, returncode, stdout, stderr, start_time, end_time, duration
 class CommandError:  # raised by raise_error=True; .tasks = the failed Tasks
-class AsyncExecutor: # run_command(s), wait, join, stop, cleanup, get_results, get_return_codes
+class AsyncExecutor: # run_command(s), wait, join, stop, cleanup, get_results, get_return_codes;
+                     # takes the options above, env / extra_env as defaults a call overrides
 ```
 
 The module also bundles a few terminal/formatting helpers used internally and
@@ -432,6 +491,51 @@ pytest -m "not slow"   # skip intentional sleep-heavy cases
 
 `test_expand_ranges_perf.py` is a manual performance microbenchmark and is not collected by pytest.
 
+## Upgrading to 1.56 from 1.55
+
+- Fix: a command that times out while it redraws a `\r` progress line on stderr keeps its `Timeout!`
+  line; 1.55 could replace it with the progress line, leaving return code 124 without the marker.
+- Simpler interrupt handling, some 700 lines lighter. One Ctrl-C still stops every command.
+  What changes is a few rare corners, each in [docs/limitations.md](docs/limitations.md):
+  - two Ctrl-Cs microseconds apart can leave a command running, still registered, until `kill_all()`
+    or the exit stops it; 1.55 stopped it at once;
+  - a Ctrl-C can lose a serial run's starting command anywhere inside `Popen` (about 51 µs per start on
+    Python 3.14), not only inside the fork (about 41 µs);
+  - a Ctrl-C that leaves `Popen.poll()`'s lock held makes that command's stop about 2 s slower;
+  - an ordinary exception your own signal handler raises as a serial run starts a command is recorded as
+    a start failure (-1) and not raised, as in 1.54;
+  - `join_threads()` on another thread can return before a batch that is still starting.
+- `__running_threads_lock` and `_live_procs_lock`, unused since 1.55 and kept only for code that imported
+  them, are gone.
+
+## Upgrading to 1.55 from 1.54
+
+- New: a per-call environment. `env=` (the whole environment, as `subprocess`'s) and `extra_env=`
+  (added on top; a `None` value removes a variable) on `run_command`, `run_commands` and
+  `AsyncExecutor` (constructor defaults, overridden per call), and `mcmd -e NAME=VALUE` / `-e NAME`;
+  see [Environment per call](#environment-per-call).
+- `quiet=True` now hides the lines about a command that could not be run: `Command path not found`
+  (127), `Command cannot be executed` (126) and the error of a command multiCMD could not run (-1),
+  which 1.54 printed even when quiet, partly on stdout. The reasons are still in `task.stderr`. Warnings
+  about the run's setup (sudo not found or not usable, no pty) still print.
+- A Ctrl-C in `join_threads()` stops the commands it waits for, skips the ones still queued, waits up
+  to 5 s for them and re-raises; 1.54 re-raised and left them running. A Ctrl-C that interrupts
+  `AsyncExecutor.run_command(s)` skips that call's commands.
+- A SIGTERM handler's `sys.exit()`, or whatever your own signal handler raises while a call waits for
+  its commands, stops them and records them as stopped before it is raised on, as a Ctrl-C does; 1.54
+  did that only for `KeyboardInterrupt`.
+- A Ctrl-C while a command starts, times out or is stopped, or while multiCMD reads the output that
+  a finished command's background processes still hold open, no longer leaves the command or those
+  processes running unknown to `kill_all()` and the exit hook, or known to them but never signalled.
+  A second Ctrl-C ends the wait for the commands at once; each is still sent SIGTERM, and `kill_all()`
+  and the exit hook finish the kill. The limits below are the exceptions.
+- Once the interpreter exits, a command queued on one of multiCMD's threads that has not started fails
+  with -1 ("not started: the interpreter is exiting") instead of starting and outliving the program.
+- A command not seen to exit a second after SIGKILL is no longer tracked, so later `kill_all()` calls and the
+  exit do not wait for it again; its pid is named on stderr, unless quiet.
+- Known limits: see [Process groups and signals](#process-groups-and-signals) and
+  [docs/limitations.md](docs/limitations.md).
+
 ## License
 
 GPLv3+ — see the package metadata. Authored by Yufei Pan (<pan@zopyr.us>).

{multicmd-1.54 → multicmd-1.56}/README.md

@@ -45,8 +45,8 @@ You can also just drop `multiCMD.py` into your project and import it directly.
 ```bash
 $ mcmd -h
 usage: mcmd [-h] [-p] [-t SECONDS] [-m max_threads] [--sudo] [-q] [-n]
-            [--shell] [-f FILE] [-a FILE] [--summary | --no-summary]
-            [--no-prefix] [--no-color] [--pty | --no-pty] [-V]
+            [--shell] [-e NAME=VALUE] [-f FILE] [-a FILE] [--summary |
+            --no-summary] [--no-prefix] [--no-color] [--pty | --no-pty] [-V]
             [command ...]
 
 Run multiple commands in parallel
@@ -70,6 +70,8 @@ options:
   -n, --dry-run         print each command, quoted, instead of running it
   --shell               run each command through /bin/sh -c ( pipes, ;, > and
                         globs work )
+  -e, --env NAME=VALUE  set NAME to VALUE in the environment of every command
+                        ( repeatable ); NAME alone removes it
   -f, --file FILE       read commands from FILE, one per line ( - for stdin;
                         blank lines and # comments are skipped )
   -a, --arg-file FILE   run each command template once per line of FILE, with
@@ -267,10 +269,47 @@ multiCMD.run_commands(cmds, max_threads=8, color=False)           # never color
 multiCMD.run_command(["python3", "train.py"], pty=True)           # live output, stderr merged
 ```
 
+### Environment per call
+
+```python
+multiCMD.run_command(["xfs_info", "/data"], extra_env={"LC_ALL": "C"})      # add / override variables
+multiCMD.run_command(["env"], extra_env={"HTTP_PROXY": None})               # None removes one
+multiCMD.run_command(["env"], env={"PATH": "/usr/bin", "HOME": "/tmp"})     # the whole environment, as subprocess's env
+```
+
+`env` is the whole environment of the command, as `subprocess`'s `env` ( names and values
+are `str`; on POSIX `bytes` and `os.PathLike` work too ). `extra_env` is applied on top of the
+inherited environment, or of `env` when both are given; a `None` value removes the variable,
+and an empty `extra_env` is the same as none. "Inherited" is `os.environ` as the process holds
+it when the command starts: a variable set behind Python's back ( `os.putenv`, `os.unsetenv`, a
+C library's `setenv` ) reaches commands started without `env` / `extra_env`, not the ones
+given them. An inherited variable with an empty name ( a corrupt `environ` entry such as `=x` ) is left out of the environment of a command given `env` / `extra_env`, and out of an `env` copied from `os.environ`; an empty name in `extra_env` is a `ValueError`. Names are case-insensitive on Windows, so `extra_env={"Path": ...}` replaces `PATH`
+there. On POSIX a command is looked up in the `PATH` of the environment it gets, on every Python
+version; Windows searches the calling process's `PATH` whatever the command's environment says.
+Before Python 3.11 the launcher starts in this process's environment and is handed the command's on
+top of it, so the two together must fit the system's argument limit ( `getconf ARG_MAX`; 2 MiB on Linux
+with the default stack, 128 KiB for one string: before Python 3.11 an entry travels as `_MULTICMD_ENV_<i>=NAME=VALUE`, 15 bytes
+plus the digits of `i` more than its `NAME=VALUE` ); one that does not fit fails with return
+code 126, `Argument list too long`, on every Python.
+On Python 3.7-3.10 a command started with
+neither `env` nor `extra_env` still gets the `LC_CTYPE=C.UTF-8` that interpreter's locale coercion
+sets in a C locale ( as before ); a command given one of them gets exactly the environment described.
+Both are per command: they never change `os.environ` and never reach another command, so
+concurrent commands each see their own. `AsyncExecutor` takes them too, as defaults a call
+overrides. `sudo` resets the environment by default, so with `use_sudo` they may not reach the
+command. On the command line: `mcmd -e LC_ALL=C -e UNSET_ME "cmd"`; `-n` shows them as
+`env LC_ALL=C cmd` ( `env -i ...` for a whole environment ).
+
 `raise_error=True` raises `multiCMD.CommandError`; its `.tasks` holds the failed `Task`
 objects and its message lists each one with its return code and last error line.
 `Task` also records `start_time`, `end_time` and `duration`. With `dry_run=True` nothing
 runs; each command is printed once, quoted so it can be pasted into a shell.
+A command that is not found (return code 127), cannot be executed (126) or that multiCMD
+itself could not run (-1, `task._error`) says why in its `task.stderr`; multiCMD also
+prints a line saying so on stderr, unless `quiet=True`. Before Python 3.11 the exec of a
+command given by its path, or of a file found in `PATH` that may not be executed, happens in
+the launcher's process: it exits 127 / 126 with the reason as the command's own stderr, which
+then shows with the command's output ( unless quiet ) instead of as a line of multiCMD's own.
 
 ### Asynchronous / fire-and-forget
 
@@ -283,7 +322,8 @@ tasks = multiCMD.run_commands(
     max_threads=2, quiet=True,
     wait_for_return=False, return_object=True,
 )
-# tasks[i].returncode is None until that command completes
+# tasks[i].returncode is None until that command completes; tasks[i].thread.join(timeout)
+# waits for one command ( a command whose thread could not start fails with -1, its thread already done )
 
 # Later, block until everything launched this way has finished:
 multiCMD.join_threads()
@@ -310,7 +350,8 @@ executor holds at most one thread per permit plus the dispatcher, however many
 commands are queued. A command's `task.thread` is `None` until it starts, and goes
 back to `None` once it has finished and the executor has joined its thread, so a
 large batch does not keep a `Thread` object per finished command. `stop()` skips
-commands that have not started yet.
+commands that have not started yet, and so does a Ctrl-C ( or an error ) that interrupts
+`run_command(s)`, for that call's commands.
 
 ### Range expansion from Python
 
@@ -344,21 +385,37 @@ default, in the API and on the command line) disables it.
 
 ## Process groups and signals
 
-Every command runs in a process group of its own, so a timeout, `stop()` or Ctrl-C
-reaches the whole process tree, not just the first process. On Python 3.11+ this uses
-`Popen(process_group=0)`; older Pythons start the command through a tiny exec wrapper.
-Commands that try to read the terminal (a password prompt, for example) fail at once
-instead of hanging. The library does this by blocking SIGTTIN/SIGTTOU for the command,
-which covers commands started directly or through bash; `mcmd` also ignores them, which
-every command inherits through any shell.
-
-Because the commands are not in your program's process group, signals sent to that
-group do not reach them. multiCMD handles this for you: a call waiting on the main
-thread that gets Ctrl-C stops its commands before re-raising, `mcmd` stops them on
-SIGTERM / SIGHUP (unless it was started with them ignored, as under `nohup`), and any
-commands still running when the interpreter exits are killed. A program that handles
-SIGTERM itself, or that runs multiCMD from its own threads (where Ctrl-C never
-arrives), can call `multiCMD.kill_all()` from its handler.
+Every command runs in a process group of its own, so a timeout, `stop()` or Ctrl-C reaches the
+whole process tree, not just the first process. On Python 3.11+ this uses `Popen(process_group=0)`;
+older Pythons start the command through a tiny exec wrapper. A command that reads the terminal (a
+password prompt, for example) fails at once instead of hanging: multiCMD blocks SIGTTIN/SIGTTOU for
+it, and `mcmd` also ignores them, which every command inherits through any shell.
+
+Signals sent to your program's group do not reach the commands, so multiCMD stops them itself. One
+Ctrl-C (or a SIGTERM handler's `sys.exit()`) in a call waiting on the main thread, `join_threads()`
+and `AsyncExecutor.wait()` included, stops every command, skips the queued ones and
+re-raises, giving them up to 5 s to exit; a second Ctrl-C ends that wait at once. `mcmd` stops its
+commands on SIGTERM / SIGHUP (unless started with them ignored, as under `nohup`). At interpreter exit
+the commands still running are killed, and a command queued on one of multiCMD's threads fails (-1,
+"not started: the interpreter is exiting") instead of outliving the program; one run from an `atexit`
+handler after that, on the main thread, runs as usual. A program that handles SIGTERM itself, or runs
+multiCMD from its own threads (where Ctrl-C never arrives), can call `multiCMD.kill_all()` from its
+handler. A command not seen to exit a second after SIGKILL is no longer tracked; its pid is named on
+stderr, unless quiet.
+
+multiCMD never touches SIGINT's handler (`mcmd` sets its own SIGTERM / SIGHUP handlers, nothing
+else). What your handler raises while a call waits for its commands is handled as a Ctrl-C.
+
+A command is registered from the moment `Popen` returns it: a Ctrl-C that Python raises inside
+`Popen` as a serial run starts a command (some 50-70 µs each) can leave it running, unknown to
+`kill_all()`. Two Ctrl-Cs microseconds apart can leave a command running, still registered, until
+`kill_all()` or the exit stops it. On Python 3.6-3.9, which raise a Ctrl-C at nearly any instruction,
+even one at a few points between the steps of a run can leave its command registered but not signalled.
+On Python 3.6-3.9 and 3.14 a Ctrl-C at the wrong instruction of a `with` on a lock can leave it held: one of
+`threading`'s can hang the program as its threads end (CPython's own), and one of multiCMD's (an
+`AsyncExecutor`'s queue, the live output) hangs that executor, or the next call that is not quiet, if the
+program keeps going.
+These and the other known limits are in [docs/limitations.md](docs/limitations.md).
 
 ## Key functions and objects
 
@@ -366,12 +423,13 @@ arrives), can call `multiCMD.kill_all()` from its handler.
 run_command(command, timeout=0, max_threads=1, quiet=False, dry_run=False,
             with_stdErr=False, return_code_only=False, return_object=False,
             wait_for_return=True, sem=None, use_sudo=..., raise_error=False,
-            prefix=False, color=None, pty=False, shell=False)
+            prefix=False, color=None, pty=False, shell=False, env=None, extra_env=None)
 
 run_commands(commands, timeout=0, max_threads=1, quiet=False, dry_run=False,
              with_stdErr=False, return_code_only=False, return_object=False,
              parse=False, wait_for_return=True, sem=None, use_sudo=...,
-             raise_error=False, prefix=False, color=None, pty=False, shell=False)
+             raise_error=False, prefix=False, color=None, pty=False, shell=False,
+             env=None, extra_env=None)
 
 ping(hosts, timeout=1, max_threads=0, ...)   # returns True/False reachability
 join_threads(threads=..., timeout=None)      # join fire-and-forget threads
@@ -380,7 +438,8 @@ set_sudo(use_sudo)                           # enable/disable sudo globally
 
 class Task:          # command, returncode, stdout, stderr, start_time, end_time, duration
 class CommandError:  # raised by raise_error=True; .tasks = the failed Tasks
-class AsyncExecutor: # run_command(s), wait, join, stop, cleanup, get_results, get_return_codes
+class AsyncExecutor: # run_command(s), wait, join, stop, cleanup, get_results, get_return_codes;
+                     # takes the options above, env / extra_env as defaults a call overrides
 ```
 
 The module also bundles a few terminal/formatting helpers used internally and
@@ -406,6 +465,51 @@ pytest -m "not slow"   # skip intentional sleep-heavy cases
 
 `test_expand_ranges_perf.py` is a manual performance microbenchmark and is not collected by pytest.
 
+## Upgrading to 1.56 from 1.55
+
+- Fix: a command that times out while it redraws a `\r` progress line on stderr keeps its `Timeout!`
+  line; 1.55 could replace it with the progress line, leaving return code 124 without the marker.
+- Simpler interrupt handling, some 700 lines lighter. One Ctrl-C still stops every command.
+  What changes is a few rare corners, each in [docs/limitations.md](docs/limitations.md):
+  - two Ctrl-Cs microseconds apart can leave a command running, still registered, until `kill_all()`
+    or the exit stops it; 1.55 stopped it at once;
+  - a Ctrl-C can lose a serial run's starting command anywhere inside `Popen` (about 51 µs per start on
+    Python 3.14), not only inside the fork (about 41 µs);
+  - a Ctrl-C that leaves `Popen.poll()`'s lock held makes that command's stop about 2 s slower;
+  - an ordinary exception your own signal handler raises as a serial run starts a command is recorded as
+    a start failure (-1) and not raised, as in 1.54;
+  - `join_threads()` on another thread can return before a batch that is still starting.
+- `__running_threads_lock` and `_live_procs_lock`, unused since 1.55 and kept only for code that imported
+  them, are gone.
+
+## Upgrading to 1.55 from 1.54
+
+- New: a per-call environment. `env=` (the whole environment, as `subprocess`'s) and `extra_env=`
+  (added on top; a `None` value removes a variable) on `run_command`, `run_commands` and
+  `AsyncExecutor` (constructor defaults, overridden per call), and `mcmd -e NAME=VALUE` / `-e NAME`;
+  see [Environment per call](#environment-per-call).
+- `quiet=True` now hides the lines about a command that could not be run: `Command path not found`
+  (127), `Command cannot be executed` (126) and the error of a command multiCMD could not run (-1),
+  which 1.54 printed even when quiet, partly on stdout. The reasons are still in `task.stderr`. Warnings
+  about the run's setup (sudo not found or not usable, no pty) still print.
+- A Ctrl-C in `join_threads()` stops the commands it waits for, skips the ones still queued, waits up
+  to 5 s for them and re-raises; 1.54 re-raised and left them running. A Ctrl-C that interrupts
+  `AsyncExecutor.run_command(s)` skips that call's commands.
+- A SIGTERM handler's `sys.exit()`, or whatever your own signal handler raises while a call waits for
+  its commands, stops them and records them as stopped before it is raised on, as a Ctrl-C does; 1.54
+  did that only for `KeyboardInterrupt`.
+- A Ctrl-C while a command starts, times out or is stopped, or while multiCMD reads the output that
+  a finished command's background processes still hold open, no longer leaves the command or those
+  processes running unknown to `kill_all()` and the exit hook, or known to them but never signalled.
+  A second Ctrl-C ends the wait for the commands at once; each is still sent SIGTERM, and `kill_all()`
+  and the exit hook finish the kill. The limits below are the exceptions.
+- Once the interpreter exits, a command queued on one of multiCMD's threads that has not started fails
+  with -1 ("not started: the interpreter is exiting") instead of starting and outliving the program.
+- A command not seen to exit a second after SIGKILL is no longer tracked, so later `kill_all()` calls and the
+  exit do not wait for it again; its pid is named on stderr, unless quiet.
+- Known limits: see [Process groups and signals](#process-groups-and-signals) and
+  [docs/limitations.md](docs/limitations.md).
+
 ## License
 
 GPLv3+ — see the package metadata. Authored by Yufei Pan (<pan@zopyr.us>).