stouputils 1.17.0__tar.gz → 1.18.1__tar.gz

{stouputils-1.17.0 → stouputils-1.18.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.17.0
+Version: 1.18.1
 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
@@ -25,6 +25,7 @@ Requires-Dist: mlflow ; extra == 'data-science'
 Requires-Dist: tensorflow ; extra == 'data-science'
 Requires-Dist: scikit-learn ; extra == 'data-science'
 Requires-Dist: pywavelets ; extra == 'data-science'
+Requires-Dist: mypy ; extra == 'docs'
 Requires-Dist: m2r2 ; extra == 'docs'
 Requires-Dist: myst-parser ; extra == 'docs'
 Requires-Dist: sphinx-copybutton ; extra == 'docs'

{stouputils-1.17.0 → stouputils-1.18.1}/pyproject.toml

@@ -8,7 +8,7 @@ module-root = ""
 
 [project]
 name = "stouputils"
-version = "1.17.0"
+version = "1.18.1"
 description = "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."
 readme = "README.md"
 keywords = ["utilities", "tools", "helpers", "development", "python"]
@@ -36,6 +36,7 @@ authors = [
 
 [project.optional-dependencies]
 docs = [
+    "mypy",
     "m2r2",
     "myst_parser",
     "sphinx_copybutton",

{stouputils-1.17.0 → stouputils-1.18.1}/stouputils/collections.py

@@ -17,7 +17,7 @@ import os
 import shutil
 import tempfile
 from collections.abc import Callable, Iterable
-from typing import TYPE_CHECKING, Any, Literal, TypeVar
+from typing import TYPE_CHECKING, Any, Literal
 
 # Lazy imports for typing
 if TYPE_CHECKING:
@@ -26,9 +26,6 @@ if TYPE_CHECKING:
 	import zarr  # pyright: ignore[reportMissingTypeStubs]
 	from numpy.typing import NDArray
 
-# Typing
-T = TypeVar("T")
-
 # Functions
 def unique_list[T](list_to_clean: Iterable[T], method: Literal["id", "hash", "str"] = "str") -> list[T]:
 	""" Remove duplicates from the list while keeping the order using ids, hash, or str
@@ -79,7 +76,7 @@ def unique_list[T](list_to_clean: Iterable[T], method: Literal["id", "hash", "st
 	return result
 
 
-def at_least_n(iterable: Iterable[T], predicate: Callable[[T], bool], n: int) -> bool:
+def at_least_n[T](iterable: Iterable[T], predicate: Callable[[T], bool], n: int) -> bool:
 	""" Return True if at least n elements in iterable satisfy predicate.
 	It's like the built-in any() but for at least n matches.
 
@@ -135,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
@@ -158,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-1.17.0 → stouputils-1.18.1}/stouputils/collections.pyi

@@ -2,9 +2,7 @@ import polars as pl
 import zarr
 from collections.abc import Callable as Callable, Iterable
 from numpy.typing import NDArray as NDArray
-from typing import Any, Literal, TypeVar
-
-T = TypeVar('T')
+from typing import Any, Literal
 
 def unique_list[T](list_to_clean: Iterable[T], method: Literal['id', 'hash', 'str'] = 'str') -> list[T]:
     ''' Remove duplicates from the list while keeping the order using ids, hash, or str
@@ -31,7 +29,7 @@ def unique_list[T](list_to_clean: Iterable[T], method: Literal['id', 'hash', 'st
 \t\t>>> unique_list([s1, s2, s1, s1, s3, s2, s3], method="str")
 \t\t[{1, 2, 3}, {2, 3, 4}]
 \t'''
-def at_least_n(iterable: Iterable[T], predicate: Callable[[T], bool], n: int) -> bool:
+def at_least_n[T](iterable: Iterable[T], predicate: Callable[[T], bool], n: int) -> bool:
     """ Return True if at least n elements in iterable satisfy predicate.
 \tIt's like the built-in any() but for at least n matches.
 
@@ -71,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-1.17.0 → stouputils-1.18.1}/stouputils/continuous_delivery/stubs.py

@@ -29,7 +29,7 @@ def generate_stubs(
 	try:
 		from mypy.stubgen import main as stubgen_main
 	except ImportError as e:
-		raise ImportError("mypy is required for array_to_disk function. Please install it via 'pip install mypy'.") from e
+		raise ImportError("mypy is required for generate_stubs function. Please install it via 'pip install mypy'.") from e
 	try:
 		stubgen_main(["-p", package_name, *extra_args.split()])
 		return 0

{stouputils-1.17.0 → stouputils-1.18.1}/stouputils/ctx.py

@@ -20,13 +20,11 @@ import sys
 import time
 from collections.abc import Callable
 from contextlib import AbstractAsyncContextManager, AbstractContextManager
-from typing import IO, Any, TextIO, TypeVar
+from typing import IO, Any, TextIO
 
 from .io import super_open
 from .print import TeeMultiOutput, debug
 
-# Type variable for context managers
-T = TypeVar("T")
 
 # Abstract base class for context managers supporting both sync and async usage
 class AbstractBothContextManager[T](AbstractContextManager[T], AbstractAsyncContextManager[T]):

{stouputils-1.17.0 → stouputils-1.18.1}/stouputils/ctx.pyi

@@ -3,9 +3,7 @@ from .io import super_open as super_open
 from .print import TeeMultiOutput as TeeMultiOutput, debug as debug
 from collections.abc import Callable as Callable
 from contextlib import AbstractAsyncContextManager, AbstractContextManager
-from typing import Any, IO, TextIO, TypeVar
-
-T = TypeVar('T')
+from typing import Any, IO, TextIO
 
 class AbstractBothContextManager[T](AbstractContextManager[T], AbstractAsyncContextManager[T], metaclass=abc.ABCMeta):
     """ Abstract base class for context managers that support both synchronous and asynchronous usage. """

{stouputils-1.17.0 → stouputils-1.18.1}/stouputils/image.py

@@ -12,7 +12,7 @@ See stouputils.data_science.data_processing for lots more image processing utili
 # Imports
 import os
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any, TypeVar, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from .io import super_open
 from .print import debug, info
@@ -22,15 +22,13 @@ if TYPE_CHECKING:
 	from numpy.typing import NDArray
 	from PIL import Image
 
-PIL_Image_or_NDArray = TypeVar("PIL_Image_or_NDArray", bound="Image.Image | NDArray[np.number]")
-
 # Functions
-def image_resize[PIL_Image_or_NDArray](
-	image: PIL_Image_or_NDArray,
+def image_resize[T: "Image.Image | NDArray[np.number]"](
+	image: T,
 	max_result_size: int,
 	resampling: "Image.Resampling | None" = None,
 	min_or_max: Callable[[int, int], int] = max,
-	return_type: type[PIL_Image_or_NDArray] | str = "same",
+	return_type: type[T] | str = "same",
 	keep_aspect_ratio: bool = True,
 ) -> Any:
 	""" Resize an image while preserving its aspect ratio by default.
@@ -121,11 +119,11 @@ def image_resize[PIL_Image_or_NDArray](
 		return new_image
 
 
-def auto_crop[PIL_Image_or_NDArray](
-	image: PIL_Image_or_NDArray,
+def auto_crop[T: "Image.Image | NDArray[np.number]"](
+	image: T,
 	mask: "NDArray[np.bool_] | None" = None,
 	threshold: int | float | Callable[["NDArray[np.number]"], int | float] | None = None,
-	return_type: type[PIL_Image_or_NDArray] | str = "same",
+	return_type: type[T] | str = "same",
 	contiguous: bool = True,
 ) -> Any:
 	""" Automatically crop an image to remove zero or uniform regions.

{stouputils-1.17.0 → stouputils-1.18.1}/stouputils/image.pyi

@@ -4,11 +4,9 @@ from .print import debug as debug, info as info
 from PIL import Image
 from collections.abc import Callable
 from numpy.typing import NDArray as NDArray
-from typing import Any, TypeVar
+from typing import Any
 
-PIL_Image_or_NDArray = TypeVar('PIL_Image_or_NDArray', bound='Image.Image | NDArray[np.number]')
-
-def image_resize[PIL_Image_or_NDArray](image: PIL_Image_or_NDArray, max_result_size: int, resampling: Image.Resampling | None = None, min_or_max: Callable[[int, int], int] = ..., return_type: type[PIL_Image_or_NDArray] | str = 'same', keep_aspect_ratio: bool = True) -> Any:
+def image_resize[T: Image.Image | NDArray[np.number]](image: T, max_result_size: int, resampling: Image.Resampling | None = None, min_or_max: Callable[[int, int], int] = ..., return_type: type[T] | str = 'same', keep_aspect_ratio: bool = True) -> Any:
     ''' Resize an image while preserving its aspect ratio by default.
 \tScales the image so that its largest dimension equals max_result_size.
 
@@ -47,7 +45,7 @@ def image_resize[PIL_Image_or_NDArray](image: PIL_Image_or_NDArray, max_result_s
 \t\t>>> image_resize(pil_image, 50, resampling=Image.Resampling.NEAREST).size
 \t\t(50, 25)
 \t'''
-def auto_crop[PIL_Image_or_NDArray](image: PIL_Image_or_NDArray, mask: NDArray[np.bool_] | None = None, threshold: int | float | Callable[[NDArray[np.number]], int | float] | None = None, return_type: type[PIL_Image_or_NDArray] | str = 'same', contiguous: bool = True) -> Any:
+def auto_crop[T: Image.Image | NDArray[np.number]](image: T, mask: NDArray[np.bool_] | None = None, threshold: int | float | Callable[[NDArray[np.number]], int | float] | None = None, return_type: type[T] | str = 'same', contiguous: bool = True) -> Any:
     ''' Automatically crop an image to remove zero or uniform regions.
 
 \tThis function crops the image to keep only the region where pixels are non-zero

{stouputils-1.17.0 → stouputils-1.18.1}/stouputils/io.py

@@ -11,6 +11,7 @@ This module provides utilities for file management.
 - super_open: Open a file with the given mode, creating the directory if it doesn't exist (only if writing)
 - replace_tilde: Replace the "~" by the user's home directory
 - clean_path: Clean the path by replacing backslashes with forward slashes and simplifying the path
+- safe_close: Safely close a file descriptor or file object after flushing, ignoring any exceptions
 
 .. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/io_module.gif
   :alt: stouputils io examples
@@ -491,3 +492,23 @@ 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:
+	""" Safely close a file object (or file descriptor) after flushing, ignoring any exceptions.
+
+	Args:
+		file (IO[Any] | int | None): The file object or file descriptor to close
+	"""
+	if isinstance(file, int):
+		if file != -1:
+			for func in (os.fsync, os.close):
+				try:
+					func(file)
+				except Exception:
+					pass
+	elif file:
+		for func in (file.flush, file.close):
+			try:
+				func()
+			except Exception:
+				pass
+

{stouputils-1.17.0 → stouputils-1.18.1}/stouputils/io.pyi

@@ -211,3 +211,9 @@ 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:
+    """ Safely close a file object (or file descriptor) after flushing, ignoring any exceptions.
+
+\tArgs:
+\t\tfile (IO[Any] | int | None): The file object or file descriptor to close
+\t"""

stouputils-1.18.1/stouputils/parallel/__init__.py

@@ -0,0 +1,29 @@
+"""
+This module provides utility functions for parallel processing, such as:
+
+- multiprocessing(): Execute a function in parallel using multiprocessing
+- multithreading(): Execute a function in parallel using multithreading
+- run_in_subprocess(): Execute a function in a subprocess with args and kwargs
+
+I highly encourage you to read the function docstrings to understand when to use each method.
+
+Priority (nice) mapping for multiprocessing():
+
+- Unix-style values from -20 (highest priority) to 19 (lowest priority)
+- Windows automatic mapping:
+  * -20 to -10: HIGH_PRIORITY_CLASS
+  * -9 to -1: ABOVE_NORMAL_PRIORITY_CLASS
+  * 0: NORMAL_PRIORITY_CLASS
+  * 1 to 9: BELOW_NORMAL_PRIORITY_CLASS
+  * 10 to 19: IDLE_PRIORITY_CLASS
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/parallel_module.gif
+  :alt: stouputils parallel examples
+"""
+
+# Imports
+from .capturer import *
+from .common import *
+from .multi import *
+from .subprocess import *
+

stouputils-1.18.1/stouputils/parallel/__init__.pyi

@@ -0,0 +1,4 @@
+from .capturer import *
+from .common import *
+from .multi import *
+from .subprocess import *

stouputils-1.18.1/stouputils/parallel/capturer.py

@@ -0,0 +1,133 @@
+
+# Imports
+import os
+from typing import IO, Any
+
+from ..io import safe_close
+
+
+class PipeWriter:
+	""" A writer that sends data to a multiprocessing Connection. """
+	def __init__(self, conn: Any, encoding: str, errors: str):
+		self.conn: Any = conn
+		self.encoding: str = encoding
+		self.errors: str = errors
+
+	def write(self, data: str) -> int:
+		self.conn.send_bytes(data.encode(self.encoding, errors=self.errors))
+		return len(data)
+
+	def flush(self) -> None:
+		pass
+
+
+class CaptureOutput:
+	""" Utility to capture stdout/stderr from a subprocess and relay it to the parent's stdout.
+
+	The class creates an os.pipe(), marks fds as inheritable (for spawn method),
+	provides methods to start a listener thread that reads from the pipe and writes
+	to the main process's sys.stdout/sys.stderr, and to close/join the listener.
+	"""
+	def __init__(self, encoding: str = "utf-8", errors: str = "replace", chunk_size: int = 1024):
+		import multiprocessing as mp
+		import threading
+		self.encoding: str = encoding
+		self.errors: str = errors
+		self.chunk_size: int = chunk_size
+		self.read_conn, self.write_conn = mp.Pipe(duplex=False)
+		self.read_fd = self.read_conn.fileno()
+		self.write_fd = self.write_conn.fileno()
+		# Internal state for the listener thread and reader handle
+		self._thread: threading.Thread | None = None
+		self._reader_file: IO[Any] | None = None
+		# Sentinel string that will terminate the listener when seen in the stream
+		try:
+			os.set_inheritable(self.read_fd, True)
+			os.set_inheritable(self.write_fd, True)
+		except Exception:
+			pass
+
+	def __repr__(self) -> str:
+		return f"<CaptureOutput read_fd={self.read_fd} write_fd={self.write_fd}>"
+
+	# Pickle support: exclude unpicklable attributes
+	def __getstate__(self) -> dict[str, Any]:
+		state = self.__dict__.copy()
+		state["_thread"] = None
+		return state
+
+	def redirect(self) -> None:
+		""" Redirect sys.stdout and sys.stderr to the pipe's write end. """
+		import sys
+		writer = PipeWriter(self.write_conn, self.encoding, self.errors)
+		sys.stdout = writer
+		sys.stderr = writer
+
+	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()
+		self.write_fd = -1	# Prevent accidental reuse
+
+	def start_listener(self) -> None:
+		""" Start a daemon thread that forwards data from the pipe to sys.stdout/sys.stderr. """
+		import sys
+		if self._thread is not None:
+			return
+
+		# Handler function for reading from the pipe
+		buffer: str = ""
+		def _handle_buffer() -> None:
+			nonlocal buffer
+			if buffer:
+				try:
+					sys.stdout.write(buffer)
+					sys.stdout.flush()
+				except Exception:
+					pass
+				buffer = ""
+
+		# Thread target function
+		def _reader() -> None:
+			nonlocal buffer
+			try:
+				while True:
+					# Read a chunk from the pipe, stop loop on error
+					try:
+						data: bytes = self.read_conn.recv_bytes(self.chunk_size)
+					except EOFError:
+						_handle_buffer()
+						break
+
+					# Decode bytes to text & append to buffer
+					try:
+						chunk: str = data.decode(self.encoding, errors=self.errors)
+					except Exception:
+						chunk = data.decode(self.encoding, errors="replace")
+					buffer += chunk
+
+					# Periodically flush large buffers to avoid holding too much memory
+					if len(buffer) > self.chunk_size * 4:
+						_handle_buffer()
+			finally:
+				safe_close(self.read_fd)
+				self.read_conn.close()
+				self.read_fd = -1
+				self._thread = None		# Mark thread as stopped so callers don't block unnecessarily
+
+		# Start the listener thread
+		import threading
+		self._thread = threading.Thread(target=_reader, daemon=True)
+		self._thread.start()
+
+	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()
+		self._thread.join(timeout)
+
+		# If thread finished, ensure read fd is closed and clear thread
+		if self._thread and not self._thread.is_alive():
+			self._thread = None
+

stouputils-1.18.1/stouputils/parallel/capturer.pyi

@@ -0,0 +1,38 @@
+from ..io import safe_close as safe_close
+from _typeshed import Incomplete
+from typing import Any, IO
+
+class PipeWriter:
+    """ A writer that sends data to a multiprocessing Connection. """
+    conn: Any
+    encoding: str
+    errors: str
+    def __init__(self, conn: Any, encoding: str, errors: str) -> None: ...
+    def write(self, data: str) -> int: ...
+    def flush(self) -> None: ...
+
+class CaptureOutput:
+    """ Utility to capture stdout/stderr from a subprocess and relay it to the parent's stdout.
+
+\tThe class creates an os.pipe(), marks fds as inheritable (for spawn method),
+\tprovides methods to start a listener thread that reads from the pipe and writes
+\tto the main process's sys.stdout/sys.stderr, and to close/join the listener.
+\t"""
+    encoding: str
+    errors: str
+    chunk_size: int
+    read_fd: Incomplete
+    write_fd: Incomplete
+    _thread: threading.Thread | None
+    _reader_file: IO[Any] | None
+    def __init__(self, encoding: str = 'utf-8', errors: str = 'replace', chunk_size: int = 1024) -> None: ...
+    def __repr__(self) -> str: ...
+    def __getstate__(self) -> dict[str, Any]: ...
+    def redirect(self) -> None:
+        """ Redirect sys.stdout and sys.stderr to the pipe's write end. """
+    def parent_close_write(self) -> None:
+        """ Close the parent's copy of the write end; the child's copy remains. """
+    def start_listener(self) -> None:
+        """ Start a daemon thread that forwards data from the pipe to sys.stdout/sys.stderr. """
+    def join_listener(self, timeout: float | None = None) -> None:
+        """ Wait for the listener thread to finish (until EOF). """