Algebra Module¶

Algebraic abstractions for functional programming.

This module provides the core algebraic type classes that form the foundation of functional programming in Katharos. These abstractions follow mathematical laws and enable composable, predictable code.

The hierarchy of abstractions (from least to most powerful):

Semigroup: Types with an associative binary operation
Monoid: Semigroups with an identity element
Functor: Types that can be mapped over
Applicative: Functors with function application
Monad: Applicatives with sequencing capabilities

Each abstraction builds upon the previous one, adding more structure and capabilities while maintaining the laws of the simpler abstractions.

Semigroup¶

class katharos.algebra.Semigroup[source]¶

Bases: ABC, Generic

Abstract base class for semigroups.

A semigroup is a set equipped with an associative binary operation. The binary operation is represented by the @ operator.

abstractmethod op(other)[source]¶

Combine this semigroup with another semigroup.

The abstract binary operation that subclasses must implement. Must satisfy associativity: (a @ b) @ c == a @ (b @ c).

Parameters:: other (TypeVar(S)) – Another semigroup of the same type.
Return type:: TypeVar(S)
Returns:: The result of combining the two semigroups.

__matmul__(other)[source]¶

Infix operator for the semigroup binary operation (@).

Must satisfy associativity: (a @ b) @ c == a @ (b @ c).

Parameters:: other (TypeVar(S)) – Another semigroup of the same type.
Return type:: TypeVar(S)
Returns:: A new semigroup representing the combination.

Monoid¶

class katharos.algebra.Monoid[source]¶

Bases: Semigroup, Generic

Abstract base class for monoids.

A monoid is a semigroup with an identity element.

abstractmethod classmethod identity()[source]¶

Return the identity element of the monoid.

Must satisfy: a @ identity() == a and identity() @ a == a for all a in the monoid.

Return type:: TypeVar(M)
Returns:: The identity element of type M.

Functor¶

class katharos.algebra.Functor[source]¶

Bases: ABC, Generic

Abstract base class for functors.

A functor is a type that implements fmap(), allowing functions to be mapped over the structure.

Note

Instances must satisfy the functor laws:

Identity: fmap(id) == id
Composition: fmap(g ∘ f) == fmap(g) ∘ fmap(f)

abstractmethod fmap(f)[source]¶

Map a function over the functor.

Parameters:: f (Callable[[TypeVar(A)], TypeVar(B)]) – A function to apply to the functor’s contents.
Return type:: Functor[TypeVar(F), TypeVar(B)]
Returns:: A new functor with the function applied.

Applicative¶

class katharos.algebra.Applicative[source]¶

Bases: Functor, ABC, Generic

Abstract base class for applicative functors.

An applicative functor extends Functor with the ability to apply functions wrapped in a context to values wrapped in a context. It sits between Functor and Monad in the abstraction hierarchy.

Use pure() to lift a plain value into the applicative context, and the ** operator (or ap()) to apply a wrapped function to a wrapped value.

Note

Instances must satisfy the applicative laws (where App is the concrete applicative type and id / compose are the identity and composition functions):

Identity: v ** App.pure(id) == v
Composition: w ** (v ** (u ** App.pure(compose))) == (w ** v) ** u
Homomorphism: App.pure(x) ** App.pure(f) == App.pure(f(x))
Interchange: App.pure(y) ** u == u ** App.pure(lambda f: f(y))

abstractmethod classmethod pure(x)[source]¶

Lift a value into the applicative context.

Parameters:: x (TypeVar(T)) – The value to wrap in an applicative.
Return type:: Applicative[TypeVar(App), TypeVar(T)]
Returns:: An applicative containing the given value.

abstractmethod ap(wrapped_funcs)[source]¶

Apply wrapped functions to this applicative’s value.

Parameters:: wrapped_funcs (Applicative[TypeVar(App), Callable[[TypeVar(A)], TypeVar(B)]]) – An applicative containing functions from A to B.
Return type:: Applicative[TypeVar(App), TypeVar(B)]
Returns:: An applicative containing the result of applying the function.

__pow__(wrapped_funcs)[source]¶

Infix operator for applicative application (**).

Parameters:: wrapped_funcs (Applicative[TypeVar(App), Callable[[TypeVar(A)], TypeVar(B)]]) – An applicative containing functions from A to B.
Return type:: Applicative[TypeVar(App), TypeVar(B)]
Returns:: An applicative containing the result of applying the function.

Monad¶

class katharos.algebra.Monad[source]¶

Bases: Applicative, ABC, Generic

Abstract base class for monads.

A monad extends Applicative with the bind operation (>>= in Haskell, exposed as |), which allows sequencing computations that produce monadic values.

Use ret() to lift a plain value, and | (or bind()) to chain computations. Use >> (or then()) to sequence actions while discarding the first result.

Note

Instances must satisfy the monad laws:

Left identity: ret(a).bind(f) == f(a)
Right identity: m.bind(ret) == m
Associativity: m.bind(f).bind(g) == m.bind(lambda x: f(x).bind(g))

Examples

Using bind (| operator):

m = SomeMonad.ret(5)
result = m | (lambda x: SomeMonad.ret(x * 2))

Sequencing with then (>> operator):

m1 = SomeMonad.ret(1)
m2 = SomeMonad.ret(2)
result = m1 >> m2  # returns m2, discarding m1's value

classmethod ret(x)[source]¶

Wrap a value in the monad.

Parameters:: x (TypeVar(T)) – The value to wrap.
Return type:: Monad[TypeVar(Mon), TypeVar(T)]
Returns:: A monad containing the given value.

abstractmethod bind(f)[source]¶

Chain this monad with a function that returns a monad.

Parameters:: f (Callable[[TypeVar(A)], Monad[TypeVar(Mon), TypeVar(B)]]) – A function that takes a value of type A and returns a monad of type B.
Return type:: Monad[TypeVar(Mon), TypeVar(B)]
Returns:: A monad containing the result of applying the function.

then(other)[source]¶

Sequence two monadic actions, discarding the first result.

Parameters:: other (Monad[TypeVar(Mon), TypeVar(B)]) – The monad to sequence after this one.
Return type:: Monad[TypeVar(Mon), TypeVar(B)]
Returns:: The result of the second monad.

__or__(f)[source]¶

Infix operator for monadic bind (|).

Parameters:: f (Callable[[TypeVar(A)], Monad[TypeVar(Mon), TypeVar(B)]]) – A function that takes a value of type A and returns a monad of type B.
Return type:: Monad[TypeVar(Mon), TypeVar(B)]
Returns:: A monad containing the result of applying the function.

__rshift__(other)[source]¶

Infix operator for sequencing two monadic actions (>>).

Parameters:: other (Monad[TypeVar(Mon), TypeVar(B)]) – The monad to sequence after this one.
Return type:: Monad[TypeVar(Mon), TypeVar(B)]
Returns:: The result of the second monad.