pipeline-toolkit 0.1.0__py3-none-any.whl

pipeline/__init__.py

@@ -0,0 +1,24 @@
+"""A small functional pipeline toolkit for Python.
+
+This package provides a simple asynchronous pipeline executor along with supporting container and utility components.
+
+The main components are:
+
+	- :class:`Pipeline`: Execute callable steps sequentially in a worker thread.
+	- :class:`Stack`: A simple LIFO container for storing values and errors.
+	- :func:`tap`: Apply a side effect to a deep copy of a value while returning the original value unchanged.
+
+Example:
+	>>> from pipeline import Pipeline
+	>>> pipeline = Pipeline(
+	...     (lambda value: value + 1,),
+	...     (lambda value: value * 2,),
+	... )
+	>>> pipeline.run(5).wait()
+	>>> pipeline.results.get()
+	12
+"""
+from .pipeline import Pipeline
+__version__ = "0.1.0"
+__author__ = "Hoàng Long"
+__all__ = ["__version__", "__author__", "Pipeline"]

pipeline/pipeline.py

@@ -0,0 +1,317 @@
+from .stack import Stack
+from collections.abc import Mapping
+import threading
+class Pipeline:
+	"""A simple asynchronous pipeline for executing callable steps sequentially.
+
+	Each step is represented by a tuple containing a callable and optional positional and keyword arguments:
+
+		(function,)
+		(function, args)
+		(function, kwargs)
+		(function, args, kwargs)
+
+	Where ``args`` must be a tuple or mapping, and ``kwargs`` must be a mapping.
+	The pipeline always passes the result of the previous step as the first positional argument to the next step.
+	The pipeline is snapshotted when execution starts, so modifications to the pipeline after ``run()`` has started do not affect the current execution.
+
+	Args:
+		iterable: An iterable of pipeline steps. Defaults to an empty pipeline.
+
+	Attributes:
+		stop_event: Event used to request that the worker stop execution.
+		skip_event: Event used to request that the next step be skipped.
+		pipeline: List containing the configured pipeline steps.
+		thread: The worker thread for the current execution, or ``None`` when no execution is active.
+		step: The one-based index of the currently executing step, or ``0`` when the pipeline is not running.
+		results: Stack containing the initial value and results produced by executed steps.
+		errors: Stack containing exceptions raised by executed steps.
+
+	Example:
+		>>> def add(value, amount):
+			...     return value + amount
+
+		>>> pipeline = Pipeline([
+		...     (add, (5,)),
+		...     (add, (10,)),
+		... ])
+		>>> pipeline.run(0)
+		>>> pipeline.wait()
+		>>> pipeline.results.get()
+		15
+	"""
+	def __init__(self, iterable=()):
+		"""Initialize a pipeline.
+
+		Args:
+			iterable: An iterable containing pipeline steps.
+
+		Raises:
+			TypeError: If any item in ``iterable`` is not a valid step.
+		"""
+		iterable = tuple(iterable)
+		self.stop_event = threading.Event()
+		self.skip_event = threading.Event()
+		self.pipeline = []
+		self.thread = None
+		self.step = 0
+		self.results = Stack()
+		self.errors = Stack()
+		for step in iterable:
+			self._validate_step(step)
+			self.pipeline.append(step)
+	def _validate_step(self, step):
+		if not step or not isinstance(step, tuple):
+			raise TypeError("Invalid step format.")
+		if not callable(step[0]):
+			raise TypeError("Invalid step format.")
+		if len(step) > 3:
+			raise TypeError("Invalid step format.")
+		if len(step) >= 2 and not isinstance(step[1], (tuple, Mapping)):
+			raise TypeError("Invalid step format.")
+		if len(step) == 3 and not isinstance(step[1], tuple):
+			raise TypeError("Invalid step format.")
+		if len(step) == 3 and not isinstance(step[2], Mapping):
+			raise TypeError("Invalid step format.")
+	def _execute_step(self, step, default):
+		if len(step) == 1:
+			return step[0](default)
+		if isinstance(step[1], tuple):
+			return step[0](default, *step[1], **step[2]) if len(step) > 2 else step[0](default, *step[1])
+		return step[0](default, **step[1])
+	def run(self, default=None, delay=0, daemon=False, stop_on_error=True):
+		"""Run the pipeline asynchronously in a worker thread.
+
+		The supplied ``default`` value is stored as the initial result.
+		Each step receives the result of the preceding step as its first positional argument.
+
+		The pipeline is snapshotted when execution starts, so modifications to ``self.pipeline`` do not affect the current execution.
+		Execution stops when all steps have completed, ``stop()`` is called, or an exception is raised while ``stop_on_error`` is enabled.
+
+		Args:
+			default: Initial value passed to the first step.
+				Defaults to ``None``.
+			delay: Delay in seconds between steps. Must be a non-negative integer or floating-point number.
+				Defaults to ``0``.
+			daemon: Whether the worker thread should be a daemon thread.
+				Defaults to ``False``.
+			stop_on_error: Whether execution should stop after the first exception.
+				Defaults to ``True``.
+
+		Returns:
+			This pipeline instance.
+
+		Raises:
+			TypeError: If ``delay`` is not an integer or floating-point number.
+			ValueError: If ``delay`` is negative.
+			RuntimeError: If the pipeline is already running.
+		"""
+		if not isinstance(delay, (int, float)):
+			raise TypeError("Delay is not int or float.")
+		if delay < 0:
+			raise ValueError("Delay cannot be negative.")
+		if self.running:
+			raise RuntimeError("Pipeline is already running.")
+		self.stop_event.clear()
+		self.skip_event.clear()
+		pipeline = tuple(self.pipeline)
+		self.step = 0
+		self.results.clear()
+		self.results.push(default)
+		self.errors.clear()
+		def worker():
+			for index, step in enumerate(pipeline):
+				if self.stop_event.is_set():
+					break
+				self.step = index + 1
+				if self.skip_event.is_set():
+					self.skip_event.clear()
+					continue
+				try:
+					self.results.push(self._execute_step(step, self.results.get()))
+				except Exception as error:
+					self.errors.push(error)
+					if stop_on_error:
+						break
+				if delay:
+					self.stop_event.wait(delay)
+			if not self.stop_event.is_set():
+				self.step = 0
+			self.thread = None
+		self.thread = threading.Thread(target=worker, daemon=daemon)
+		self.thread.start()
+		return self
+	def run_step(self, step, default):
+		"""Execute a single pipeline step synchronously.
+
+		This method does not create or modify the worker thread and does not store the result or exception in the pipeline's ``results`` or ``errors`` stacks.
+		Exceptions are allowed to propagate to the caller.
+
+		Args:
+			step: One-based index of the pipeline step to execute.
+			default: Value passed to the selected step as its first argument.
+
+		Returns:
+			The value returned by the selected step.
+
+		Raises:
+			TypeError: If ``step`` is not an integer.
+			ValueError: If ``step`` is less than ``1``.
+			IndexError: If ``step`` is outside the pipeline.
+			RuntimeError: If the pipeline is currently running.
+		"""
+		if not isinstance(step, int):
+			raise TypeError("Step is not int.")
+		if step < 1:
+			raise ValueError("Step < 1.")
+		if not 1 <= step <= len(self.pipeline):
+			raise IndexError("Step out of pipeline.")
+		if self.running:
+			raise RuntimeError("Pipeline is already running.")
+		step = self.pipeline[step - 1]
+		return self._execute_step(step, default)
+	def stop(self):
+		"""Request the running pipeline to stop and wait for termination.
+
+		Returns:
+			The one-based index of the step at which execution was stopped, or ``0`` if the pipeline was not running.
+		"""
+		if self.thread is not None and self.running:
+			self.stop_event.set()
+			self.thread.join()
+			step = self.step
+			self.step = 0
+			return step
+		return 0
+	def skip(self):
+		"""Request the currently running pipeline to skip its next step.
+
+		If the worker has not yet checked the skip event, the next step that reaches the worker's skip check will be skipped.
+
+		Returns:
+			This pipeline instance.
+		"""
+		if self.thread is not None and self.running:
+			self.skip_event.set()
+		return self
+	def wait(self):
+		"""Wait until the currently running pipeline finishes.
+
+		This method blocks only when the pipeline is running.
+
+		Returns:
+			This pipeline instance.
+		"""
+		if self.thread is not None and self.running:
+			self.thread.join()
+		return self
+	def rerun(self, *args, **kwargs):
+		"""Stop the current execution and start the pipeline again.
+
+		All arguments are passed directly to :meth:`run`.
+
+		Returns:
+			This pipeline instance.
+		"""
+		self.stop()
+		self.run(*args, **kwargs)
+		return self
+	@property
+	def running(self):
+		"""Whether the pipeline currently has a running worker thread."""
+		return self.thread is not None and self.thread.is_alive()
+	def add(self, step):
+		"""Append a validated step to the pipeline.
+
+		Args:
+			step: The step to append.
+
+		Raises:
+			TypeError: If ``step`` has an invalid format.
+		"""
+		self._validate_step(step)
+		self.pipeline.append(step)
+	def insert(self, index, step):
+		"""Insert a validated step at the specified index.
+
+		Args:
+			index: One-based position at which to insert the step.
+			step: The step to insert.
+
+		Raises:
+			TypeError: If ``index`` is not an integer or ``step`` is invalid.
+			IndexError: If ``index`` is outside the pipeline.
+		"""
+		if not isinstance(index, int):
+			raise TypeError(f"{index} is not int.")
+		if not 1 < index <= len(self.pipeline) + 1:
+			raise IndexError("Index out of range.")
+		self._validate_step(step)
+		self.pipeline.insert(index - 1, step)
+	def pop(self, index):
+		"""Remove and return the step at the specified index.
+
+		Args:
+			index: One-based index of the step to remove.
+
+		Returns:
+			The removed pipeline step.
+
+		Raises:
+			TypeError: If ``index`` is not an integer.
+			IndexError: If ``index`` is outside the pipeline.
+		"""
+		if not isinstance(index, int):
+			raise TypeError(f"{index} is not int.")
+		if not 1 <= index <= len(self.pipeline):
+			raise IndexError("Index out of range.")
+		return self.pipeline.pop(index - 1)
+	def clear(self):
+		"""Remove all steps from the pipeline."""
+		self.pipeline.clear()
+	def _format_step(self, step):
+		func = step[0]
+		if len(step) >= 2:
+			args = step[1]
+		else:
+			args = ()
+		if isinstance(args, tuple):
+			parts = [repr(arg) for arg in args]
+			if len(step) == 3:
+				parts.extend(f"{key}={value!r}" for key, value in step[2].items())
+		else:
+			parts = [f"{key}={value!r}" for key, value in args.items()]
+		return f"{func.__name__}({', '.join(parts)})"
+	def __str__(self):
+		"""Return a human-readable representation of the pipeline."""
+		return " | ".join(self._format_step(step) for step in self.pipeline)
+	def __repr__(self):
+		"""Return the developer-oriented representation of the pipeline."""
+		return f"{type(self).__name__}(total_steps={len(self.pipeline)}, current_step={self.step}, running={self.running})"
+	def __bool__(self):
+		"""Return whether the pipeline is currently running."""
+		return self.running
+	def __call__(self, *args, **kwargs):
+		"""Run the pipeline.
+
+		Arguments are passed directly to :meth:`run`.
+
+		Returns:
+			This pipeline instance.
+		"""
+		return self.run(*args, **kwargs)
+	def __contains__(self, item):
+		"""Return whether a callable exists as a pipeline step.
+
+		Identity comparison is used, so the callable must be the exact same object as the callable stored in the step.
+
+		Args:
+			item: Callable to search for.
+
+		Returns:
+			``True`` if the callable is present, otherwise ``False``.
+		"""
+		return any(step[0] is item for step in self.pipeline)
+	def __len__(self):
+		"""Return the number of configured pipeline steps."""
+		return len(self.pipeline)

