stouputils 1.18.1__py3-none-any.whl → 1.18.3__py3-none-any.whl

stouputils/io.py

@@ -492,7 +492,7 @@ def clean_path(file_path: str, trailing_slash: bool = True) -> str:
 	# Return the cleaned path
 	return file_path if file_path != "." else ""
 
-def safe_close(file: IO[Any] | int | None) -> None:
+def safe_close(file: IO[Any] | int | Any | None) -> None:
 	""" Safely close a file object (or file descriptor) after flushing, ignoring any exceptions.
 
 	Args:
@@ -506,9 +506,9 @@ def safe_close(file: IO[Any] | int | None) -> None:
 				except Exception:
 					pass
 	elif file:
-		for func in (file.flush, file.close):
+		for func in ("flush", "close"):
 			try:
-				func()
+				getattr(file, func)()
 			except Exception:
 				pass
 

stouputils/io.pyi

@@ -211,7 +211,7 @@ def clean_path(file_path: str, trailing_slash: bool = True) -> str:
 \t\t>>> clean_path("C:/folder1\\\\folder2")
 \t\t\'C:/folder1/folder2\'
 \t'''
-def safe_close(file: IO[Any] | int | None) -> None:
+def safe_close(file: IO[Any] | int | Any | None) -> None:
     """ Safely close a file object (or file descriptor) after flushing, ignoring any exceptions.
 
 \tArgs:

stouputils/parallel/capturer.py

@@ -65,8 +65,7 @@ class CaptureOutput:
 
 	def parent_close_write(self) -> None:
 		""" Close the parent's copy of the write end; the child's copy remains. """
-		safe_close(self.write_fd)
-		self.write_conn.close()
+		safe_close(self.write_conn)
 		self.write_fd = -1	# Prevent accidental reuse
 
 	def start_listener(self) -> None:
@@ -110,8 +109,7 @@ class CaptureOutput:
 					if len(buffer) > self.chunk_size * 4:
 						_handle_buffer()
 			finally:
-				safe_close(self.read_fd)
-				self.read_conn.close()
+				safe_close(self.read_conn)
 				self.read_fd = -1
 				self._thread = None		# Mark thread as stopped so callers don't block unnecessarily
 
@@ -123,8 +121,9 @@ class CaptureOutput:
 	def join_listener(self, timeout: float | None = None) -> None:
 		""" Wait for the listener thread to finish (until EOF). """
 		if self._thread is None:
-			safe_close(self.read_fd)
-			return self.read_conn.close()
+			safe_close(self.read_conn)
+			self.read_fd = -1
+			return
 		self._thread.join(timeout)
 
 		# If thread finished, ensure read fd is closed and clear thread

stouputils/parallel/subprocess.py

@@ -4,9 +4,20 @@ import time
 from collections.abc import Callable
 from typing import Any
 
+from ..typing import JsonDict
 from .capturer import CaptureOutput
 
 
