Home

Awesome

Expression

PyPI Python package Publish Package Documentation Status codecov

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.10+.

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:

Getting Started

You can install the latest expression from PyPI by running pip (or pip3). Note that expression only works for Python 3.10+.

> pip install expression

To add Pydantic v2 support, install the pydantic extra:

> pip install expression[pydantic]

Goals

Supported features

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.

Pipelining

Expression provides a pipe function similar to |> in F#. We don't want to overload any Python operators, e.g., | so 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., Some, Seq, 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

# Since static type checkes aren't good good at inferring lambda types
mapper: Callable[[int], int] = lambda x: x * 10
predicate: Callable[[int], bool] = lambda x: x > 100
folder: Callable[[int, int], int] = lambda s, x: s + x

xs = Seq.of(9, 10, 11)
ys = xs.pipe(
    seq.map(mapper),
    seq.filter(predicate),
    seq.fold(folder, 0),
)

assert ys == 110

Composition

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

Fluent and Functional

Expression can be used both with a fluent or functional syntax (or both.)

Fluent syntax

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.

Functional syntax

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

The 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., Nothing.

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:
    match x:
        case Some(_):
            return True
    return False

Option as an effect

Effects in Expression is implemented as specially decorated coroutines (enhanced generators) using yield, yield from and return to consume or generate optional values:

from expression import effect, Some

@effect.option[int]()
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 Ok(value) or Error(error_value).

from expression import effect, Some, Nothing

@effect.option[int]()
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

Option as an applicative

In functional programming, we sometimes want to combine two Option values into a new Option. However, this combination should only happen if both Options are Some. If either Option is None, the resulting value should also be None.

The map2 function allows us to achieve this behavior. It takes two Option values and a function as arguments. The function is applied only if both Options are Some, and the result becomes the new Some value. Otherwise, map2 returns None.

This approach ensures that our combined value reflects the presence or absence of data in the original Options.

from expression import Some, Nothing, Option
from operator import add

def keep_positive(a: int) -> Option[int]:
    if a > 0:
        return Some(a)
    else:
      return Nothing

def add_options(a: Option[int], b: Option[int]):
  return a.map2(add, b)

assert add_options(
  keep_positive(4),
  keep_positive(-2)
) is Nothing

assert add_options(
  keep_positive(3),
  keep_positive(2)
) == Some(5)

For more information about options:

Result

The 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 Right for a success value.

from expression import effect, Ok, Result

@effect.result[int, Exception]()
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 pinned to Exception i.e., Result[TSource, Exception].

Sequence

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

Tagged Unions

Tagged Unions (aka discriminated unions) may look similar to normal Python Unions. But they are different in that the operands in a type union (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 similar to a dataclass and decorate it with @tagged_union and add the appropriate generic types that this union represent for each case. Then you optionally define static or class-method constructors for creating each of the tagged union cases.

from dataclasses import dataclass
from expression import TaggedUnion, tag

@dataclass
class Rectangle:
    width: float
    length: float

@dataclass
class Circle:
    radius: float

@tagged_union
class Shape:
    tag: Literal["rectangle", "circle"] = tag()

    rectangle: Rectangle = case()
    circle: Circle = case()

    @staticmethod
    def Rectangle(width: float, length: float) -> Shape:
        """Optional static method for creating a tagged union case"""
        return Shape(rectangle=Rectangle(width, length))

    @staticmethod
    def Circle(radius: float) -> Shape:
        """Optional static method for creating a tagged union case"""
        return Shape(circle=Circle(radius))

Note that the tag field is optional, but recommended. If you don't specify a tag field then then it will be created for you, but static type checkers will not be able to type check correctly when pattern matching. The tag field if specified should be a literal type with all the possible values for the tag. This is used by static type checkers to check exhaustiveness of pattern matching.

Each case is given the case() field initializer. This is optioal, but recommended for static type checkers to work correctly. It's not required for the code to work properly,

Now you may pattern match the shape to get back the actual value:

    shape = Shape.Rectangle(2.3, 3.3)

    match shape:
        case Shape(tag="rectangle", rectangle=Rectangle(width=2.3)):
            assert shape.value.width == 2.3
        case _:
            assert False

Note that when matching keyword arguments, then the tag keyword argument must be specified for static type checkers to check exhaustiveness correctly. It's not required for the code to work properly, but it's recommended to avoid typing errors.

Notable differences between Expression and F#

In F# modules are capitalized, in Python they are lowercase (PEP-8). 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 Option.

Thus in Expression you use option as the module to access module functions such as 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'>

Common Gotchas and Pitfalls

A list of common problems and how you may solve it:

Expression is missing the function/operator I need

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.

Resources and References

A collection of resources that were used as reference and inspiration for creating this library.

How-to Contribute

You are very welcome to contribute with suggestions or PRs :heart_eyes: 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:

> pre-commit install

Code of Conduct

This project follows https://www.contributor-covenant.org, see our Code of Conduct.

License

MIT, see LICENSE.