pipeline/stack.py

@@ -0,0 +1,132 @@
+class StackOverflowError(Exception):
+	"""Raised when attempting to push an item onto a full stack."""
+	pass
+class StackUnderflowError(Exception):
+	"""Raised when attempting to access or remove an item from an empty stack."""
+	pass
+class Stack:
+	"""A simple LIFO stack container with optional maximum capacity.
+
+	The stack follows the Last-In, First-Out (LIFO) principle. The most recently pushed item is returned by :meth:`get` or removed by :meth:`pop`.
+
+	A maximum size can optionally be specified.
+	A ``maxsize`` of ``0`` means that the stack has no size limit.
+
+	Args:
+		maxsize: Maximum number of items allowed in the stack.
+			Defaults to ``0``, meaning unlimited capacity.
+
+	Raises:
+		TypeError: If ``maxsize`` is not an integer.
+		ValueError: If ``maxsize`` is negative.
+
+	Example:
+		>>> stack = Stack(3)
+		>>> stack.push("first")
+		>>> stack.push("second")
+		>>> stack.get()
+		'second'
+		>>> stack.pop()
+		'second'
+		>>> len(stack)
+		1
+	"""
+	def __init__(self, maxsize=0):
+		"""Initialize an empty stack.
+
+		Args:
+			maxsize: Maximum number of items allowed in the stack.
+				``0`` means unlimited capacity.
+
+		Raises:
+			TypeError: If ``maxsize`` is not an integer.
+			ValueError: If ``maxsize`` is negative.
+		"""
+		if not isinstance(maxsize, int):
+			raise TypeError("maxsize is not int.")
+		if maxsize < 0:
+			raise ValueError("maxsize < 0.")
+		self._maxsize = maxsize
+		self._stack = []
+	def push(self, value):
+		"""Push an item onto the top of the stack.
+
+		Args:
+			value: Value to push onto the stack.
+
+		Raises:
+			StackOverflowError: If the stack has reached its maximum capacity.
+		"""
+		if self._maxsize and len(self._stack) >= self._maxsize:
+			raise StackOverflowError("stack overflow")
+		self._stack.append(value)
+	def get(self):
+		"""Return the item at the top of the stack without removing it.
+
+		Returns:
+			The most recently pushed item.
+
+		Raises:
+			StackUnderflowError: If the stack is empty.
+		"""
+		if not self._stack:
+			raise StackUnderflowError("stack underflow")
+		return self._stack[-1]
+	def pop(self):
+		"""Remove and return the item at the top of the stack.
+
+		Returns:
+			The most recently pushed item.
+
+		Raises:
+			StackUnderflowError: If the stack is empty.
+		"""
+		if not self._stack:
+			raise StackUnderflowError("stack underflow")
+		return self._stack.pop()
+	def clear(self):
+		"""Remove all items from the stack."""
+		self._stack.clear()
+	def empty(self):
+		"""Return whether the stack is empty.
+
+		Returns:
+			``True`` if the stack contains no items, otherwise ``False``.
+		"""
+		return len(self._stack) == 0
+	def full(self):
+		"""Return whether the stack has reached its maximum capacity.
+
+		An unlimited stack is never considered full.
+
+		Returns:
+			``True`` if the stack is full, otherwise ``False``.
+		"""
+		return bool(self._maxsize and len(self._stack) >= self._maxsize)
+	def __len__(self):
+		"""Return the number of items currently in the stack."""
+		return len(self._stack)
+	def __bool__(self):
+		"""Return whether the stack contains at least one item."""
+		return bool(self._stack)
+	def __contains__(self, value):
+		"""Return whether a value exists in the stack.
+
+		Args:
+			value: Value to search for.
+
+		Returns:
+			``True`` if ``value`` is present, otherwise ``False``.
+		"""
+		return value in self._stack
+	def __iter__(self):
+		"""Iterate over the items in the stack from bottom to top.
+
+		Returns:
+			An iterator over the stack's items.
+		"""
+		for item in self._stack:
+			yield item
+	def __repr__(self):
+		"""Return the developer-oriented representation of the stack."""
+		return f"{type(self).__name__}({self._stack!r}, maxsize={self._maxsize})"

