Core

Generated from the type stubs and docstrings. Do not edit by hand.

Types

AvroRegistrySerde

Avro serde with Confluent Schema Registry integration.

Wire format: [0x00 magic][schema_id: 4 bytes BE][avro payload]

Schema registration is lazy (happens on first serialize() call). Reader schemas are fetched from the registry on first deserialize() per schema ID and cached for the serde’s lifetime.

TLS/mTLS: pass ca_path to trust a custom CA, or cert_path + key_path for mutual TLS (both required together; applies only when registry_url is https://). Encrypted private keys are not supported - key_path must point to an unencrypted PEM.

reader_schema: the schema every record is resolved INTO on deserialize (standard Avro schema resolution); without one a record decodes to its own writer schema’s shape, fetched by the id in its framing.

logical_types and strict: as for AvroSerde. See the docsite for a usage example including mTLS setup.

timeout_ms: the bound on one registry HTTP request, from connect to the last byte of the response (default 5000, 1 to 300000; ValueError otherwise). A call that makes one request fails within about this long when the registry is down or silent. A failed lookup, including a 404 for an unknown schema id, is remembered for 5 seconds, so records that need the same schema do not each ask the registry again; a registry follower that is behind on a brand-new id keeps that id failing for up to 5 seconds. A batch asks for each schema id at most once and, once the registry is unreachable or answers 5xx, makes no further requests; records that needed one fail with that error.

AvroRegistrySerde(registry_url: str, subject: str, schema: str, username: Optional[str] = None, password: Optional[str] = None, ca_path: Optional[str] = None, cert_path: Optional[str] = None, key_path: Optional[str] = None, reader_schema: Optional[str] = None, *, logical_types: Literal['python', 'raw'] = 'python', strict: bool = False, timeout_ms: int = 5000)

for_topic

for_topic(registry_url: str, topic: str, schema: str, is_key: bool = False, username: Optional[str] = None, password: Optional[str] = None, ca_path: Optional[str] = None, cert_path: Optional[str] = None, key_path: Optional[str] = None, reader_schema: Optional[str] = None, *, logical_types: Literal['python', 'raw'] = 'python', strict: bool = False, timeout_ms: int = 5000) -> AvroRegistrySerde

register

register(self) -> Ok[int] | Err[SerdeError]

subject

subject(self) -> str

serialize

serialize(self, obj: Any) -> Ok[bytes] | Err[SerdeError]

deserialize

deserialize(self, data: bytes) -> Ok[Any] | Err[SerdeError]

serialize_many

serialize_many(self, items: Iterable[Any]) -> IList

serialize_many_bytes

serialize_many_bytes(self, items: Iterable[Any]) -> BytesList

deserialize_many

deserialize_many(self, bytes_list: Iterable[bytes] | BytesList) -> IList

deserialize_many_objects

deserialize_many_objects(self, bytes_list: Iterable[bytes] | BytesList) -> IList

deserialize_many_from_packed

deserialize_many_from_packed(self, packed: bytes, count: int) -> IList

check_compatibility

check_compatibility(self, schema: str, version: Optional[str] = None) -> Ok[bool] | Err[SerdeError]

list_versions

list_versions(self) -> Ok[list[int]] | Err[SerdeError]

get_schema_by_version

get_schema_by_version(self, version: int) -> Ok[str] | Err[SerdeError]

delete_version

delete_version(self, version: int) -> Ok[bool] | Err[SerdeError]

---

AvroSerde

Avro serde over a single schema, returning Either instead of raising.

Logical types convert as fastavro (and so confluent-kafka) converts them: timestamp-* to an aware UTC datetime, local-timestamp-* to a naive datetime, date to a date, time-* to a time, decimal to a Decimal, uuid to a UUID. Writing takes those types or the plain value on the wire.

logical_types: “raw” decodes logical types to their value on the wire instead - int, bytes or str. Encoding takes either form whichever is chosen.

strict: refuse what fastavro converts by guessing - a naive datetime for a timestamp-* (fastavro takes it as the host’s local time), a datetime for a date (fastavro drops its time), and a decoded decimal with more digits than its precision (fastavro rounds it).

AvroSerde(schema_json: str, *, logical_types: Literal['python', 'raw'] = 'python', strict: bool = False)

serialize

serialize(self, obj: Any) -> Ok[bytes] | Err[SerdeError]

deserialize

deserialize(self, data: bytes) -> Ok[Any] | Err[SerdeError]

serialize_many

serialize_many(self, items: Iterable[Any]) -> IList

serialize_many_bytes

serialize_many_bytes(self, items: Iterable[Any]) -> BytesList

deserialize_many

deserialize_many(self, bytes_list: Iterable[bytes] | BytesList) -> IList

---

BytesList

BytesList(items: Any = ...)

empty

empty(cls) -> BytesList

from_packed

from_packed(buf: bytes, count: int) -> BytesList

get

get(self, index: int) -> Some[bytes] | _Nothing

append

append(self, item: bytes) -> BytesList

to_list

to_list(self) -> list[bytes]

to_packed

to_packed(self) -> bytes

to_ilist

to_ilist(self) -> IList[bytes]

length

length(self) -> int

is_empty

is_empty(self) -> bool

index

index(self, value: Any, start: int = 0, stop: int = ...) -> int

count

count(self, value: Any) -> int

---

DeserializationError

---

Duration

A typed time-span value backed by an i64 nanosecond count.

Mirrors Scala’s FiniteDuration - a precise, immutable quantity of time with unit-converting constructors and full arithmetic support.

nanos

nanos(n: int) -> Duration

micros

micros(n: int) -> Duration

millis

millis(n: int) -> Duration

seconds

seconds(n: float) -> Duration

minutes

minutes(n: float) -> Duration

hours

hours(n: float) -> Duration

days

days(n: float) -> Duration

from_timedelta

from_timedelta(td: Any) -> Duration

to_nanos

to_nanos(self) -> int

to_millis

to_millis(self) -> int

to_seconds

to_seconds(self) -> float

to_timedelta

to_timedelta(self) -> Any

---

Either

A value (Ok) or an error (Err). Subclassed by Ok and Err, the same way Scala’s Either is by Right/Left, so Either[A, E] is a real generic and isinstance(x, Either) holds for both. Abstract: build values through the factories below (or Ok/Err directly), not Either(...).

ok

ok(value: T) -> Ok[T]

err

err(error: E) -> Err[E]

try_of

try_of(f: Callable[[], T]) -> Either[T, Exception]

cond

cond(condition: bool, ok: T, err: E) -> Either[T, E]

sequence

sequence(values: Iterable[Either[T, E]]) -> Either[list[T], E]

traverse

traverse(values: Iterable[_A], fn: Callable[[_A], Either[U, F]]) -> Either[list[U], F]

map

map(self, f: Callable[..., Any]) -> Either[Any, E]

flat_map

flat_map(self, f: Callable[..., Any]) -> Either[Any, E]

map_err

map_err(self, f: Callable[..., Any]) -> Either[T, Any]

ensure

ensure(self, predicate: Callable[[T], bool], error: Callable[[T], F]) -> Either[T, E | F]
ensure(self, predicate: Callable[[T], bool], error: F) -> Either[T, E | F]

tap

tap(self, fn: Callable[[T], Any]) -> Either[T, E]

tap_err

tap_err(self, fn: Callable[[E], Any]) -> Either[T, E]

flatten

flatten(self: Either[Ok[U], E]) -> Either[U, E]
flatten(self: Either[Err[F], E]) -> Err[E | F]
flatten(self: Either[Either[U, F], E]) -> Either[U, E | F]

bimap

bimap(self, err_fn: Callable[[E], F], ok_fn: Callable[[T], U]) -> Either[U, F]

recover

recover(self, f: Callable[[E], Any]) -> Either[Any, Any]

recover_with

recover_with(self, f: Callable[[E], Either[Any, Any]]) -> Either[Any, Any]

or_else

or_else(self, alt: Either[Any, Any] | Callable[[], Either[Any, Any]]) -> Either[Any, Any]

fold

fold(self, err: Callable[..., Any], ok: Callable[..., Any]) -> Any

get_or_else

get_or_else(self, default: Any) -> Any

get_or_else_with

get_or_else_with(self, factory: Callable[[], U]) -> T | U

unwrap_or_raise

unwrap_or_raise(self, exc: Any = None) -> Any

to_option

to_option(self) -> Option[T]

is_ok

is_ok(self) -> bool

is_err

is_err(self) -> bool

---

Err

Err(error: E)

Fields:

• error: E

map

map(self, f: Callable[..., Any]) -> Err[E]

flat_map

flat_map(self, f: Callable[..., Any]) -> Err[E]

recover

recover(self, f: Callable[[E], Any]) -> Either[Any, Any]

recover_with

recover_with(self, f: Callable[[E], Either[Any, Any]]) -> Either[Any, Any]

map_err

map_err(self, f: Callable[..., Any]) -> Err[Any]

ensure

ensure(self, predicate: Callable[[Any], bool], error: F | Callable[[Any], F]) -> Err[E]

tap

tap(self, fn: Callable[[Any], Any]) -> Err[E]

tap_err

tap_err(self, fn: Callable[[E], Any]) -> Err[E]

flatten

flatten(self) -> Err[E]

bimap

bimap(self, err_fn: Callable[[E], F], ok_fn: Callable[[Any], U]) -> Err[F]

or_else

or_else(self, alt: Either[Any, Any] | Callable[[], Either[Any, Any]]) -> Either[Any, Any]

fold

fold(self, err: Callable[..., Any], ok: Callable[..., Any]) -> Any

get_or_else

get_or_else(self, default: Any) -> Any

get_or_else_with

get_or_else_with(self, factory: Callable[[], U]) -> U

unwrap_or_raise

unwrap_or_raise(self, exc: Any = None) -> Any

to_option

to_option(self) -> _Nothing

is_ok

is_ok(self) -> bool

is_err

is_err(self) -> bool

---

Failure

Failure(error: BaseException)

Fields:

• error: BaseException

map

map(self, f: Callable[..., Any]) -> Failure

flat_map

flat_map(self, f: Callable[..., Any]) -> Failure

tap

tap(self, fn: Callable[[Any], Any]) -> Failure

tap_failure

tap_failure(self, fn: Callable[[BaseException], Any]) -> Failure

flatten

flatten(self) -> Failure

recover

recover(self, f: Callable[[Any], Any]) -> Try[Any]

recover_with

recover_with(self, f: Callable[[Any], Try[Any]]) -> Try[Any]

or_else

or_else(self, alt: Try[Any] | Callable[[], Try[Any]]) -> Try[Any]

fold

fold(self, failure: Callable[..., Any], success: Callable[..., Any]) -> Any

get_or_else

get_or_else(self, default: Any) -> Any

get_or_else_with

get_or_else_with(self, factory: Callable[[], U]) -> U

to_either

to_either(self) -> Err[Any]

is_success

is_success(self) -> bool

is_failure

is_failure(self) -> bool

---

FloatList

FloatList(items: Any = ...)

empty

empty(cls) -> FloatList

map_float

map_float(self, f: Callable[[float], float]) -> FloatList

filter

filter(self, pred: Callable[[float], bool]) -> FloatList

fold_left

fold_left(self, initial: Any, f: Callable[..., Any]) -> Any

add_scalar

add_scalar(self, n: float) -> FloatList

sub_scalar

sub_scalar(self, n: float) -> FloatList

mul_scalar

mul_scalar(self, n: float) -> FloatList

div_scalar

div_scalar(self, n: float) -> FloatList

abs_vals

abs_vals(self) -> FloatList

clamp_vals

clamp_vals(self, lo: float, hi: float) -> FloatList

zip_add

zip_add(self, other: FloatList) -> FloatList

zip_mul

zip_mul(self, other: FloatList) -> FloatList

sum

sum(self) -> float

min

min(self) -> float

max

max(self) -> float

mean

mean(self) -> float

std_dev

std_dev(self) -> float

to_list

to_list(self) -> list[float]

to_ilist

to_ilist(self) -> IList[float]

length

length(self) -> int

is_empty

is_empty(self) -> bool

index

index(self, value: Any, start: int = 0, stop: int = ...) -> int

count

count(self, value: Any) -> int

---

IList

IList(items: Any = ...)

empty

empty(cls) -> IList[Any]

map

map(self, f: Callable[..., Any]) -> IList[Any]

flat_map

flat_map(self, f: Callable[..., Any]) -> IList[Any]

filter

filter(self, pred: Callable[..., bool]) -> IList[T]

fold_left

fold_left(self, initial: Any, f: Callable[..., Any]) -> Any

head

head(self) -> Some[T] | _Nothing

last

last(self) -> Some[T] | _Nothing

tail

tail(self) -> IList[T]

find

find(self, pred: Callable[..., bool]) -> Some[T] | _Nothing

take

take(self, n: int) -> IList[T]

drop

drop(self, n: int) -> IList[T]

distinct

distinct(self) -> IList[T]

zip

zip(self, other: IList[Any]) -> IList[tuple[T, Any]]

append

append(self, item: T) -> IList[T]

prepend

prepend(self, item: T) -> IList[T]

concat

concat(self, other: IList[T]) -> IList[T]

to_list

to_list(self) -> list[T]

collect_ok

collect_ok(self) -> IList[Any]

collect_err

collect_err(self) -> IList[Any]

partition_either

partition_either(self) -> tuple[IList[Any], IList[Any]]

length

length(self) -> int

is_empty

is_empty(self) -> bool

index

index(self, value: Any, start: int = 0, stop: int = ...) -> int

count

count(self, value: Any) -> int

---

IMap

Keys are found as in a dict: placed by Python’s hash() and compared with ==, so any key equal to a stored one finds it, whatever its type.

An IMap iterates in a fixed order that depends only on its contents, not on insertion order, the process or PYTHONHASHSEED, when every key is an exact str or bytes, an int, float, bool or None, or a tuple or frozenset of those. The order is by a 64-bit value computed from each key’s content, on first iteration, and it is neither insertion order nor sorted order. A key that hashes by identity (a plain object), through a str (a plain Enum member), or a str or bytes subclass with its own hash, iterates in a process-dependent order, and NaN keys with identical bits, or distinct keys of another type that share a hash, stay in insertion order among themselves.

IMap(items: Any = ...)

empty

empty(cls) -> IMap[Any, Any]

get

get(self, key: object, /) -> Optional[V]
get(self, key: object, default: V, /) -> V
get(self, key: object, default: _T, /) -> V | _T

get_option

get_option(self, key: K) -> Some[V] | _Nothing

set

set(self, key: K, value: V) -> IMap[K, V]

remove

remove(self, key: K) -> IMap[K, V]

contains

contains(self, key: K) -> bool

to_dict

to_dict(self) -> dict

keys

keys(self) -> KeysView[K]

values

values(self) -> ValuesView[V]

items

items(self) -> ItemsView[K, V]

map_values

map_values(self, f: Callable[[V], Any]) -> IMap[K, Any]

filter_values

filter_values(self, pred: Callable[[V], bool]) -> IMap[K, V]

merge

merge(self, other: IMap[K, V]) -> IMap[K, V]

length

length(self) -> int

is_empty

is_empty(self) -> bool

---

ISet

Keys are found as in a frozenset: placed by Python’s hash() and compared with ==, so any key equal to a stored one finds it, whatever its type.

An ISet iterates in a fixed order that depends only on its contents, not on insertion order, the process or PYTHONHASHSEED, when every key is an exact str or bytes, an int, float, bool or None, or a tuple or frozenset of those. The order is by a 64-bit value computed from each key’s content, on first iteration, and it is neither insertion order nor sorted order. A key that hashes by identity (a plain object), through a str (a plain Enum member), or a str or bytes subclass with its own hash, iterates in a process-dependent order, and NaN keys with identical bits, or distinct keys of another type that share a hash, stay in insertion order among themselves.

ISet(items: Optional[Iterable[T]] = None)

empty

empty(cls) -> ISet[Any]

add

add(self, item: T) -> ISet[T]

remove

remove(self, item: T) -> ISet[T]

contains

contains(self, item: T) -> bool

union

union(self, other: ISet[T]) -> ISet[T]

intersection

intersection(self, other: ISet[T]) -> ISet[T]

difference

difference(self, other: ISet[T]) -> ISet[T]

is_subset_of

is_subset_of(self, other: ISet[T]) -> bool

map

map(self, f: Callable[[T], Any]) -> ISet[Any]

filter

filter(self, pred: Callable[[T], bool]) -> ISet[T]

to_set

to_set(self) -> set[T]

to_ilist

to_ilist(self) -> IList[T]

size

size(self) -> int

is_empty

is_empty(self) -> bool

isdisjoint

isdisjoint(self, other: Iterable[Any]) -> bool

---

IntList

IntList(items: Any = ...)

empty

empty(cls) -> IntList

map_int

map_int(self, f: Callable[[int], int]) -> IntList

filter

filter(self, pred: Callable[[int], bool]) -> IntList

fold_left

fold_left(self, initial: Any, f: Callable[..., Any]) -> Any

add_scalar

add_scalar(self, n: int) -> IntList

sub_scalar

sub_scalar(self, n: int) -> IntList

mul_scalar

mul_scalar(self, n: int) -> IntList

div_scalar

div_scalar(self, n: int) -> IntList

abs_vals

abs_vals(self) -> IntList

clamp_vals

clamp_vals(self, lo: int, hi: int) -> IntList

zip_add

zip_add(self, other: IntList) -> IntList

zip_mul

zip_mul(self, other: IntList) -> IntList

sum

sum(self) -> int

min

min(self) -> int

max

max(self) -> int

mean

mean(self) -> float

std_dev

std_dev(self) -> float

to_list

to_list(self) -> list[int]

to_ilist

to_ilist(self) -> IList[int]

length

length(self) -> int

is_empty

is_empty(self) -> bool

index

index(self, value: Any, start: int = 0, stop: int = ...) -> int

count

count(self, value: Any) -> int

---

IntSet

IntSet(items: Any = ...)

empty

empty(cls) -> IntSet

add

add(self, value: int) -> IntSet

remove

remove(self, value: int) -> IntSet

contains

contains(self, value: Any) -> bool

union

union(self, other: IntSet) -> IntSet

intersection

intersection(self, other: IntSet) -> IntSet

difference

difference(self, other: IntSet) -> IntSet

symmetric_difference

symmetric_difference(self, other: IntSet) -> IntSet

is_subset

is_subset(self, other: IntSet) -> bool

is_disjoint

is_disjoint(self, other: IntSet) -> bool

cardinality

cardinality(self) -> int

to_list

to_list(self) -> list[int]

to_bytes

to_bytes(self) -> bytes

from_bytes

from_bytes(data: bytes) -> IntSet

is_empty

is_empty(self) -> bool

isdisjoint

isdisjoint(self, other: Iterable[Any]) -> bool

---

Invalid

Invalid(error: E)

Fields:

• errors: tuple[E, ...]

sequence

sequence(values: Iterable[Validated[U, F]]) -> Validated[list[U], F]

traverse

traverse(values: Iterable[_A], fn: Callable[[_A], Validated[U, F]]) -> Validated[list[U], F]

---

JsonSchemaRegistrySerde

JSON Schema serde with Confluent Schema Registry integration.

Wire format: [0x00 magic][schema_id: 4 bytes BE][json payload]

Same magic byte as Avro; content is JSON. NOTE: payloads are NOT validated against the JSON Schema - this serde provides Confluent wire framing ([0x00][schema_id:4B BE][json]) and registry registration only. (confluent’s JSONSerializer validates; pyrula does not yet.)

timeout_ms: the bound on one registry HTTP request, from connect to the last byte of the response (default 5000, 1 to 300000; ValueError otherwise). A failed registration is remembered for 5 seconds, so serializing many records against a registry that is down makes one request, not one per record; register() always asks again.

JsonSchemaRegistrySerde(registry_url: str, subject: str, schema: str, username: Optional[str] = None, password: Optional[str] = None, ca_path: Optional[str] = None, cert_path: Optional[str] = None, key_path: Optional[str] = None, *, timeout_ms: int = 5000)

for_topic

for_topic(registry_url: str, topic: str, schema: str, is_key: bool = False, username: Optional[str] = None, password: Optional[str] = None, ca_path: Optional[str] = None, cert_path: Optional[str] = None, key_path: Optional[str] = None, *, timeout_ms: int = 5000) -> JsonSchemaRegistrySerde

register

register(self) -> Ok[int] | Err[SerdeError]

subject

subject(self) -> str

serialize

serialize(self, obj: Any) -> Ok[bytes] | Err[SerdeError]

deserialize

deserialize(self, data: bytes) -> Ok[Any] | Err[SerdeError]

serialize_many

serialize_many(self, items: Iterable[Any]) -> IList

serialize_many_bytes

serialize_many_bytes(self, items: Iterable[Any]) -> BytesList

deserialize_many

deserialize_many(self, bytes_list: Iterable[bytes] | BytesList) -> IList

deserialize_many_objects

deserialize_many_objects(self, bytes_list: Iterable[bytes] | BytesList) -> IList

deserialize_many_from_packed

deserialize_many_from_packed(self, packed: bytes, count: int) -> IList

check_compatibility

check_compatibility(self, schema: str, version: Optional[str] = None) -> Ok[bool] | Err[SerdeError]

list_versions

list_versions(self) -> Ok[list[int]] | Err[SerdeError]

get_schema_by_version

get_schema_by_version(self, version: int) -> Ok[str] | Err[SerdeError]

delete_version

delete_version(self, version: int) -> Ok[bool] | Err[SerdeError]

---

JsonSerde

JsonSerde()

serialize

serialize(self, obj: Any) -> Ok[bytes] | Err[SerdeError]

deserialize

deserialize(self, data: bytes) -> Ok[Any] | Err[SerdeError]

serialize_many

serialize_many(self, items: Iterable[Any]) -> IList

serialize_many_raw

serialize_many_raw(self, items: Iterable[Any]) -> BytesList

deserialize_many

deserialize_many(self, bytes_list: Iterable[bytes] | BytesList) -> IList

deserialize_many_raw

deserialize_many_raw(self, bytes_list: Iterable[bytes] | BytesList) -> IList

---

NonEmptyList

A list with at least one element.

head, last, and reduce are total - they return T, not Option[T], because the non-empty invariant is enforced at construction time. from_list is the safe boundary: it returns Option[NonEmptyList[T]].

NonEmptyList(head: T, *tail: T)

of

of(head: T, *tail: T) -> NonEmptyList[T]

from_list

from_list(items: IList[T] | list[T]) -> Option[NonEmptyList[T]]

head

head(self) -> T

tail

tail(self) -> IList[T]

last

last(self) -> T

map

map(self, f: Callable[[T], Any]) -> NonEmptyList[Any]

flat_map

flat_map(self, f: Callable[[T], NonEmptyList[Any]]) -> NonEmptyList[Any]

reduce

reduce(self, f: Callable[[T, T], T]) -> T

fold_left

fold_left(self, init: Any, f: Callable[[Any, T], Any]) -> Any

append

append(self, item: T) -> NonEmptyList[T]

prepend

prepend(self, item: T) -> NonEmptyList[T]

to_ilist

to_ilist(self) -> IList[T]

to_list

to_list(self) -> list[T]

length

length(self) -> int

index

index(self, value: Any, start: int = 0, stop: int = ...) -> int

count

count(self, value: Any) -> int

---

Ok

Ok(value: T)

Fields:

• value: T

map

map(self, f: Callable[..., Any]) -> Ok[Any]

flat_map

flat_map(self, f: Callable[..., Any]) -> Any

map_err

map_err(self, f: Callable[..., Any]) -> Ok[T]

ensure

ensure(self, predicate: Callable[[T], bool], error: Callable[[T], F]) -> Either[T, F]
ensure(self, predicate: Callable[[T], bool], error: F) -> Either[T, F]

tap

tap(self, fn: Callable[[T], Any]) -> Ok[T]

tap_err

tap_err(self, fn: Callable[[Any], Any]) -> Ok[T]

flatten

flatten(self: Ok[_EitherResult]) -> _EitherResult

bimap

bimap(self, err_fn: Callable[[Any], F], ok_fn: Callable[[T], U]) -> Ok[U]

recover

recover(self, f: Callable[[Any], Any]) -> Ok[T]

recover_with

recover_with(self, f: Callable[[Any], Either[Any, Any]]) -> Ok[T]

or_else

or_else(self, alt: Either[Any, Any] | Callable[[], Either[Any, Any]]) -> Ok[T]

fold

fold(self, err: Callable[..., Any], ok: Callable[..., Any]) -> Any

get_or_else

get_or_else(self, default: Any) -> T

get_or_else_with

get_or_else_with(self, factory: Callable[[], U]) -> T

unwrap_or_raise

unwrap_or_raise(self, exc: Any = None) -> T

to_option

to_option(self) -> Some[T]

is_ok

is_ok(self) -> bool

is_err

is_err(self) -> bool

---

Option

Some(value) or Nothing; subclassed by both like Scala’s Option.

of

of(value: Optional[T]) -> Option[T]

when

when(condition: bool, value: T) -> Option[T]

from_callable

from_callable(f: Callable[[], T]) -> Option[T]

sequence

sequence(values: Iterable[Option[T]]) -> Option[list[T]]

traverse

traverse(values: Iterable[_A], fn: Callable[[_A], Option[U]]) -> Option[list[U]]

map

map(self, f: Callable[..., Any]) -> Option[Any]

flat_map

flat_map(self, f: Callable[..., Any]) -> Option[Any]

tap

tap(self, fn: Callable[[T], Any]) -> Option[T]

flatten

flatten(self: Option[Some[U]]) -> Option[U]
flatten(self: Option[_Nothing]) -> _Nothing
flatten(self: Option[Option[U]]) -> Option[U]

filter

filter(self, pred: Callable[..., bool]) -> Option[T]

get_or_else

get_or_else(self, default: Any) -> Any

get_or_else_with

get_or_else_with(self, factory: Callable[[], U]) -> T | U

or_else

or_else(self, alt: Option[Any] | Callable[[], Option[Any]]) -> Option[Any]

fold

fold(self, nothing_val: Any, some_fn: Callable[..., Any]) -> Any

to_either

to_either(self, left: Any) -> Either[T, Any]

to_either_with

to_either_with(self, error_factory: Callable[[], E]) -> Either[T, E]

to_list

to_list(self) -> IList[T]

is_some

is_some(self) -> bool

is_nothing

is_nothing(self) -> bool

is_empty

is_empty(self) -> bool

---

ProtobufRegistrySerde

Protobuf serde with Confluent Schema Registry integration.

Wire format: [0x00 magic][schema_id: 4 bytes BE][msg-index zigzag varint array][protobuf payload]

Accepts a serialized FileDescriptorSet and a fully-qualified message name. Deserialization decodes to Python dicts using prost-reflect; no compiled message types needed. Registration requires proto_source (the .proto source text) so the Confluent SR can parse and validate the schema.

LIMITATION: the Confluent message-index is always written as [0] (first message) - only correct when message_name is the first top-level message; multi-message/nested .proto files will not interoperate with Confluent consumers that rely on the message index.

NOTE: proto3 implicit-presence scalar fields at their default are omitted on deserialize, absent from the returned dict (standard protobuf semantics). NOTE: enum fields accept the enum value name (str) or number (int) on serialize; deserialize returns the number (int).

timeout_ms: the bound on one registry HTTP request, from connect to the last byte of the response (default 5000, 1 to 300000; ValueError otherwise). A failed registration is remembered for 5 seconds, so serializing many records against a registry that is down makes one request, not one per record; register() always asks again.

ProtobufRegistrySerde(registry_url: str, subject: str, file_descriptor_set: bytes, message_name: str, proto_source: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, ca_path: Optional[str] = None, cert_path: Optional[str] = None, key_path: Optional[str] = None, *, timeout_ms: int = 5000)

for_topic

for_topic(registry_url: str, topic: str, file_descriptor_set: bytes, message_name: str, is_key: bool = False, proto_source: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, ca_path: Optional[str] = None, cert_path: Optional[str] = None, key_path: Optional[str] = None, *, timeout_ms: int = 5000) -> ProtobufRegistrySerde

register

register(self) -> Ok[int] | Err[SerdeError]

subject

subject(self) -> str

serialize

serialize(self, obj: Any) -> Ok[bytes] | Err[SerdeError]

serialize_with_id

serialize_with_id(self, obj: Any, schema_id: int) -> Ok[bytes] | Err[SerdeError]

deserialize

deserialize(self, data: bytes) -> Ok[Any] | Err[SerdeError]

serialize_many

serialize_many(self, items: Iterable[Any]) -> IList

serialize_many_bytes

serialize_many_bytes(self, items: Iterable[Any]) -> BytesList

deserialize_many

deserialize_many(self, bytes_list: Iterable[bytes] | BytesList) -> IList

deserialize_many_objects

deserialize_many_objects(self, bytes_list: Iterable[bytes] | BytesList) -> IList

deserialize_many_from_packed

deserialize_many_from_packed(self, packed: bytes, count: int) -> IList

check_compatibility

check_compatibility(self, proto_source: str, version: Optional[str] = None) -> Ok[bool] | Err[SerdeError]

list_versions

list_versions(self) -> Ok[list[int]] | Err[SerdeError]

get_schema_by_version

get_schema_by_version(self, version: int) -> Ok[str] | Err[SerdeError]

delete_version

delete_version(self, version: int) -> Ok[bool] | Err[SerdeError]

---

RecordedError

A journaled exception that could not be rebuilt as its original class.

type_path is the original module:qualname and message its text; str() is the message, and serializing it again writes the original pair.

RecordedError(type_path: str, message: str)

Fields:

• type_path: str
• message: str

---

SerdeError

---

SerializationError

---

Some

Some(value: T)

Fields:

• value: T

map

map(self, f: Callable[..., Any]) -> Some[Any]

flat_map

flat_map(self, f: Callable[..., Any]) -> Any

tap

tap(self, fn: Callable[[T], Any]) -> Some[T]

flatten

flatten(self: Some[_OptionResult]) -> _OptionResult

filter

filter(self, pred: Callable[..., bool]) -> Any

get_or_else

get_or_else(self, default: Any) -> T

get_or_else_with

get_or_else_with(self, factory: Callable[[], U]) -> T

or_else

or_else(self, alt: Option[Any] | Callable[[], Option[Any]]) -> Some[T]

fold

fold(self, nothing_val: Any, some_fn: Callable[..., Any]) -> Any

to_either

to_either(self, left: Any) -> Ok[T]

to_either_with

to_either_with(self, error_factory: Callable[[], E]) -> Ok[T]

to_list

to_list(self) -> IList[T]

is_some

is_some(self) -> bool

is_nothing

is_nothing(self) -> bool

is_empty

is_empty(self) -> bool

---

Success

Success(value: T)

Fields:

• value: T

map

map(self, f: Callable[..., Any]) -> Any

flat_map

flat_map(self, f: Callable[..., Any]) -> Any

tap

tap(self, fn: Callable[[T], Any]) -> Success[T]

tap_failure

tap_failure(self, fn: Callable[[BaseException], Any]) -> Success[T]

flatten

flatten(self: Success[_TryResult]) -> _TryResult

recover

recover(self, f: Callable[[Any], Any]) -> Success[T]

recover_with

recover_with(self, f: Callable[[Any], Try[Any]]) -> Success[T]

or_else

or_else(self, alt: Try[Any] | Callable[[], Try[Any]]) -> Success[T]

fold

fold(self, failure: Callable[..., Any], success: Callable[..., Any]) -> Any

get_or_else

get_or_else(self, default: Any) -> T

get_or_else_with

get_or_else_with(self, factory: Callable[[], U]) -> T

to_either

to_either(self) -> Ok[T]

is_success

is_success(self) -> bool

is_failure

is_failure(self) -> bool

---

Try

Success(value) or Failure(exc); subclassed by both like Scala’s Try.

apply

apply(f: Callable[[], T]) -> Try[T]

of

of(f: Callable[[], T]) -> Try[T]

sequence

sequence(values: Iterable[Try[T]]) -> Try[list[T]]

traverse

traverse(values: Iterable[_A], fn: Callable[[_A], Try[U]]) -> Try[list[U]]

map

map(self, f: Callable[..., Any]) -> Try[Any]

flat_map

flat_map(self, f: Callable[..., Any]) -> Try[Any]

tap

tap(self, fn: Callable[[T], Any]) -> Try[T]

tap_failure

tap_failure(self, fn: Callable[[BaseException], Any]) -> Try[T]

flatten

flatten(self: Try[Success[U]]) -> Try[U]
flatten(self: Try[Failure]) -> Failure
flatten(self: Try[Try[U]]) -> Try[U]

recover

recover(self, f: Callable[[Any], Any]) -> Try[Any]

recover_with

recover_with(self, f: Callable[[Any], Try[Any]]) -> Try[Any]

or_else

or_else(self, alt: Try[Any] | Callable[[], Try[Any]]) -> Try[Any]

fold

fold(self, failure: Callable[..., Any], success: Callable[..., Any]) -> Any

get_or_else

get_or_else(self, default: Any) -> Any

get_or_else_with

get_or_else_with(self, factory: Callable[[], U]) -> T | U

to_either

to_either(self) -> Either[T, Any]

is_success

is_success(self) -> bool

is_failure

is_failure(self) -> bool

---

Valid

Valid(value: T)

Fields:

• value: T

sequence

sequence(values: Iterable[Validated[U, F]]) -> Validated[list[U], F]

traverse

traverse(values: Iterable[_A], fn: Callable[[_A], Validated[U, F]]) -> Validated[list[U], F]

---

Validated

Like Either, but zip accumulates errors instead of short-circuiting.

valid

valid(value: T) -> Validated[T, E]

invalid

invalid(error: E) -> Validated[T, E]

from_either

from_either(either: Either[T, E]) -> Validated[T, E]

cond

cond(condition: bool, value: T, error: E) -> Validated[T, E]

sequence

sequence(values: Iterable[Validated[U, F]]) -> Validated[list[U], F]

traverse

traverse(values: Iterable[_A], fn: Callable[[_A], Validated[U, F]]) -> Validated[list[U], F]

map

map(self, f: Callable[[T], Any]) -> Validated[Any, E]

map_err

map_err(self, f: Callable[[tuple[E, ...]], Any]) -> Validated[T, Any]

zip

zip(self, other: Validated[Any, E]) -> Validated[Any, E]

fold

fold(self, invalid: Callable[[tuple[E, ...]], Any], valid: Callable[[T], Any]) -> Any

get_or_else

get_or_else(self, default: T) -> T

to_either

to_either(self) -> Either[T, tuple[E, ...]]

is_valid

is_valid(self) -> bool

is_invalid

is_invalid(self) -> bool

Constants

• Nothing: _Nothing = _nothing()

Functions

case

case(cls: type[T]) -> type[T]

Make cls a frozen dataclass. Use dataclasses.replace and dataclasses.asdict.

do

do(func: Callable[..., Any]) -> Callable[..., Any]

do_async

do_async(func: Callable[..., Any]) -> Callable[..., Any]

flow

flow(*funcs: Callable[..., Any]) -> Callable[..., Any]

Compose funcs left to right into a single callable.

match

match(value: Any) -> Callable[..., Any]

match(value)(on(T1, h1), on(T2, h2), ...): dispatch to the first matching handler. For a @sealed hierarchy, raises if any concrete case is uncovered.

newtype

newtype(name: str, base_type: type[T]) -> type[T]

A lightweight subclass of base_type named name, for a distinct domain type.

newtype_strict

newtype_strict(name: str, base_type: type[T], *, validate: Optional[Callable[..., bool]] = None, err_msg: Optional[str] = None) -> type[T]

Like newtype, but raises on construction if validate rejects the value.

on

on(typ: type[T], handler: Callable[..., Any]) -> Any

Build a match arm: dispatch to handler when the value is an instance of typ.

partial

partial(f: Callable[..., Any], *args: Any, **kwargs: Any) -> Callable[..., Any]

pipe

pipe(value: Any, *funcs: Callable[..., Any]) -> Any

Thread value through funcs left to right, each result feeding the next.

sealed

sealed(cls: type[T]) -> type[T]

Mark cls as a closed hierarchy: match enforces exhaustiveness over its cases.

Subclasses may be declared only in the module that defines cls; any other module gets a TypeError at class creation.