Ipctools

Ipctools is a library to facilitate inter-process communication.

Installation

pip install ipctools

Usage

The store API is used to get or set values in a key-value store. This store is implemented as a temporary file on the system. The default file location may be overridden with the IPCTOOLS_STORE environment variable.

Set, and get a value from the store.

from ipctools import store

store.set_value("my_key", "my_value")
value = store.get_value("my_key")
assert value == "my_value"

Setting a value updates it if exists.

store.set_value("my_key", "my_value_1")
store.set_value("my_key", "my_value_2")
value = store.get_value("my_key")
assert value == "my_value_2"

However, creating a value will fail if it already exits. You can perform leader election across multiple processes by having each one try to set a value. Only one process will succeed, so that one can be the leader.

import os

from ipctools import store

is_leader = store.create_value("leader", str(os.getpid()))

Since the value of leader was set to the process ID of a single process, any process can also determine who the leader is.

def am_i_the_leader() -> bool:
    return store.get_value("leader") == str(os.getpid())

If mutliple processes try to set a value at the same time, some of them may fail. You can try to set a value with retries.

store.try_set_value("my_key", "my_value", retries=2)

Persist data to a key-value store.

The store is a file. By default it is in the systemp temporary directory, but its full path may be specified with the IPCTOOLS_STORE environment variable.

exception ipctools.store.StoreError

Bases: RuntimeError

Raised when a store operation fails.

ipctools.store.get_value(key: str) → str | None

Get a value from the store.

Return the value, or None if the key doesn’t exist.

Raises a StoreError if the value can’t be gotten, e.g., because the store has not been initialized yet.

ipctools.store.set_value(key: str, value: str, *, _timeout: float = 5) → None

Set a value in the store.

If the key already exists, its value will be updated.

Raises a StoreError if the value can’t be set, e.g., because another process is currently setting the value.

ipctools.store.create_value(key: str, value: str) → bool

Create a value in the store.

If the key already exists, its value will not be updated.

Returns True if the value was created, or False otherwise.

ipctools.store.try_get_value(key: str) → str | None

Try to get a value from the store.

Returns the value, or None if the key doesn’t exist, or there was a StoreError.

ipctools.store.try_set_value(key: str, value: str, *, retries: int = 0, _timeout: float = 5) → bool

Try to set a value in the store, with optional retries.

Returns True if the value was set. Otherwise False.