punctional 0.1.2__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.2"
+
+__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.2.dist-info/METADATA

@@ -0,0 +1,426 @@
+Metadata-Version: 2.4
+Name: punctional
+Version: 0.1.2
+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 Yaminli <mehdiyamin@gmail.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.10
+Description-Content-Type: text/markdown
+
+# Punctional
+
+> Functional programming for Python — monads, composable filters, 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** brings robust functional programming patterns to Python. It provides:
+
+- **Monads** for safe error handling and null-safety (`Option`, `Result`)
+- **Composable filters** that chain with the pipe (`|`) operator
+- **Functional wrappers** for native types enabling method chaining
+
+No dependencies. Pure Python. Type-safe.
+
+## Installation
+
+```bash
+pip install punctional
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/peghaz/punctional.git
+cd punctional
+pip install -e .
+```
+
+---
+
+## Core Features
+
+### 1. Option Monad — Safe Null Handling
+
+The `Option` type represents a value that may or may not exist. Use `Some` to wrap a value and `Nothing` to represent absence — eliminating `None` checks and `AttributeError` exceptions.
+
+```python
+from punctional import Some, Nothing, some
+
+# Wrap existing values
+user_name = Some("Alice")
+print(user_name.map(str.upper))         # Some('ALICE')
+print(user_name.get_or_else("Unknown")) # 'Alice'
+
+# Handle missing values safely
+missing = Nothing()
+print(missing.map(str.upper))           # Nothing
+print(missing.get_or_else("Unknown"))   # 'Unknown'
+
+# Auto-convert from potentially None values
+def find_user(user_id):
+    return {"alice": "Alice"}.get(user_id)
+
+result = some(find_user("bob"))  # Nothing (because get returns None)
+result = some(find_user("alice"))  # Some('Alice')
+```
+
+**Option Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `map(f)` | Transform the value if present |
+| `flat_map(f)` / `bind(f)` | Chain operations that return `Option` |
+| `filter(predicate)` | Return `Nothing` if predicate fails |
+| `get_or_else(default)` | Get value or return default |
+| `get_or_none()` | Get value or `None` |
+| `or_else(alternative)` | Return alternative `Option` if `Nothing` |
+| `is_some()` / `is_nothing()` | Check presence |
+
+**Chaining with Option:**
+
+```python
+from punctional import Some, Nothing
+
+def parse_int(s: str) -> Option[int]:
+    try:
+        return Some(int(s))
+    except ValueError:
+        return Nothing()
+
+def double(x: int) -> Option[int]:
+    return Some(x * 2)
+
+# Chain operations safely
+result = Some("42").flat_map(parse_int).flat_map(double)  # Some(84)
+result = Some("abc").flat_map(parse_int).flat_map(double) # Nothing
+```
+
+---
+
+### 2. Result Monad — Explicit Error Handling
+
+The `Result` type represents either success (`Ok`) or failure (`Error`). Unlike exceptions, errors are explicit in the type signature and must be handled.
+
+```python
+from punctional import Ok, Error, try_result
+
+# Explicit success and failure
+success = Ok(42)
+failure = Error("Something went wrong")
+
+print(success.map(lambda x: x * 2))  # Ok(84)
+print(failure.map(lambda x: x * 2))  # Error('Something went wrong')
+
+print(success.get_or_else(0))  # 42
+print(failure.get_or_else(0))  # 0
+```
+
+**Wrapping exceptions with `try_result`:**
+
+```python
+from punctional import try_result
+
+def divide(a, b):
+    return a / b
+
+result = try_result(lambda: divide(10, 2))  # Ok(5.0)
+result = try_result(lambda: divide(10, 0))  # Error(ZeroDivisionError(...))
+
+# With custom error handler
+result = try_result(
+    lambda: divide(10, 0),
+    error_handler=lambda e: f"Division failed: {e}"
+)  # Error('Division failed: division by zero')
+```
+
+**Result Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `map(f)` | Transform success value |
+| `map_error(f)` | Transform error value |
+| `flat_map(f)` / `bind(f)` | Chain operations returning `Result` |
+| `get_or_else(default)` | Get value or default |
+| `is_ok()` / `is_error()` | Check success/failure |
+| `to_option()` | Convert to `Option` (discards error info) |
+
+**Railway-oriented programming:**
+
+```python
+from punctional import Result, Ok, Error
+
+def validate_age(age: int) -> Result[int, str]:
+    if age < 0:
+        return Error("Age cannot be negative")
+    if age > 150:
+        return Error("Age seems unrealistic")
+    return Ok(age)
+
+def validate_name(name: str) -> Result[str, str]:
+    if not name.strip():
+        return Error("Name cannot be empty")
+    return Ok(name.strip())
+
+# Chain validations
+age_result = validate_age(25).map(lambda a: f"Age: {a}")     # Ok('Age: 25')
+age_result = validate_age(-5).map(lambda a: f"Age: {a}")     # Error('Age cannot be negative')
+```
+
+---
+
+### 3. Pipe Operator & Filters
+
+Chain transformations using the `|` operator for readable, left-to-right data flow.
+
+```python
+from punctional import fint, fstr, ffloat, Add, Mult, Sub, Div, ToUpper
+
+# Arithmetic chaining
+result = fint(10) | Add(5) | Mult(2) | Sub(3)  # (10 + 5) * 2 - 3 = 27
+
+# String transformations
+text = fstr("hello") | ToUpper() | Add(" WORLD!")  # 'HELLO WORLD!'
+
+# Float operations
+value = ffloat(10.0) | Div(4) | Mult(2)  # 5.0
+```
+
+**Functional Wrappers:**
+
+| Function | Type | Description |
+|----------|------|-------------|
+| `fint(x)` | `FunctionalInt` | Enables piping for integers |
+| `ffloat(x)` | `FunctionalFloat` | Enables piping for floats |
+| `fstr(x)` | `FunctionalStr` | Enables piping for strings |
+
+---
+
+### 4. Built-in Filters
+
+**Arithmetic:**
+```python
+from punctional import fint, 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:**
+```python
+from punctional import fint, GreaterThan, LessThan, Equals
+
+fint(42) | GreaterThan(10)  # True
+fint(5) | LessThan(10)      # True
+fint(42) | Equals(42)       # True
+```
+
+**Logical:**
+```python
+from punctional import fint, AndFilter, OrFilter, NotFilter, GreaterThan, LessThan
+
+# All conditions must pass
+fint(42) | AndFilter(GreaterThan(10), LessThan(100))  # True
+
+# At least one condition must pass
+fint(5) | OrFilter(LessThan(3), GreaterThan(3))  # True
+
+# Negate a condition
+fint(5) | NotFilter(Equals(0))  # True
+```
+
+**String:**
+```python
+from punctional import fstr, ToUpper, ToLower, Contains, Mult
+
+fstr("hello") | ToUpper()               # 'HELLO'
+fstr("WORLD") | ToLower()               # 'world'
+fstr("hello world") | Contains("world") # True
+fstr("ha") | Mult(3)                    # 'hahaha'
+```
+
+**List Operations:**
+```python
+from punctional import Map, FilterList, Mult, GreaterThan
+
+numbers = [1, 2, 3, 4, 5]
+
+Map(Mult(2)).apply(numbers)              # [2, 4, 6, 8, 10]
+FilterList(GreaterThan(2)).apply(numbers) # [3, 4, 5]
+```
+
+---
+
+### 5. Composition
+
+Create reusable pipelines with `Compose`:
+
+```python
+from punctional import Compose, Mult, Add, fint
+
+# Define a reusable transformation
+double_then_add_ten = Compose(Mult(2), Add(10))
+
+fint(5) | double_then_add_ten   # 20  (5 * 2 + 10)
+fint(10) | double_then_add_ten  # 30  (10 * 2 + 10)
+```
+
+---
+
+### 6. Custom Filters
+
+Create your own filters by extending the `Filter` base class:
+
+```python
+from punctional import Filter, fint
+
+class Square(Filter[int, int]):
+    def apply(self, value: int) -> int:
+        return value ** 2
+
+class Power(Filter[int, int]):
+    def __init__(self, exponent: int):
+        self.exponent = exponent
+    
+    def apply(self, value: int) -> int:
+        return value ** self.exponent
+
+fint(5) | Square()    # 25
+fint(2) | Power(10)   # 1024
+```
+
+---
+
+### 7. Functional Dataclasses
+
+Add the `Functional` mixin to any dataclass to enable piping:
+
+```python
+from dataclasses import dataclass
+from punctional import Functional, Filter
+
+@dataclass
+class Point(Functional):
+    x: float
+    y: float
+
+class Scale(Filter[Point, Point]):
+    def __init__(self, factor: float):
+        self.factor = factor
+    
+    def apply(self, p: Point) -> Point:
+        return Point(p.x * self.factor, p.y * self.factor)
+
+class Translate(Filter[Point, Point]):
+    def __init__(self, dx: float, dy: float):
+        self.dx, self.dy = dx, dy
+    
+    def apply(self, p: Point) -> Point:
+        return Point(p.x + self.dx, p.y + self.dy)
+
+# Chain transformations on custom types
+point = Point(3, 4)
+result = point | Scale(2) | Translate(10, 10)  # Point(16, 18)
+```
+
+---
+
+## Complete API Reference
+
+### Monads
+
+| Type | Description |
+|------|-------------|
+| `Option[T]` | Abstract base for optional values |
+| `Some(value)` | Contains a value |
+| `Nothing()` | Represents absence |
+| `some(value)` | Creates `Some` or `Nothing` based on `None` check |
+| `Result[T, E]` | Abstract base for success/failure |
+| `Ok(value)` | Successful result |
+| `Error(error)` | Failed result |
+| `try_result(fn)` | Wraps a function, catching exceptions as `Error` |
+
+### Filters
+
+| Filter | Input → Output | Description |
+|--------|----------------|-------------|
+| `Add(n)` | `number → number` | Addition |
+| `Sub(n)` | `number → number` | Subtraction |
+| `Mult(n)` | `number → number` | Multiplication |
+| `Div(n)` | `number → number` | Division |
+| `GreaterThan(n)` | `number → bool` | Greater than comparison |
+| `LessThan(n)` | `number → bool` | Less than comparison |
+| `Equals(n)` | `any → bool` | Equality check |
+| `AndFilter(*filters)` | `T → bool` | Logical AND |
+| `OrFilter(*filters)` | `T → bool` | Logical OR |
+| `NotFilter(filter)` | `T → bool` | Logical NOT |
+| `ToUpper()` | `str → str` | Uppercase |
+| `ToLower()` | `str → str` | Lowercase |
+| `Contains(s)` | `str → bool` | Substring check |
+| `Map(filter)` | `list → list` | Apply filter to each element |
+| `FilterList(pred)` | `list → list` | Filter elements by predicate |
+| `Compose(*filters)` | `T → U` | Compose multiple filters |
+
+### Core Classes
+
+| Class | Description |
+|-------|-------------|
+| `Filter[T, U]` | Abstract base class for all filters |
+| `Functional` | Mixin that enables `\|` operator on any class |
+| `FunctionalInt` | Wrapper for `int` with pipe support |
+| `FunctionalFloat` | Wrapper for `float` with pipe support |
+| `FunctionalStr` | Wrapper for `str` with pipe support |
+
+---
+
+## Examples
+
+Run the included examples:
+
+```bash
+python -m examples.basics              # Introduction to all features
+python -m examples.extending           # Creating custom filters
+python -m examples.data_transformation # Real-world patterns
+python -m examples.quick_reference     # Quick lookup cheatsheet
+```
+
+---
+
+## Design Principles
+
+1. **Explicit over implicit** — Errors are values, not exceptions
+2. **Composability** — Small, reusable units that combine easily
+3. **Type safety** — Generics provide IDE support and catch bugs early
+4. **Immutability** — Filters return new values, never mutate
+5. **Zero dependencies** — Pure Python, works everywhere
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  Made with ❤️ for functional programming in Python
+</p>

punctional-0.1.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+punctional/__init__.py,sha256=CUSYY084_Vkm9_ql59owgyVtoMKJzsiN4cJN740MeKQ,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.2.dist-info/METADATA,sha256=Bc3ZwYvYZlxGLW64TwiUCiZvHIId_mJn0TQOK5CCrRg,12049
+punctional-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+punctional-0.1.2.dist-info/licenses/LICENSE,sha256=-iDh_gcypGAb576TWRWkMhTMvuAaOML4rZwKV1s8Xoo,1070
+punctional-0.1.2.dist-info/RECORD,,

punctional-0.1.2.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.2.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.