+class RemoteSubprocessError(RuntimeError):
+	""" Raised in the parent when the child raised an exception - contains the child's formatted traceback. """
+	def __init__(self, exc_type: str, exc_repr: str, traceback_str: str):
+		msg = f"Exception in subprocess ({exc_type}): {exc_repr}\n\nRemote traceback:\n{traceback_str}"
+		super().__init__(msg)
+		self.remote_type = exc_type
+		self.remote_repr = exc_repr
+		self.remote_traceback = traceback_str
+
+
 def run_in_subprocess[R](
 	func: Callable[..., R],
 	*args: Any,
@@ -37,7 +48,8 @@ def run_in_subprocess[R](
 		R: The return value of the function.
 
 	Raises:
-		RuntimeError: If the subprocess exits with a non-zero exit code or times out.
+		RemoteSubprocessError: If the child raised an exception - contains the child's formatted traceback.
+		RuntimeError: If the subprocess exits with a non-zero exit code or did not return a result.
 		TimeoutError: If the subprocess exceeds the specified timeout.
 
 	Examples:
@@ -66,7 +78,7 @@ def run_in_subprocess[R](
 	from multiprocessing import Queue
 
 	# Create a queue to get the result from the subprocess (only if we need to wait)
-	result_queue: Queue[R | Exception] | None = None if no_join else Queue()
+	result_queue: Queue[JsonDict] | None = None if no_join else Queue()
 
 	# Optionally setup output capture pipe and listener
 	capturer: CaptureOutput | None = None
@@ -105,23 +117,22 @@ def run_in_subprocess[R](
 			process.join()
 			raise TimeoutError(f"Subprocess exceeded timeout of {timeout} seconds and was terminated")
 
-		# Check exit code
+		# Retrieve the payload if present
+		result_payload: JsonDict | None = result_queue.get_nowait() if not result_queue.empty() else None
+
+		# If the child sent a structured exception, raise it with the formatted traceback
+		if isinstance(result_payload, dict):
+			if result_payload.pop("ok", False) is False:
+				raise RemoteSubprocessError(**result_payload)
+			else:
+				return result_payload["result"]
+
+		# Raise an error according to the exit code presence
 		if process.exitcode != 0:
-			# Try to get any exception from the queue (non-blocking)
-			if not result_queue.empty():
-				result_or_exception = result_queue.get_nowait()
-				if isinstance(result_or_exception, Exception):
-					raise result_or_exception
 			raise RuntimeError(f"Subprocess failed with exit code {process.exitcode}")
+		raise RuntimeError("Subprocess did not return any result")
 
-		# Retrieve the result
-		try:
-			result_or_exception = result_queue.get_nowait()
-			if isinstance(result_or_exception, Exception):
-				raise result_or_exception
-			return result_or_exception
-		except Exception as e:
-			raise RuntimeError("Subprocess did not return any result") from e
+	# Finally, ensure we drain/join the listener if capturing output
 	finally:
 		if capturer is not None:
 			capturer.join_listener(timeout=5.0)
@@ -154,10 +165,21 @@ def _subprocess_wrapper[R](
 		# Execute the target function and put the result in the queue
 		result: R = func(*args, **kwargs)
 		if result_queue is not None:
-			result_queue.put(result)
+			result_queue.put({"ok": True, "result": result})
 
 	# Handle cleanup and exceptions
 	except Exception as e:
 		if result_queue is not None:
-			result_queue.put(e)
+			try:
+				import traceback
+				tb = traceback.format_exc()
+				result_queue.put({
+					"ok": False,
+					"exc_type": e.__class__.__name__,
+					"exc_repr": repr(e),
+					"traceback_str": tb,
+				})
+			except Exception:
+				# Nothing we can do if even this fails
+				pass
 

stouputils/parallel/subprocess.pyi

@@ -1,7 +1,16 @@
+from ..typing import JsonDict as JsonDict
 from .capturer import CaptureOutput as CaptureOutput
+from _typeshed import Incomplete
 from collections.abc import Callable as Callable
 from typing import Any
 
+class RemoteSubprocessError(RuntimeError):
+    """ Raised in the parent when the child raised an exception - contains the child's formatted traceback. """
+    remote_type: Incomplete
+    remote_repr: Incomplete
+    remote_traceback: Incomplete
+    def __init__(self, exc_type: str, exc_repr: str, traceback_str: str) -> None: ...
+
 def run_in_subprocess[R](func: Callable[..., R], *args: Any, timeout: float | None = None, no_join: bool = False, capture_output: bool = False, **kwargs: Any) -> R:
     ''' Execute a function in a subprocess with positional and keyword arguments.
 
@@ -25,7 +34,8 @@ def run_in_subprocess[R](func: Callable[..., R], *args: Any, timeout: float | No
 \t\tR: The return value of the function.
 
 \tRaises:
-\t\tRuntimeError: If the subprocess exits with a non-zero exit code or times out.
+\t\tRemoteSubprocessError: If the child raised an exception - contains the child\'s formatted traceback.
+\t\tRuntimeError: If the subprocess exits with a non-zero exit code or did not return a result.
 \t\tTimeoutError: If the subprocess exceeds the specified timeout.
 
 \tExamples:

stouputils/print.py

@@ -328,39 +328,39 @@ def info(
 		else:
 			print(message, *values, RESET, file=file, **print_kwargs)
 
-def debug(*values: Any, **print_kwargs: Any) -> None:
+def debug(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
 	""" Print a debug message looking like "[DEBUG HH:MM:SS] message" in cyan by default. """
 	if "text" not in print_kwargs:
 		print_kwargs["text"] = "DEBUG"
 	if "color" not in print_kwargs:
 		print_kwargs["color"] = CYAN
-	info(*values, **print_kwargs)
+	info(*values, flush=flush, **print_kwargs)
 
-def alt_debug(*values: Any, **print_kwargs: Any) -> None:
+def alt_debug(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
 	""" Print a debug message looking like "[DEBUG HH:MM:SS] message" in blue by default. """
 	if "text" not in print_kwargs:
 		print_kwargs["text"] = "DEBUG"
 	if "color" not in print_kwargs:
 		print_kwargs["color"] = BLUE
-	info(*values, **print_kwargs)
+	info(*values, flush=flush, **print_kwargs)
 
-def suggestion(*values: Any, **print_kwargs: Any) -> None:
+def suggestion(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
 	""" Print a suggestion message looking like "[SUGGESTION HH:MM:SS] message" in cyan by default. """
 	if "text" not in print_kwargs:
 		print_kwargs["text"] = "SUGGESTION"
 	if "color" not in print_kwargs:
 		print_kwargs["color"] = CYAN
-	info(*values, **print_kwargs)
+	info(*values, flush=flush, **print_kwargs)
 
-def progress(*values: Any, **print_kwargs: Any) -> None:
+def progress(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
 	""" Print a progress message looking like "[PROGRESS HH:MM:SS] message" in magenta by default. """
 	if "text" not in print_kwargs:
 		print_kwargs["text"] = "PROGRESS"
 	if "color" not in print_kwargs:
 		print_kwargs["color"] = MAGENTA
-	info(*values, **print_kwargs)
+	info(*values, flush=flush, **print_kwargs)
 
-def warning(*values: Any, **print_kwargs: Any) -> None:
+def warning(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
 	""" Print a warning message looking like "[WARNING HH:MM:SS] message" in yellow by default and in sys.stderr. """
 	if "file" not in print_kwargs:
 		print_kwargs["file"] = sys.stderr
@@ -368,9 +368,9 @@ def warning(*values: Any, **print_kwargs: Any) -> None:
 		print_kwargs["text"] = "WARNING"
 	if "color" not in print_kwargs:
 		print_kwargs["color"] = YELLOW
-	info(*values, **print_kwargs)
+	info(*values, flush=flush, **print_kwargs)
 
-def error(*values: Any, exit: bool = False, **print_kwargs: Any) -> None:
+def error(*values: Any, exit: bool = False, flush: bool = True, **print_kwargs: Any) -> None:
 	""" Print an error message (in sys.stderr and in red by default)
 	and optionally ask the user to continue or stop the program.
 
@@ -390,7 +390,7 @@ def error(*values: Any, exit: bool = False, **print_kwargs: Any) -> None:
 		print_kwargs["text"] = "ERROR"
 	if "color" not in print_kwargs:
 		print_kwargs["color"] = RED
-	info(*values, **print_kwargs)
+	info(*values, flush=flush, **print_kwargs)
 	if exit:
 		try:
 			print("Press enter to ignore error and continue, or 'CTRL+C' to stop the program... ", file=file)
@@ -402,6 +402,7 @@ def error(*values: Any, exit: bool = False, **print_kwargs: Any) -> None:
 def whatisit(
 	*values: Any,
 	print_function: Callable[..., None] = debug,
+	flush: bool = True,
 	max_length: int = 250,
 	color: str = CYAN,
 	**print_kwargs: Any,
@@ -473,11 +474,11 @@ def whatisit(
 
 	# Print the values
 	if len(values) > 1:
-		print_function("".join(f"\n  {_internal(value)}" for value in values), **print_kwargs)
+		print_function("".join(f"\n  {_internal(value)}" for value in values), flush=flush, **print_kwargs)
 	elif len(values) == 1:
-		print_function(_internal(values[0]), **print_kwargs)
+		print_function(_internal(values[0]), flush=flush, **print_kwargs)
 
-def breakpoint(*values: Any, print_function: Callable[..., None] = warning, **print_kwargs: Any) -> None:
+def breakpoint(*values: Any, print_function: Callable[..., None] = warning, flush: bool = True, **print_kwargs: Any) -> None:
 	""" Breakpoint function, pause the program and print the values.
 
 	Args:
@@ -493,7 +494,7 @@ def breakpoint(*values: Any, print_function: Callable[..., None] = warning, **pr
 			file = cast(TextIO, print_kwargs["file"][0])
 		else:
 			file = print_kwargs["file"]
-	whatisit(*values, print_function=print_function, **print_kwargs)
+	whatisit(*values, print_function=print_function, flush=flush, **print_kwargs)
 	try:
 		input()
 	except (KeyboardInterrupt, EOFError):

stouputils/print.pyi

@@ -125,17 +125,17 @@ def info(*values: Any, color: str = ..., text: str = 'INFO ', prefix: str = '',
 \t\tuse_colored\t\t(bool):\t\t\t\t\tWhether to use the colored() function to format the message
 \t\tprint_kwargs\t(dict):\t\t\t\t\tKeyword arguments to pass to the print function
 \t'''
-def debug(*values: Any, **print_kwargs: Any) -> None:
+def debug(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
     ''' Print a debug message looking like "[DEBUG HH:MM:SS] message" in cyan by default. '''
-def alt_debug(*values: Any, **print_kwargs: Any) -> None:
+def alt_debug(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
     ''' Print a debug message looking like "[DEBUG HH:MM:SS] message" in blue by default. '''
-def suggestion(*values: Any, **print_kwargs: Any) -> None:
+def suggestion(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
     ''' Print a suggestion message looking like "[SUGGESTION HH:MM:SS] message" in cyan by default. '''
-def progress(*values: Any, **print_kwargs: Any) -> None:
+def progress(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
     ''' Print a progress message looking like "[PROGRESS HH:MM:SS] message" in magenta by default. '''
-def warning(*values: Any, **print_kwargs: Any) -> None:
+def warning(*values: Any, flush: bool = True, **print_kwargs: Any) -> None:
     ''' Print a warning message looking like "[WARNING HH:MM:SS] message" in yellow by default and in sys.stderr. '''
-def error(*values: Any, exit: bool = False, **print_kwargs: Any) -> None:
+def error(*values: Any, exit: bool = False, flush: bool = True, **print_kwargs: Any) -> None:
     """ Print an error message (in sys.stderr and in red by default)
 \tand optionally ask the user to continue or stop the program.
 
@@ -145,7 +145,7 @@ def error(*values: Any, exit: bool = False, **print_kwargs: Any) -> None:
 \t\t\tfalse to ignore the error automatically and continue
 \t\tprint_kwargs\t(dict):\t\tKeyword arguments to pass to the print function
 \t"""
-def whatisit(*values: Any, print_function: Callable[..., None] = ..., max_length: int = 250, color: str = ..., **print_kwargs: Any) -> None:
+def whatisit(*values: Any, print_function: Callable[..., None] = ..., flush: bool = True, max_length: int = 250, color: str = ..., **print_kwargs: Any) -> None:
     ''' Print the type of each value and the value itself, with its id and length/shape.
 
 \tThe output format is: "type, <id id_number>:\t(length/shape) value"
@@ -157,7 +157,7 @@ def whatisit(*values: Any, print_function: Callable[..., None] = ..., max_length
 \t\tcolor\t\t\t(str):\t\tColor of the message (default: CYAN)
 \t\tprint_kwargs\t(dict):\t\tKeyword arguments to pass to the print function
 \t'''
-def breakpoint(*values: Any, print_function: Callable[..., None] = ..., **print_kwargs: Any) -> None:
+def breakpoint(*values: Any, print_function: Callable[..., None] = ..., flush: bool = True, **print_kwargs: Any) -> None:
     """ Breakpoint function, pause the program and print the values.
 
 \tArgs:

{stouputils-1.18.1.dist-info → stouputils-1.18.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.18.1
+Version: 1.18.3
 Summary: Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more.
 Keywords: utilities,tools,helpers,development,python
 Author: Stoupy51

{stouputils-1.18.1.dist-info → stouputils-1.18.3.dist-info}/RECORD

@@ -125,8 +125,8 @@ stouputils/installer/main.py,sha256=8wrx_cnQo1dFGRf6x8vtxh6-96tQ-AzMyvJ0S64j0io,
 stouputils/installer/main.pyi,sha256=r3j4GoMBpU06MpOqjSwoDTiSMOmbA3WWUA87970b6KE,3134
 stouputils/installer/windows.py,sha256=r2AIuoyAmtMEuoCtQBH9GWQWI-JUT2J9zoH28j9ruOU,4880
 stouputils/installer/windows.pyi,sha256=tHogIFhPVDQS0I10liLkAxnpaFFAvmFtEVMpPIae5LU,1616
-stouputils/io.py,sha256=Q0Erzy7k8MTEw50s1O_CbuP2bh7oxt42tbcXcUeX97E,17782
-stouputils/io.pyi,sha256=zsId531UOFs-P5kc5cCl3W6oA0X47T_RD2HPDpElZX8,9308
+stouputils/io.py,sha256=3-n6RGItDn7mdHSkzK4oSUMeL-3VJ1k2cvoSfzBH_ak,17797
+stouputils/io.pyi,sha256=n2o28-4BfhlEH1f-vCLU8YlaqzG-4qgrZ3p8jEnJFeE,9314
 stouputils/lock/__init__.py,sha256=8EvKPwnd5oHAWP-2vs6ULUDCSNyUh-mw12nYvBqgVAc,1029
 stouputils/lock/__init__.pyi,sha256=qcTm6JcGXfwQB2dUCa2wFEInSwJF2pOrYnejSpvGd7k,120
 stouputils/lock/base.py,sha256=hjSXRzOLVTMNrxpf4QcmfCfdlSRHFT9e130Zz_cqxY8,20483
@@ -141,22 +141,22 @@ stouputils/lock/shared.py,sha256=G8Mcy7dXtNESyU7hSaeihNrCU4l98VhyQyO_vQYPJ7g,788
 stouputils/lock/shared.pyi,sha256=0CV6TpTaDEkcGA35Q-ijp8ckImZ32umlMA4U-8C_O-I,545
 stouputils/parallel/__init__.py,sha256=myD8KiVfPPKF26Xu8Clu0p-VaYDK74loMUjUkl6-9XU,1013
 stouputils/parallel/__init__.pyi,sha256=UtZKtl9i__OH0Edypap9oZUcTF1h91qfpItG1-x7TfE,97
-stouputils/parallel/capturer.py,sha256=lo7D1x2RGo9SHkr2sIrY6wL4V5wbsxngnmBMbn5-o_I,4177
+stouputils/parallel/capturer.py,sha256=1ON8QuMrk9B0WS5lCIKtItzKRmlddrHsJAhMHYvKFyE,4127
 stouputils/parallel/capturer.pyi,sha256=DWa3biPFzrGJBmkaFhAWwhbX4gbKQAipBAOJm4_XBy8,1665
 stouputils/parallel/common.py,sha256=niDcAiEX3flX0ow91gXOB4umlOrR8PIYvpcKPClJHfM,4910
 stouputils/parallel/common.pyi,sha256=jbyftOYHKP2qaA8YC1f1f12-BDBkhfsQsnPdsR4oet8,2493
 stouputils/parallel/multi.py,sha256=tHJgcQJwsI6QeKEHoGJC4tsVK_6t1Fazkb06i1u-W_8,12610
 stouputils/parallel/multi.pyi,sha256=DWolZn1UoXxOfuw7LqEJcU8aQJsN-_DRhPGJlJCA5pQ,8021
-stouputils/parallel/subprocess.py,sha256=YD9mda-zMRpudlby4cLwLJxIY5BjPwn8K11eJ-3k-6E,5790
-stouputils/parallel/subprocess.pyi,sha256=9g5FDYfcnIikd9OOtDP1u_NPT2elk5YjUsQN9eIMSso,3145
-stouputils/print.py,sha256=PNyKvKheI7ior_-jQQ0Xu8ym7tSctheyHXTFykw2MKc,24552
-stouputils/print.pyi,sha256=0z-BFpOEZ48GBGcD08C4Be67cPKX4ZxSHqKyOLRS_M8,10205
+stouputils/parallel/subprocess.py,sha256=LWbwwAmnz54dCz9TAcKNg1TOMCVSP0C-0GIXaS5nVx0,6728
+stouputils/parallel/subprocess.pyi,sha256=gzRtpTslvoENLtSNk79fe3Xz8lV3IwuopT9uMHW9BTU,3680
+stouputils/print.py,sha256=WITobaFWrnVfrE4YRwHTRzf6H6V0BhxSIoQ9LRIrRiQ,24831
+stouputils/print.pyi,sha256=GOgbg7YomG-D9n2hcM0bUOaUU1PBjazWIn4vUSBYDDU,10365
 stouputils/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
 stouputils/typing.py,sha256=TwvxrvxhBRkyHkoOpfyXebN13M3xJb8MAjKXiNIWjew,2205
 stouputils/typing.pyi,sha256=U2UmFZausMYpnsUQROQE2JOwHcjx2hKV0rJuOdR57Ew,1341
 stouputils/version_pkg.py,sha256=Jsp-s03L14DkiZ94vQgrlQmaxApfn9DC8M_nzT1SJLk,7014
 stouputils/version_pkg.pyi,sha256=QPvqp1U3QA-9C_CC1dT9Vahv1hXEhstbM7x5uzMZSsQ,755
-stouputils-1.18.1.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-stouputils-1.18.1.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
-stouputils-1.18.1.dist-info/METADATA,sha256=PWMcVUM25QN5JXf9cDGGl-xPQQc3evJlWk8QX6FliFQ,14011
-stouputils-1.18.1.dist-info/RECORD,,
+stouputils-1.18.3.dist-info/WHEEL,sha256=e_m4S054HL0hyR3CpOk-b7Q7fDX6BuFkgL5OjAExXas,80
+stouputils-1.18.3.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
+stouputils-1.18.3.dist-info/METADATA,sha256=jA1lFVcNiNE1xCh5-QlKwvLG-VRVpK-BKKms71jisoI,14011
+stouputils-1.18.3.dist-info/RECORD,,

{stouputils-1.18.1.dist-info → stouputils-1.18.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.26
+Generator: uv 0.9.27
 Root-Is-Purelib: true
 Tag: py3-none-any