Skip to main content

Esiur for Python

Python implementation of Esiur v3, a distributed resource framework for real-time properties, asynchronous function invocation and events over the Esiur EP protocol. It is a port of esiur-ts and must stay wire-compatible with esiur-dotnet.

Status: alpha (0.1.0). The wire data layer, the packet framing, an anonymous connection over WebSocket and TCP, remote resources (attach, read properties, call functions, write properties, events), hosting resources (Resource, Warehouse, EpServer), and authentication and encryption (password login, AES-GCM records) exist and interoperate with esiur-ts in both directions.

Compatibility: interoperability is tested against a real esiur-ts client and server (the esiur-ts tests in tests/test_interop_*.py run when Node and an esiur-ts checkout are available). It has not yet been verified against esiur-dotnet, so treat that pairing as untested.

Port status

Layer Status
TDU framing, limits (esiur.data.tdu, guard) Done
Dynamic values: ints, floats, str, bytes, datetime, UUID, Decimal128, Int128/UInt128, list, map, TypeContinuation Done, byte-identical to esiur-ts
Tru, Gvwie integer arrays, typed lists/maps/tuples (TypedList, TypedMap, TypedTuple, t) Done, byte-identical to esiur-ts
TypeDefs: indexed structures, TypeDefInfo and member infos, signatures (name64), records, enums, TypeRegistry Done, byte-identical to esiur-ts (resource-kind values and remote TypeDefs wait for the resource layer)
EP packets: EpPacket, EpAuthPacket and their enums (esiur.net.packets) Done; parsing and composing match esiur-ts on every header byte and every truncation
EpConnection core: anonymous handshake (initiator and responder), request/reply correlation, progress/warning/chunk replies, notifications, limits exchange, close handling Done, interoperates with esiur-ts over WebSocket; attach, subscribe, streaming, reconnect, keep-alive wait for the resource layer
Remote resources (client): EpResource proxies, attach/get, TypeDef fetching, property snapshots and notifications, calls, property writes, ref-counted event subscriptions, resource references (including cycles) Done, tested against a real esiur-ts server. Not yet: streaming functions, historical event replay, reattach/reconnect, SyncTypeDefs, record/enum values from a peer's TypeDefs
Local resources: Resource, Property/Event/@function declarations, Instance, Warehouse, MemoryStore, TypeDefs built from classes, permissions managers Done. Not yet: historical members and the journal, streaming functions, per-instance managers, rate-control and auditing managers, persistent stores, store children/parents
Server-side request handlers: attach, detach, link lookup, TypeDef by id / by resource, invoke, static call, set property, subscribe, unsubscribe Done, a real esiur-ts client drives a Python server. Answered NotImplemented: reattach, SyncTypeDefs, TypeDefIdsByNames, query, link TypeDefs, create/delete/move resource, stream control, journal query
Transports: WebSocket (pip install esiur[websockets]) and TCP Done, client and server. HTTP long-poll not started
Server: EpServer (WebSocket and TCP listeners) Done. No connection-admission limits yet. EpHttpHandler (ASGI) not started
Authentication: password-sha3-v1 in all three modes (initiator, responder, dual identity), providers, sessions seen by permissions managers Done, both directions against esiur-ts. Only the password protocol exists; others plug in as AuthenticationProviders
Encryption: aes-gcm (AES-256-GCM records, HKDF-SHA256 keys), negotiated in the handshake (pip install esiur[crypto]) Done, both directions against esiur-ts. Not yet: address-bound mode (EncryptWithSessionKeyAndAddress; esiur-ts cannot run it either)

The plan follows the order esiur-ts was built in, so each layer can be checked against it before the next is added.

Python mapping

