Skip to main content

A library that encapsulates stateful computations into a monadic structure.

Project description

State-Monad

State-Monad is a Python library that encapsulates stateful computations into a monadic structure.

Features

  • Pragmatic Monad: Implements the core concepts of a state monad in a way that is practical and relevant for a Python developpers. It focus on usability rather than strict adherence to mathematical correctness.
  • Object-Orgiented Design: State monad operations are built using Python classes, favoring an object-oriented approach that prioritizes working with objects rather than deeply nested functions.
  • Type hinting: The implemented type hinting ensures that types are correctly inferred by type checkers like pyright.

Installation

You can install State-Monad using pip:

pip install statemonad

Usage

The state object is a Python object that represents the state in your computations. Each operation may modify the state and return a new values based on the updated state. The result is a chain of operations where the state flows through each step, with the State-Monad keeping the flow clean and organized.

Example

In this example, we define the collect_even_numbers operations, which returns a CollectEvenNumbers state monad if the given number is even, or a default state monad encapsulating the value otherwise. The example function performs monadic operations using the collect_even_numbers operator, resulting in a state monad. Finally, the constructed state monad is applied with an empty tuple as the initial state.

from dataclassabc import dataclassabc

import statemonad
from statemonad.abc import StateMonadNode
from statemonad.typing import StateMonad


type State = tuple[int, ...]
state = tuple()


def collect_even_numbers(num: int):
    """
    This function encapsulates the given number within a state monad
    and saves it to the state if the number is even.
    """

    if num % 2 == 0:

        @dataclassabc(frozen=True, slots=True)
        class CollectEvenNumbers(StateMonadNode[State, int]):
            num: int

            def apply(self, state: State):
                n_state = state + (self.num,)
                return n_state, self.num

        return statemonad.from_node(CollectEvenNumbers(num=num))

    else:
        return statemonad.from_[State](num)


# do some monadic operations using `flat_map`
def example(init):
    return collect_even_numbers(init + 1).flat_map(
        lambda x: collect_even_numbers(x + 1).flat_map(
            lambda y: collect_even_numbers(y + 1).flat_map(
                lambda z: collect_even_numbers(z + 1)
            )
        )
    )


monad: StateMonad[State, int] = example(3)

# Output will be
# StateMonad(flat_map(CollectEvenNumbers(num=4), <lambda>))
print(monad)

# Output will be
# monad=StateMonadImpl(
#   child=FlatMapImpl(
#       child=CollectEvenNumbers(num=4),
#   func=<function example.<locals>.<lambda> at 0x000001A546B53D80>))
print(f"{monad=}")

state, value = monad.apply(state)

print(f"{value=}")  # Output will be value=7
print(f"{state=}")  # Output will be state=(4, 6)

Defining the CollectEvenNumbers state monad as a class allows for a clean and readable representation of the resulting Python object. However, some details of this representation is obscured by the lambda function used with the flat_map method.

Do-notation

Using the donotation library, the monadic sequence above can be rewritten with the do-notation as follows:

from donotation import do

@do()
def example(init):
    x = yield from collect_even_numbers(init + 1)
    y = yield from collect_even_numbers(x + 1)
    z = yield from collect_even_numbers(y + 1)
    return collect_even_numbers(z + 1)

Enhanced Traceback

References

Here are some Python libraries that implement the state monad:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

statemonad-0.0.4.tar.gz (11.7 kB view details)

Uploaded Source

Built Distribution

statemonad-0.0.4-py3-none-any.whl (17.9 kB view details)

Uploaded Python 3

File details

Details for the file statemonad-0.0.4.tar.gz.

File metadata

  • Download URL: statemonad-0.0.4.tar.gz
  • Upload date:
  • Size: 11.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for statemonad-0.0.4.tar.gz
Algorithm Hash digest
SHA256 058ce9a06cdcdcbb8d00855352f2ff502bde539177af4f5c042634e82efc37cf
MD5 d5c61196c13bd0e0e3ff4cf0ed82f856
BLAKE2b-256 2120c2eea0e96dc1b87d76e777a677b0d25d196008fc292da46959dbdcb871a1

See more details on using hashes here.

File details

Details for the file statemonad-0.0.4-py3-none-any.whl.

File metadata

  • Download URL: statemonad-0.0.4-py3-none-any.whl
  • Upload date:
  • Size: 17.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.4

File hashes

Hashes for statemonad-0.0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 297aff11a43d663f6d0099413ce9152190ea7178f13ea5effc120a2575147af5
MD5 4c2804c1ef6a991bd4f7080068cd4ebf
BLAKE2b-256 fd1c093bb0293a41a33cc6273870520cf4d0dbdbc475aa02ff097ee326aa13ee

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page