koruspy 0.9.5

Uma biblioteca inspirada em Rust e Kotlin para lidar com Option, println colorido e utilitários.

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

pip install koruspy

---

🚀 Exemplo de uso

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

[e-mail]

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

pip install koruspy

---

🚀 Usage Example

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

[e-mail]