Python Wire
None, bool Null, True/False
int narrowest of Int8/16/32/64 (UInt64 above 2**63)
float Int8/16/32 when whole, else Float32 when exact, else Float64; NaN/inf is one token
str, bytes String (UTF-8), RawData
datetime DateTime (naive values are taken as UTC; 100 ns ticks round to microseconds)
uuid.UUID, decimal.Decimal UUID, Decimal128 (96-bit mantissa, scale 0 to 28)
list/tuple, dict List, Map
Int8, UInt32, Float32, Int128, ... pin a specific width
TypedList(t.i32, [...]), TypedMap(t.string, t.f64, {...}), TypedTuple([t.i32, t.string], (...)) Typed list / map / tuple; decode back to list / dict / tuple
t.list(t.i32), t.nullable(t.string), ... (a Tru) TRU value
TypeDefInfo, PropertyDefInfo, ... or any IndexedStructure dataclass TypeDef (0x81) / sparse TypedMap<UInt8, dynamic>; decode back to the dataclass (TypeDefInfo) or a dict
dataclass registered with TypeRegistry.register_record, Enum registered with register_enum Typed value with a TruTypeDef; pass types=registry to compose and parse

Development

python -m venv .venv
.venv/Scripts/python -m pip install pytest pytest-asyncio ruff mypy websockets cryptography   # Windows; use .venv/bin on Linux/macOS
.venv/Scripts/python -m pytest
.venv/Scripts/python -m ruff check src tests
.venv/Scripts/python -m mypy

tests/fixtures/ts-vectors.json holds bytes produced by the real esiur-ts encoder. Regenerate it after building esiur-ts with node tools/gen-ts-vectors.mjs ../esiur-ts. tests/fixtures/ts-typedef-vectors.json (TypeDefs, records, enums, signatures) is built from the esiur-ts source instead, with node tools/gen-typedef-vectors.mjs ../esiur-ts. tests/fixtures/ts-packet-vectors.json (packet composing, all 256 header bytes, every truncated prefix) comes from the esiur-ts build, with node tools/gen-packet-vectors.mjs ../esiur-ts.

Connecting

from esiur.net import EpConnection
from esiur.net.packets import EpPacketRequest

async with await EpConnection.connect("ws://127.0.0.1:51018") as connection:
    resource_id = await connection.send_request(EpPacketRequest.GET_RESOURCE_ID_BY_LINK, "sys/greeter")

Or work with the resource itself:

greeter = await connection.get("sys/greeter")        # attach: fetches the type and the values
print(greeter.visits)                                # cached, kept fresh by the peer's notifications
print(await greeter.greet("Ahmed"))                  # a remote call (`say_hi` finds `sayHi`)
await greeter.set("label", "hello")                  # a remote write
greeter.on_property("visits", print)                 # property listeners are synchronous
await greeter.on_event("ping", print)                # subscribes on the first listener

Resource references in results, properties and notifications become EpResource proxies; a reference back to a resource being attached resolves to that proxy. Listeners may be plain functions or coroutine functions, and one that raises is logged without affecting the others.

send_request sends at once and returns a future, so requests can be pipelined with asyncio.gather. A failed request raises esiur.core.AsyncException (its type and code are what the peer sent). tcp://, ws://, wss://, ep:// and eps:// endpoints are accepted; a missing port means 51018.

tests/test_interop_ts.py starts a real esiur-ts EpServer (tools/ts-test-server.mjs) and talks to it; it is skipped without Node and an esiur-ts checkout (ESIUR_TS_PATH, default ../esiur-ts).

Hosting resources

import asyncio
from esiur.data import t
from esiur.net import EpServer
from esiur.resource import Event, MemoryStore, Property, Resource, Warehouse, function
from esiur.security import AllowAll


class Greeter(Resource):
    visits = Property(t.i32, default=0)                 # peers are told when it changes
    serial = Property(t.string, default="S-1", read_only=True)
    ping = Event(t.string)                              # peers subscribe to it
    tick = Event(t.string, auto_delivered=True)         # pushed to every attached peer

    @function(t.string, [t.string])                     # a method (sync or async) peers can call
    def greet(self, name):
        self.visits += 1
        self.ping.emit(f"greeted {name}")
        return f"Hi {name}"


async def main():
    warehouse = Warehouse()
    warehouse.register_permissions(AllowAll())          # without a manager, peers cannot write
    await warehouse.put("sys", MemoryStore())           # a store, then resources into it
    await warehouse.put("sys/greeter", Greeter())
    await warehouse.open()
    server = await EpServer.listen(warehouse, port=51018)   # transport="tcp" for raw TCP
    await asyncio.Event().wait()

asyncio.run(main())

