python-monads 0.0.6
Either and Maybe monads for Python
Requires Python: >=3.11

[![GitHub Workflow Status][github workflow status]][github actions link]
[![Donate!][donate github]][github sponsors link]

# Python-Monads

`python-monads` is a Python library that provides implementations for `Either`
and `Maybe` monads. These functional programming constructs help simplify error
handling, chaining computations, and dealing with optional values in a clean and
expressive way.

## Features

- **`Either` Monad**: Represent computations that can return a result (`Right`)
  or an error (`Left`).
- **`Maybe` Monad**: Encapsulate optional values, eliminating the need for
  `None` checks.
- **Type-safe and Pythonic**: Leverages Python's type hints and idiomatic
  programming style.
- **Extensive Test Suite**: Ensure reliability with a high test coverage.

## Installation

### Using UV

```bash
uv add python-monads
```

## Quick Start

### Using `Either`

```python
from python_monads.either import Either

# Example with Right
result = Either.from_right("Success")
print(result)  # Output: Right(Success)

# Example with Left
error = Either.from_left("Error")
print(error)  # Output: Left(Error)

def process_value(value):
    return Either.from_right(value.upper())

# Chaining computations
chained_result = result.bind(process_value)
print(chained_result)  # Output: Right(SUCCESS)
```

### Using `Maybe`

```python
from python_monads.maybe import Maybe

# Example with value
value = Maybe.just(42)
print(value)  # Output: 42

# Example with None
nothing = Maybe.nothing()
print(nothing)  # Output: None

# Transforming values
result = value.map(lambda x: x * 2)
print(result)  # Output: 84
```

## Development Setup

This project uses **Nix** for reproducible development environments.

### Prerequisites

- [Nix](https://nixos.org/)

### Setup

1. Clone the repository:

   ```bash
   git clone https://github.com/drupol/python-monads.git
   cd python-monads
   ```

2. Create a virtual environment and install dependencies:

   ```bash
   nix develop
   ```

## Testing

Run the tests using `pytest`:

```bash
pytest
```

### Code Style

We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. Run
the following command to ensure your code adheres to the style guide:

```bash
ruff check .
ruff format .
```

## Contributing

Feel free to contribute by sending pull requests. We are a usually very
responsive team and we will help you going through your pull request from the
beginning to the end, read more about it in the
[documentation][contributing doc page].

For some reasons, if you can't contribute to the code and willing to help,
sponsoring is a good, sound and safe way to show us some gratitude for the hours
we invested in this package.

Sponsor me on [Github][github sponsors link] and/or any of [the
contributors][the contributors].

[github actions link]: https://github.com/drupol/python-monads/actions
[github sponsors link]: https://github.com/sponsors/drupol
[github workflow status]:
  https://img.shields.io/github/actions/workflow/status/drupol/python-monads/tests.yml?branch=main&style=flat-square
[donate github]:
  https://img.shields.io/badge/Sponsor-Github-brightgreen.svg?style=flat-square
[the contributors]: https://github.com/loophp/collection/graphs/contributors