punctional 0.1.0__py3-none-any.whl

punctional/__init__.py

@@ -0,0 +1,61 @@
+"""
+Punctional - A functional programming framework for Python.
+
+Provides composable filters and method chaining for native types and custom dataclasses.
+"""
+
+from .core import Filter, Functional, Compose
+from .types import FunctionalInt, FunctionalFloat, FunctionalStr, fint, ffloat, fstr
+from .arithmetic import Add, Mult, Sub, Div
+from .logical import AndFilter, OrFilter, NotFilter
+from .comparison import GreaterThan, LessThan, Equals
+from .string import ToUpper, ToLower, Contains
+from .list_filters import Map, FilterList, Reduce
+from .monads import Option, Some, Nothing, Result, Ok, Error, some, try_result
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "Filter",
+    "Functional",
+    # Types
+    "FunctionalInt",
+    "FunctionalFloat",
+    "FunctionalStr",
+    "fint",
+    "ffloat",
+    "fstr",
+    # Arithmetic
+    "Add",
+    "Mult",
+    "Sub",
+    "Div",
+    # Logical
+    "AndFilter",
+    "OrFilter",
+    "NotFilter",
+    # Comparison
+    "GreaterThan",
+    "LessThan",
+    "Equals",
+    # String
+    "ToUpper",
+    "ToLower",
+    "Contains",
+    # Composition
+    "Compose",
+    # List
+    "Map",
+    "FilterList",
+    "Reduce",
+    # Monads
+    "Option",
+    "Some",
+    "Nothing",
+    "Result",
+    "Ok",
+    "Error",
+    "some",
+    "try_result",
+]

punctional/arithmetic.py

@@ -0,0 +1,46 @@
+"""
+Arithmetic operation filters (Add, Mult, Sub, Div).
+"""
+
+from typing import Any
+from .core import Filter
+
+
+class Add(Filter[Any, Any]):
+    """Addition filter - adds a value."""
+    
+    def __init__(self, addend: Any):
+        self.addend = addend
+    
+    def apply(self, value: Any) -> Any:
+        return value + self.addend
+
+
+class Mult(Filter[Any, Any]):
+    """Multiplication filter - multiplies by a value."""
+    
+    def __init__(self, multiplier: Any):
+        self.multiplier = multiplier
+    
+    def apply(self, value: Any) -> Any:
+        return value * self.multiplier
+
+
+class Sub(Filter[Any, Any]):
+    """Subtraction filter - subtracts a value."""
+    
+    def __init__(self, subtrahend: Any):
+        self.subtrahend = subtrahend
+    
+    def apply(self, value: Any) -> Any:
+        return value - self.subtrahend
+
+
+class Div(Filter[Any, Any]):
+    """Division filter - divides by a value."""
+    
+    def __init__(self, divisor: Any):
+        self.divisor = divisor
+    
+    def apply(self, value: Any) -> Any:
+        return value / self.divisor

punctional/comparison.py

@@ -0,0 +1,36 @@
+"""
+Comparison filters (GreaterThan, LessThan, Equals).
+"""
+
+from typing import Any
+from .core import Filter
+
+
+class GreaterThan(Filter[Any, bool]):
+    """Check if value is greater than threshold."""
+    
+    def __init__(self, threshold: Any):
+        self.threshold = threshold
+    
+    def apply(self, value: Any) -> bool:
+        return value > self.threshold
+
+
+class LessThan(Filter[Any, bool]):
+    """Check if value is less than threshold."""
+    
+    def __init__(self, threshold: Any):
+        self.threshold = threshold
+    
+    def apply(self, value: Any) -> bool:
+        return value < self.threshold
+
+
+class Equals(Filter[Any, bool]):
+    """Check if value equals another value."""
+    
+    def __init__(self, target: Any):
+        self.target = target
+    
+    def apply(self, value: Any) -> bool:
+        return value == self.target

punctional/core.py

