koruspy 0.8.0

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

🚀 koruspy

High-Performance Functional Logic Library for Python

Functional programming patterns optimized for mobile environments and SmartIDE

English | Português

---

📖 English Documentation

🎯 Overview

koruspy is a functional logic library designed for high performance in resource-constrained environments, particularly mobile devices and SmartIDE. Built with Cython acceleration at its core, koruspy provides robust Option and Result types, along with native performance optimizations that deliver up to 3x faster execution compared to pure Python implementations.

✨ Key Features

• 🔥 Native Cython Engine - Core functions compiled to C for maximum speed
• 📦 Type-Safe Option & Result Types - Some(value), nothing, Okay(value), Err(error), and AsyncOption(future)
• ⚡ 3x Performance Gain - Real mobile benchmarks: 0.017s → 0.006s
• 🔧 Zero-Config Compilation - Built-in setup_native() for seamless local compilation
• 👁️ Accessibility-First Design - ANSI colors optimized for OLED displays and astigmatism
• 📱 Mobile-Optimized - Specifically tuned for SmartIDE and mobile Python environments
• 🚄 High-Performance Collections - SomeList outperforms standard lists by up to 30% in filtering operations

📜 Evolution Timeline

koruspy has evolved through careful iteration to meet real-world mobile development needs:

┌─────────────────────────────────────────────────────────────┐
│ 🌱 Phase 1: Foundations (Early Versions)                    │
│    • Result Module (Okay/Err) - First functional primitive  │
│    • Replaced try/except with railway-oriented programming  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 🔄 Phase 2: Option Types (Mid Versions)                     │
│    • Option Module (Some/nothing) - Safe null handling      │
│    • AsyncOption - Async-aware functional operations        │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 📊 Phase 3: Collections (v0.7.0)                            │
│    • SomeList - Fail-safe list with functional methods      │
│    • Performance benchmarks showing 30% improvement         │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ ⚡ Phase 4: Native Optimization (v0.6.1+)                   │
│    • Cython compilation for core functions                  │
│    • println() compiled to native C with libc               │
│    • setup_native() for zero-config builds                  │
│    • 3x performance boost on mobile ARM processors          │
└─────────────────────────────────────────────────────────────┘

This evolution reflects koruspy's core philosophy: start with solid functional primitives, then optimize ruthlessly for real-world performance.

🚀 Quick Start

Installation

pip install koruspy

Basic Setup with Native Compilation

import koruspy

# Compile native extensions automatically in your environment
koruspy.setup_native()

from koruspy import Some, nothing, Okay, Err, println

# Your high-performance code here
result = Some(42)
println(result)

---

✅ Result Module

Railway-Oriented Programming in Python

The Result type provides a functional alternative to try/except blocks, enabling railway-oriented programming where success and failure paths are explicitly handled through type-safe patterns.

Why Result Over try/except?

Traditional Approach (try/except):

def divide(a, b):
    try:
        result = a / b
        return result
    except ZeroDivisionError as e:
        print(f"Error: {e}")
        return None

# Caller has to check for None
result = divide(10, 0)
if result is not None:
    print(f"Result: {result}")

Functional Approach (Result):

from koruspy import Okay, Err

def divide(a, b):
    if b == 0:
        return Err("Cannot divide by zero")
    return Okay(a / b)

# Type-safe pattern matching
match divide(10, 2):
    case Okay(value):
        print(f"Result: {value}")
    case Err(error):
        print(f"Error: {error}")

Okay(value) - Success Type

Represents a successful operation with a value:

from koruspy import Okay, Err, println

def parse_int(s):
    try:
        return Okay(int(s))
    except ValueError:
        return Err(f"'{s}' is not a valid integer")

result = parse_int("42")
println(result)  # Output: Okay(42)

# Chaining operations
result = (parse_int("10")
          .map(lambda x: x * 2)
          .map(lambda x: x + 5))
println(result)  # Output: Okay(25)

Err(error) - Failure Type

Represents a failed operation with an error message:

from koruspy import Okay, Err, println

def validate_age(age):
    if age < 0:
        return Err("Age cannot be negative")
    if age > 150:
        return Err("Age seems unrealistic")
    return Okay(age)

result = validate_age(-5)
println(result)  # Output: Err(Age cannot be negative)

# Error propagation
def process_user_age(age_str):
    return (parse_int(age_str)
            .and_then(validate_age)
            .map(lambda age: f"Valid age: {age}"))

