koruspy 0.9.7
Uma biblioteca inspirada em Rust e Kotlin para lidar com Option, println colorido e utilitários.
Requires Python: >=3.10

# Koruspy 🦀

> **v0.9.5** — Biblioteca Python inspirada em abstrações funcionais (Rust / FP)

Koruspy oferece tipos como `Option`, `Result` e estruturas auxiliares com contratos claros, comportamento previsível e sem magia. A versão 0.9.5 consolida a API e introduz estruturas imutáveis e assíncronas mais robustas, preparando o caminho para a versão 1.0.0.

---

## ✨ Principais recursos

### 🔹 Option

Representa um valor opcional que pode estar presente (`Some`) ou ausente (`nothing`).

- **Construtores**: `Some(value)` e `nothing`
- **Operações funcionais**: `map`, `and_then`, `filter`, `flatten`
- **Métodos seguros de extração**: `unwrap_or`, `unwrap_or_else`, `expect`
- **Comparações bem-definidas** (`__eq__`) sem recursão infinita
- **Propagação correta** de `nothing`

### 🔹 Result

Representa o resultado de uma operação que pode ter sucesso (`Okay`) ou falhar (`Err`).

- **Construtores**: `Okay(value)` e `Err(error)`
- **Operações funcionais**: `map`, `and_then`, `flat_map`, `fold`
- **Extração segura**: `unwrap`, `unwrap_or`, `unwrap_or_else`, `unwrap_err`
- **Exceções propagadas de forma explícita**
- **`result_of(fn)`** para captura automática de exceções

### 🔹 AsyncOption

Wrapper assíncrono para `Option`, compatível com `await`.

- **Métodos assíncronos**:
  - `map_async`
  - `and_then_async`
  - `filter_async`
  - `unwrap_or_async`
  - `unwrap_or_else_async`
- **Sem "auto-await" implícito** ou comportamento oculto

### 🔹 SomeList / FrozenSomeList

Coleções funcionais baseadas em `Option`.

- **`SomeList`**: coleção funcional mutável
- **`FrozenSomeList`**:
  - Estrutura **imutável**
  - **Hashável** (pode ser usada como chave de `dict` ou em `set`)
  - Baseada em `collections.abc.Sequence`
- **Contratos claros** entre mutabilidade e imutabilidade

---

## 🧪 Qualidade e testes

- ✅ **62 testes automatizados** passando
- **Cobertura de testes**:
  - Contratos de igualdade (`__eq__`)
  - Imutabilidade e hashing
  - Propagação de `nothing` / `Err`
  - Comportamento funcional consistente
- **API pensada para refatoração segura**

---

## 🎯 Objetivo da biblioteca

Koruspy busca ser:

- **Pequena, previsível e explícita**
- **Livre de exceções silenciosas**
- **Livre de efeitos colaterais escondidos**
- **Priorizar clareza e correção** sobre "açúcar sintático"

---

## 🚧 Status

- **Versão atual**: 0.9.5 (pré-1.0)
- **API majoritariamente estável**
- Pequenos ajustes de naming e contratos ainda podem ocorrer
- **A versão 1.0.0 marcará o congelamento da API pública**

---

## 📦 Instalação

```bash
pip install koruspy
```

---

## 🚀 Exemplo de uso

```python
from koruspy import Some, nothing, Okay, Err, result_of

# Option
opt = Some(42)
result = opt.map(lambda x: x * 2).unwrap_or(0)  # 84

# Result
def divide(a: int, b: int):
    if b == 0:
        return Err("Division by zero")
    return Okay(a / b)

result = divide(10, 2).map(lambda x: x + 1).unwrap()  # 6.0

# Captura automática de exceções

def may_fail():
    return result_of(lambda: 1 / 0)

result = may_fail()  # Err(ZeroDivisionError)
```

---

## 📄 Licença

MIT License

---

## 📞 Contato

leozin17892@gmail.com


### English 🇬🇧🇺🇸

# Koruspy 🦀

> **v0.9.5** — Python library inspired by functional abstractions (Rust / FP)

Koruspy provides types like `Option`, `Result`, and auxiliary structures with clear contracts, predictable behavior, and no magic. Version 0.9.5 consolidates the API and introduces more robust immutable and asynchronous structures, paving the way for version 1.0.0.

---

## ✨ Key Features

### 🔹 Option

Represents an optional value that can be present (`Some`) or absent (`nothing`).

- **Constructors**: `Some(value)` and `nothing`
- **Functional operations**: `map`, `and_then`, `filter`, `flatten`
- **Safe extraction methods**: `unwrap_or`, `unwrap_or_else`, `expect`
- **Well-defined comparisons** (`__eq__`) without infinite recursion
- **Correct propagation** of `nothing`

### 🔹 Result

Represents the result of an operation that can succeed (`Okay`) or fail (`Err`).

- **Constructors**: `Okay(value)` and `Err(error)`
- **Functional operations**: `map`, `and_then`, `flat_map`, `fold`
- **Safe extraction**: `unwrap`, `unwrap_or`, `unwrap_or_else`, `unwrap_err`
- **Explicitly propagated exceptions**
- **`result_of(fn)`** for automatic exception capture

### 🔹 AsyncOption

Asynchronous wrapper for `Option`, compatible with `await`.

- **Asynchronous methods**:
  - `map_async`
  - `and_then_async`
  - `filter_async`
  - `unwrap_or_async`
  - `unwrap_or_else_async`
- **No implicit "auto-await"** or hidden behavior

### 🔹 SomeList / FrozenSomeList

Functional collections based on `Option`.

- **`SomeList`**: mutable functional collection
- **`FrozenSomeList`**:
  - **Immutable** structure
  - **Hashable** (can be used as `dict` key or in `set`)
  - Based on `collections.abc.Sequence`
- **Clear contracts** between mutability and immutability

---

## 🧪 Quality and Testing

- ✅ **62 automated tests** passing
- **Test coverage**:
  - Equality contracts (`__eq__`)
  - Immutability and hashing
  - Propagation of `nothing` / `Err`
  - Consistent functional behavior
- **API designed for safe refactoring**

---

## 🎯 Library Goals

Koruspy aims to be:

- **Small, predictable, and explicit**
- **Free from silent exceptions**
- **Free from hidden side effects**
- **Prioritize clarity and correctness** over "syntactic sugar"

---

## 🚧 Status

- **Current version**: 0.9.5 (pre-1.0)
- **API mostly stable**
- Minor naming and contract adjustments may still occur
- **Version 1.0.0 will mark the freeze of the public API**

---

## 📦 Installation

```bash
pip install koruspy
```

---

## 🚀 Usage Example

```python
from koruspy import Some, nothing, Okay, Err, result_of

# Option
opt = Some(42)
result = opt.map(lambda x: x * 2).unwrap_or(0)  # 84

# Result
def divide(a: int, b: int):
    if b == 0:
        return Err("Division by zero")
    return Okay(a / b)

result = divide(10, 2).map(lambda x: x + 1).unwrap()  # 6.0

# Automatic exception capture
def may_fail():
    return result_of(lambda: 1 / 0)

result = may_fail()  # Err(ZeroDivisionError)
```

---

## 📄 License

MIT License

---

## 📞 Contact

leozin17892@gmail.com