@@ -0,0 +1,92 @@
+"""
+Core abstractions for the Punctional functional programming framework.
+"""
+
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Any, TypeVar, Generic
+
+T = TypeVar('T')
+U = TypeVar('U')
+
+
+class Filter(ABC, Generic[T, U]):
+    """
+    Abstract base class for all functional filters.
+    A filter transforms input of type T to output of type U.
+    """
+
+    @abstractmethod
+    def apply(self, value: T) -> U:
+        """Apply the filter to a value."""
+        pass
+
+    def __call__(self, value: T) -> U:
+        """Allow filters to be called as functions."""
+        return self.apply(value)
+
+    def __or__(self, other: Filter) -> Compose:
+        """Enable pipe operator for filter composition: filter1 | filter2"""
+        # Import here to avoid circular dependency at module level
+        # Compose is defined below in this same module
+        return Compose(self, other)
+
+    def __and__(self, other: Filter) -> 'AndFilter':
+        """Enable & operator for logical AND"""
+        return AndFilter(self, other)
+
+
+class AndFilter(Filter[T, bool]):
+    """Logical AND filter - applies multiple filters and returns True if all are True."""
+
+    def __init__(self, *filters: Filter):
+        self.filters = filters
+
+    def apply(self, value: T) -> bool:
+        return all(f.apply(value) for f in self.filters)
+
+
+class Compose(Filter[T, Any]):
+    """Compose multiple filters into a pipeline."""
+
+    def __init__(self, *filters: Filter):
+        self.filters = filters
+
+    def apply(self, value: T) -> Any:
+        result = value
+        for filter in self.filters:
+            result = filter.apply(result)
+        return result
+
+
+class Functional:
+    """
+    Mixin class that adds functional programming capabilities to any class.
+    Inherit from this to enable method chaining and filter application.
+    """
+
+    def pipe(self, filter: Filter) -> Any:
+        """Apply a filter to this object."""
+        result = filter.apply(self)
+        return self._wrap_result(result)
+
+    def __or__(self, filter: Filter) -> Any:
+        """Enable pipe operator: obj | filter"""
+        result = filter.apply(self)
+        return self._wrap_result(result)
+
+    @staticmethod
+    def _wrap_result(result: Any) -> Any:
+        """Wrap basic types in functional wrappers for continued chaining."""
+        if isinstance(result, Functional):
+            return result
+        elif isinstance(result, int) and not isinstance(result, bool):
+            from .types import FunctionalInt
+            return FunctionalInt(result)
+        elif isinstance(result, float):
+            from .types import FunctionalFloat
+            return FunctionalFloat(result)
+        elif isinstance(result, str):
+            from .types import FunctionalStr
+            return FunctionalStr(result)
+        return result

punctional/list_filters.py

@@ -0,0 +1,40 @@
+"""
+Filters for List operations (Map, FilterList, Reduce).
+"""
+
+from typing import Any, List
+from functools import reduce
+from .core import Filter
+
+
+class Map(Filter[List, List]):
+    """Map a filter over a List."""
+
+    def __init__(self, filter: Filter):
+        self.filter = filter
+
+    def apply(self, values: List) -> List:
+        return [self.filter.apply(v) for v in values]
+
+
+class FilterList(Filter[List, List]):
+    """Filter a List based on a predicate."""
+
+    def __init__(self, predicate: Filter[Any, bool]):
+        self.predicate = predicate
+
+    def apply(self, values: List) -> List:
+        return [v for v in values if self.predicate.apply(v)]
+
+
+class Reduce(Filter[List, Any]):
+    """Reduce a List to a single value using a filter."""
+
+    def __init__(self, filter: Filter, initial: Any = None):
+        self.filter = filter
+        self.initial = initial
+
+    def apply(self, values: List) -> Any:
+        if self.initial is not None:
+            return reduce(lambda acc, x: self.filter.apply((acc, x)), values, self.initial)
+        return reduce(lambda acc, x: self.filter.apply((acc, x)), values)

punctional/logical.py

@@ -0,0 +1,38 @@
+"""
+Logical operation filters (And, Or, Not).
+"""
+
+from typing import TypeVar
+from .core import Filter
+
+T = TypeVar('T')
+
+
+class AndFilter(Filter[T, bool]):
+    """Logical AND filter - applies multiple filters and returns True if all are True."""
+
+    def __init__(self, *filters: Filter):
+        self.filters = filters
+
+    def apply(self, value: T) -> bool:
+        return all(f.apply(value) for f in self.filters)
+
+
+class OrFilter(Filter[T, bool]):
+    """Logical OR filter - applies multiple filters and returns True if any is True."""
+
+    def __init__(self, *filters: Filter):
+        self.filters = filters
+
+    def apply(self, value: T) -> bool:
+        return any(f.apply(value) for f in self.filters)
+
+
+class NotFilter(Filter[T, bool]):
+    """Logical NOT filter - negates the result of another filter."""
+
+    def __init__(self, filter: Filter[T, bool]):
+        self.filter = filter
+
+    def apply(self, value: T) -> bool:
+        return not self.filter.apply(value)

punctional/monads.py

