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! 🦀 🦀 🦀
Carcinization 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 might give you cancer. Who's to say which is correct?
No. No it is not.
Install with uv:
uv add carcinizeNo I won't add examples for pip, poetry, or ...🤮... conda. It's 2026, grow up and use uv.
It's 2026, grow up and use uv.
A type representing either success (Ok) or failure (Err). Errors must be Exception subclasses, so unwrap() raises the actual error.
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(), context(), note()
Converting to Option: The ok() and err() methods return Option types, matching Rust's API:
Ok(v).ok()returnsSome(v),Ok(v).err()returnsNothing()Err(e).ok()returnsNothing(),Err(e).err()returnsSome(e)
Type variance: Both Ok[T] and Err[E] are covariant in their type parameters, meaning Ok[Subclass] is a subtype of Ok[Superclass] and Err[SubException] is a subtype of Err[SuperException]. This is safe because both types are immutable, and matches Rust's Result<T, E> which is covariant in both type parameters.
Enhanced error context: When you create an Err, it automatically captures where in your code it was created. When you later call unwrap(), the traceback includes this origin information, making debugging much easier:
def fetch_user(id: int) -> Result[User, ValueError]:
if id < 0:
return Err(ValueError("invalid user id")) # Origin captured here
return Ok(User(id))
# When unwrap() is called, the traceback shows:
# 1. Where unwrap() was called
# 2. A note showing where the Err was originally created
fetch_user(-1).unwrap()
# ValueError: invalid user id
# Error originated at:
# /path/to/file.py:3 in fetch_user
# return Err(ValueError("invalid user id"))Adding context: Use .context() and .note() to add debugging information (similar to Rust's anyhow):
result = (
fetch_user(user_id)
.context("while loading user profile")
.note(f"user_id={user_id}")
)
# If this fails, the traceback will include both the context and note
# Works on both Ok and Err - Ok ignores them, Err adds them
# So you can add context without checking the variant firstConverting exceptions to Result: Use try_except to convert exception-throwing code:
from carcinize import try_except
result = try_except(lambda: int("not a number"), ValueError)
# Returns Err(ValueError(...)) instead of raising
result = try_except(lambda: 42, ValueError)
# Returns Ok(42)A type representing an optional value (Some or Nothing). We use Nothing instead of None to avoid confusion with Python's None.
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()
Type variance: Some[T] is covariant in T, meaning Some[Subclass] is a subtype of Some[Superclass]. This is safe because Some is immutable, and matches Rust's Option<T> which is covariant in T.
Pydantic-based structs with Rust-like semantics. Immutable by default, use mut=True for mutable structs.
from carcinize import Struct
# Immutable by default (like Rust's default)
class User(Struct):
name: str
age: int
user = User(name="Alice", age=30)
# user.age = 31 # ValidationError: frozen instance
# Mutable when you need it
class Config(Struct, mut=True):
host: str
port: int = 8080
config = Config(host="localhost")
config.port = 9000 # OK - mutable
# Pattern matching (via __match_args__)
match user:
case User(name, age) if age >= 18:
print(f"{name} is an adult")
case User(name, _):
print(f"{name} is a minor")
# Functional updates (like Rust's struct update syntax)
updated_user = user.replace(age=31) # Returns new instance
# Safe parsing with Result
match User.try_from({"name": "Bob", "age": 25}):
case Ok(u):
print(u.name)
case Err(validation_error):
print(validation_error)
# Also accepts JSON strings
User.try_from('{"name": "Charlie", "age": 35}')Features:
- Extra fields forbidden
- Strict type validation (no coercion)
- Pattern matching support via
__match_args__ - Functional updates via
replace() is_mut()classmethod and__mutable__class variable for runtime mutability checks- Immutable structs are hashable (can be used in sets/dicts)
Methods: try_from(), replace(), clone(), as_dict(), as_json(), is_mut()
Rust-like immutability: Like Rust, immutability applies to the binding, not the type. An immutable struct can contain fields of any type - you just can't mutate them through the immutable binding:
class Inner(Struct, mut=True):
value: int
class Outer(Struct): # Immutable
inner: Inner
outer = Outer(inner=Inner(value=42))
# outer.inner = Inner(value=100) # Error: can't mutate through outer
# But inner itself is a mutable type - this is fine, just like RustFluent iterator with chainable combinators, inspired by Rust's Iterator trait.
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
# Clone an iterator
it = Iter([1, 2, 3])
cloned = it.clone() # Independent copyTransformations: 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()
Thread-safe lazy initialization primitives.
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
# Check without triggering computation
expensive_config.is_computed() # True (after first get())
expensive_config.get_if_computed() # Some(config) or Nothing
# 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)
# Initialize with a function if not already set
value = cell.get_or_init(lambda: compute_default())
# Take the value out, resetting the cell
taken = cell.take() # Some(42), cell is now emptyBoth are thread-safe and use double-checked locking for performance.
All unwrap operations raise UnwrapError (importable from carcinize) when they fail on the wrong variant:
from carcinize import Nothing, Err, UnwrapError
try:
Nothing().unwrap()
except UnwrapError as e:
print(e) # "called `unwrap()` on a `Nothing` value"
# Err.unwrap() raises the contained error directly
try:
Err(ValueError("oops")).unwrap()
except ValueError as e:
print(e) # "oops"Rich error context: When Err.unwrap() raises, the exception includes notes showing where the error originated. If you caught an exception and wrapped it in Err, the original raise location is also shown:
def risky_operation() -> Result[int, ValueError]:
try:
return Ok(some_external_api())
except ValueError as e:
return Err(e) # Original traceback preserved
# Later...
result = risky_operation().context("while syncing data")
result.unwrap()
# The traceback will show:
# 1. Where unwrap() was called
# 2. "Context: while syncing data"
# 3. "Error originated at: ..." (where Err() was created)
# 4. "Exception was originally raised at: ..." (where ValueError was raised)This library is fully typed using ty. If you are already using carcinize in your project, you should absolutely be using ty as your static type checker, and maybe even as your LSP, for the closest possible Rust-like experience.
The Struct class uses @dataclass_transform to ensure proper type inference for fields.
WTFPL - Do What The F*ck You Want To Public License. Because life's too short for licensing drama.