Metadata-Version: 2.3
Name: python-fp-flow
Version: 0.1.0.post2
Summary: A minimalistic FP-oriented function-chaining/flowing library.
Keywords: flow,chain,pipe
Author: Matthijs Wensveen
Author-email: Matthijs Wensveen <matthijs.wensveen@gmail.com>
License: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Project-URL: repository, https://github.com/mrwensveen/python-fp-flow
Description-Content-Type: text/markdown

# python-fp-flow

A minimal FP-oriented library for composing function pipelines in Python.

This project provides two utilities:

- `Flow`: a value wrapper that lets you pipe transformations with the `>>` operator.
- `chain(...)`: a function composer that combines multiple unary callables into one callable.

## Why this library?

Python already lets you compose transformations, but once a pipeline has many steps, nested calls become harder to parse.

Assume we want to:

1. trim and lowercase text
2. remove punctuation
3. split into words
4. remove common stopwords
5. sort unique words
6. format as a summary string

### Shared setup (used by all examples)

```python
import re

STOPWORDS = {"the", "and", "is", "a", "of", "to"}


def strip_punctuation(s: str) -> str:
    return re.sub(r"[^a-z0-9\s]", "", s)


def to_words(s: str) -> list[str]:
    return s.split()


def remove_stopwords(words: list[str]) -> list[str]:
    return [w for w in words if w not in STOPWORDS]


def unique_sorted(words: list[str]) -> list[str]:
    return sorted(set(words))


def summarize(words: list[str]) -> str:
    return f"keywords({len(words)}): {', '.join(words)}"


input_text = "  The Quick, brown fox jumps over the lazy dog!  "
```

### Without this library (nested calls)

```python
result = summarize(
    unique_sorted(
        remove_stopwords(
            to_words(
                strip_punctuation(
                    input_text.strip().lower()
                )
            )
        )
    )
)
```

### With `Flow` (left-to-right data pipeline)

```python
from flow import Flow

result = (
    Flow(input_text)
    >> str.strip
    >> str.lower
    >> strip_punctuation
    >> to_words
    >> remove_stopwords
    >> unique_sorted
    >> summarize
).value()
```

### With `chain` (reusable transformation function)

```python
from chain import chain

text_pipeline = chain(
    str.strip,
    str.lower,
    strip_punctuation,
    to_words,
    remove_stopwords,
    unique_sorted,
    summarize,
)

result = text_pipeline(input_text)
```

`Flow` and `chain` reduce cognitive load by making each step explicit and ordered from top-to-bottom / left-to-right, rather than inside-out.

## Requirements

- Python `>= 3.14`

## Installation

This repository is configured for `uv`.

```bash
uv add python-fp-flow
uv sync
```

If you prefer `pip`: `pip install python-fp-flow`.

## API overview

### `Flow`

- `Flow(value)`: wraps any value.
- `.value()`: returns the current wrapped value.
- `flow >> fn`: applies `fn` to the wrapped value and returns a new `Flow`.

### `chain`

- `chain(fn1, fn2, ..., fnN)`: returns a new callable that applies each function in sequence.
- Designed for unary callables (`Callable[[T], U]`).
- Includes typing overloads for better inference across multi-step pipelines.

## Running tests

```bash
uv run pytest
```

Current tests cover:

- basic `Flow` behavior (`value`, chaining, `repr`, `str`)
- `chain` composition order and exception propagation