pipeline/tap.py

@@ -0,0 +1,43 @@
+import copy
+def tap(value, function, *args, **kwargs):
+	"""Apply a function to a deep copy of a value and return the original value.
+
+	The function is called for its side effect.
+	A deep copy of ``value`` is passed to the function, so modifications made by the function do not affect the original value.
+
+	The return value of ``function`` is ignored.
+	This makes ``tap`` useful for inspecting, logging, debugging, or otherwise processing a value without interrupting a chain of operations.
+
+	Args:
+		value: Value to pass to ``function`` and return unchanged.
+		function: Callable to invoke with a deep copy of ``value``.
+		*args: Additional positional arguments passed to ``function``.
+		**kwargs: Additional keyword arguments passed to ``function``.
+
+	Returns:
+		The original ``value`` object.
+
+	Raises:
+		TypeError: If ``function`` is not callable.
+		Any exception raised by ``copy.deepcopy`` or ``function`` is propagated to the caller.
+
+	Example:
+		>>> data = {"items": [1, 2, 3]}
+		>>> tap(data, print)
+		{'items': [1, 2, 3]}
+
+		A function can modify its argument without modifying the original:
+
+		>>> def inspect(data):
+			...     data["items"].append(4)
+		>>> original = {"items": [1, 2, 3]}
+		>>> result = tap(original, inspect)
+		>>> result is original
+		True
+		>>> original
+		{'items': [1, 2, 3]}
+	"""
+	if not callable(function):
+		raise TypeError("function is not callable.")
+	function(copy.deepcopy(value), *args, **kwargs)
+	return value

