Metadata-Version: 2.1
Name: stolas
Version: 0.1.2
Summary: The strict, multi-paradigm framework enabling pure functional patterns in Python.
Author: Stolas Contributors
Project-URL: Homepage, https://github.com/eaksit-bua/stolas
Project-URL: Repository, https://github.com/eaksit-bua/stolas
Project-URL: Documentation, https://github.com/eaksit-bua/stolas#readme
Keywords: functional,monads,immutable,struct,trait
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
License-File: LICENSE.md
Provides-Extra: dev
Requires-Dist: mypy >=1.19.1 ; extra == 'dev'
Requires-Dist: pytest >=9.0.2 ; extra == 'dev'
Requires-Dist: pytest-cov >=7.0.0 ; extra == 'dev'

# 🦉 Stolas

**The strict, multi-paradigm framework enabling pure functional patterns in Python.**

*Wisdom through pure functional patterns* — Safe separation of data and behavior with monadic safety, immutability, and type-safe composition.

## 🦉 The S-T-O-L-A-S Framework

### **S**truct
Fast, immutable data classes with `@struct` and polymorphic `@trait` for behavior dispatch.

### **T**ypes  
Safe monadic containers: `Result`, `Option`, `Validated`, `Effect`, `Many`

### **O**perands
Powerful decorators: `@ops`, `@cases`, `@binary`, `@as_result`, `concurrent()`

### **L**ogic
Ergonomic functional combinators: `get`, `at`, `where`, `apply`, `_` placeholder, and 20+ utilities

### **A-S**
*(Reserved for future expansion)*

## 🦉 Key Features

- ✅ **Strictness**: Runtime type checking + `__slots__` for memory efficiency
- ✅ **Sealed ADTs**: `@cases` decorator with pattern matching and monadic compatibility
- ✅ **Functional Composition**: Pipeline chaining with `>>`
- ✅ **Async Concurrency**: Parallel workflows with `concurrent()`
- ✅ **Polymorphism**: Trait-based dispatch for decoupled behavior
- ✅ **Type Safety**: Full `mypy --strict` compatibility

## 🦉 Installation

```bash
pip install stolas
```

## 🦉 Quick Example

```python
from stolas.struct import struct
from stolas.types import Many
from stolas.operand import binary, as_result, ops
from stolas.logic import where, apply, _

# Immutable data
@struct
class User:
    id: int
    name: str
    email: str

# Safe, curried operations
@ops(binary, as_result)
def divide(a: int, b: int) -> float:
    return a / b

# Functional pipelines with placeholder
users = Many([
    User(1, "Alice", "alice@example.com"),
    User(2, "Bob", "bob@example.com"),
])

result = users >> where(_.id > 1) >> apply(_.name)  # Many(["Bob"])

# Monadic safety
divide(10)(2)  # Ok(5.0)
divide(10)(0)  # Error(ZeroDivisionError(...))
```

## 🦉 Documentation

For detailed documentation, see the **[docs/](docs/)** directory:

- **[Struct & Trait](docs/struct.md)** - Polymorphism (`@trait`) and immutable data (`@struct`)
- **[Monadic Types](docs/types.md)** - `Result`, `Option`, `Validated`, `Effect`, `Many`
- **[Operands](docs/operands.md)** - Decorators `@cases`, `@safe`, and Concurrency
- **[Logic Reference](docs/logic.md)** - Combinators and Placeholder (`_`)

## 🦉 Testing

```bash
# Run tests
python -m pytest tests/

# Type checking
mypy src/stolas --strict
```

**Status:** 🦉 739 tests passing • 100% coverage • 100% mypy strict compliance

## 🦉 License

MIT License
