Python API Reference
Native Python implementation of Twilic v2 (v3 support pending). Dynamic Profile remains largely wire-compatible with the Go and Rust encoders where tags are unchanged; Bound/Batch v3 forms require a v3 SDK.
Package: twilic
Source: github.com/twilic/twilic-python
Install
bash
pip install twilicHigh-level API
python
import twilic
# Stateless dynamic
payload = twilic.encode(value)
restored = twilic.decode(payload)
# Batch
payload = twilic.encode_batch(records)
# Schema-aware
payload = twilic.encode_with_schema(schema, value)
# Session
enc = twilic.create_session_encoder()
frame = enc.encode(value)
patch = enc.encode_patch(updated)
enc.reset()Building values
python
import twilic
value = twilic.new_map(
twilic.entry("id", twilic.new_u64(1001)),
twilic.entry("name", twilic.new_string("alice")),
twilic.entry("active", twilic.new_bool(True)),
twilic.entry("tags", twilic.new_array(
twilic.new_string("admin"),
twilic.new_string("beta"),
)),
)| Constructor | Type |
|---|---|
new_null() | null |
new_bool(v) | bool |
new_i64(v) / new_u64(v) | integer |
new_f64(v) | float |
new_string(v) | str |
new_binary(v) | bytes |
new_array(*items) | list |
new_map(*entries) | dict |
entry(key, value) | map entry |
SessionEncoder
python
enc = twilic.create_session_encoder(
max_base_snapshots=8,
enable_state_patch=True,
enable_template_batch=True,
enable_trained_dictionary=True,
unknown_reference_policy="failFast", # or "statelessRetry"
)
enc.encode(value) # full frame
enc.encode_patch(value) # state patch
enc.encode_batch(records) # row batch
enc.encode_micro_batch(records)
enc.reset()TwilicCodec (low-level)
python
codec = twilic.TwilicCodec()
payload = codec.encode_value(value)
restored = codec.decode_value(payload)
msg = codec.encode_message(message)
restored_msg = codec.decode_message(payload)Access to full Message model, patch opcodes, control messages, and column batches.
Message model
Full message kinds for advanced pipelines:
MessageKindScalar,MessageKindArray,MessageKindMapMessageKindShapedObject,MessageKindSchemaObjectMessageKindTypedVector,MessageKindRowBatch,MessageKindColumnBatchMessageKindStatePatch,MessageKindTemplateBatchMessageKindControl,MessageKindControlStream,MessageKindBaseSnapshot
Patch opcodes: PatchOpcodeKeep, PatchOpcodeReplaceScalar, PatchOpcodePrefixDelta, and others.
Errors
python
from twilic import TwilicError, ErrStatelessRetryRequired, ErrUnknownReference| Exception | Meaning |
|---|---|
ErrStatelessRetryRequired | Unknown base/shape ref — request full frame |
ErrUnknownReference | Reference not in session tables |
ErrInvalidData | Malformed wire bytes |
Interop
Python encoder output decodes in any v2-conforming SDK. Run cross-language smoke tests:
bash
cd twilic-python && ./scripts/check-interop.shSee Interop guide.