stouputils 1.18.0__py3-none-any.whl → 1.18.2__py3-none-any.whl

stouputils/collections.py

@@ -132,16 +132,45 @@ def sort_dict_keys[T](dictionary: dict[T, Any], order: list[T], reverse: bool =
 def upsert_in_dataframe(
 	df: "pl.DataFrame",
 	new_entry: dict[str, Any],
-	primary_keys: dict[str, Any] | None = None
+	primary_keys: list[str] | dict[str, Any] | None = None
 ) -> "pl.DataFrame":
 	""" Insert or update a row in the Polars DataFrame based on primary keys.
 
 	Args:
 		df				(pl.DataFrame):		The Polars DataFrame to update.
 		new_entry		(dict[str, Any]):	The new entry to insert or update.
-		primary_keys	(dict[str, Any]):	The primary keys to identify the row (default: empty).
+		primary_keys	(list[str] | dict[str, Any] | None):	The primary keys to identify the row (for updates).
 	Returns:
 		pl.DataFrame: The updated Polars DataFrame.
+	Examples:
+		>>> import polars as pl
+		>>> df = pl.DataFrame({"id": [1, 2], "value": ["a", "b"]})
+		>>> new_entry = {"id": 2, "value": "updated"}
+		>>> updated_df = upsert_in_dataframe(df, new_entry, primary_keys=["id"])
+		>>> print(updated_df)
+		shape: (2, 2)
+		┌─────┬─────────┐
+		│ id  ┆ value   │
+		│ --- ┆ ---     │
+		│ i64 ┆ str     │
+		╞═════╪═════════╡
+		│ 1   ┆ a       │
+		│ 2   ┆ updated │
+		└─────┴─────────┘
+
+		>>> new_entry = {"id": 3, "value": "new"}
+		>>> updated_df = upsert_in_dataframe(updated_df, new_entry, primary_keys=["id"])
+		>>> print(updated_df)
+		shape: (3, 2)
+		┌─────┬─────────┐
+		│ id  ┆ value   │
+		│ --- ┆ ---     │
+		│ i64 ┆ str     │
+		╞═════╪═════════╡
+		│ 1   ┆ a       │
+		│ 2   ┆ updated │
+		│ 3   ┆ new     │
+		└─────┴─────────┘
 	"""
 	# Imports
 	import polars as pl
@@ -155,6 +184,10 @@ def upsert_in_dataframe(
 		new_row_df = pl.DataFrame([new_entry])
 		return pl.concat([df, new_row_df], how="diagonal_relaxed")
 
+	# If primary keys are provided as a list, convert to dict with values from new_entry
+	if isinstance(primary_keys, list):
+		primary_keys = {key: new_entry[key] for key in primary_keys if key in new_entry}
+
 	# Build mask based on primary keys
 	mask: pl.Expr = pl.lit(True)
 	for key, value in primary_keys.items():

stouputils/collections.pyi

@@ -69,16 +69,45 @@ def sort_dict_keys[T](dictionary: dict[T, Any], order: list[T], reverse: bool =
 \t\t>>> sort_dict_keys({\'b\': 2, \'a\': 1, \'c\': 3, \'d\': 4}, order=["c", "b"])
 \t\t{\'c\': 3, \'b\': 2, \'a\': 1, \'d\': 4}
 \t'''
-def upsert_in_dataframe(df: pl.DataFrame, new_entry: dict[str, Any], primary_keys: dict[str, Any] | None = None) -> pl.DataFrame:
-    """ Insert or update a row in the Polars DataFrame based on primary keys.
+def upsert_in_dataframe(df: pl.DataFrame, new_entry: dict[str, Any], primary_keys: list[str] | dict[str, Any] | None = None) -> pl.DataFrame:
+    ''' Insert or update a row in the Polars DataFrame based on primary keys.
 
 \tArgs:
 \t\tdf\t\t\t\t(pl.DataFrame):\t\tThe Polars DataFrame to update.
 \t\tnew_entry\t\t(dict[str, Any]):\tThe new entry to insert or update.
-\t\tprimary_keys\t(dict[str, Any]):\tThe primary keys to identify the row (default: empty).
+\t\tprimary_keys\t(list[str] | dict[str, Any] | None):\tThe primary keys to identify the row (for updates).
 \tReturns:
 \t\tpl.DataFrame: The updated Polars DataFrame.
-\t"""
+\tExamples:
+\t\t>>> import polars as pl
+\t\t>>> df = pl.DataFrame({"id": [1, 2], "value": ["a", "b"]})
+\t\t>>> new_entry = {"id": 2, "value": "updated"}
+\t\t>>> updated_df = upsert_in_dataframe(df, new_entry, primary_keys=["id"])
+\t\t>>> print(updated_df)
+\t\tshape: (2, 2)
+\t\t┌─────┬─────────┐
+\t\t│ id  ┆ value   │
+\t\t│ --- ┆ ---     │
+\t\t│ i64 ┆ str     │
+\t\t╞═════╪═════════╡
+\t\t│ 1   ┆ a       │
+\t\t│ 2   ┆ updated │
+\t\t└─────┴─────────┘
+
+\t\t>>> new_entry = {"id": 3, "value": "new"}
+\t\t>>> updated_df = upsert_in_dataframe(updated_df, new_entry, primary_keys=["id"])
+\t\t>>> print(updated_df)
+\t\tshape: (3, 2)
+\t\t┌─────┬─────────┐
+\t\t│ id  ┆ value   │
+\t\t│ --- ┆ ---     │
+\t\t│ i64 ┆ str     │
+\t\t╞═════╪═════════╡
+\t\t│ 1   ┆ a       │
+\t\t│ 2   ┆ updated │
+\t\t│ 3   ┆ new     │
+\t\t└─────┴─────────┘
+\t'''
 def array_to_disk(data: NDArray[Any] | zarr.Array, delete_input: bool = True, more_data: NDArray[Any] | zarr.Array | None = None) -> tuple['zarr.Array', str, int]:
     """ Easily handle large numpy arrays on disk using zarr for efficient storage and access.
 

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-1.18.0.dist-info → stouputils-1.18.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.18.0
+Version: 1.18.2
 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.0.dist-info → stouputils-1.18.2.dist-info}/RECORD

@@ -21,8 +21,8 @@ stouputils/archive.py,sha256=uDrPFxbY_C8SwUZRH4FWnYSoJKkFWynCx751zP9AHaY,12144
 stouputils/archive.pyi,sha256=Z2BbQAiErRYntv53QC9uf_XPw3tx3Oy73wB0Bbil11c,3246
 stouputils/backup.py,sha256=AE5WKMLiyk0VkRUfhmNfO2EUeUbZY5GTFVIuI5z7axA,20947
 stouputils/backup.pyi,sha256=-SLVykkR5U8479T84zjNPVBNnV193s0zyWjathY2DDA,4923
-stouputils/collections.py,sha256=jUNJQaMhmgLetVyZrYm0FFiaU0RkBfuXeJEvJ7wyGzU,9815
-stouputils/collections.pyi,sha256=naOr5vsvu2SOW-IUFLaoyxYXVv0Vk5pC9zD_mmT0dg8,4297
+stouputils/collections.py,sha256=73799uJ5ryQoNBo7N4Cz41Q992QP_kSsw_hy33ZpDyw,11121
+stouputils/collections.pyi,sha256=jPzyaeesz1IqutuT69Bt4DFOguURjXbcYO2l2sifXRA,5448
 stouputils/continuous_delivery/__init__.py,sha256=JqPww29xZ-pp6OJDGhUj2dxyV9rgTTMUz0YDDVr9RaA,731
 stouputils/continuous_delivery/__init__.pyi,sha256=_Sz2D10n1CDEyY8qDFwXNKdr01HVxanY4qdq9aN19cc,117
 stouputils/continuous_delivery/cd_utils.py,sha256=fkaHk2V3j66uFAUsM2c_UddNhXW2KAQcrh7jVsH79pU,8594
@@ -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,14 +141,14 @@ 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/parallel/subprocess.py,sha256=LWbwwAmnz54dCz9TAcKNg1TOMCVSP0C-0GIXaS5nVx0,6728
+stouputils/parallel/subprocess.pyi,sha256=gzRtpTslvoENLtSNk79fe3Xz8lV3IwuopT9uMHW9BTU,3680
 stouputils/print.py,sha256=PNyKvKheI7ior_-jQQ0Xu8ym7tSctheyHXTFykw2MKc,24552
 stouputils/print.pyi,sha256=0z-BFpOEZ48GBGcD08C4Be67cPKX4ZxSHqKyOLRS_M8,10205
 stouputils/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
@@ -156,7 +156,7 @@ 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.0.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-stouputils-1.18.0.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
-stouputils-1.18.0.dist-info/METADATA,sha256=OrIKAYzFOAG8DIJjpNj2UQzc2QW7iRSH_PS3yc6EnMQ,14011
-stouputils-1.18.0.dist-info/RECORD,,
+stouputils-1.18.2.dist-info/WHEEL,sha256=e_m4S054HL0hyR3CpOk-b7Q7fDX6BuFkgL5OjAExXas,80
+stouputils-1.18.2.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
+stouputils-1.18.2.dist-info/METADATA,sha256=74JWSrmZCgZa1xNxkPpitRGeL9SUre0dE8dFIY8BosA,14011
+stouputils-1.18.2.dist-info/RECORD,,

{stouputils-1.18.0.dist-info → stouputils-1.18.2.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