Members are indexed in declaration order (base classes first), and peers address them by index, so reorder or remove them only together with their clients. Python names are exported as written (fire_ping); name="firePing" on Property, Event or @function exports a different one. The declared types describe the members to peers; values are written the way esiur-ts writes them (integers in the narrowest width). A peer's call that raises answers with an Exception error (RuntimeError: boom), and one the permissions managers deny with AccessDenied. By default a peer may attach, read and call but not write; register a PermissionsManager (or AllowAll) to decide otherwise.

Authentication and encryption

By default a connection is anonymous. To log in, give the client a provider and the identity to prove; to encrypt, add the mode (everything after the handshake then travels as AES-GCM records):

from esiur.security import (AuthenticationMode, EncryptionMode, StaticPasswordProvider,
                            AesEncryptionProvider)

provider = StaticPasswordProvider(credentials={"alice": "wonderland"}, identity="alice")
connection = await EpConnection.connect(
    "ws://server:51018",
    authentication_mode=AuthenticationMode.INITIALIZER_IDENTITY,   # or RESPONDER_/DUAL_IDENTITY
    encryption_mode=EncryptionMode.ENCRYPT_WITH_SESSION_KEY,       # optional; needs esiur[crypto]
    authentication_provider=provider,
    identity="alice",
)

A server hosts accounts (only salted SHA3 hashes are kept) and decides who may connect:

accounts = StaticPasswordProvider(
    accounts={"alice": "wonderland"},                              # who may log in
    credentials={"server": "srv-secret"}, identity="server",       # how it proves itself
)
server = await EpServer.listen(
    warehouse, port=51018,
    allow_unauthorized=False,                                      # refuse anonymous peers
    authentication_provider=accounts,
    encryption_providers=[AesEncryptionProvider()],
)

RESPONDER_IDENTITY makes the server prove its identity to the client (which needs the server's account to check it), and DUAL_IDENTITY both. Subclass PasswordAuthenticationProvider to look accounts up elsewhere (get_hosted_account_credential, get_self_credential, get_self_identity_and_credential), and AuthenticationProvider for another protocol. A finished session is connection.session (identities, key, the peer's headers); local_identity, remote_identity and session_key are shortcuts, and permissions managers receive the session as their second argument, so rules can depend on who is asking.

The session identities are from each side's own point of view: remote_identity is what the peer proved. (esiur-ts reports the initiator's identity as the responder's localIdentity.) Encryption needs a session key, so it requires authentication; a server rejects an offer it has no matching provider for. Logging in over an unencrypted connection sends the nonces and challenges in the clear, so use encryption (or wss://) on an untrusted network.

tests/test_hosting_net.py runs a Python client against a Python server, and tests/test_interop_ts_client.py runs a real esiur-ts client (tools/ts-test-client.mjs) against one. tests/test_interop_security.py repeats the authentication modes, with and without encryption, in both directions against esiur-ts, and tests/test_secure_sessions.py checks with a recording relay that an encrypted session shows nothing readable on the wire.

Metadata

Release files for esiur 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for esiur 0.1.0
File Size Uploaded Provenance Actions
esiur-0.1.0.tar.gz 144.6 kB With provenance Details for esiur-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for esiur 0.1.0
File Interpreter ABI Platform Actions
esiur-0.1.0-py3-none-any.whl Python 3 none any Details for esiur-0.1.0-py3-none-any.whl

Total release size: 249.0 kB

Release files / esiur-0.1.0.tar.gz

Download URL esiur-0.1.0.tar.gz
Size 144.6 kB
Tags Source
SHA-256 checksum
How to use checksums
cd29b89ddca52b0505defed3a49e4fb104226b6f4ff370e58ba8b910f96690bc
BLAKE2b-256 checksum
How to use checksums
581c1aa2c761d0baa374c8b4faa636e888ca93be1f26c20b1fb117dc743b501e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / esiur-0.1.0-py3-none-any.whl

Download URL esiur-0.1.0-py3-none-any.whl
Size 104.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ae81a3b777954a8e10770a457498c07d370344a42597adac384be26ff965c90a
BLAKE2b-256 checksum
How to use checksums
9315b4fbf4b4d0934793793fd3b02524d1689fcb3a0845314f1c2ad1800e2000
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for esiur 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for esiur-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page