Pragmatic functional programming
Expression aims to be a solid, type-safe, pragmatic, and high performance library for frictionless and practical functional programming in Python 3.9+.
By pragmatic, we mean that the goal of the library is to use simple abstractions to enable you to do practical and productive functional programming in Python (instead of being a Monad tutorial).
Python is a multi-paradigm programming language that also supports functional programming constructs such as functions, higher-order functions, lambdas, and in many ways favors composition over inheritance.
Better Python with F#
Expression tries to make a better Python by providing several functional features inspired by F#. This serves several purposes:
Expression will enable you to work with Python using many of the same programming concepts and abstractions. This enables concepts such as Railway oriented programming (ROP) for better and predictable error handling. Pipelining for workflows, computational expressions, etc.
Expressions evaluate to a value. Statements do something.
F# is a functional programming language for .NET that is succinct (concise, readable, and type-safe) and kind of Pythonic. F# is in many ways very similar to Python, but F# can also do a lot of things better than Python:
You can install the latest
expression from PyPI by running
pip3). Note that
expression only works for Python 3.9+.
pip3 install expression
>>, etc) overloading, this usually confuses more than it helps.
Expression will never provide you with all the features of F# and .NET. We are providing a few of the features we think are useful, and will add more on-demand as we go along.
Expression provides a
pipe function similar to
|> in F#. We don't want to
overload any Python operators, e.g.,
pipe is a plain old function taking
N-arguments, and will let you pipe a value through any number of functions.
from expression import pipe v = 1 fn = lambda x: x + 1 gn = lambda x: x * 2 assert pipe(v, fn, gn) == gn(fn(v))
Expression objects (e.g.,
Result) also have a
pipe method, so you can dot chain pipelines
directly on the object:
from expression import Some v = Some(1) fn = lambda x: x.map(lambda y: y + 1) gn = lambda x: x.map(lambda y: y * 2) assert v.pipe(fn, gn) == gn(fn(v))
So for example with sequences you may create sequence transforming pipelines:
from expression.collections import seq, Seq xs = Seq.of(9, 10, 11) ys = xs.pipe( seq.map(lambda x: x * 10), seq.filter(lambda x: x > 100), seq.fold(lambda s, x: s + x, 0) ) assert ys == 110
Functions may even be composed directly into custom operators:
from expression import compose from expression.collections import seq, Seq xs = Seq.of(9, 10, 11) custom = compose( seq.map(lambda x: x * 10), seq.filter(lambda x: x > 100), seq.fold(lambda s, x: s + x, 0) ) ys = custom(xs) assert ys == 110
Expression can be used both with a fluent or functional syntax (or both.)
The fluent syntax uses methods and is very compact. But it might get you into trouble for large pipelines since it's not a natural way of adding line breaks.
from expression.collections import Seq xs = Seq.of(1, 2, 3) ys = xs.map(lambda x: x * 100).filter(lambda x: x > 100).fold(lambda s, x: s + x, 0)
Note that fluent syntax is probably the better choice if you use mypy for type checking since mypy may have problems inferring types through larger pipelines.
The functional syntax is a bit more verbose but you can easily add new operations on new lines. The functional syntax is great to use together with pylance/pyright.
from expression import pipe from expression.collections import seq, Seq xs = Seq.of(1, 2, 3) ys = pipe(xs, seq.map(lambda x: x * 100), seq.filter(lambda x: x > 100), seq.fold(lambda s, x: s + x, 0), )
Both fluent and functional syntax may be mixed and even pipe can be used fluently.
from expression.collections import seq, Seq xs = Seq.of(1, 2, 3).pipe(seq.map(...))
Option type is used when a function or method cannot produce a meaningful
output for a given input.
An option value may have a value of a given type, i.e.,
Some(value), or it might
not have any meaningful value, i.e.,
from expression import Some, Nothing, Option def keep_positive(a: int) -> Option[int]: if a > 0: return Some(a) return Nothing
from expression import Option, Ok def exists(x : Option[int]) -> bool: for value in x.match(Ok): return True return False
Effects in Expression is implemented as specially decorated coroutines
(enhanced generators) using
yield from and
return to consume or generate optional values:
from expression import effect, Some def fn(): x = yield 42 y = yield from Some(43) return x + y xs = fn()
This enables "railway oriented
programming", e.g., if one part of the
function yields from
Nothing then the function is side-tracked
(short-circuit) and the following statements will never be executed. The end
result of the expression will be
Nothing. Thus results from such an option
decorated function can either be
from expression import effect, Some, Nothing def fn(): x = yield from Nothing # or a function returning Nothing # -- The rest of the function will never be executed -- y = yield from Some(43) return x + y xs = fn() assert xs is Nothing
For more information about options:
Result[T, TError] type lets you write error-tolerant code that can be
composed. A Result works similar to
Option, but lets you define the value used
for errors, e.g., an exception type or similar. This is great when you want to
know why some operation failed (not just
Nothing). This type serves the same
purpose of an
Either type where
Left is used for the error condition and
for a success value.
from expression import effect, Ok, Result def fn(): x = yield from Ok(42) y = yield from Ok(10) return x + y xs = fn() assert isinstance(xs, Result)
A simplified type called
Try is also available. It's a result type that is
Sequences is a thin wrapper on top of iterables and contains operations for working with Python iterables. Iterables are immutable by design, and perfectly suited for functional programming.
import functools from expression import pipe from expression.collections import seq # Normal python way. Nested functions are hard to read since you need to # start reading from the end of the expression. xs = range(100) ys = functools.reduce(lambda s, x: s + x, filter(lambda x: x > 100, map(lambda x: x * 10, xs)), 0) # With Expression, you pipe the result, so it flows from one operator to the next: zs = pipe( xs, seq.map(lambda x: x * 10), seq.filter(lambda x: x > 100), seq.fold(lambda s, x: s + x, 0), ) assert ys == zs
Pattern matching is tricky for a language like Python. We are waiting for PEP 634 and structural pattern matching for Python. But we need something that can by handled by static type checkers and will also decompose or unwrap inner values.
What we want to achieve with pattern matching:
The solution we propose is based on loops, singleton iterables and resource management. This lets us write our code inline, decompose, and unwrap inner values, and also effectively skip the cases that do not match.
from expression import match with match("expression") as case: if case("rxpy"): # will not match assert False for value in case(str): # will match assert value == "expression" for value in case(float): # will not match assert False if case._: # will run if any previous case does not match assert False
match as a context manager will make sure that a case was actually
found. You might need to have a default handler to avoid
Test cases may be additionally be wrapped in a function to have a match expression that returns a value:
def matcher(value) -> Option[int]: with match(value) as case: for value in case(Some[int]): return Some(42) if case._: return Some(2) return Nothing result = matcher(42).
Classes may also support
match fluently, i.e:
xs.match(pattern). If you add generic types to the pattern then
unwrapped values will get the right type without having to cast.
xs = Some(42) ys = xs.map(lambda x: x + 1) for value in ys.match(Some[int]): assert value == 43 break else: assert False
Pattern matching can also be used with destructuring of iterables:
xs: Block[int] = empty.cons(42) for (head, *tail) in xs.match(Block): assert head == 42
Classes can support more advanced pattern matching and decompose inner values by subclassing or implementing the matching protocol.
class SupportsMatch(Protocol[TSource]): """Pattern matching protocol.""" def __match__(self, pattern: Any) -> Iterable[TSource]: """Return a singleton iterable item (e.g., `[value]`) if pattern matches, else an empty iterable (e.g. ``).""" raise NotImplementedError
This significantly simplifies the decomposition and type handling
compared to using
isinstance directly. E.g code from
if isinstance(msg, InnerObservableMsg): msg = cast(InnerObservableMsg[TSource], msg) xs: AsyncObservable[TSource] = msg.inner_observable ...
with match(msg) as case: for xs in case(InnerObservableMsg[TSource]): ...
Note that the matching protocol may be implemented by both values and patterns. Patterns implementing the matching protocol effectively becomes active patterns.
class ParseInteger_(SupportsMatch[int]): """Active pattern for parsing integers.""" def __match__(self, pattern: Any) -> Iterable[int]: """Match value with pattern.""" try: number = int(pattern) except ValueError: return  else: return [number] ParseInteger = ParseInteger_() # Pattern singleton instance text = "42" with match(text) as case: for value in case(ParseInteger): assert value == int(text) if case._: assert False
Tagged Unions (aka discriminated unions) may looks similar to normal Python Unions. But
they are different in that the operands in a
(A | B) are both types, while the cases in a tagged union type
U = A | B
are both constructors for the type U and are not types themselves. One consequence is
that tagged unions can be nested in a way union types might not.
In Expression you make a tagged union by defining your type as a sub-class of
TaggedUnion with the appropriate generic types that this union represent for
each case. Then you define static or class-method constructors for creating each of the
tagged union cases.
from dataclasses import dataclass from expression import TaggedUnion, tag class Rectangle: width: float length: float class Circle: radius: float class Shape(TaggedUnion): RECTANGLE = tag(Rectangle) CIRCLE = tag(Circle) def rectangle(width: float, length: float) -> Shape: return Shape(Shape.RECTANGLE, Rectangle(width, length)) def circle(radius: float) -> Shape: return Shape(Shape.CIRCLE, Circle(radius))
Now you may pattern match the shape to get back the actual value:
from expression import match shape = Shape.Rectangle(2.3, 3.3) with match(shape) as case: if case(Circle): assert False for rect in case(Shape.RECTANGLE(width=2.3)): assert rect.length == 3.3 if case.default(): assert False
In F# modules are capitalized, in Python they are lowercase
E.g in F#
Option is both a module (
OptionModule internally) and a
type. In Python the module is
option and the type is capitalized i.e
Thus in Expression you use
option as the module to access module functions
option.map and the name
Option for the type itself.
from expression import Option, option Option <class 'expression.core.option.Option'> option <module 'expression.core.option' from '/Users/dbrattli/Developer/Github/Expression/expression/core/option.py'>
F# pattern matching is awesome and the alternative we present here cannot be compared. But it helps us match and decompose without having to type-cast every time.
A list of common problems and how you may solve it:
Remember that everything is just a function, so you can easily implement a custom function yourself and use it with Expression. If you think the function is also usable for others, then please open a PR to include it with Expression.
A collection of resources that were used as reference and inspiration for creating this library.
You are very welcome to contribute with suggestions or PRs 😍 It is nice if you can try to align the code and naming with F# modules, functions, and documentation if possible. But submit a PR even if you should feel unsure.
Code, doc-strings, and comments should also follow the Google Python Style Guide.
Code checks are done using
To run code checks on changed files every time you commit, install the pre-commit hooks by running:
MIT, see LICENSE.