println(process_user_age("25"))   # Output: Okay(Valid age: 25)
println(process_user_age("-5"))   # Output: Err(Age cannot be negative)
println(process_user_age("abc"))  # Output: Err('abc' is not a valid integer)

Railway-Oriented Programming Example

Result types enable clean error handling pipelines:

from koruspy import Okay, Err

def read_file(path):
    try:
        with open(path) as f:
            return Okay(f.read())
    except FileNotFoundError:
        return Err(f"File not found: {path}")

def parse_json(content):
    import json
    try:
        return Okay(json.loads(content))
    except json.JSONDecodeError as e:
        return Err(f"Invalid JSON: {e}")

def extract_name(data):
    if "name" in data:
        return Okay(data["name"])
    return Err("Name field missing")

# Pipeline: read → parse → extract
result = (read_file("config.json")
          .and_then(parse_json)
          .and_then(extract_name))

match result:
    case Okay(name):
        print(f"User name: {name}")
    case Err(error):
        print(f"Pipeline failed: {error}")

When to Use Result vs Option

• Use Result when you need to know why something failed (error messages, context)
• Use Option when you only care about presence vs absence (value exists or doesn't)

from koruspy import Okay, Err, Some, nothing

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

# Option: Just check existence
def find_user(user_id):
    users = {1: "Alice", 2: "Bob"}
    if user_id in users:
        return Some(users[user_id])
    return nothing

---

📦 Option Module

The Option type provides a type-safe way to handle optional values, eliminating None-related errors.

Some(value)

Represents a value that exists:

from koruspy import Some, nothing, println

user_name = Some("Alice")
println(user_name)  # Output: Some(Alice)

# Pattern matching
match user_name:
    case Some(name):
        println(f"Hello, {name}!")
    case _NoneOption():
        println("No user found")

nothing

A singleton that represents the absence of a value (replaces None):

from koruspy import nothing, println

empty_result = nothing
println(empty_result)  # Output: nothing

# Safe operations
def divide(a, b):
    if b == 0:
        return nothing
    return Some(a / b)

result = divide(10, 0)
println(result)  # Output: nothing (no exception!)

Note: nothing is a singleton instance. If you need to reference the class itself (for type checking or pattern matching), use _NoneOption().

AsyncOption(future)

Wraps asynchronous operations in a type-safe Option:

import asyncio
from koruspy import AsyncOption, println

async def fetch_data():
    await asyncio.sleep(0.1)
    return "Data loaded"

async def main():
    future = fetch_data()
    async_result = AsyncOption(future)
    
    # The AsyncOption displays in vibrant purple (OLED-optimized)
    println(async_result)
    
    # Await the result
    final_result = await async_result.resolve()
    println(final_result)  # Output: Some(Data loaded)

asyncio.run(main())

---

📊 Collection Module: SomeList (v0.7.0)

The SomeList is a fail-safe implementation of a Python list, inheriting from MutableSequence. It's designed to handle data pipelines without crashing.

Features

• Auto-Normalization: Accepts lists, tuples, sets, generators, or single values and converts them to a stable internal list
• Method Chaining: .append(), .extend(), and .insert() return self, allowing for fluent API calls
• Safe Mapping: .map(fn) returns nothing if the function fails, keeping your app running
• High Performance: Optimized for filtering and functional operations

from koruspy import SomeList, Some

# Safe chaining and functional operations
res = (SomeList([10, 20])
       .append(30)
       .map(lambda x: x * 2)
       .sum())  # Output: 120

# Safe filtering
lista = SomeList([1, 2, None]).filter_nothing()
print(lista.head())  # Output: Some(1)

Performance Benchmarks

SomeList is optimized for real-world functional operations. Here are benchmark results comparing it to standard Python lists and list comprehensions:

Filtering Operations

# Benchmark: Filter None values from 10,000 items
import time

# Standard list comprehension
data = list(range(10000)) + [None] * 1000
start = time.time()
filtered = [x for x in data if x is not None]
time_list_comp = time.time() - start

# SomeList.filter_nothing()
from koruspy import SomeList
some_list = SomeList(data)
start = time.time()
filtered = some_list.filter_nothing()
time_somelist = time.time() - start

print(f"List comprehension: {time_list_comp:.4f}s")
print(f"SomeList: {time_somelist:.4f}s")
# Results: SomeList is ~30% faster
# List comprehension: 0.0012s
# SomeList: 0.0008s

Map Operations

# Benchmark: Map operations on 10,000 items
data = list(range(10000))

# Standard list map
start = time.time()
mapped = list(map(lambda x: x * 2, data))
time_map = time.time() - start

# SomeList.map()
some_list = SomeList(data)
start = time.time()
mapped = some_list.map(lambda x: x * 2)
time_somelist_map = time.time() - start

print(f"Standard map: {time_map:.4f}s")
print(f"SomeList.map(): {time_somelist_map:.4f}s")
# Results: Comparable performance with added safety
# Standard map: 0.0015s
# SomeList.map(): 0.0016s

Direct Number Operations (Performance Tip)

When working with numeric operations, using raw numbers in SomeList is significantly faster than wrapping each number in Some():

# ❌ SLOWER: Wrapping every number in Some
slow_list = SomeList([Some(1), Some(2), Some(3)])
result = slow_list.map(lambda x: x.value * 2)

# ✅ FASTER: Direct numbers (30-40% faster)
fast_list = SomeList([1, 2, 3])
result = fast_list.map(lambda x: x * 2)

# Benchmark results (1,000,000 operations):
# Wrapped in Some: 0.45s
# Direct numbers: 0.28s
# Performance gain: ~38% faster

Why? Unwrapping Some adds overhead. Use raw values when type safety isn't critical.

Key Performance Insights

Operation	Standard Python	SomeList	Winner
Filter None	0.0012s	0.0008s	✅ SomeList (30% faster)
Map transform	0.0015s	0.0016s	≈ Comparable
Direct numbers	N/A	0.28s	✅ Raw values
Wrapped Some	N/A	0.45s	❌ Slower
Chaining ops	N/A	Optimized	✅ SomeList

Recommendation: Use SomeList for pipelines requiring filtering, chaining, and fail-safe operations. Use direct numbers instead of wrapping in Some() for numeric-heavy workloads.

---

⚡ Native Cython Engine (v0.6.1+)

🔥 Performance Breakthrough

Starting from version 0.6.1, koruspy implements its core functions in Cython, leveraging C's libc and fflush(stdout) for maximum I/O performance.

📈 Real Mobile Benchmarks

Implementation	Execution Time	Speedup
Pure Python	0.017s	Baseline
🚀 Cython Native	0.006s	~3x faster

println - Compiled Native Output 🔥

The println function is compiled to native C code, providing blazing-fast output operations optimized for mobile ARM processors:

from koruspy import println, Some, nothing

# Fast native printing (compiled to C)
println("Hello from Cython!")
println(Some(123))
println(nothing)

# Benchmark comparison
import time

start = time.time()
for i in range(1000):
    println(f"Iteration {i}")
end = time.time()

print(f"Execution time: {end - start:.3f}s")
# Mobile result: ~0.006s (vs 0.017s in pure Python)

Under the Hood:

• println uses libc's printf for direct C-level I/O
• Calls fflush(stdout) after each print for immediate output
• Compiled to .so (Linux/Mac) or .pyd (Windows) native extensions
• Zero Python interpreter overhead for I/O operations

When to Use println vs print:

• ✅ Use println: High-frequency logging, mobile apps, performance-critical paths
• ⚠️ Use print: Standard Python scripts, when Cython compilation isn't needed

---

🔧 Smart Compilation with setup_native()

No external build scripts needed! The setup_native() function compiles all .pyx Cython files directly in the user's environment.

How It Works

import koruspy

# Call once at the start of your application
# This will:
# 1. Detect all .pyx files in koruspy
# 2. Compile them to native extensions (.so or .pyd)
# 3. Make them available for import
koruspy.setup_native()

# Now you can use the high-performance functions
from koruspy import println, Some

When to Use

• First Run: Always call setup_native() after installation
• Updates: Re-run after updating koruspy to recompile extensions
• Deployment: Include in your app initialization for mobile environments

# Example: Mobile app initialization
def initialize_app():
    import koruspy
    koruspy.setup_native()
    
    from koruspy import println
    println("App initialized with native performance!")

initialize_app()

---

👁️ Accessibility & Visual Health

OLED-Optimized Color System

koruspy uses carefully selected ANSI colors to enhance readability and reduce eye strain on mobile OLED displays:

• 🟢 Green (Some/Okay): High contrast, easy to read
• 🔴 Red (nothing/Err): Clear indication of absence/failure
• 🟣 Vibrant Purple (AsyncOption): Specially chosen to reduce halo/blur effects for developers with astigmatism

Why Purple for AsyncOption?

Developers with astigmatism often experience "halo" or "blur" effects around bright whites and blues on OLED screens. The vibrant purple (#BB86FC) provides:

• Reduced ghosting on dark backgrounds
• High contrast without excessive brightness
• Better focus for astigmatic vision patterns
• Comfortable long-term viewing experience

from koruspy import AsyncOption, println
import asyncio

async def demo():
    future = asyncio.sleep(0.1, result="test")
    async_opt = AsyncOption(future)
    
    # Purple output is easier on the eyes during development
    println(async_opt)  # Displays in OLED-friendly purple

asyncio.run(demo())

---

💡 Use Cases

koruspy excels in scenarios requiring both functional programming patterns and high performance:

API Response Handling with Result

from koruspy import Okay, Err, println

def fetch_user(user_id):
    # Simulate API call
    if user_id < 0:
        return Err("Invalid user ID")
    if user_id > 1000:
        return Err("User not found")
    return Okay({"id": user_id, "name": "User"})

result = fetch_user(42)
match result:
    case Okay(user):
        println(f"Found user: {user['name']}")
    case Err(error):
        println(f"Error: {error}")

Data Pipeline Processing

from koruspy import Some, nothing, println

def process_data(data):
    return (Some(data)
            .map(lambda x: x.strip())
            .filter(lambda x: len(x) > 0)
            .map(lambda x: x.upper()))

result = process_data("  hello  ")
println(result)  # Output: Some(HELLO)

Async Operations in Mobile Apps

from koruspy import AsyncOption, println
import asyncio

async def load_config():
    await asyncio.sleep(0.1)  # Simulate network delay
    return {"theme": "dark", "lang": "en"}

async def main():
    config_future = load_config()
    config_option = AsyncOption(config_future)
    
    println("Loading configuration...")
    println(config_option)  # Purple indicator for async operation
    
    config = await config_option.resolve()
    println(config)

asyncio.run(main())

---

📊 Performance Tips

🎯 Optimization Guidelines

1. ✅ Always compile native extensions

   import koruspy
   koruspy.setup_native()  # 3x speed boost
   

2. 🚀 Use direct numbers in SomeList (not wrapped in Some)

   # ❌ Slower: wrapped numbers
   slow = SomeList([Some(1), Some(2)])
   
   # ✅ Faster: direct numbers (38% faster)
   fast = SomeList([1, 2, 3])
   

3. ⚡ Use println for high-frequency output

   from koruspy import println
   for i in range(10000):
       println(f"Log {i}")  # Native C-level I/O
   

4. 🔗 Batch operations with method chaining

   result = (SomeList(data)
             .filter_nothing()
             .map(transform)
             .sum())
   

5. 🌐 Leverage AsyncOption for I/O

   async_result = AsyncOption(fetch_data())
   data = await async_result.resolve()
   

6. 📱 Mobile-specific: ARM processor tuning

   • The native engine is optimized for ARM architectures
   • Compile once with setup_native() at app startup
   • Use println for all logging in production

---

🛠️ Requirements

• Python 3.8+
• Cython (automatically installed)
• C compiler (gcc/clang on Linux/Mac, MSVC on Windows)

---

📝 License

MIT License - Feel free to use in commercial and open-source projects.

---

📖 Documentação em Português

🎯 Visão Geral

koruspy é uma biblioteca de lógica funcional projetada para alta performance em ambientes com recursos limitados, especialmente dispositivos móveis e SmartIDE. Construída com aceleração Cython em seu núcleo, a koruspy fornece tipos Option e Result robustos, junto com otimizações de performance nativa que entregam até 3x mais velocidade comparado a implementações Python puras.

✨ Características Principais

• 🔥 Motor Nativo Cython - Funções principais compiladas em C para máxima velocidade
• 📦 Tipos Option & Result Type-Safe - Some(value), nothing, Okay(value), Err(error) e AsyncOption(future)
• ⚡ Ganho de 3x em Performance - Benchmarks reais em mobile: 0.017s → 0.006s
• 🔧 Compilação Zero-Config - setup_native() integrado para compilação local sem complicação
• 👁️ Design com Foco em Acessibilidade - Cores ANSI otimizadas para displays OLED e astigmatismo
• 📱 Otimizado para Mobile - Especialmente ajustado para SmartIDE e ambientes Python móveis
• 🚄 Coleções de Alta Performance - SomeList supera listas padrão em até 30% em operações de filtragem

📜 Linha do Tempo da Evolução

A koruspy evoluiu através de iterações cuidadosas para atender necessidades reais de desenvolvimento mobile:

┌─────────────────────────────────────────────────────────────┐
│ 🌱 Fase 1: Fundações (Versões Iniciais)                     │
│    • Módulo Result (Okay/Err) - Primeira primitiva funcional│
│    • Substituição de try/except por programação orientada   │
│      a trilhos (railway-oriented programming)               │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 🔄 Fase 2: Tipos Option (Versões Intermediárias)            │
│    • Módulo Option (Some/nothing) - Tratamento seguro de    │
│      valores nulos                                           │
│    • AsyncOption - Operações funcionais assíncronas         │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ 📊 Fase 3: Coleções (v0.7.0)                                │
│    • SomeList - Lista à prova de falhas com métodos         │
│      funcionais                                              │
│    • Benchmarks mostrando 30% de melhoria de performance    │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ ⚡ Fase 4: Otimização Nativa (v0.6.1+)                      │
│    • Compilação Cython para funções principais              │
│    • println() compilado para C nativo com libc             │
│    • setup_native() para builds zero-config                 │
│    • Ganho de 3x em performance em processadores ARM mobile │
└─────────────────────────────────────────────────────────────┘

Esta evolução reflete a filosofia central da koruspy: começar com primitivas funcionais sólidas, então otimizar impiedosamente para performance real.

🚀 Início Rápido

Instalação

pip install koruspy

Configuração Básica com Compilação Nativa

import koruspy

# Compila as extensões nativas automaticamente no seu ambiente
koruspy.setup_native()

from koruspy import Some, nothing, Okay, Err, println

# Seu código de alta performance aqui
resultado = Some(42)
println(resultado)

---

✅ Módulo Result

Programação Orientada a Trilhos em Python

O tipo Result fornece uma alternativa funcional aos blocos try/except, habilitando programação orientada a trilhos onde caminhos de sucesso e falha são explicitamente tratados através de padrões type-safe.

Por Que Result em Vez de try/except?

Abordagem Tradicional (try/except):

def dividir(a, b):
    try:
        resultado = a / b
        return resultado
    except ZeroDivisionError as e:
        print(f"Erro: {e}")
        return None

# Chamador tem que verificar None
resultado = dividir(10, 0)
if resultado is not None:
    print(f"Resultado: {resultado}")

Abordagem Funcional (Result):

from koruspy import Okay, Err

def dividir(a, b):
    if b == 0:
        return Err("Não é possível dividir por zero")
    return Okay(a / b)

# Pattern matching type-safe
match dividir(10, 2):
    case Okay(valor):
        print(f"Resultado: {valor}")
    case Err(erro):
        print(f"Erro: {erro}")

Okay(value) - Tipo de Sucesso

Representa uma operação bem-sucedida com um valor:

from koruspy import Okay, Err, println

def parse_int(s):
    try:
        return Okay(int(s))
    except ValueError:
        return Err(f"'{s}' não é um inteiro válido")

resultado = parse_int("42")
println(resultado)  # Saída: Okay(42)

# Encadeamento de operações
resultado = (parse_int("10")
             .map(lambda x: x * 2)
             .map(lambda x: x + 5))
println(resultado)  # Saída: Okay(25)

Err(error) - Tipo de Falha

Representa uma operação falhada com uma mensagem de erro:

from koruspy import Okay, Err, println

def validar_idade(idade):
    if idade < 0:
        return Err("Idade não pode ser negativa")
    if idade > 150:
        return Err("Idade parece irrealista")
    return Okay(idade)

resultado = validar_idade(-5)
println(resultado)  # Saída: Err(Idade não pode ser negativa)

# Propagação de erros
def processar_idade_usuario(idade_str):
    return (parse_int(idade_str)
            .and_then(validar_idade)
            .map(lambda idade: f"Idade válida: {idade}"))

println(processar_idade_usuario("25"))   # Saída: Okay(Idade válida: 25)
println(processar_idade_usuario("-5"))   # Saída: Err(Idade não pode ser negativa)
println(processar_idade_usuario("abc"))  # Saída: Err('abc' não é um inteiro válido)

Exemplo de Programação Orientada a Trilhos

Tipos Result permitem pipelines limpos de tratamento de erros:

from koruspy import Okay, Err

def ler_arquivo(caminho):
    try:
        with open(caminho) as f:
            return Okay(f.read())
    except FileNotFoundError:
        return Err(f"Arquivo não encontrado: {caminho}")

def parse_json(conteudo):
    import json
    try:
        return Okay(json.loads(conteudo))
    except json.JSONDecodeError as e:
        return Err(f"JSON inválido: {e}")

def extrair_nome(dados):
    if "name" in dados:
        return Okay(dados["name"])
    return Err("Campo nome ausente")

# Pipeline: ler → parsear → extrair
resultado = (ler_arquivo("config.json")
             .and_then(parse_json)
             .and_then(extrair_nome))

match resultado:
    case Okay(nome):
        print(f"Nome do usuário: {nome}")
    case Err(erro):
        print(f"Pipeline falhou: {erro}")

Quando Usar Result vs Option

• Use Result quando você precisa saber por que algo falhou (mensagens de erro, contexto)
• Use Option quando você só se importa com presença vs ausência (valor existe ou não)

from koruspy import Okay, Err, Some, nothing

# Result: Saber por que falhou
def dividir(a, b):
    if b == 0:
        return Err("Divisão por zero")
    return Okay(a / b)

# Option: Apenas verificar existência
def encontrar_usuario(user_id):
    usuarios = {1: "Alice", 2: "Bob"}
    if user_id in usuarios:
        return Some(usuarios[user_id])
    return nothing

---

📦 Módulo Option

O tipo Option fornece uma maneira type-safe de lidar com valores opcionais, eliminando erros relacionados ao None.

Some(value)

Representa um valor que existe:

from koruspy import Some, nothing, println

nome_usuario = Some("Alice")
println(nome_usuario)  # Saída: Some(Alice)

# Pattern matching
match nome_usuario:
    case Some(nome):
        println(f"Olá, {nome}!")
    case _NoneOption():
        println("Usuário não encontrado")

nothing

Um singleton que representa a ausência de um valor (substitui o None):

from koruspy import nothing, println

resultado_vazio = nothing
println(resultado_vazio)  # Saída: nothing

# Operações seguras
def dividir(a, b):
    if b == 0:
        return nothing
    return Some(a / b)

resultado = dividir(10, 0)
println(resultado)  # Saída: nothing (sem exceção!)

Nota: nothing é uma instância singleton. Se você precisar referenciar a classe em si (para verificação de tipo ou pattern matching), use _NoneOption().

AsyncOption(future)

Envolve operações assíncronas em um Option type-safe:

import asyncio
from koruspy import AsyncOption, println

async def buscar_dados():
    await asyncio.sleep(0.1)
    return "Dados carregados"

async def main():
    future = buscar_dados()
    resultado_async = AsyncOption(future)
    
    # O AsyncOption é exibido em roxo vibrante (otimizado para OLED)
    println(resultado_async)
    
    # Aguarda o resultado
    resultado_final = await resultado_async.resolve()
    println(resultado_final)  # Saída: Some(Dados carregados)

asyncio.run(main())

---

📊 Módulo de Coleções: SomeList (v0.7.0)

A SomeList é uma implementação de lista à prova de falhas, herdando de MutableSequence. Projetada para processar dados sem interrupções.

Características

• Normalização Automática: Aceita listas, tuplas, sets, geradores ou valores únicos e os normaliza internamente
• Encadeamento de Métodos: .append(), .extend() e .insert() retornam self
• Mapeamento Seguro: .map(fn) retorna nothing se a função falhar, protegendo a execução
• Alta Performance: Otimizada para filtragem e operações funcionais

from koruspy import SomeList, Some

# Operações funcionais seguras e encadeadas
res = (SomeList([10, 20])
       .append(30)
       .map(lambda x: x * 2)
       .sum())  # Saída: 120

# Filtragem segura
lista = SomeList([1, 2, None]).filter_nothing()
print(lista.head())  # Saída: Some(1)

Benchmarks de Performance

SomeList é otimizada para operações funcionais do mundo real. Aqui estão os resultados de benchmarks comparando com listas Python padrão e list comprehensions:

Operações de Filtragem

# Benchmark: Filtrar valores None de 10.000 itens
import time

# List comprehension padrão
data = list(range(10000)) + [None] * 1000
start = time.time()
filtered = [x for x in data if x is not None]
time_list_comp = time.time() - start

# SomeList.filter_nothing()
from koruspy import SomeList
some_list = SomeList(data)
start = time.time()
filtered = some_list.filter_nothing()
time_somelist = time.time() - start

print(f"List comprehension: {time_list_comp:.4f}s")
print(f"SomeList: {time_somelist:.4f}s")
# Resultados: SomeList é ~30% mais rápida
# List comprehension: 0.0012s
# SomeList: 0.0008s

Operações de Map

# Benchmark: Operações map em 10.000 itens
data = list(range(10000))

# Map padrão de lista
start = time.time()
mapped = list(map(lambda x: x * 2, data))
time_map = time.time() - start

# SomeList.map()
some_list = SomeList(data)
start = time.time()
mapped = some_list.map(lambda x: x * 2)
time_somelist_map = time.time() - start

print(f"Map padrão: {time_map:.4f}s")
print(f"SomeList.map(): {time_somelist_map:.4f}s")
# Resultados: Performance comparável com segurança adicional
# Map padrão: 0.0015s
# SomeList.map(): 0.0016s

Operações com Números Diretos (Dica de Performance)

Ao trabalhar com operações numéricas, usar números brutos em SomeList é significativamente mais rápido do que embrulhar cada número em Some():

# ❌ MAIS LENTO: Embrulhar cada número em Some
lista_lenta = SomeList([Some(1), Some(2), Some(3)])
resultado = lista_lenta.map(lambda x: x.value * 2)

# ✅ MAIS RÁPIDO: Números diretos (30-40% mais rápido)
lista_rapida = SomeList([1, 2, 3])
resultado = lista_rapida.map(lambda x: x * 2)

# Resultados de benchmark (1.000.000 operações):
# Embrulhado em Some: 0.45s
# Números diretos: 0.28s
# Ganho de performance: ~38% mais rápido

Por quê? Desembrulhar Some adiciona overhead. Use valores brutos quando segurança de tipo não é crítica.

Insights de Performance Principais

Operação	Python Padrão	SomeList	Vencedor
Filter None	0.0012s	0.0008s	✅ SomeList (30% mais rápida)
Map transform	0.0015s	0.0016s	≈ Comparável
Números diretos	N/A	0.28s	✅ Valores brutos
Some embrulhado	N/A	0.45s	❌ Mais lento
Operações encadeadas	N/A	Otimizado	✅ SomeList

Recomendação: Use SomeList para pipelines que requerem filtragem, encadeamento e operações à prova de falhas. Use números diretos em vez de embrulhar em Some() para cargas de trabalho com muitas operações numéricas.

---

⚡ Motor Nativo Cython (v0.6.1+)

🔥 Avanço em Performance

A partir da versão 0.6.1, a koruspy implementa suas funções principais em Cython, aproveitando a libc do C e fflush(stdout) para máxima performance de I/O.

📈 Benchmarks Reais em Mobile

Implementação	Tempo de Execução	Aceleração
Python Puro	0.017s	Baseline
🚀 Cython Nativo	0.006s	~3x mais rápido

println - Saída Nativa Compilada 🔥

A função println é compilada para código C nativo, fornecendo operações de saída extremamente rápidas otimizadas para processadores ARM móveis:

from koruspy import println, Some, nothing

# Impressão nativa rápida (compilada para C)
println("Olá do Cython!")
println(Some(123))
println(nothing)

# Comparação de benchmark
import time

inicio = time.time()
for i in range(1000):
    println(f"Iteração {i}")
fim = time.time()

print(f"Tempo de execução: {fim - inicio:.3f}s")
# Resultado mobile: ~0.006s (vs 0.017s em Python puro)

Por Baixo do Capô:

• println usa printf da libc para I/O direto em nível C
• Chama fflush(stdout) após cada impressão para saída imediata
• Compilada para extensões nativas .so (Linux/Mac) ou .pyd (Windows)
• Zero overhead do interpretador Python para operações de I/O

Quando Usar println vs print:

• ✅ Use println: Logging de alta frequência, apps mobile, caminhos críticos de performance
• ⚠️ Use print: Scripts Python padrão, quando compilação Cython não é necessária

---

🔧 Compilação Inteligente com setup_native()

Sem necessidade de scripts de build externos! A função setup_native() compila todos os arquivos .pyx Cython diretamente no ambiente do usuário.

Como Funciona

import koruspy

# Chame uma vez no início da sua aplicação
# Isso irá:
# 1. Detectar todos os arquivos .pyx na koruspy
# 2. Compilá-los para extensões nativas (.so ou .pyd)
# 3. Disponibilizá-los para importação
koruspy.setup_native()

# Agora você pode usar as funções de alta performance
from koruspy import println, Some

Quando Usar

• Primeira Execução: Sempre chame setup_native() após a instalação
• Atualizações: Execute novamente após atualizar a koruspy para recompilar as extensões
• Deploy: Inclua na inicialização do seu app para ambientes móveis

# Exemplo: Inicialização de app mobile
def inicializar_app():
    import koruspy
    koruspy.setup_native()
    
    from koruspy import println
    println("App inicializado com performance nativa!")

inicializar_app()

---

👁️ Acessibilidade e Saúde Visual

Sistema de Cores Otimizado para OLED

A koruspy usa cores ANSI cuidadosamente selecionadas para melhorar a legibilidade e reduzir fadiga visual em displays OLED móveis:

• 🟢 Verde (Some/Okay): Alto contraste, fácil de ler
• 🔴 Vermelho (nothing/Err): Indicação clara de ausência/falha
• 🟣 Roxo Vibrante (AsyncOption): Especialmente escolhido para reduzir efeitos de halo/borrão para desenvolvedores com astigmatismo

Por Que Roxo para AsyncOption?

Desenvolvedores com astigmatismo frequentemente experimentam efeitos de "halo" ou "borrão" ao redor de brancos e azuis brilhantes em telas OLED. O roxo vibrante (#BB86FC) proporciona:

• Redução de ghosting em fundos escuros
• Alto contraste sem brilho excessivo
• Melhor foco para padrões de visão astigmática
• Experiência de visualização confortável a longo prazo

from koruspy import AsyncOption, println
import asyncio

async def demo():
    future = asyncio.sleep(0.1, result="teste")
    async_opt = AsyncOption(future)
    
    # Saída roxa é mais confortável para os olhos durante desenvolvimento
    println(async_opt)  # Exibe em roxo amigável para OLED

asyncio.run(demo())

---

💡 Casos de Uso

A koruspy se destaca em cenários que exigem tanto padrões de programação funcional quanto alta performance:

Manipulação de Respostas de API com Result

from koruspy import Okay, Err, println

def buscar_usuario(user_id):
    # Simula chamada de API
    if user_id < 0:
        return Err("ID de usuário inválido")
    if user_id > 1000:
        return Err("Usuário não encontrado")
    return Okay({"id": user_id, "name": "Usuário"})

resultado = buscar_usuario(42)
match resultado:
    case Okay(usuario):
        println(f"Usuário encontrado: {usuario['name']}")
    case Err(erro):
        println(f"Erro: {erro}")

Processamento de Pipeline de Dados

from koruspy import Some, nothing, println

def processar_dados(dados):
    return (Some(dados)
            .map(lambda x: x.strip())
            .filter(lambda x: len(x) > 0)
            .map(lambda x: x.upper()))

resultado = processar_dados("  olá  ")
println(resultado)  # Saída: Some(OLÁ)

Operações Assíncronas em Apps Mobile

from koruspy import AsyncOption, println
import asyncio

async def carregar_config():
    await asyncio.sleep(0.1)  # Simula delay de rede
    return {"tema": "escuro", "idioma": "pt"}

async def main():
    config_future = carregar_config()
    config_option = AsyncOption(config_future)
    
    println("Carregando configuração...")
    println(config_option)  # Indicador roxo para operação async
    
    config = await config_option.resolve()
    println(config)

asyncio.run(main())

---

📊 Dicas de Performance

🎯 Diretrizes de Otimização

1. ✅ Sempre compile as extensões nativas

   import koruspy
   koruspy.setup_native()  # Ganho de 3x em velocidade
   

2. 🚀 Use números diretos em SomeList (não embrulhados em Some)

   # ❌ Mais lento: números embrulhados
   lenta = SomeList([Some(1), Some(2)])
   
   # ✅ Mais rápido: números diretos (38% mais rápido)
   rapida = SomeList([1, 2, 3])
   

3. ⚡ Use println para saída de alta frequência

   from koruspy import println
   for i in range(10000):
       println(f"Log {i}")  # I/O nativo em nível C
   

4. 🔗 Operações em lote com encadeamento de métodos

   resultado = (SomeList(dados)
                .filter_nothing()
                .map(transformar)
                .sum())
   

5. 🌐 Aproveite AsyncOption para I/O

   resultado_async = AsyncOption(buscar_dados())
   dados = await resultado_async.resolve()
   

6. 📱 Específico para Mobile: ajuste de processador ARM

   • O motor nativo é otimizado para arquiteturas ARM
   • Compile uma vez com setup_native() na inicialização do app
   • Use println para todo logging em produção

---

🛠️ Requisitos

• Python 3.8+
• Cython (instalado automaticamente)
• Compilador C (gcc/clang no Linux/Mac, MSVC no Windows)

---

📝 Licença

Licença MIT - Livre para uso em projetos comerciais e open-source.

---

Feito com ❤️ para desenvolvedores mobile

Alta performance encontra elegância funcional

### Contact Options: - Gmail=[e-mail]