Glossary
This page collects the key terms used across the trcks documentation.
Agent skill
A bundle of instructions, distributed alongside trcks,
that teaches AI coding agents how to use trcks for railway-oriented programming.
Every release of trcks ships its agent skill,
so it always matches your installed version of trcks.
See installation instructions
for more details.
Awaitable and Coroutine
collections.abc.Awaitable is the broad type for anything
that can be awaited using await.
collections.abc.Coroutine is a specific, narrower subtype
produced by async def functions.
In Python 3.13 and older, asyncio.run requires a Coroutine, not just any Awaitable.
trcks provides helpers such as
trcks.oop.BaseAwaitableWrapper.core_as_coroutine and
trcks.fp.monads.awaitable_result.to_coroutine_result to convert an Awaitable
result into a Coroutine.
Double-track
A value that is either a success or a failure, represented by trcks.Result. One track carries successful results forward; the other carries information about failures.
Higher-order function
A function that accepts a function as an argument,
returns a function, or both.
The map* helpers in trcks are higher-order functions.
Homogeneous tuple
A tuple[T, ...] whose elements all share the same type,
processed individually by trcks.
Mapping helper (or map* function)
A helper that lifts a plain function so that it operates on a
wrapped value (trcks.oop) or becomes a pipeline step (trcks.fp).
For example, trcks.oop.ResultWrapper.map_success and
trcks.fp.monads.result.map_success both apply a function to the success
value of a trcks.Result, leaving failures unchanged.
These helpers live in trcks.oop classes and in the modules under trcks.fp.monads.
Mapping and tap helpers also forward any extra positional and keyword
arguments to the given function, so a lambda or functools.partial is not
needed just to bind an extra argument.
Pipeline and pipe
A pipeline is a start value followed by zero or more compatible functions.
The Pipeline* type aliases in trcks.fp.composition model pipelines
as tuples, and help static type checkers validate the compatibility of
the start value and the functions.
trcks.fp.composition.pipe runs a pipeline by passing the
start value through each function in turn.
Railway-oriented programming (ROP)
A design pattern for composing functions that may fail. See the motivation page for a full introduction.
Short-circuiting
Once a step produces a failure, all subsequent map* steps
are skipped and the failure is carried through to the end of the
pipeline without further processing.
Single-track
A plain Python value not wrapped in a success-or-failure type — in other words, an ordinary Python value that carries no information about whether an operation succeeded or failed.
Success, Failure, and Result
The three generic types at the heart of trcks.
See Tuple types provided by trcks
for definitions and examples.
tap and side effects
A side effect is an operation (such as logging or file I/O) that does
not change the value flowing through the pipeline.
The tap* helpers run a side effect and then return the original
value unchanged, keeping the pipeline intact.
Widening
A transition from a simpler monad to a richer one.
For example, trcks can widen:
Like mapping helpers, widening helpers are named map* or tap*.
Unlike helpers that stay within the same monad
(e.g. map_success and tap_failure),
they return a value wrapped in a different, richer type.