pipeline_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,477 @@
+Metadata-Version: 2.4
+Name: pipeline-toolkit
+Version: 0.1.0
+Summary: A small functional pipeline toolkit for Python.
+Author-email: Hoàng Long <hoanglongcodes@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Hoang-Long2012/pipeline-toolkit
+Project-URL: Repository, https://github.com/Hoang-Long2012/pipeline-toolkit
+Project-URL: Issues, https://github.com/Hoang-Long2012/pipeline-toolkit/issues
+Project-URL: Changelog, https://github.com/Hoang-Long2012/pipeline-toolkit/blob/main/CHANGELOG.md
+Keywords: pipeline,functional programming,functional pipeline,workflow,async,asynchronous,threading,utilities
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Pipeline Toolkit
+
+A small functional pipeline toolkit for Python.
+
+`pipeline-toolkit` provides a simple way to build sequential pipelines from ordinary Python callables. Each step receives the result of the previous step, while the pipeline runs asynchronously in a worker thread.
+
+## Features
+
+- Sequential functional pipeline execution
+- Asynchronous execution using a worker thread
+- Positional and keyword arguments for pipeline steps
+- Stop, skip, wait, and rerun execution
+- Manual synchronous step execution
+- Result and error history using a stack
+- Pipeline modification with `add()`, `insert()`, `pop()`, and `clear()`
+- Small utility modules for functional workflows
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install pipeline-toolkit
+```
+
+Or install directly from GitHub:
+
+```bash
+pip install git+https://github.com/Hoang-Long2012/pipeline-toolkit.git
+```
+
+## Quick Start
+
+A pipeline is created from an iterable of steps. Each step is a tuple whose first item is a callable.
+
+```python
+from pipeline import Pipeline
+
+def add(value, amount):
+	return value + amount
+
+def multiply(value, factor):
+	return value * factor
+
+pipeline = Pipeline([
+	(add, (5,)),
+	(multiply, (2,)),
+])
+
+pipeline.run(10).wait()
+
+print(pipeline.results.get())
+```
+
+The execution flow is:
+
+```text
+10
+ ↓
+add(10, 5)
+ ↓
+15
+ ↓
+multiply(15, 2)
+ ↓
+30
+```
+
+The final result is `30`.
+
+## Pipeline Steps
+
+Each step can use one of four supported forms.
+
+### Callable only
+
+```python
+(function,)
+```
+
+The callable receives the previous result:
+
+```python
+pipeline = Pipeline([
+	(str.upper,),
+])
+
+pipeline.run("hello").wait()
+```
+
+### Positional arguments
+
+```python
+(function, args)
+```
+
+where `args` is a tuple:
+
+```python
+pipeline = Pipeline([
+	(add, (5,)),
+	(multiply, (2,)),
+])
+```
+
+A step such as:
+
+```python
+(add, (5,))
+```
+
+is executed as:
+
+```python
+add(previous_result, 5)
+```
+
+### Keyword arguments
+
+```python
+(function, kwargs)
+```
+
+where `kwargs` is a mapping:
+
+```python
+pipeline = Pipeline([
+	(pow, {"exp": 2}),
+])
+```
+
+The step is executed as:
+
+```python
+pow(previous_result, exp=2)
+```
+
+### Positional and keyword arguments
+
+```python
+(function, args, kwargs)
+```
+
+For example:
+
+```python
+pipeline = Pipeline([
+	(my_function, (1, 2), {"option": True}),
+])
+```
+
+The callable receives the previous result followed by the supplied positional and keyword arguments.
+
+## Execution
+
+### `run()`
+
+Start the pipeline asynchronously.
+
+```python
+pipeline.run(default=None, delay=0, daemon=False, stop_on_error=True)
+```
+
+The `default` value becomes the initial result and is passed to the first step.
+
+`delay` specifies the delay between steps.
+
+`daemon` controls whether the worker thread is a daemon thread.
+
+`stop_on_error` controls whether execution stops after the first exception.
+
+`run()` returns the pipeline instance, allowing calls such as:
+
+```python
+pipeline.run(10).wait()
+```
+
+The pipeline is snapshotted when execution starts. Changes made to `pipeline.pipeline` after `run()` begins do not affect the current execution.
+
+### `wait()`
+
+Wait for the current execution to finish.
+
+```python
+pipeline.wait()
+```
+
+It returns the pipeline instance.
+
+### `stop()`
+
+Request the running pipeline to stop and wait for its worker thread to terminate.
+
+```python
+step = pipeline.stop()
+```
+
+The return value is the current one-based step index when execution is stopped, or `0` if the pipeline was not running.
+
+### `skip()`
+
+Request the worker to skip the next step that reaches its skip check.
+
+```python
+pipeline.skip()
+```
+
+The method returns the pipeline instance.
+
+### `rerun()`
+
+Stop the current execution and start the pipeline again.
+
+```python
+pipeline.rerun(10)
+```
+
+Arguments are passed directly to `run()`.
+
+## Manual Step Execution
+
+`run_step()` executes one configured step synchronously.
+
+```python
+result = pipeline.run_step(2, 10)
+```
+
+Unlike `run()`, this method:
+
+- does not create a worker thread
+- does not modify the worker thread or pipeline execution state
+- does not store the result in `results`
+- does not store exceptions in `errors`
+- allows exceptions to propagate to the caller
+
+This makes it useful when a single pipeline step needs to be executed manually.
+
+## Results and Errors
+
+The pipeline provides two `Stack` instances:
+
+```python
+pipeline.results
+pipeline.errors
+```
+
+`results` contains the initial value and the results produced by executed steps.
+
+For example:
+
+```python
+pipeline.run(10).wait()
+
+print(pipeline.results.get())
+```
+
+`errors` contains exceptions raised by pipeline steps.
+
+When `stop_on_error=True`, execution stops after the first exception.
+
+When `stop_on_error=False`, the exception is stored in `errors` and execution continues with the previous result.
+
+## Managing Pipeline Steps
+
+Pipeline steps can be modified before or between executions.
+
+### `add()`
+
+Append a step:
+
+```python
+pipeline.add((str.upper,))
+```
+
+### `insert()`
+
+Insert a step at a one-based position:
+
+```python
+pipeline.insert(2, (str.strip,))
+```
+
+### `pop()`
+
+Remove and return a step:
+
+```python
+step = pipeline.pop(1)
+```
+
+Pipeline indexes are one-based.
+
+### `clear()`
+
+Remove all configured steps:
+
+```python
+pipeline.clear()
+```
+
+## Pipeline State
+
+The `running` property indicates whether the worker thread is currently running:
+
+```python
+if pipeline.running:
+	print("Pipeline is running")
+```
+
+The `step` attribute contains the one-based index of the currently executing step. It is `0` when the pipeline is not running.
+
+A `Pipeline` instance can also be used as a boolean:
+
+```python
+if pipeline:
+	print("Pipeline is running")
+```
+
+Calling a pipeline instance is equivalent to calling `run()`:
+
+```python
+pipeline(10)
+```
+
+is equivalent to:
+
+```python
+pipeline.run(10)
+```
+
+The length of a pipeline is the number of configured steps:
+
+```python
+len(pipeline)
+```
+
+A callable can be checked with the `in` operator:
+
+```python
+if add in pipeline:
+	print("add is part of the pipeline")
+```
+
+Callable membership uses identity comparison.
+
+## Utilities
+
+### `Stack`
+
+`Stack` is a simple LIFO stack container with optional capacity limits.
+
+It supports common stack operations such as pushing, retrieving, peeking, and removing items, with dedicated exceptions for overflow and underflow conditions.
+
+Import it directly from its submodule:
+
+```python
+from pipeline.stack import Stack
+```
+
+`Stack` is also used internally by `Pipeline` for storing results and errors.
+
+For example:
+
+```python
+from pipeline.stack import Stack
+
+stack = Stack()
+
+stack.push("first")
+stack.push("second")
+
+print(stack.get())
+```
+
+For detailed stack operations and behavior, see the `pipeline.stack` module.
+
+### `tap`
+
+`tap` is a small functional utility for performing a side effect while keeping the pipeline value available for subsequent processing.
+
+`tap` performs a side effect on a deep copy of the current value and returns the original value unchanged.
+
+Import it directly from its submodule:
+
+```python
+from pipeline.tap import tap
+```
+
+For example:
+
+```python
+from pipeline import Pipeline
+from pipeline.tap import tap
+
+def add(value, amount):
+	return value + amount
+
+pipeline = Pipeline([
+	(add, (5,)),
+	(tap, (print,)),
+	(add, (10,)),
+])
+
+pipeline.run(10).wait()
+```
+
+Utilities are provided as separate submodules rather than being exported from the top-level `pipeline` package.
+
+## API Overview
+
+### `Pipeline`
+
+| Member       | Description                           |
+| ------------ | ------------------------------------- |
+| `run()`      | Start asynchronous pipeline execution |
+| `run_step()` | Execute one step synchronously        |
+| `stop()`     | Stop the current execution            |
+| `skip()`     | Request the next step to be skipped   |
+| `wait()`     | Wait for the current execution        |
+| `rerun()`    | Restart the pipeline                  |
+| `add()`      | Append a step                         |
+| `insert()`   | Insert a step                         |
+| `pop()`      | Remove and return a step              |
+| `clear()`    | Remove all steps                      |
+| `running`    | Whether the worker is running         |
+| `step`       | Current one-based step index          |
+| `results`    | Stack of initial value and results    |
+| `errors`     | Stack of raised exceptions            |
+
+## Requirements
+
+* Python 3.8 or newer
+
+## Changelog
+
+See changelog from: [CHANGELOG.md](https://github.com/Hoang-Long2012/pipeline-toolkit/blob/main/CHANGELOG.md)
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](https://github.com/Hoang-Long2012/pipeline-toolkit/blob/main/LICENSE) for details.
+
+## Contribution
+
+If you'd like to contribute, feel free to submit a pull request.  
+If you'd like to report a bug or request a feature, please open an issue.
+
+Copyright (C) 2026 Hoàng Long

pipeline_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pipeline/__init__.py,sha256=OqDA6wIp3_I4rPtf9fnN9YVUWHd_AOTduG02-F3tRbk,827
+pipeline/pipeline.py,sha256=HGkfBTn-KU28k--FAVoQ13fKQSFhXYztplyG-3chPHM,10714
+pipeline/stack.py,sha256=1Ng_Tb4B2vQaU61OJMIiC2Kfl_qqIn4c-A6g_ERSzxA,3742
+pipeline/tap.py,sha256=rmcQWGk6ulSieJTvN_KabfEvaSmN4NM7n8X_hDbeYxE,1492
+pipeline_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=c1qSpYLFRd3y_-AO7xnys7ntD8rcvVy7_E5Ue5-QIBo,1068
+pipeline_toolkit-0.1.0.dist-info/METADATA,sha256=XAmz4Jucy3Yhx6fagBvJ6YWVB_929qUME1u0ImY9Wyo,10704
+pipeline_toolkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pipeline_toolkit-0.1.0.dist-info/top_level.txt,sha256=Qdc1eKrvhKK_o9CPbdooOdDt7g3ZSXZDrNXHmUGl94Q,9
+pipeline_toolkit-0.1.0.dist-info/RECORD,,

pipeline_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pipeline_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hoàng Long
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pipeline_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pipeline