# 🦀 Carcinize 🦀

Born to write Rust but forced to use Python to survive?
Learned Rust for fun and now all the missing language features are driving you crazy?
Want to look really p̶r̶e̶t̶e̶n̶t̶i̶o̶u̶s̶ cool in front of your coworkers?

Try Carcinization! 🦀 🦀 🦀

## What's up with the name?

[Carcinization](https://en.wikipedia.org/wiki/Carcinisation) is the tendency for convergent evolution of many species to eventually become crabs, or as Lancelot Alexander Borradaile put it: "the many attempts of Nature to evolve a crab".

As I have fully drunk the Rust kool-aid, I am now fully committed to the idea that everything should be a crab. Including Python.

Another equally valid interpretation is it's a verb form of "carcinogen", because using this library will give your Python projects cancer. Who's to say which is correct?

## Installation

Install with uv:

```bash
uv add carcinize
```

No I won't add examples for `pip`, `poetry`, or god forbid `conda`. It's 2026, grow up and use uv.

Requires Python 3.12+.

## Features

### Result

A type representing either success (`Ok`) or failure (`Err`). Errors must be `Exception` subclasses, so `unwrap()` raises the actual error.

```python
from carcinize import Ok, Err, Result

def divide(a: int, b: int) -> Result[float, ZeroDivisionError]:
    if b == 0:
        return Err(ZeroDivisionError("cannot divide by zero"))
    return Ok(a / b)

# Pattern matching
match divide(10, 2):
    case Ok(value):
        print(f"Result: {value}")
    case Err(error):
        print(f"Error: {error}")

# Method chaining
result = (
    divide(10, 2)
    .map(lambda x: x * 2)
    .unwrap_or(0.0)
)
```

**Methods:** `is_ok()`, `is_err()`, `ok()`, `err()`, `unwrap()`, `unwrap_err()`, `expect()`, `expect_err()`, `unwrap_or()`, `unwrap_or_else()`, `map()`, `map_err()`, `map_or()`, `map_or_else()`, `and_then()`, `or_else()`

### Option

A type representing an optional value (`Some` or `Nothing`). We use `Nothing` instead of `None` to avoid confusion with Python's `None`.

```python
from carcinize import Some, Nothing, Option

def find_user(id: int) -> Option[str]:
    users = {1: "alice", 2: "bob"}
    if id in users:
        return Some(users[id])
    return Nothing()

# Pattern matching
match find_user(1):
    case Some(name):
        print(f"Found: {name}")
    case Nothing():
        print("User not found")

# Method chaining
name = find_user(1).map(str.upper).unwrap_or("anonymous")
```

**Methods:** `is_some()`, `is_nothing()`, `unwrap()`, `expect()`, `unwrap_or()`, `unwrap_or_else()`, `map()`, `map_or()`, `map_or_else()`, `and_then()`, `or_else()`, `filter()`, `ok_or()`, `ok_or_else()`, `zip()`

### Struct / MutStruct

Pydantic-based structs with Rust-like semantics. Extra fields are forbidden, strict validation is enabled, and fields are validated on assignment.

```python
from carcinize import Struct, MutStruct

# Immutable (frozen, hashable)
class Point(Struct):
    x: int
    y: int

p = Point(x=1, y=2)
# p.x = 3  # Error: frozen

# Mutable
class Config(MutStruct):
    host: str
    port: int = 8080

config = Config(host="localhost")
config.port = 9000  # OK

# Safe parsing with Result
match Config.try_from({"host": "localhost"}):
    case Ok(cfg):
        print(cfg.host)
    case Err(validation_error):
        print(validation_error)
```

**Methods:** `try_from()`, `clone()`, `as_dict()`, `as_json()`

`Struct` also enforces deep immutability - nested mutable objects are rejected at construction time.

Note: `try_from()` accepts either a `dict` or a JSON string. Other types return `Err(TypeError)`.

### Iter

Fluent iterator with chainable combinators, inspired by Rust's `Iterator` trait.

```python
from carcinize import Iter

# Chain transformations
result = (
    Iter([1, 2, 3, 4, 5])
    .filter(lambda x: x > 2)
    .map(lambda x: x * 2)
    .collect_list()
)  # [6, 8, 10]

# Find with Option
first_even = Iter([1, 3, 4, 5]).find(lambda x: x % 2 == 0)  # Some(4)

# Fold/reduce
total = Iter([1, 2, 3]).fold(0, lambda acc, x: acc + x)  # 6
```

**Transformations:** `map()`, `filter()`, `filter_map()`, `flat_map()`, `flatten()`, `inspect()`

**Slicing:** `take()`, `skip()`, `take_while()`, `skip_while()`, `step_by()`

**Combining:** `chain()`, `zip()`, `zip_longest()`, `enumerate()`, `interleave()`

**Folding:** `fold()`, `reduce()`, `sum()`, `product()`

**Searching:** `find()`, `find_map()`, `position()`, `any()`, `all()`, `count()`, `min()`, `max()`

**Collecting:** `collect_list()`, `collect_set()`, `collect_dict()`, `collect_string()`, `partition()`, `group_by()`

**Accessing:** `first()`, `last()`, `nth()`

**Sorting:** `sorted()`, `sorted_by()`

**Deduplication:** `unique()`, `unique_by()`

### Lazy / OnceCell

Thread-safe lazy initialization primitives.

```python
from carcinize import Lazy, OnceCell

# Lazy - computed on first access
expensive_config = Lazy(lambda: load_config_from_disk())
# ... nothing computed yet ...
config = expensive_config.get()  # computed once, cached forever

# OnceCell - write exactly once
cell: OnceCell[int] = OnceCell()
cell.get()      # Nothing
cell.set(42)    # Ok(None)
cell.get()      # Some(42)
cell.set(100)   # Err(OnceCellAlreadyInitializedError)
```

Both are thread-safe and use double-checked locking for performance.
