multiCMD 1.48__tar.gz → 1.50__tar.gz

{multicmd-1.48 → multicmd-1.50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multiCMD
-Version: 1.48
+Version: 1.50
 Summary: Run commands simultaneously
 Home-page: https://github.com/yufei-pan/multiCMD
 Author: Yufei Pan
@@ -206,6 +206,12 @@ print(ex.get_return_codes())
 print(ex.get_results())
 ```
 
+`run_command(s)` returns right away and queues the commands. One dispatcher thread
+starts each queued command only after taking a permit from the semaphore, so the
+executor holds at most one thread per permit plus the dispatcher, however many
+commands are queued. A queued command's `task.thread` is `None` until it starts,
+and `stop()` skips commands that have not started yet.
+
 ### Range expansion from Python
 
 ```python
@@ -268,9 +274,12 @@ Run the test suite with [pytest](https://pytest.org):
 
 ```bash
 pip install pytest
-pytest
+pytest                 # full suite under tests/
+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.
+
 ## License
 
 GPLv3+ — see the package metadata. Authored by Yufei Pan (<pan@zopyr.us>).

{multicmd-1.48 → multicmd-1.50}/README.md

@@ -180,6 +180,12 @@ print(ex.get_return_codes())
 print(ex.get_results())
 ```
 
+`run_command(s)` returns right away and queues the commands. One dispatcher thread
+starts each queued command only after taking a permit from the semaphore, so the
+executor holds at most one thread per permit plus the dispatcher, however many
+commands are queued. A queued command's `task.thread` is `None` until it starts,
+and `stop()` skips commands that have not started yet.
+
 ### Range expansion from Python
 
 ```python
@@ -242,9 +248,12 @@ Run the test suite with [pytest](https://pytest.org):
 
 ```bash
 pip install pytest
-pytest
+pytest                 # full suite under tests/
+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.
+
 ## License
 
 GPLv3+ — see the package metadata. Authored by Yufei Pan (<pan@zopyr.us>).

{multicmd-1.48 → multicmd-1.50}/multiCMD.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multiCMD
-Version: 1.48
+Version: 1.50
 Summary: Run commands simultaneously
 Home-page: https://github.com/yufei-pan/multiCMD
 Author: Yufei Pan
@@ -206,6 +206,12 @@ print(ex.get_return_codes())
 print(ex.get_results())
 ```
 
+`run_command(s)` returns right away and queues the commands. One dispatcher thread
+starts each queued command only after taking a permit from the semaphore, so the
+executor holds at most one thread per permit plus the dispatcher, however many
+commands are queued. A queued command's `task.thread` is `None` until it starts,
+and `stop()` skips commands that have not started yet.
+
 ### Range expansion from Python
 
 ```python
@@ -268,9 +274,12 @@ Run the test suite with [pytest](https://pytest.org):
 
 ```bash
 pip install pytest
-pytest
+pytest                 # full suite under tests/
+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.
+
 ## License
 
 GPLv3+ — see the package metadata. Authored by Yufei Pan (<pan@zopyr.us>).

multicmd-1.50/multiCMD.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+multiCMD.py
+setup.py
+multiCMD.egg-info/PKG-INFO
+multiCMD.egg-info/SOURCES.txt
+multiCMD.egg-info/dependency_links.txt
+multiCMD.egg-info/entry_points.txt
+multiCMD.egg-info/requires.txt
+multiCMD.egg-info/top_level.txt
+tests/test_async_executor.py
+tests/test_cli.py
+tests/test_expand_ranges.py
+tests/test_helpers.py
+tests/test_ping.py
+tests/test_regressions.py
+tests/test_run_command.py
+tests/test_run_commands.py
+tests/test_sudo.py
+tests/test_task.py

{multicmd-1.48 → multicmd-1.50}/multiCMD.py

@@ -7,6 +7,7 @@
 # ///
 #%% imports
 import argparse
+import collections
 import itertools
 import math
 import os
@@ -22,10 +23,14 @@ import time
 from pprint import pformat
 
 #%% global vars
-version = '1.48'
+version = '1.50'
 __version__ = version
-COMMIT_DATE = '2026-06-04'
+COMMIT_DATE = '2026-10-09'
+# fire-and-forget threads (run_commands with wait_for_return=False) that join_threads() waits on
 __running_threads = set()
+__running_threads_lock = threading.Lock()
+# fire-and-forget threads append themselves here when done, so they get joined and dropped from __running_threads
+__finished_threads = collections.deque()
 __variables = {}
 
 # immutable helpers compiled once at import time
@@ -69,10 +74,30 @@ stop={self.stop!r})"""
 	def is_alive(self):
 		return self.thread is not None and self.thread.is_alive()
 
+class _HeldPermit:
+	'''
+	Semaphore stand-in for a command whose permit the dispatcher already holds ( internal )
+	Entering is free, exiting releases the permit.
+	'''
+	def __init__(self, semaphore):
+		self.semaphore = semaphore
+
+	def __enter__(self):
+		return self
+
+	def __exit__(self, *exc_info):
+		self.semaphore.release()
+		return False
+
 class AsyncExecutor:
 	def __init__(self, max_threads=1,semaphore=...,timeout=0,quiet=True,dry_run=False,parse=False):
 		'''
 		AsyncExecutor class to run commands in parallel asynchronously
+
+		Commands are queued and a dispatcher thread starts each one only after taking a permit
+		from the semaphore, so the executor holds at most one thread per permit it uses plus the
+		dispatcher, however many commands are queued. A queued command's task.thread stays None
+		until it starts.
 		@params:
 			max_threads: The maximum number of threads to use ( int ) ( Note: if passing semaphore, this likely will be ignored )
 			semaphore: The semaphore to use for threading ( threading.Semaphore )
@@ -85,13 +110,19 @@ class AsyncExecutor:
 		if semaphore is ...:
 			semaphore = threading.Semaphore(max_threads)
 		self.semaphore = semaphore
-		self.runningThreads = []
 		self.tasks = []
 		self.timeout = timeout
 		self.quiet = quiet
 		self.dry_run = dry_run
 		self.parse = parse
-		self.__lastNotJoined = 0
+		self._lock = threading.Lock()
+		# (task, sem, timeout, quiet, dry_run) waiting for a permit
+		self._queue = collections.deque()
+		self._dispatching = False
+		# started threads not yet joined, in start order ( dict used as an ordered set )
+		self._threads = {}
+		# threads append themselves here when done, so _reap() joins them without scanning
+		self._finished = collections.deque()
 
 	def __iter__(self):
 		return iter(self.tasks)
@@ -107,10 +138,82 @@ class AsyncExecutor:
 	
 	def __bool__(self):
 		return bool(self.tasks)
-	
+
+	@property
+	def runningThreads(self):
+		'''
+		The threads that have not finished yet: the dispatcher while commands are queued, and the started commands
+		@returns:
+			list[threading.Thread]: The unfinished threads
+		'''
+		self._reap()
+		with self._lock:
+			return list(self._threads)
+
+	def _reap(self):
+		'''
+		Join the threads that finished and forget them ( internal )
+		Joining releases the thread's stack: a finished thread that is still referenced but never
+		joined keeps its stack mapped.
+		'''
+		while True:
+			try:
+				thread = self._finished.popleft()
+			except IndexError:
+				return
+			thread.join()
+			with self._lock:
+				self._threads.pop(thread, None)
+
+	def _start_thread(self, target, args):
+		thread = threading.Thread(target=target, args=args, daemon=True)
+		# registered before it starts, so it is tracked before it can report itself finished
+		with self._lock:
+			self._threads[thread] = None
+			try:
+				thread.start()
+			except BaseException:
+				# never started: it would never report itself finished
+				del self._threads[thread]
+				raise
+		return thread
+
+	def _dispatch(self):
+		'''
+		Start queued commands one permit at a time ( internal )
+		'''
+		try:
+			while True:
+				with self._lock:
+					if not self._queue:
+						self._dispatching = False
+						break
+					task, sem, timeout, quiet, dry_run = self._queue.popleft()
+				# wait for a permit, but give up on a command that gets stopped meanwhile
+				acquired = False
+				while not task.stop and not acquired:
+					acquired = sem.acquire(timeout=0.1)
+				if task.stop:
+					if acquired:
+						sem.release()
+					continue
+				self._reap()
+				try:
+					task.thread = self._start_thread(_run_executor_task, (task, _HeldPermit(sem), timeout, quiet, dry_run, self._finished))
+				except BaseException:
+					sem.release()
+					raise
+		except BaseException:
+			# let the next run_commands() start a new dispatcher for what is still queued
+			with self._lock:
+				self._dispatching = False
+			raise
+		finally:
+			self._finished.append(threading.current_thread())
+
 	def run_commands(self, commands, timeout=...,max_threads=...,quiet=...,dry_run=...,parse = ...,sem = ...):
 		'''
-		Run multiple commands in parallel asynchronously
+		Run multiple commands in parallel asynchronously. Returns right away, the commands are queued
 		@params:
 			commands: A list of commands to run ( list[str] | list[list[str]] )
 			timeout: The timeout for each command to override the object default
@@ -134,19 +237,26 @@ class AsyncExecutor:
 			parse = self.parse
 		if sem is ...:
 			sem = self.semaphore
-		if len(self.runningThreads) > 130000:
-			self.wait(timeout=0)
-			if len(self.runningThreads) > 130000:
-				print('The amount of running threads approching cpython limit of 130704. Waiting until some available.')
-				while len(self.runningThreads) > 120000:
-					self.wait(timeout=1)
-		elif len(self.runningThreads) + self.__lastNotJoined > 1000:
-			self.wait(timeout=0)
-			self.__lastNotJoined = len(self.runningThreads)
-		taskObjects: list[Task] = run_commands(commands,timeout=timeout,max_threads=max_threads,quiet=quiet,dry_run=dry_run,with_stdErr=False,
-				 return_code_only=False,return_object=True, parse = parse, wait_for_return = False, sem = sem)
-		self.tasks.extend(taskObjects)
-		self.runningThreads.extend([task.thread for task in taskObjects])
+		taskObjects, use_sudo = _build_tasks(commands, parse=parse)
+		if not sem:
+			sem = threading.Semaphore(max_threads if max_threads >= 1 else max(len(taskObjects), 1))
+		if use_sudo:
+			_validate_sudo(sem)
+		self._reap()
+		with self._lock:
+			self.tasks.extend(taskObjects)
+			self._queue.extend((task, sem, timeout, quiet, dry_run) for task in taskObjects)
+			start_dispatcher = not self._dispatching and bool(self._queue)
+			if start_dispatcher:
+				# only the dispatcher clears this, under the lock, once it sees the queue empty
+				self._dispatching = True
+		if start_dispatcher:
+			try:
+				self._start_thread(self._dispatch, ())
+			except BaseException:
+				with self._lock:
+					self._dispatching = False
+				raise
 		return taskObjects
 	
 	def run_command(self, command, timeout=...,max_threads=...,quiet=...,dry_run=...,parse = ...,sem = ...):
@@ -169,26 +279,30 @@ class AsyncExecutor:
 		'''
 		Wait for the threads to finish
 		@params:
-			timeout: The timeout for each command to override the object default
-			threads: The threads to join, default to all running threads managed by this object
+			timeout: The timeout for each thread to override the object default ( negative waits forever )
+			threads: The threads to join, default to all running threads managed by this object,
+				including the ones the dispatcher starts while waiting
 		@returns:
 			list[threading.Thread]: The list of running threads that are still running
 		'''
-		if threads is ...:
-			threads = self.runningThreads
 		if timeout is ...:
 			timeout = self.timeout
-		for thread in threads:
-			if timeout >= 0:
-				thread.join(timeout=timeout)
-			else:
-				thread.join()
-		self.runningThreads = [thread for thread in self.runningThreads if thread.is_alive()]
+		while True:
+			pending = self.runningThreads if threads is ... else list(threads)
+			for thread in pending:
+				if timeout >= 0:
+					thread.join(timeout=timeout)
+				else:
+					thread.join()
+			# once a pass finishes every thread, look again for commands the dispatcher started meanwhile
+			if threads is not ... or not pending or any(thread.is_alive() for thread in pending):
+				break
 		return self.runningThreads
 	
 	def stop(self,timeout=...):
 		'''
-		Stop all running threads. This signals all threads to stop and joins them
+		Stop all running threads. This signals all threads to stop and joins them.
+		Commands still queued are skipped: they keep task.thread None and returncode None
 		@params:
 			None
 		@returns:
@@ -208,8 +322,10 @@ class AsyncExecutor:
 			list[Task]: The list of tasks that are managed by this object
 		'''
 		self.stop(timeout)
-		self.tasks = []
-		self.runningThreads = []
+		with self._lock:
+			self.tasks = []
+			self._queue.clear()
+			self._threads.clear()
 		return self.tasks
 	
 	def join(self, timeout=..., threads = ..., print_error=True):
@@ -503,6 +619,7 @@ def __run_command(task,sem, timeout=60, quiet=False,dry_run=False,with_stdErr=Fa
 			outLength = len(task.stdout) + len(task.stderr)
 			time.sleep(0)
 			sleep_time = 1.0e-7 # 100 nanoseconds
+			inactivity_timeout = False
 			while proc.poll() is None:  # while the process is still running
 				if task.stop:
 					proc.send_signal(signal.SIGINT)
@@ -515,6 +632,7 @@ def __run_command(task,sem, timeout=60, quiet=False,dry_run=False,with_stdErr=Fa
 						outLength = len(task.stdout) + len(task.stderr)
 					elif time.time() - start_time > timeout:
 						task.stderr.append('Timeout!')
+						inactivity_timeout = True
 						proc.send_signal(signal.SIGINT)
 						time.sleep(0.01)
 						proc.terminate()
@@ -548,11 +666,11 @@ def __run_command(task,sem, timeout=60, quiet=False,dry_run=False,with_stdErr=Fa
 						stream.close()
 				except Exception:
 					pass
-			if task.returncode is None:
-				# process been killed via timeout or sigkill
-				if task.stderr and task.stderr[-1].strip().startswith('Timeout!'):
-					task.returncode = 124
-				elif task.stderr and task.stderr[-1].strip().startswith('Ctrl C detected, Emergency Stop!'):
+			if inactivity_timeout:
+				task.returncode = 124
+			elif task.returncode is None:
+				# process been killed via sigkill or similar without a normal exit code
+				if task.stderr and task.stderr[-1].strip().startswith('Ctrl C detected, Emergency Stop!'):
 					task.returncode = 137
 				else:
 					task.returncode = -1
@@ -576,6 +694,69 @@ def __run_command(task,sem, timeout=60, quiet=False,dry_run=False,with_stdErr=Fa
 		else:
 			return task.stdout
 
+def _run_executor_task(task, permit, timeout, quiet, dry_run, finished):
+	'''
+	Run an AsyncExecutor command, then report this thread finished so the executor joins it ( internal )
+	'''
+	try:
+		__run_command(task, permit, timeout, quiet, dry_run, identity=...)
+	finally:
+		finished.append(threading.current_thread())
+
+def __run_tracked_command(task, sem, timeout, quiet, dry_run, identity):
+	'''
+	Run a fire-and-forget command, then report this thread finished so it leaves __running_threads ( internal )
+	'''
+	try:
+		__run_command(task, sem, timeout, quiet, dry_run, identity=identity)
+	finally:
+		__finished_threads.append(threading.current_thread())
+
+def __reap_finished_threads():
+	'''
+	Join finished fire-and-forget threads and drop them from __running_threads ( internal )
+	Joining releases the thread's stack: a finished thread that is still referenced but never
+	joined keeps its stack mapped.
+	'''
+	while True:
+		try:
+			thread = __finished_threads.popleft()
+		except IndexError:
+			return
+		thread.join()
+		with __running_threads_lock:
+			__running_threads.discard(thread)
+
+def _build_tasks(commands, parse=False, use_sudo=...):
+	'''
+	Format commands into Tasks, prefixing sudo when requested and available ( internal )
+
+	@returns:
+		tuple[list[Task], bool]: The tasks and whether sudo is used
+	'''
+	global USE_SUDO
+	global SUDO_PATH
+	if use_sudo is ...:
+		use_sudo = USE_SUDO
+	# Guard against requesting sudo when it is not available. Without this,
+	# prepending a None SUDO_PATH would crash subprocess.Popen with a TypeError.
+	if use_sudo and not SUDO_PATH:
+		print("sudo not found in PATH, cannot use sudo. ignoring it...", file=sys.stderr)
+		use_sudo = False
+	# split the commands in commands if it is a string
+	formatedCommands = []
+	for command in commands:
+		formatedCommands.extend(__format_command(command,expand=parse))
+	if use_sudo:
+		formatedCommands = [[SUDO_PATH] + command for command in formatedCommands]
+	return [Task(command) for command in formatedCommands], bool(use_sudo)
+
+def _validate_sudo(sem):
+	'''
+	Validate sudo access before running sudo commands ( internal )
+	'''
+	__run_command(Task([SUDO_PATH, '-v']),sem,timeout=60,quiet=True,dry_run=False,with_stdErr=False,identity=None)
+
 def __format_command(command,expand = False):
 	'''
 	Format a command
@@ -712,41 +893,31 @@ def run_commands(commands, timeout=0,max_threads=1,quiet=False,dry_run=False,wit
 	@returns:
 		list: The output of the commands ( list[None] | list[int] | list[list[str]] | list[Task] | None )
 	'''
-	global USE_SUDO
-	global SUDO_PATH
-	if use_sudo is ...:
-		use_sudo = USE_SUDO
-	# Guard against requesting sudo when it is not available. Without this,
-	# prepending a None SUDO_PATH would crash subprocess.Popen with a TypeError.
-	if use_sudo and not SUDO_PATH:
-		print("sudo not found in PATH, cannot use sudo. ignoring it...", file=sys.stderr)
-		use_sudo = False
-	# split the commands in commands if it is a string
-	formatedCommands = []
-	for command in commands:
-		formatedCommands.extend(__format_command(command,expand=parse))
 	# initialize the tasks
-	if use_sudo:
-		formatedCommands = [[SUDO_PATH] + command for command in formatedCommands]
-	tasks = [Task(command) for command in formatedCommands]
+	tasks, use_sudo = _build_tasks(commands, parse=parse, use_sudo=use_sudo)
 	# run the tasks with max_threads. if max_threads is 0, use the number of commands
 	if max_threads < 1:
-		max_threads = len(formatedCommands)
+		max_threads = len(tasks)
 	if not sem:
 		sem = threading.Semaphore(max_threads)  # Limit concurrent sessions
 	if use_sudo:
-		# validate sudo access
-		__run_command(Task([SUDO_PATH, '-v']),sem,timeout=60,quiet=True,dry_run=False,with_stdErr=False,identity=None)	
-	if max_threads > 1 or not wait_for_return:
+		_validate_sudo(sem)
+	if not wait_for_return:
+		__reap_finished_threads()
+		threads = [threading.Thread(target=__run_tracked_command, args=(task,sem,timeout,quiet,dry_run,...),daemon=True) for task in tasks]
+		# tracked before they start, so a thread is always registered before it reports itself finished
+		with __running_threads_lock:
+			__running_threads.update(threads)
+		for thread,task in zip(threads,tasks):
+			task.thread = thread
+			thread.start()
+	elif max_threads > 1:
 		threads = [threading.Thread(target=__run_command, args=(task,sem,timeout,quiet,dry_run,...),daemon=True) for task in tasks]
 		for thread,task in zip(threads,tasks):
 			task.thread = thread
 			thread.start()
-		if wait_for_return:
-			for thread in threads:
-				thread.join()
-		else:
-			__running_threads.update(threads)
+		for thread in threads:
+			thread.join()
 	else:
 		for task in tasks:
 			__run_command(task,sem,timeout,quiet,dry_run,identity=None)
@@ -775,13 +946,12 @@ def join_threads(threads=...,timeout=None):
 	@returns:
 		None
 	'''
-	global __running_threads
 	if threads is ...:
-		threads = __running_threads
+		with __running_threads_lock:
+			threads = list(__running_threads)
 	for thread in threads:
 		thread.join(timeout=timeout)
-	if threads is __running_threads:
-		__running_threads = {t for t in threads if t.is_alive()}
+	__reap_finished_threads()
 
 def main():
 	parser = argparse.ArgumentParser(description='Run multiple commands in parallel')

multicmd-1.50/tests/test_async_executor.py

@@ -0,0 +1,165 @@
+import os
+import threading
+import time
+
+import pytest
+
+import multiCMD
+from multiCMD import AsyncExecutor, run_commands
+
+
+@pytest.mark.slow
+def test_executor_run_wait_results_codes():
+	ex = AsyncExecutor(max_threads=2, timeout=0, quiet=True)
+	ex.run_command(["echo", "a"])
+	ex.run_commands([["echo", "b"], ["false"]])
+	assert len(ex) == 3
+	assert bool(ex)
+	ex.wait(timeout=2)
+	assert ex.get_return_codes() == [0, 0, 1]
+	assert ex.get_results() == [["a"], ["b"], []]
+
+
+@pytest.mark.slow
+def test_executor_join_prints_errors(capsys):
+	ex = AsyncExecutor(max_threads=1, quiet=True)
+	ex.run_command(["false"])
+	ex.join(timeout=2, print_error=True)
+	captured = capsys.readouterr()
+	assert "failed with return code" in captured.out
+
+
+@pytest.mark.slow
+def test_executor_stop_and_cleanup():
+	ex = AsyncExecutor(max_threads=1, quiet=True)
+	ex.run_command(["sleep", "5"])
+	time.sleep(0.1)
+	ex.stop(timeout=3)
+	# stop signals task.stop; process should end
+	assert all(not t.is_alive() for t in ex.tasks)
+	ex.cleanup(timeout=1)
+	assert list(ex) == []
+
+
+@pytest.mark.slow
+def test_join_threads_module_helper():
+	tasks = run_commands(
+		[["sleep", "0.3"]],
+		wait_for_return=False,
+		return_object=True,
+		quiet=True,
+	)
+	assert tasks[0].returncode is None
+	multiCMD.join_threads(timeout=2)
+	assert tasks[0].returncode == 0
+
+
+def _global_threads():
+	return getattr(multiCMD, '__running_threads')
+
+
+def _stack_mappings(size):
+	count = 0
+	with open('/proc/self/maps') as maps:
+		for line in maps:
+			fields = line.split()
+			if len(fields) == 5 and fields[1] == 'rw-p':
+				low, high = (int(x, 16) for x in fields[0].split('-'))
+				count += high - low == size
+	return count
+
+
+def test_executor_queues_commands_instead_of_parking_threads():
+	gate = threading.Semaphore(0)
+	baseline = threading.active_count()
+	ex = AsyncExecutor(semaphore=gate, quiet=True, dry_run=True)
+	start = time.monotonic()
+	tasks = [ex.run_command(['true']) for _ in range(5000)]
+	assert time.monotonic() - start < 5
+	# no permit is free, so only the dispatcher exists and it waits for one
+	assert threading.active_count() <= baseline + 1
+	assert all(task.thread is None for task in tasks)
+	for _ in range(len(tasks)):
+		gate.release()
+	ex.wait(timeout=-1)
+	assert ex.runningThreads == []
+	assert all(task.thread is not None and not task.is_alive() for task in tasks)
+
+
+@pytest.mark.slow
+def test_executor_thread_count_stays_bounded():
+	baseline = threading.active_count()
+	ex = AsyncExecutor(semaphore=threading.Semaphore(3), quiet=True)
+	ex.run_commands([['sleep', '0.05']] * 60)
+	peak = 0
+	while ex.runningThreads:
+		peak = max(peak, threading.active_count())
+		time.sleep(0.005)
+	# the dispatcher, plus a runner and two stream readers per running command
+	assert peak - baseline <= 1 + 3 * 3
+	assert ex.get_return_codes() == [0] * 60
+
+
+@pytest.mark.slow
+@pytest.mark.skipif(not os.path.exists('/proc/self/maps'), reason='needs /proc/self/maps')
+def test_executor_releases_finished_thread_stacks():
+	# a stack size nothing else uses, so these threads' stacks can be counted in /proc/self/maps
+	stack = 8 * 1024 * 1024 + 3 * 4096
+	old_stack = threading.stack_size(stack)
+	try:
+		ex = AsyncExecutor(semaphore=threading.Semaphore(6), quiet=True)
+		for _ in range(1200):
+			ex.run_command(['sleep', '0.01'])
+		ex.wait(timeout=-1)
+		# the executor and its tasks are still referenced: every finished thread must already be joined
+		assert ex.get_return_codes() == [0] * 1200
+		# glibc keeps a few freed stacks cached for reuse
+		assert _stack_mappings(stack) <= 8
+	finally:
+		threading.stack_size(old_stack)
+
+
+def test_executor_threads_stay_out_of_global_set():
+	ex = AsyncExecutor(max_threads=2, quiet=True)
+	tasks = ex.run_commands([['true'], ['true']])
+	ex.wait(timeout=-1)
+	assert not {task.thread for task in tasks} & _global_threads()
+
+
+def test_finished_fire_and_forget_threads_leave_global_set():
+	tasks = run_commands([['true']] * 20, wait_for_return=False, return_object=True, quiet=True)
+	for task in tasks:
+		task.thread.join()
+	run_commands([['true']], wait_for_return=False, quiet=True)
+	assert not {task.thread for task in tasks} & _global_threads()
+
+
+def test_stop_skips_queued_commands():
+	ex = AsyncExecutor(semaphore=threading.Semaphore(0), quiet=True)
+	tasks = ex.run_commands([['sleep', '5']] * 3)
+	start = time.monotonic()
+	ex.stop(timeout=2)
+	assert time.monotonic() - start < 2
+	assert ex.runningThreads == []
+	assert all(task.thread is None and task.returncode is None for task in tasks)
+
+
+@pytest.mark.filterwarnings("ignore::pytest.PytestUnhandledThreadExceptionWarning")
+def test_failed_thread_start_keeps_executor_usable(monkeypatch):
+	ex = AsyncExecutor(max_threads=2, quiet=True)
+	real_start = threading.Thread.start
+
+	def fail_start(self):
+		if getattr(self, '_target', None) is multiCMD._run_executor_task:
+			raise RuntimeError("can't start new thread")
+		real_start(self)
+	monkeypatch.setattr(threading.Thread, 'start', fail_start)
+	failed = ex.run_command(['true'])
+	ex.wait(timeout=-1)
+	assert ex.runningThreads == []
+	assert failed.thread is None
+	monkeypatch.setattr(threading.Thread, 'start', real_start)
+	# the permit taken for the failed start was given back, and a new dispatcher picks up new work
+	tasks = ex.run_commands([['true'], ['true']])
+	ex.wait(timeout=-1)
+	assert [task.returncode for task in tasks] == [0, 0]

multicmd-1.50/tests/test_cli.py

@@ -0,0 +1,45 @@
+from conftest import run_cli
+import multiCMD
+
+
+def test_version_flag():
+	proc = run_cli(["-V"])
+	assert proc.returncode == 0
+	assert multiCMD.version in (proc.stdout + proc.stderr)
+
+
+def test_help_flag():
+	proc = run_cli(["-h"])
+	assert proc.returncode == 0
+	assert "max_threads" in proc.stdout
+
+
+def test_two_echoes():
+	proc = run_cli(["echo hello", "echo world"])
+	assert proc.returncode == 0
+	combined = proc.stdout + proc.stderr
+	assert "hello" in combined
+	assert "world" in combined
+
+
+def test_parse_flag_expands():
+	proc = run_cli(["-p", "echo [1-2]"])
+	assert proc.returncode == 0
+	combined = proc.stdout + proc.stderr
+	assert "[1-2]" not in combined
+	assert "Running command: echo 1" in combined
+	assert "Running command: echo 2" in combined
+
+
+def test_max_threads_and_timeout_smoke():
+	proc = run_cli(["-q", "-m", "2", "-t", "5", "echo a", "echo b"], timeout=20)
+	assert proc.returncode == 0
+
+
+def test_sudo_flag_without_sudo_binary_does_not_crash(monkeypatch):
+	# Force child env: PATH without sudo by invoking python -c wrapper is heavy;
+	# instead assert current host behavior: --sudo with missing sudo should not
+	# abort with traceback. If sudo exists, command still succeeds for echo.
+	proc = run_cli(["-q", "--sudo", "echo ok"], timeout=20)
+	assert proc.returncode == 0
+	assert "Traceback" not in (proc.stdout + proc.stderr)

multicmd-1.50/tests/test_expand_ranges.py

@@ -0,0 +1,48 @@
+import multiCMD
+from multiCMD import _expand_ranges, _expand_ranges_fast
+
+
+def test_alias_is_fast_implementation():
+	assert _expand_ranges is _expand_ranges_fast
+
+
+def test_numeric_alpha_and_comma():
+	assert _expand_ranges("file[1-3].txt") == ["file1.txt", "file2.txt", "file3.txt"]
+	assert _expand_ranges("file[a-c].txt") == ["filea.txt", "fileb.txt", "filec.txt"]
+	assert _expand_ranges("file[1-2,a-b].txt") == [
+		"file1.txt", "file2.txt", "filea.txt", "fileb.txt"
+	]
+	assert _expand_ranges("file[1-3,5].txt") == [
+		"file1.txt", "file2.txt", "file3.txt", "file5.txt"
+	]
+
+
+def test_zero_padding_shorter_endpoint_rule():
+	assert _expand_ranges("file[01-03].txt") == [
+		"file01.txt", "file02.txt", "file03.txt"
+	]
+	assert _expand_ranges("[0-10]") == [str(i) for i in range(11)]
+	assert _expand_ranges("[01-10]") == [f"{i:02d}" for i in range(1, 11)]
+
+
+def test_hex_style_alpha_range():
+	assert _expand_ranges("v[a-f]") == [f"v{c}" for c in "abcdef"]
+
+
+def test_multi_bracket_cartesian():
+	assert _expand_ranges("[1-2]-[a-b]") == ["1-a", "1-b", "2-a", "2-b"]
+
+
+def test_variable_assignment_and_reference():
+	multiCMD.__variables.clear()
+	assert _expand_ranges("[n:3]host[1-n]") == ["host1", "host2", "host3"]
+
+
+def test_brace_expression_eval():
+	multiCMD.__variables.clear()
+	assert _expand_ranges("host[{2+3}]") == ["host5"]
+
+
+def test_passthrough_without_brackets():
+	assert _expand_ranges("plainhost") == ["plainhost"]
+	assert _expand_ranges("") == [""]

multicmd-1.50/tests/test_helpers.py

@@ -0,0 +1,76 @@
+import builtins
+import select
+import sys
+
+from multiCMD import (
+	_genrate_progress_bar,
+	format_bytes,
+	get_terminal_size,
+	input_with_timeout_and_countdown,
+	int_to_color,
+	parseTable,
+	pretty_format_table,
+	print_progress_bar,
+	slugify,
+)
+
+
+def test_pretty_format_table_basic_and_remove_empty():
+	data = [["a", ""], ["b", ""]]
+	header = ["h1", "h2"]
+	out = pretty_format_table(data, header=header, remove_empty_columns=True)
+	assert out == "h1\n--\na \nb \n"
+
+
+def test_parse_table():
+	text = "col1  col2\nfoo   bar\n"
+	table = parseTable(text)
+	assert table == [["col1", "col2"], ["foo", "bar"]]
+
+
+def test_slugify_ascii_and_unicode():
+	assert slugify("Hello World!") == "hello-world"
+	assert slugify("café", allow_unicode=True) == "café"  # runtime: preserves unicode
+	assert slugify("café", allow_unicode=False) == "cafe"
+
+
+def test_format_bytes_roundtrip():
+	assert format_bytes(1024, use_1024_bytes=True, to_str=True) == "1.00 Ki"
+	assert format_bytes("1 KiB", to_int=True) == 1024
+
+
+def test_int_to_color_deterministic_and_in_range():
+	assert int_to_color(0x123456) == (36, 103, 171)
+	assert int_to_color(0) == (160, 160, 160)
+	assert int_to_color(0xFFFFFF) == (220, 220, 220)
+
+
+def test_progress_bar_helpers(capsys, monkeypatch):
+	expected_bar = (
+		"P██████████████████████████████████▁__________________________________|50.0% S"
+	)
+	assert _genrate_progress_bar(5, 10, prefix="P", suffix="S", columns=80) == expected_bar
+
+	monkeypatch.setattr(
+		"multiCMD.get_terminal_size", lambda: (80, 24)
+	)
+	print_progress_bar(5, 10, prefix="Progress:", suffix="Complete")
+	captured = capsys.readouterr()
+	assert captured.out == (
+		"\rProgress: |████████████████████████▄_________________________|50.0% | Complete"
+	)
+
+
+def test_get_terminal_size_tuple():
+	cols, rows = get_terminal_size()
+	assert cols > 0 and rows > 0
+
+
+def test_input_with_timeout_and_countdown(monkeypatch):
+	monkeypatch.setattr(builtins, "input", lambda prompt="": "user input")
+	monkeypatch.setattr(
+		select, "select", lambda r, w, x, timeout=None: ([sys.stdin], [], [])
+	)
+	assert input_with_timeout_and_countdown(5) == "user input"
+	monkeypatch.setattr(select, "select", lambda r, w, x, timeout=None: ([], [], []))
+	assert input_with_timeout_and_countdown(1) is None

multicmd-1.50/tests/test_ping.py

@@ -0,0 +1,31 @@
+import shutil
+
+import pytest
+
+from conftest import loopback_ping_works
+from multiCMD import ping
+
+pytestmark = [
+	pytest.mark.ping,
+	pytest.mark.skipif(shutil.which("ping") is None, reason="ping not installed"),
+	pytest.mark.skipif(not loopback_ping_works(), reason="loopback ping failed"),
+]
+
+
+def test_ping_single_true_false():
+	assert ping("127.0.0.1", timeout=2, quiet=True) is True
+
+
+def test_ping_list_true_false():
+	assert ping(["127.0.0.1", "127.0.0.1"], timeout=2, quiet=True) == [True, True]
+
+
+def test_ping_raw_return_codes():
+	rcs = ping(
+		["127.0.0.1"],
+		timeout=2,
+		quiet=True,
+		return_true_false=False,
+		return_code_only=True,
+	)
+	assert rcs == [0]

multicmd-1.50/tests/test_regressions.py

@@ -0,0 +1,68 @@
+import time
+
+import pytest
+
+import multiCMD
+from multiCMD import int_to_color, run_command
+
+
+def test_regression_sudo_none_path_no_typeerror():
+	"""use_sudo with SUDO_PATH=None must not prepend None into Popen argv."""
+	multiCMD.SUDO_PATH = None
+	out = run_command(["echo", "ok"], quiet=True, use_sudo=True)
+	assert out == ["ok"]
+
+
+@pytest.mark.slow
+def test_regression_stdin_eof_no_hang():
+	"""Commands that read stdin must see EOF (DEVNULL), not hang until timeout."""
+	t0 = time.time()
+	task = run_command(["cat"], quiet=True, return_object=True, timeout=2)
+	elapsed = time.time() - t0
+	assert elapsed < 1.5
+	assert task.returncode == 0
+	assert task.stdout == []
+
+
+def test_regression_int_to_color_no_recursion():
+	# Previously could RecursionError / non-deterministic str hashing
+	colors = [int_to_color(i) for i in range(0, 5000, 97)]
+	assert int_to_color(42) == int_to_color(42)
+	for rgb in colors:
+		assert all(0 <= c <= 255 for c in rgb)
+	# Distinct inputs should not all collapse onto the same color.
+	assert len(set(colors)) > 1
+
+
+@pytest.mark.slow
+def test_regression_concurrent_stdout_stderr_no_race():
+	code = (
+		"import sys\n"
+		"for i in range(200):\n"
+		"    print('O', i, flush=True)\n"
+		"    print('E', i, file=sys.stderr, flush=True)\n"
+	)
+	task = run_command(["python3", "-c", code], quiet=True, return_object=True)
+	assert task.returncode == 0
+	assert len(task.stdout) == 200
+	assert len(task.stderr) == 200
+
+
+@pytest.mark.slow
+def test_regression_inactivity_timeout_not_total_runtime():
+	"""A chatty process lasting longer than timeout must not be killed for wall time."""
+	code = (
+		"import time\n"
+		"for _ in range(6):\n"
+		"    print('tick', flush=True)\n"
+		"    time.sleep(0.25)\n"
+	)
+	task = run_command(
+		["python3", "-c", code],
+		timeout=0.5,
+		quiet=True,
+		return_object=True,
+	)
+	assert task.returncode == 0
+	assert not any(line.strip().startswith("Timeout!") for line in task.stderr)
+	assert len(task.stdout) == 6

multicmd-1.50/tests/test_run_command.py

@@ -0,0 +1,97 @@
+import time
+
+import pytest
+
+from multiCMD import run_command
+
+
+def test_echo_stdout_list():
+	assert run_command(["echo", "hello"], quiet=True) == ["hello"]
+
+
+def test_string_command_form():
+	assert run_command("echo hello", quiet=True) == ["hello"]
+
+
+def test_dry_run_empty():
+	assert run_command(["echo", "hello"], dry_run=True, quiet=True) == []
+
+
+def test_return_code_only_success_and_failure():
+	assert run_command(["echo", "hello"], return_code_only=True, quiet=True) == 0
+	assert run_command(["false"], return_code_only=True, quiet=True) == 1
+
+
+def test_return_object():
+	task = run_command(["echo", "hello"], return_object=True, quiet=True)
+	assert task.returncode == 0
+	assert task.stdout == ["hello"]
+	assert task.stderr == []
+
+
+def test_with_stderr_merged():
+	# python writes to stderr
+	out = run_command(
+		["python3", "-c", "import sys; sys.stderr.write('e\\n'); print('o')"],
+		quiet=True,
+		with_stdErr=True,
+	)
+	assert "o" in out
+	assert "e" in out
+
+
+@pytest.mark.slow
+def test_timeout_silent_command():
+	result = run_command(["sleep", "2"], timeout=0.3, quiet=True, with_stdErr=False)
+	assert "Timeout!" not in result
+	result = run_command(["sleep", "2"], timeout=0.3, quiet=True, with_stdErr=True)
+	assert "Timeout!" in "\n".join(result)
+	task = run_command(
+		["sleep", "2"], timeout=0.3, quiet=True, return_object=True
+	)
+	assert task.returncode == 124
+	assert task.stderr and task.stderr[-1].strip().startswith("Timeout!")
+
+
+@pytest.mark.slow
+def test_timeout_returncode_preserved_after_sigint_handler_stderr():
+	task = run_command(
+		[
+			"python3",
+			"-c",
+			"import signal, sys, time\n"
+			"def handler(sig, frame):\n"
+			"    sys.stderr.write('handled\\n')\n"
+			"    sys.stderr.flush()\n"
+			"    sys.exit(0)\n"
+			"signal.signal(signal.SIGINT, handler)\n"
+			"time.sleep(10)\n",
+		],
+		timeout=0.3,
+		quiet=True,
+		return_object=True,
+	)
+	assert task.returncode == 124
+	assert "Timeout!" in task.stderr
+	assert "handled" in task.stderr
+	assert task.stderr[-1].strip() == "handled"
+
+
+@pytest.mark.slow
+def test_wait_for_return_false():
+	task = run_command(
+		["sleep", "0.4"],
+		wait_for_return=False,
+		quiet=True,
+		return_object=True,
+	)
+	assert task.returncode is None
+	deadline = time.time() + 2
+	while task.returncode is None and time.time() < deadline:
+		time.sleep(0.05)
+	assert task.returncode == 0
+
+
+def test_raise_error_on_failure():
+	with pytest.raises(Exception, match="Commands failed"):
+		run_command(["false"], quiet=True, raise_error=True)

multicmd-1.50/tests/test_run_commands.py

@@ -0,0 +1,119 @@
+import threading
+import time
+
+import pytest
+
+from multiCMD import run_commands
+
+
+def test_batch_stdout():
+	assert run_commands(
+		[["echo", "hello"], ["echo", "world"]], quiet=True
+	) == [["hello"], ["world"]]
+
+
+def test_dry_run_and_return_codes():
+	cmds = [["echo", "hello"], ["echo", "world"]]
+	assert run_commands(cmds, dry_run=True, quiet=True) == [[], []]
+	assert run_commands(cmds, return_code_only=True, quiet=True) == [0, 0]
+
+
+def test_return_objects_preserve_order():
+	tasks = run_commands(
+		[["echo", "hello"], ["false"], ["echo", "world"]],
+		return_object=True,
+		quiet=True,
+	)
+	assert [t.returncode for t in tasks] == [0, 1, 0]
+	assert tasks[0].stdout == ["hello"]
+	assert tasks[2].stdout == ["world"]
+
+
+def test_parse_expands_commands():
+	result = run_commands([["echo", "[0-10]"]], quiet=True, parse=True)
+	assert result == [[str(i)] for i in range(11)]
+
+
+@pytest.mark.slow
+def test_timeout_mixed_batch():
+	result = run_commands(
+		[["sleep", "2"], ["echo", "done"]],
+		timeout=0.3,
+		quiet=True,
+		with_stdErr=True,
+		max_threads=2,
+	)
+	assert "Timeout!" in "\n".join(result[0])
+	assert result[1] == ["done"]
+
+
+@pytest.mark.slow
+def test_max_threads_scheduling():
+	# Port of legacy test_run_commands_max_threads with slightly tighter sleeps.
+	# With max_threads=2, only 2 of the 3 sleeps can run concurrently, so the
+	# 3rd is queued behind the first 2 and won't start (let alone finish)
+	# until one of them completes around t=0.6s.
+	cmds = [["sleep", "0.6"], ["sleep", "0.6"], ["sleep", "0.6"]]
+	tasks = run_commands(
+		cmds,
+		wait_for_return=False,
+		timeout=0,
+		quiet=True,
+		return_object=True,
+		max_threads=2,
+	)
+	time.sleep(0.2)
+	alive = sum(1 for t in tasks if t.returncode is None)
+	assert alive == 3
+
+	# By ~0.8s, exactly 2 of the 3 sleeps have had time to finish (the ones
+	# that started immediately); the 3rd was blocked until ~0.6s and is
+	# still running. If max_threads were not enforced (e.g. unbounded),
+	# all 3 would already be finished by this point.
+	time.sleep(0.6)
+	finished = sum(1 for t in tasks if t.returncode is not None)
+	assert finished == 2
+
+	deadline = time.time() + 3
+	while any(t.returncode is None for t in tasks) and time.time() < deadline:
+		time.sleep(0.05)
+	assert [t.returncode for t in tasks] == [0, 0, 0]
+
+
+@pytest.mark.slow
+def test_max_threads_scheduling_wall_time():
+	# Direct wall-time invariant: with max_threads=2, three 0.6s sleeps must
+	# take noticeably longer than a single 0.6s batch (2 batches of work),
+	# whereas with an unbounded/8-thread pool they'd all run concurrently
+	# and finish in ~0.6s.
+	cmds = [["sleep", "0.6"], ["sleep", "0.6"], ["sleep", "0.6"]]
+	start = time.time()
+	run_commands(
+		cmds,
+		wait_for_return=True,
+		timeout=0,
+		quiet=True,
+		max_threads=2,
+	)
+	elapsed = time.time() - start
+	assert elapsed >= 1.1
+
+
+@pytest.mark.slow
+def test_shared_semaphore_bounds_concurrency():
+	sem = threading.Semaphore(1)
+	# With sem=1, two 0.3s sleeps cannot overlap even if max_threads=2
+	t0 = time.time()
+	run_commands(
+		[["sleep", "0.3"], ["sleep", "0.3"]],
+		quiet=True,
+		max_threads=2,
+		sem=sem,
+	)
+	elapsed = time.time() - t0
+	assert elapsed >= 0.55
+
+
+def test_raise_error_batch():
+	with pytest.raises(Exception, match="Commands failed"):
+		run_commands([["true"], ["false"]], quiet=True, raise_error=True)

multicmd-1.50/tests/test_sudo.py

@@ -0,0 +1,45 @@
+import os
+
+import pytest
+
+import multiCMD
+from conftest import has_sudo_binary
+from multiCMD import run_command, set_sudo
+
+
+def test_set_sudo_false():
+	multiCMD.USE_SUDO = True
+	set_sudo(False)
+	assert multiCMD.USE_SUDO is False
+
+
+def test_set_sudo_true_when_root():
+	if os.geteuid() != 0:
+		pytest.skip("requires root to exercise root-disables-sudo path")
+	set_sudo(True)
+	assert multiCMD.USE_SUDO is False
+
+
+def test_set_sudo_true_without_sudo_binary(capsys):
+	multiCMD.SUDO_PATH = None
+	if os.geteuid() == 0:
+		pytest.skip("root path short-circuits before SUDO_PATH check")
+	set_sudo(True)
+	assert multiCMD.USE_SUDO is False
+	err = capsys.readouterr().err
+	assert "sudo not found" in err
+
+
+@pytest.mark.sudo
+def test_set_sudo_true_non_root_with_binary():
+	if os.geteuid() == 0 or not has_sudo_binary():
+		pytest.skip("needs non-root and sudo in PATH")
+	set_sudo(True)
+	assert multiCMD.USE_SUDO is True
+
+
+def test_use_sudo_none_path_does_not_crash():
+	multiCMD.SUDO_PATH = None
+	# Must not raise TypeError from Popen([None, ...])
+	result = run_command(["echo", "ok"], quiet=True, use_sudo=True)
+	assert result == ["ok"]

multicmd-1.50/tests/test_task.py

@@ -0,0 +1,22 @@
+from multiCMD import Task, run_command
+
+
+def test_task_defaults_and_iter():
+	t = Task(["echo", "x"])
+	assert t.returncode is None
+	assert t.stdout == []
+	assert t.stderr == []
+	assert t.stop is False
+	assert dict(t) == {
+		"command": ["echo", "x"],
+		"returncode": None,
+		"stdout": [],
+		"stderr": [],
+	}
+
+
+def test_task_repr_str_and_alive():
+	t = run_command(["echo", "hi"], return_object=True, quiet=True)
+	assert "hi" in str(t)
+	assert "Task(" in repr(t)
+	assert t.is_alive() is False

multicmd-1.48/multiCMD.egg-info/SOURCES.txt

@@ -1,9 +0,0 @@
-README.md
-multiCMD.py
-setup.py
-multiCMD.egg-info/PKG-INFO
-multiCMD.egg-info/SOURCES.txt
-multiCMD.egg-info/dependency_links.txt
-multiCMD.egg-info/entry_points.txt
-multiCMD.egg-info/requires.txt
-multiCMD.egg-info/top_level.txt