🔗 simplibs-actions
Turn ordinary functions into composable pipeline steps — chain them with >>, &, and |.
A lightweight Python library for building Action objects: single-purpose pipeline steps
that chain into sequences, run in parallel, and fall back on failure using plain Python
operators — no pipeline framework, no DSL, no boilerplate. Any function (sync or async)
becomes an Action with one decorator, complete with type-checked construction and calls,
native acall support, structured diagnostics on failure, and its own dedicated testing toolkit.
from simplibs.actions import to_action
@to_action
def strip(data: str) -> str:
return data.strip()
@to_action
def shout(data: str) -> str:
return data.upper() + "!"
pipeline = strip() >> shout()
pipeline(" hello ") # -> "HELLO!"
simplibs-actionsis the pipeline layer of the ecosystem, built directly onsimplibs-rules(conditions),simplibs-validate(validate_call,log_this), andsimplibs-exception(structured diagnostics) — see Related libraries below.
🧭 The Core Philosophy
Most pipeline/workflow tooling forces a choice: write ad-hoc chains of if/try calls
scattered through your codebase, or adopt a heavy orchestration framework with its own
configuration language. simplibs-actions takes neither route. An Action is nothing
more than a plain function with a real signature — create_action/@to_action wraps it
once, and from then on it composes with the same three operators every function in this
library composes with:
step_a >> step_b >> step_c # sequence — thread output into the next input
step_a & step_b & step_c # parallel — same input, every branch, one flat tuple out
step_a | step_b # fallback — try step_a; on failure, run step_b instead
Every generated Action keeps the function's own signature intact — its parameters are
still individually annotated, still individually type-checked at call time (via
simplibs-validate's validate_call), and still individually documented, rather than
being flattened into an opaque (*args, **kwargs) wrapper. Because that generation is
itself a well-defined, mechanical process, the library ships its own testing tool
(assert_action) that audits the entire contract of any Action — this library's own
containers, or any Action a downstream library builds — with one function call.
📦 Installation
pip install simplibs-actions
🚀 Quick Start in 60 Seconds
Level 1: Turning a function into an Action
from simplibs.actions import to_action
@to_action
def double(data: int) -> int:
return data * 2
action = double()
action(21) # -> 42
Level 2: Composing Actions (Sync & Async)
from simplibs.actions import to_action
@to_action
def strip(data: str) -> str:
return data.strip()
@to_action
def upper(data: str) -> str:
return data.upper()
@to_action
def lower(data: str) -> str:
return data.lower()
# Sequence: thread output into the next input
pipeline = strip() >> upper()
pipeline(" hi ") # -> "HI"
# Parallel: same input, every branch, one flat tuple out
both = upper() & lower()
both("Hi") # -> ("HI", "hi")
# Fallback: try the left side; on failure, run the right side instead
safe = risky_parse() | default_value(value=None)
safe(raw_input)
# Async Support: native async def functions expose acall()
@to_action
async def fetch_user(user_id: int) -> dict:
return {"id": user_id, "name": "Alice"}
user_action = fetch_user()
user_data = await user_action.acall(42) # -> {"id": 42, "name": "Alice"}
Rule instances from simplibs-rules compose the same way — is_integer >> add_one
verifies the rule first, then continues with the action.
Level 3: Testing an Action
from simplibs.actions.testing import assert_action
def test_double_contract(subtests):
assert_action(
subtests,
double(),
valid_values=[21],
expected_outputs=[42],
invalid_values=["not-a-number"],
expected_exception_type=ValidationError,
)
One call audits the full deterministic contract: valid inputs produce the right output,
invalid inputs raise the right exception, and (by default) the generated class carries
correct _input_type/_output_type introspection.
🛠️ Architecture & Package Structure
src/simplibs/actions/
├── base_class/ ◄── Abstract base class Action — __call__, operators, resolve_action
├── containers/ ◄── Every built-in Action
│ ├── flow_control/ ◄── guard, branch, for_each
│ ├── operators/ ◄── sequence, parallel, fallback, compose_class/ (self-flattening)
│ ├── primitives/ ◄── identity, constant
│ └── wrappers/ ◄── lambda_action, tap, retry, log_action
├── creator/ ◄── create_action — dynamically builds Action classes from functions
├── decorator/ ◄── to_action — the decorator interface for create_action
└── testing/ ◄── assert_action, assert_action_alias
🧩 The Action Class
Every action in this library — hand-written or generated — is an Action. It defines
the one mandatory contract (__call__) and provides full operator-based composition out
of the box.
class Action(ABC):
@abstractmethod
def __call__(self, data: Any, /) -> Any:
"""Run this action synchronously over `data` and return the result.
Raises AsyncActionRequiresAcallError if called on an async action.
"""
raise NotImplementedError
async def acall(self, data: Any, /) -> Any:
"""Run this action asynchronously over `data` and return the result."""
...
def then(self, next_step: Any) -> "Action":
"""Chains this action with a subsequent action, rule, or callable."""
...
def __and__(self, other: Any) -> "Action":
"""Executes actions in parallel over identical input data."""
...
def __or__(self, other: Any) -> "Action":
"""Fallback handling: executes `other` if this action fails."""
...
@staticmethod
def resolve_action(obj: Any) -> "Action":
"""Convert an Action, a Rule, or a plain callable into an Action instance."""
...
➡️ Full method-by-method reference: README_ACTION
📖 Built-in Containers
Every built-in Action is exposed as a @to_action-generated class, constructed with
its own configuration parameters and called with one main input value.
| Container | Package | Description |
|---|---|---|
guard |
flow_control |
Hard gate — passes data through, or raises, based on a Rule/condition. |
branch |
flow_control |
Soft conditional — runs one of two actions based on a condition, no error either way. |
for_each |
flow_control |
Applies an action to every item of an iterable, collecting the results. |
sequence |
operators |
Chains any number of steps left to right. Self-flattening variant: SequenceCompose. |
parallel |
operators |
Runs N actions over the same input, returning a flat tuple of results. Self-flattening variant: ParallelCompose. |
fallback |
operators |
Tries one action; on failure, runs another or returns the original data. |
identity |
primitives |
No-op — returns data unchanged. |
constant |
primitives |
Ignores data, always returns a fixed value. |
lambda_action |
wrappers |
Adapts a raw callable into an Action. |
tap |
wrappers |
Runs an action for its side effect; always returns the original data. |
retry |
wrappers |
Retries an action up to N times on failure. |
log_action |
wrappers |
Logs the data flowing through one pipeline point, unchanged. |
Every container above also ships under a more descriptive alias (guarded_action,
run_in_sequence, pass_through, ...) — see the full list in the containers reference.
🏗️ Creating Actions
Any function becomes an Action two ways: the decorator (everyday use), or the
function it wraps (when you need to build one dynamically):
from simplibs.actions import to_action, create_action
@to_action
def greet(data: dict, prefix: str = "Hi") -> str:
return f"{prefix}, {data['name']}!"
# Equivalent, without the decorator:
Greet = create_action(greet)
create_action fully annotates, validates, and documents the generated class's
__init__/__call__/acall/act — nothing about the source function's own signature is lost
or flattened into (*args, **kwargs). Sync functions support __call__, while async def
functions generate native acall methods.
➡️ README_CREATOR — create_action and every internal resolver/generator it's built from
➡️ README_DECOTATOR — to_action, the decorator interface
🧪 Testing Utilities
simplibs-actions includes its own contract-testing tools, so this library's containers
— and any Action a downstream library builds on top of it — can be audited with one
function call instead of a hand-written test module per action:
from simplibs.actions.testing import assert_action
# Full deterministic contract: valid/invalid execution, type introspection, construction guard
assert_action(
subtests,
my_action,
valid_values=[...], expected_outputs=[...],
invalid_values=[...], expected_exception_type=SomeError,
)
➡️ README_TESTING_ASSERT_ACTION ➡️ README_TESTING_ASSERT_ACTION_ALIAS — identity + smoke-test verification for alias objects
⚠️ Exceptions
Every diagnostic this library raises — a rejected constructor argument, calling an
async action via sync __call__ (AsyncActionRequiresAcallError), a type mismatch
on call, or an unsupported source-function signature — is a structured
simplibs.exception card
(ParamError, ValidationError, AsyncActionRequiresAcallError), not a bare
TypeError/ValueError traceback.
Validation failures on a generated Action's own parameters (constructor or call) go
through simplibs-validate's
validate_call, using the same annotation-decomposition engine as
simplibs-rules.
🔗 Related libraries
simplibs-rules— theRuleabstraction actions compose with directly (rule >> action,rule & action, ...) and the engine behindguard's condition checking.simplibs-validate—validate_call/log_this, applied to every generatedAction's__init__/__call__/act.simplibs-exception— the structured diagnostic cards every failure in this library raises, and the testing primitives (assert_function_raises,assert_exception_function)assert_actionis built on.simplibs-types— reusable validated types (liketuple_not_empty) used as annotations on several built-in containers (sequence'ssteps,parallel'sbranches).
simplibs-actions is, in turn, the foundation other simplibs libraries build their
own domain-specific actions on top of — each ships ready-made Actions for its own
area alongside its standalone functions.
☯️ About simplibs
All libraries in the simplibs (Simple Libraries) ecosystem share a common engineering philosophy:
- Dyslexia-friendly: We actively minimize cognitive load. Code is atomized into small, self-contained units, files are named directly after the logical task they perform, and explanations describe why something is designed, not just what it is.
- Programmer's Zen: Nothing should be missing, and nothing should be superfluous. We value clean execution paths and robust, understandable code architectures over rushed, messy feature sets.
- Defensive Style: We actively anticipate edge cases and failure modes so that only safe operational paths remain. Our code is built to degrade gracefully rather than crash unexpectedly.
- Minimalism: Find the most direct path to the goal in as few operational steps as possible without taking shortcuts on safety, readability, or completeness.
- Code as Craft: Code should be pleasant to look at, readable at a glance, and evoke structural harmony. We treat software engineering as a precision trade.
🤝 Contributing & Community
This is an open-source project built with love and care. We strongly believe in community collaboration and welcome any feedback, bug reports, or feature ideas!
- Want to contribute? Feel free to open an Issue or submit a Pull Request.
- Want to get in touch? If you'd like to discuss the project further, collaborate, or just say hello, feel free to open a GitHub Issue or start a Discussion.
📝 License
This library is released under the MIT License. Build great things!
Metadata
Release files for simplibs-actions 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| simplibs_actions-0.2.0.tar.gz | 81.1 kB | Without provenance | Details for simplibs_actions-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| simplibs_actions-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for simplibs_actions-0.2.0-py3-none-any.whl |
Total release size: 198.5 kB
Release files / simplibs_actions-0.2.0.tar.gz
| Download URL | simplibs_actions-0.2.0.tar.gz |
|---|---|
| Size | 81.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
715c91a3c2cc730e9ba067d2809dc33193619b17a5de82327e96ab8fbd96983a
|
|
BLAKE2b-256 checksum How to use checksums |
ed3c31559b6899db42b0a2ce8b63cf748c0a5a12876dfad6ac9b72457cec7967
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / simplibs_actions-0.2.0-py3-none-any.whl
| Download URL | simplibs_actions-0.2.0-py3-none-any.whl |
|---|---|
| Size | 117.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
37a2f719fe97ae43732312f0f658273b8a6b3fa57f8c5427affe879e7662eacc
|
|
BLAKE2b-256 checksum How to use checksums |
30e7a4d25de7426174cb619c45a06ea013e7b1f3ed48055737f6148536fc26f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for simplibs-actions 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.