Python Client Overview
The Python Client is a pybind11 binding that exposes the ChronoLog C++ Client API as the py_chronolog_client Python module. It provides the same chronicle, story, and event operations as the C++ client, allowing Python applications to interact with ChronoLog without writing any C++ code.
Key Features
- Direct pybind11 binding over the native C++ client — no extra serialization layer.
- Supports both writer-only and writer+reader client modes.
- On-demand in-memory tail reads (
StoryHandle.playback) for millisecond-scale retrieval of the latest events directly from keeper RAM. - Chronicle and story lifecycle management, event logging, and historical story replay.
- Ideal for prototyping, data analysis, and integration into Python-based pipelines.
Installation and Setup
- Build and install ChronoLog. The install puts
py_chronolog_clientin thelibdirectory of the installation. - Add that directory to
PYTHONPATH:export PYTHONPATH=/path/to/chronolog/lib:$PYTHONPATH - Run Python from ChronoLog's Spack environment,
/path/to/ChronoLog/.spack-env/view/bin/python3. The module is built for that Python (3.14 on the 3.5.0 stack), and no other Python can import it. Its library paths are set at install, so it needs noLD_LIBRARY_PATH, and its file name needs no symbolic link.
Client Modes
The Client class supports two modes depending on which constructor is used:
| Mode | Constructor | Capabilities |
|---|---|---|
| WRITER_MODE | Client(ClientPortalServiceConf) | Event logging only |
| WRITER + READER MODE | Client(ClientPortalServiceConf, ClientQueryServiceConf) | Event logging and story replay |
Use the single-argument constructor when you only need to produce events. Pass both a portal and a query service configuration to also enable ReplayStory.
Connection Lifecycle
A typical session follows this sequence:
- Connect — establish a session with ChronoVisor.
- CreateChronicle — create a named chronicle (top-level namespace).
- AcquireStory — open a story within the chronicle and obtain a
StoryHandle. - log_event — append events through the
StoryHandle. WithLogEventOptionsset toDurability.Durablethe call returnsCL_SUCCESSonly once the keeper has synced the event to its write-ahead log (seeLogEventOptions). - playback — retrieve the most recent $N$ events from keeper memory (writer or reader mode).
- ReplayStory — read back historical events within a time range (READER mode only).
- ReleaseStory — release the story handle.
- DestroyStory / DestroyChronicle — clean up resources when no longer needed.
- Disconnect — close the session.
import py_chronolog_client
portal_conf = py_chronolog_client.ClientPortalServiceConf("ofi+sockets", "127.0.0.1", 5555, 55)
client = py_chronolog_client.Client(portal_conf)
client.Connect()
client.CreateChronicle("MyChronicle")
ret, handle = client.AcquireStory("MyChronicle", "MyStory")
handle.log_event("hello world")
client.ReleaseStory("MyChronicle", "MyStory")
client.Disconnect()
Next Steps
- API Reference — full method signatures and return codes.
- Error Codes — complete list of integer return codes.
- Examples — annotated end-to-end examples including story replay.