@@ -0,0 +1,357 @@
+"""
+Monad implementations for functional programming patterns.
+
+Provides Option (Some/Nothing) and Result (Ok/Error) monads with standard
+monadic operations like map, bind, and flat_map.
+"""
+
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import TypeVar, Generic, Callable, Any, Union, Optional
+from dataclasses import dataclass
+
+T = TypeVar('T')
+U = TypeVar('U')
+E = TypeVar('E')
+
+
+class Option(ABC, Generic[T]):
+    """
+    Option monad representing the presence (Some) or absence (Nothing) of a value.
+    
+    Useful for handling nullable values without explicit None checks.
+    """
+
+    @abstractmethod
+    def map(self, f: Callable[[T], U]) -> Option[U]:
+        """Transform the contained value if present."""
+        pass
+
+    @abstractmethod
+    def flat_map(self, f: Callable[[T], Option[U]]) -> Option[U]:
+        """Chain operations that return Options (also called bind or >>=)."""
+        pass
+
+    @abstractmethod
+    def bind(self, f: Callable[[T], Option[U]]) -> Option[U]:
+        """Alias for flat_map (monadic bind operation)."""
+        pass
+
+    @abstractmethod
+    def get_or_else(self, default: T) -> T:
+        """Get the value or return a default."""
+        pass
+
+    @abstractmethod
+    def get_or_none(self) -> Optional[T]:
+        """Get the value or return None."""
+        pass
+
+    @abstractmethod
+    def is_some(self) -> bool:
+        """Check if this is Some."""
+        pass
+
+    @abstractmethod
+    def is_nothing(self) -> bool:
+        """Check if this is Nothing."""
+        pass
+
+    @abstractmethod
+    def filter(self, predicate: Callable[[T], bool]) -> Option[T]:
+        """Return Nothing if predicate is False, otherwise return self."""
+        pass
+
+    @abstractmethod
+    def or_else(self, alternative: Option[T]) -> Option[T]:
+        """Return self if Some, otherwise return alternative."""
+        pass
+
+    def __bool__(self) -> bool:
+        """Enable truthiness checks."""
+        return self.is_some()
+
+
+@dataclass(frozen=True)
+class Some(Option[T]):
+    """Represents the presence of a value."""
+    
+    value: T
+
+    def map(self, f: Callable[[T], U]) -> Option[U]:
+        """Apply function to the contained value."""
+        return Some(f(self.value))
+
+    def flat_map(self, f: Callable[[T], Option[U]]) -> Option[U]:
+        """Apply function that returns an Option."""
+        return f(self.value)
+
+    def bind(self, f: Callable[[T], Option[U]]) -> Option[U]:
+        """Monadic bind (alias for flat_map)."""
+        return self.flat_map(f)
+
+    def get_or_else(self, default: T) -> T:
+        """Return the contained value."""
+        return self.value
+
+    def get_or_none(self) -> Optional[T]:
+        """Return the contained value."""
+        return self.value
+
+    def is_some(self) -> bool:
+        """Always True for Some."""
+        return True
+
+    def is_nothing(self) -> bool:
+        """Always False for Some."""
+        return False
+
+    def filter(self, predicate: Callable[[T], bool]) -> Option[T]:
+        """Return self if predicate passes, otherwise Nothing."""
+        return self if predicate(self.value) else Nothing()
+
+    def or_else(self, alternative: Option[T]) -> Option[T]:
+        """Return self since we have a value."""
+        return self
+
+    def __repr__(self) -> str:
+        return f"Some({self.value!r})"
+
+
+class NothingType(Option[T]):
+    """Represents the absence of a value (singleton pattern)."""
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def map(self, f: Callable[[T], U]) -> Option[U]:
+        """Nothing remains Nothing."""
+        return self
+
+    def flat_map(self, f: Callable[[T], Option[U]]) -> Option[U]:
+        """Nothing remains Nothing."""
+        return self
+
+    def bind(self, f: Callable[[T], Option[U]]) -> Option[U]:
+        """Nothing remains Nothing."""
+        return self
+
+    def get_or_else(self, default: T) -> T:
+        """Return the default value."""
+        return default
+
+    def get_or_none(self) -> Optional[T]:
+        """Return None."""
+        return None
+
+    def is_some(self) -> bool:
+        """Always False for Nothing."""
+        return False
+
+    def is_nothing(self) -> bool:
+        """Always True for Nothing."""
+        return True
+
+    def filter(self, predicate: Callable[[T], bool]) -> Option[T]:
+        """Nothing remains Nothing."""
+        return self
+
+    def or_else(self, alternative: Option[T]) -> Option[T]:
+        """Return the alternative since we have no value."""
+        return alternative
+
+    def __repr__(self) -> str:
+        return "Nothing"
+
+    def __bool__(self) -> bool:
+        """Nothing is falsy."""
+        return False
+
+
+# Singleton instance
+Nothing = NothingType
+
+
+def some(value: Optional[T], allow_none: bool = False) -> Option[T]:
+    """
+    Create an Option from a potentially None value.
+    
+    Args:
+        value: The value to wrap
+        allow_none: If True, wrap None as Some(None). If False, return Nothing for None.
+    
+    Returns:
+        Some(value) if value is not None or allow_none is True
+        Nothing if value is None and allow_none is False
+    
+    Examples:
+        >>> some(5)
+        Some(5)
+        >>> some(None)
+        Nothing
+        >>> some(None, allow_none=True)
+        Some(None)
+    """
+    if value is None and not allow_none:
+        return Nothing()
+    return Some(value)
+
+
+class Result(ABC, Generic[T, E]):
+    """
+    Result monad representing either a success (Ok) or failure (Error).
+    
+    Useful for operations that can fail with an error value.
+    """
+
+    @abstractmethod
+    def map(self, f: Callable[[T], U]) -> Result[U, E]:
+        """Transform the success value if present."""
+        pass
+
+    @abstractmethod
+    def map_error(self, f: Callable[[E], U]) -> Result[T, U]:
+        """Transform the error value if present."""
+        pass
+
+    @abstractmethod
+    def flat_map(self, f: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        """Chain operations that return Results."""
+        pass
+
+    @abstractmethod
+    def bind(self, f: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        """Alias for flat_map (monadic bind)."""
+        pass
+
+    @abstractmethod
+    def get_or_else(self, default: T) -> T:
+        """Get the success value or return a default."""
+        pass
+
+    @abstractmethod
+    def is_ok(self) -> bool:
+        """Check if this is Ok."""
+        pass
+
+    @abstractmethod
+    def is_error(self) -> bool:
+        """Check if this is Error."""
+        pass
+
+    @abstractmethod
+    def to_option(self) -> Option[T]:
+        """Convert to Option, discarding error information."""
+        pass
+
+    def __bool__(self) -> bool:
+        """Enable truthiness checks (Ok is truthy, Error is falsy)."""
+        return self.is_ok()
+
+
+@dataclass(frozen=True)
+class Ok(Result[T, E]):
+    """Represents a successful result."""
+    
+    value: T
+
+    def map(self, f: Callable[[T], U]) -> Result[U, E]:
+        """Apply function to the success value."""
+        return Ok(f(self.value))
+
+    def map_error(self, f: Callable[[E], U]) -> Result[T, U]:
+        """Leave Ok unchanged."""
+        return self
+
+    def flat_map(self, f: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        """Apply function that returns a Result."""
+        return f(self.value)
+
+    def bind(self, f: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        """Monadic bind (alias for flat_map)."""
+        return self.flat_map(f)
+
+    def get_or_else(self, default: T) -> T:
+        """Return the success value."""
+        return self.value
+
+    def is_ok(self) -> bool:
+        """Always True for Ok."""
+        return True
+
+    def is_error(self) -> bool:
+        """Always False for Ok."""
+        return False
+
+    def to_option(self) -> Option[T]:
+        """Convert to Some with the value."""
+        return Some(self.value)
+
+    def __repr__(self) -> str:
+        return f"Ok({self.value!r})"
+
+
+@dataclass(frozen=True)
+class Error(Result[T, E]):
+    """Represents a failed result with an error value."""
+    
+    error: E
+
+    def map(self, f: Callable[[T], U]) -> Result[U, E]:
+        """Error remains Error."""
+        return self
+
+    def map_error(self, f: Callable[[E], U]) -> Result[T, U]:
+        """Apply function to the error value."""
+        return Error(f(self.error))
+
+    def flat_map(self, f: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        """Error remains Error."""
+        return self
+
+    def bind(self, f: Callable[[T], Result[U, E]]) -> Result[U, E]:
+        """Error remains Error."""
+        return self
+
+    def get_or_else(self, default: T) -> T:
+        """Return the default value."""
+        return default
+
+    def is_ok(self) -> bool:
+        """Always False for Error."""
+        return False
+
+    def is_error(self) -> bool:
+        """Always True for Error."""
+        return True
+
+    def to_option(self) -> Option[T]:
+        """Convert to Nothing."""
+        return Nothing()
+
+    def __repr__(self) -> str:
+        return f"Error({self.error!r})"
+
+
+# Utility functions for creating Results
+def try_result(f: Callable[[], T], error_handler: Optional[Callable[[Exception], E]] = None) -> Result[T, Union[E, Exception]]:
+    """
+    Execute a function and wrap the result in Ok or Error.
+    
+    Args:
+        f: Function to execute
+        error_handler: Optional function to transform exceptions into error values
+    
+    Returns:
+        Ok(result) if successful, Error(exception) or Error(error_handler(exception)) if failed
+    """
+    try:
+        return Ok(f())
+    except Exception as e:
+        if error_handler:
+            return Error(error_handler(e))
+        return Error(e)

punctional/string.py

@@ -0,0 +1,29 @@
+"""
+String manipulation filters.
+"""
+
+from .core import Filter
+
+
+class ToUpper(Filter[str, str]):
+    """Convert string to uppercase."""
+    
+    def apply(self, value: str) -> str:
+        return value.upper()
+
+
+class ToLower(Filter[str, str]):
+    """Convert string to lowercase."""
+    
+    def apply(self, value: str) -> str:
+        return value.lower()
+
+
+class Contains(Filter[str, bool]):
+    """Check if string contains substring."""
+    
+    def __init__(self, substring: str):
+        self.substring = substring
+    
+    def apply(self, value: str) -> bool:
+        return self.substring in value

punctional/types.py

@@ -0,0 +1,63 @@
+"""
+Functional wrapper types for Python native types (int, float, str).
+"""
+
+from .core import Functional, Filter
+
+
+class FunctionalInt(int, Functional):
+    """Int with functional programming capabilities."""
+    
+    def __or__(self, other):
+        """Override to support Filter piping, fall back to bitwise OR for ints."""
+        if isinstance(other, Filter):
+            result = other.apply(self)
+            return self._wrap_result(result)
+        return int.__or__(self, other)
+    
+    def __new__(cls, value):
+        return int.__new__(cls, value)
+
+
+class FunctionalFloat(float, Functional):
+    """Float with functional programming capabilities."""
+    
+    def __or__(self, other):
+        """Support Filter piping."""
+        if isinstance(other, Filter):
+            result = other.apply(self)
+            return self._wrap_result(result)
+        return NotImplemented
+    
+    def __new__(cls, value):
+        return float.__new__(cls, value)
+
+
+class FunctionalStr(str, Functional):
+    """String with functional programming capabilities."""
+    
+    def __or__(self, other):
+        """Support Filter piping."""
+        if isinstance(other, Filter):
+            result = other.apply(self)
+            return self._wrap_result(result)
+        return NotImplemented
+    
+    def __new__(cls, value):
+        return str.__new__(cls, value)
+
+
+# Convenience constructors
+def fint(value: int) -> FunctionalInt:
+    """Create a functional integer."""
+    return FunctionalInt(value)
+
+
+def ffloat(value: float) -> FunctionalFloat:
+    """Create a functional float."""
+    return FunctionalFloat(value)
+
+
+def fstr(value: str) -> FunctionalStr:
+    """Create a functional string."""
+    return FunctionalStr(value)

punctional-0.1.0.dist-info/METADATA

@@ -0,0 +1,445 @@
+Metadata-Version: 2.4
+Name: punctional
+Version: 0.1.0
+Summary: A functional programming framework for Python — composable filters, method chaining, and expressive data pipelines with Option and Result monads.
+Project-URL: Homepage, https://github.com/peghaz/punctional
+Project-URL: Repository, https://github.com/peghaz/punctional
+Project-URL: Documentation, https://github.com/peghaz/punctional#readme
+Project-URL: Issues, https://github.com/peghaz/punctional/issues
+Author-email: Mehdi Peghaz <peghaz@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: composition,data-pipeline,filters,functional-programming,method-chaining,monads,option,pipe-operator,result
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Punctional
+
+> A functional programming framework for Python — enabling composable filters, method chaining, and expressive data pipelines.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## 🎯 What is Punctional?
+
+**Punctional** is a lightweight functional programming library that brings powerful functional programming patterns to Python. It allows you to compose operations using an intuitive pipe (`|`) operator, create reusable transformation filters, and apply common functional design patterns like Option and Result monads.
+
+Whether you're building data pipelines, validation logic, or just want cleaner, more declarative code — Punctional provides the building blocks.
+
+## ✨ Key Features
+
+- **🔗 Pipe Operator Chaining** — Chain transformations using the intuitive `|` operator
+- **🧱 Composable Filters** — Create reusable, testable transformation units
+- **📦 Functional Wrappers** — Wrap native types (`int`, `float`, `str`) for functional operations
+- **🎭 Monads** — Built-in `Option` (Some/Nothing) and `Result` (Ok/Error) monads
+- **🔧 Extensible** — Easily create custom filters for your domain
+- **📋 Dataclass Support** — Make any dataclass functional with the `Functional` mixin
+
+## 📦 Installation
+
+```bash
+pip install punctional
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/peghaz/punctional.git
+cd punctional
+pip install -e .
+```
+
+## 🚀 Quick Start
+
+```python
+from punctional import fint, fstr, Add, Mult, ToUpper, GreaterThan, AndFilter, LessThan
+
+# Arithmetic chaining
+result = fint(10) | Add(5) | Mult(2)  # (10 + 5) * 2 = 30
+
+# String transformations
+text = fstr("hello") | ToUpper() | Add("!")  # "HELLO!"
+
+# Logical validation
+is_valid = fint(42) | AndFilter(GreaterThan(10), LessThan(100))  # True
+```
+
+## 📚 Core Concepts
+
+### Filters
+
+A **Filter** is the fundamental building block — a transformation that takes an input and produces an output:
+
+```python
+from punctional import Filter, fint
+
+class Square(Filter[int, int]):
+    def apply(self, value: int) -> int:
+        return value ** 2
+
+# Use it
+result = fint(5) | Square()  # 25
+```
+
+### Functional Wrappers
+
+Wrap native Python types to enable pipe operations:
+
+| Function | Type | Description |
+|----------|------|-------------|
+| `fint(x)` | `FunctionalInt` | Functional integer wrapper |
+| `ffloat(x)` | `FunctionalFloat` | Functional float wrapper |
+| `fstr(x)` | `FunctionalStr` | Functional string wrapper |
+
+### The Pipe Operator
+
+Chain filters using the `|` operator for readable, left-to-right transformations:
+
+```python
+# Instead of nested calls:
+result = Div(4).apply(Sub(3).apply(Mult(2).apply(Add(5).apply(10))))
+
+# Write declaratively:
+result = fint(10) | Add(5) | Mult(2) | Sub(3) | Div(4)
+```
+
+## 🔧 Built-in Filters
+
+### Arithmetic Filters
+
+```python
+from punctional import Add, Sub, Mult, Div
+
+fint(10) | Add(5)   # 15
+fint(10) | Sub(3)   # 7
+fint(10) | Mult(2)  # 20
+fint(10) | Div(4)   # 2.5
+```
+
+### Comparison Filters
+
+```python
+from punctional import GreaterThan, LessThan, Equals
+
+fint(42) | GreaterThan(10)  # True
+fint(5) | LessThan(10)      # True
+fint(42) | Equals(42)       # True
+```
+
+### Logical Filters
+
+```python
+from punctional import AndFilter, OrFilter, NotFilter, GreaterThan, LessThan, Equals
+
+# AND: all conditions must be true
+fint(42) | AndFilter(GreaterThan(10), LessThan(100))  # True
+
+# OR: at least one condition must be true
+fint(5) | OrFilter(LessThan(10), GreaterThan(100))    # True
+
+# NOT: negate a condition
+fint(5) | NotFilter(Equals(0))                        # True
+```
+
+### String Filters
+
+```python
+from punctional import ToUpper, ToLower, Contains, fstr
+
+fstr("hello") | ToUpper()              # "HELLO"
+fstr("WORLD") | ToLower()              # "world"
+fstr("hello world") | Contains("world") # True
+fstr("ha") | Mult(3)                   # "hahaha"
+```
+
+### List Filters
+
+```python
+from punctional import Map, FilterList, Reduce, Mult, GreaterThan
+
+numbers = [1, 2, 3, 4, 5]
+
+# Transform each element
+Map(Mult(2)).apply(numbers)  # [2, 4, 6, 8, 10]
+
+# Filter elements
+FilterList(GreaterThan(2)).apply(numbers)  # [3, 4, 5]
+```
+
+### Composition
+
+Create reusable pipelines with `Compose`:
+
+```python
+from punctional import Compose, Mult, Add, fint
+
+# Create a reusable transformation
+double_plus_ten = Compose(Mult(2), Add(10))
+
+fint(5) | double_plus_ten   # 20
+fint(10) | double_plus_ten  # 30
+```
+
+## 🎭 Functional Design Patterns
+
+### Option Monad (Some/Nothing)
+
+Handle nullable values without explicit `None` checks:
+
+```python
+from punctional import Some, Nothing, some
+
+# Wrap a value
+value = Some(42)
+print(value.map(lambda x: x * 2))  # Some(84)
+print(value.get_or_else(0))        # 42
+
+# Handle absence
+empty = Nothing()
+print(empty.map(lambda x: x * 2))  # Nothing
+print(empty.get_or_else(0))        # 0
+
+# Auto-convert from potentially None values
+result = some(potentially_none_value)  # Returns Nothing if None
+```
+
+#### Option Operations
+
+| Method | Description |
+|--------|-------------|
+| `map(f)` | Transform value if present |
+| `flat_map(f)` | Chain operations returning Option |
+| `bind(f)` | Alias for flat_map |
+| `get_or_else(default)` | Get value or default |
+| `get_or_none()` | Get value or None |
+| `filter(predicate)` | Return Nothing if predicate fails |
+| `or_else(alternative)` | Return alternative if Nothing |
+| `is_some()` | Check if value is present |
+| `is_nothing()` | Check if value is absent |
+
+### Result Monad (Ok/Error)
+
+Handle operations that can fail with meaningful errors:
+
+```python
+from punctional import Ok, Error, try_result
+
+# Successful operation
+success = Ok(42)
+print(success.map(lambda x: x * 2))  # Ok(84)
+
+# Failed operation
+failure = Error("Something went wrong")
+print(failure.map(lambda x: x * 2))  # Error("Something went wrong")
+
+# Wrap potentially throwing functions
+def divide(a, b):
+    return a / b
+
+result = try_result(lambda: divide(10, 0))
+# Error(ZeroDivisionError(...))
+```
+
+#### Result Operations
+
+| Method | Description |
+|--------|-------------|
+| `map(f)` | Transform success value |
+| `map_error(f)` | Transform error value |
+| `flat_map(f)` | Chain operations returning Result |
+| `bind(f)` | Alias for flat_map |
+| `get_or_else(default)` | Get value or default |
+| `is_ok()` | Check if successful |
+| `is_error()` | Check if failed |
+| `to_option()` | Convert to Option (discards error info) |
+
+## 🏗️ Extending the Framework
+
+### Creating Custom Filters
+
+#### Simple Filter
+
+```python
+from punctional import Filter
+
+class Increment(Filter[int, int]):
+    def apply(self, value: int) -> int:
+        return value + 1
+```
+
+#### Parameterized Filter
+
+```python
+class Power(Filter[int, int]):
+    def __init__(self, exponent: int):
+        self.exponent = exponent
+    
+    def apply(self, value: int) -> int:
+        return value ** self.exponent
+
+fint(2) | Power(3)  # 8
+```
+
+#### Stateful Filter
+
+```python
+class Accumulator(Filter[int, int]):
+    def __init__(self, initial: int = 0):
+        self.total = initial
+    
+    def apply(self, value: int) -> int:
+        self.total += value
+        return self.total
+
+acc = Accumulator()
+acc(5)   # 5
+acc(10)  # 15
+acc(3)   # 18
+```
+
+### Functional Dataclasses
+
+Make any dataclass functional with the `Functional` mixin:
+
+```python
+from dataclasses import dataclass
+from punctional import Functional, Filter
+
+@dataclass
+class Point(Functional):
+    x: float
+    y: float
+
+class ScalePoint(Filter[Point, Point]):
+    def __init__(self, factor: float):
+        self.factor = factor
+    
+    def apply(self, point: Point) -> Point:
+        return Point(point.x * self.factor, point.y * self.factor)
+
+# Now Point supports piping!
+point = Point(3, 4)
+scaled = point | ScalePoint(2.5)  # Point(7.5, 10.0)
+```
+
+## 📖 Examples
+
+The [examples/](examples/) directory contains comprehensive examples:
+
+| File | Description |
+|------|-------------|
+| [basics.py](examples/basics.py) | Basic usage and introduction to all features |
+| [extending.py](examples/extending.py) | Guide to creating custom filters and domain-specific extensions |
+| [data_transformation.py](examples/data_transformation.py) | Advanced patterns: validation pipelines, data transformations |
+| [quick_reference.py](examples/quick_reference.py) | Cheat sheet for quick lookup |
+
+### Run the examples:
+
+```bash
+python -m examples.basics
+python -m examples.extending
+python -m examples.data_transformation
+```
+
+## 🧪 Common Patterns
+
+### Validation Pipeline
+
+```python
+from punctional import AndFilter, Functional, Filter
+from dataclasses import dataclass
+
+@dataclass
+class Person(Functional):
+    name: str
+    age: int
+    email: str
+
+class ValidateName(Filter[Person, bool]):
+    def apply(self, person: Person) -> bool:
+        return 1 <= len(person.name) <= 100
+
+class ValidateAge(Filter[Person, bool]):
+    def apply(self, person: Person) -> bool:
+        return 0 <= person.age <= 150
+
+class ValidateEmail(Filter[Person, bool]):
+    def apply(self, person: Person) -> bool:
+        return "@" in person.email and "." in person.email
+
+# Use the validation pipeline
+person = Person("Alice", 30, "alice@example.com")
+is_valid = person | AndFilter(ValidateName(), ValidateAge(), ValidateEmail())  # True
+```
+
+### Data Transformation Pipeline
+
+```python
+class ApplyBonus(Filter[Person, Person]):
+    def __init__(self, percentage: float):
+        self.percentage = percentage
+    
+    def apply(self, person: Person) -> Person:
+        return Person(person.name, person.age, person.email)
+
+person | ApplyBonus(10) | PromoteAge() | SaveToDatabase()
+```
+
+### List Processing Pipeline
+
+```python
+from punctional import FilterList, Map, Mult
+
+class IsEven(Filter[int, bool]):
+    def apply(self, value: int) -> bool:
+        return value % 2 == 0
+
+numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+result = FilterList(IsEven()).apply(numbers)  # [2, 4, 6, 8, 10]
+doubled = Map(Mult(2)).apply(result)          # [4, 8, 12, 16, 20]
+```
+
+### Error Handling with Result
+
+```python
+from punctional import Result, Ok, Error
+
+def fetch_user(id: int) -> Result[dict, str]:
+    if id < 0:
+        return Error("Invalid ID")
+    return Ok({"id": id, "name": "Alice"})
+
+result = fetch_user(42).map(lambda u: u["name"]).get_or_else("Unknown")  # "Alice"
+result = fetch_user(-1).map(lambda u: u["name"]).get_or_else("Unknown")  # "Unknown"
+```
+
+## 🎓 Design Principles
+
+1. **Immutability** — Filters don't modify input; they return new values
+2. **Composability** — Filters can be combined to create complex transformations
+3. **Type Safety** — Generic types help catch errors at development time
+4. **Readability** — Pipe operator makes data flow explicit and easy to follow
+5. **Extensibility** — Easy to create domain-specific filters
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+<p align="center">
+  Made with ❤️ for functional programming enthusiasts
+</p>

punctional-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+punctional/__init__.py,sha256=gylyr0Ij6x97I0vc62JzaoRszhcPUdGqwhHl03ooBKY,1271
+punctional/arithmetic.py,sha256=TzU5wJqu0olmEyh-TuHIpMH_2mw-EFoDRxmK6kAFbUU,1071
+punctional/comparison.py,sha256=X9SzAXbNXUR5_lmPaZPaTMqM_0zwlvNPb93pcpipogI,850
+punctional/core.py,sha256=g3VuKNpfbIBoNf8OEAUDtc5bLdr-PAbbMwupnkz8wPE,2838
+punctional/list_filters.py,sha256=Ta9Te7D_qwf32hyQxkThw7nazbSts0jn6gF3qKjgzPk,1127
+punctional/logical.py,sha256=3TR0Bgv-SwUjo4o177hHe8YLTr3jG4Kb13GZBGmEb9w,980
+punctional/monads.py,sha256=zDGr7GMhiGc5whNj81lQTDgxfJtBOuh8IuNGpT7gq5g,9739
+punctional/string.py,sha256=E8Ajo7_Rok55_ZNbDFQgCub0VCM4-fW_bUNswyUqDds,607
+punctional/types.py,sha256=gS8Z3XtHKT0dttuGUMFsZWMoiLKuE51cRZMOVVaNKJw,1724
+punctional-0.1.0.dist-info/METADATA,sha256=bht_JYz963a87ZmZVfSFspxfZAwxd67UrhPqFSOFBls,12337
+punctional-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+punctional-0.1.0.dist-info/licenses/LICENSE,sha256=-iDh_gcypGAb576TWRWkMhTMvuAaOML4rZwKV1s8Xoo,1070
+punctional-0.1.0.dist-info/RECORD,,

punctional-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

punctional-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mehdi Yaminli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.