dflockd-client

A Python client for dflockd — a distributed FIFO lock and counting-semaphore server.

Features

Sync and async clients — pick the one that matches your runtime
Distributed locks and counting semaphores with FIFO ordering
Single-phase acquire and two-phase enqueue + wait
Background lease renewal — call acquire, hold for as long as you need
Grant tokens carry a monotonic fence prefix — usable as fencing tokens
Multi-server sharding (deterministic CRC-32; matches the Go and TypeScript clients)
TLS and shared-secret authentication
Zero runtime dependencies; Python 3.12+

Install

pip install dflockd-client
# or
uv add dflockd-client

Quick start

A running dflockd server on 127.0.0.1:6388 is the only prerequisite.

Lock

from dflockd_client import SyncDistributedLock

with SyncDistributedLock("my-key") as lock:
    # critical section — lease auto-renews in a daemon thread
    print(f"acquired: {lock.token}")

import asyncio
from dflockd_client import AsyncDistributedLock

async def main():
    async with AsyncDistributedLock("my-key") as lock:
        print(f"acquired: {lock.token}")

asyncio.run(main())

Semaphore

Up to limit concurrent holders on the same key:

from dflockd_client import SyncDistributedSemaphore

with SyncDistributedSemaphore("pool", limit=3) as sem:
    print(f"slot: {sem.token}")

Authentication and TLS

import ssl
from dflockd_client import SyncDistributedLock

with SyncDistributedLock(
    "my-key",
    auth_token="shared-secret",
    ssl_context=ssl.create_default_context(),
) as lock:
    ...

Multi-server sharding

from dflockd_client import SyncDistributedLock

with SyncDistributedLock(
    "my-key",
    servers=[("a", 6388), ("b", 6388), ("c", 6388)],
) as lock:
    # the same key always routes to the same server
    ...

Fencing tokens

Every grant returns a 32-char hex token whose first 16 hex chars are a monotonic uint64 (big-endian) that strictly increases on every grant from a server. fence_from_token parses it, so the token doubles as a fencing token: a downstream resource stores the highest fence it has seen for a key and rejects any write whose fence compares less.

from dflockd_client import SyncDistributedLock, fence_from_token

with SyncDistributedLock("row:42") as lock:
    fence = fence_from_token(lock.token)  # int — pass to your DB / blob store

See the docs for two-phase acquisition, exception handling, low-level transport, and more.

Metadata

Release files for dflockd-client 2.1.1

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

Source distribution (sdist)

Source distribution for dflockd-client 2.1.1
File	Size	Uploaded
dflockd_client-2.1.1.tar.gz	18.4 kB	May 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dflockd-client 2.1.1
File	Interpreter	ABI	Platform	Reset
dflockd_client-2.1.1-py3-none-any.whl 21.9 kB May 11, 2026	Python 3	none	any	Details

Total release size: 40.3 kB

Release files / dflockd_client-2.1.1.tar.gz

Download URL	dflockd_client-2.1.1.tar.gz
Size	18.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`7dd0f224d238725c51df8e92a3ac33f4512e4c57d28938859ab24a7162ac417d`
BLAKE2b-256 checksum How to use checksums	`78a89b31914339c816f8e426b22a39f777189bef48681e76ce705bd19ca45b3a`
Upload date	May 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mtingers/dflockd-client-py
Publishing commit: github.com/mtingers/dflockd-client-py/tree/2ef31b3f968ad03dc051559f1101789f74ef72dd

Workflow

Publishing configuration: github.com/mtingers/dflockd-client-py/blob/2ef31b3f968ad03dc051559f1101789f74ef72dd/.github/workflows/publish.yml
Publishing logs: github.com/mtingers/dflockd-client-py/actions/runs/25647809659/attempts/2

Artifact

Subject: dflockd_client-2.1.1.tar.gz
SHA-256 checksum: 7dd0f224d238725c51df8e92a3ac33f4512e4c57d28938859ab24a7162ac417d Verifying attestations

Release files / dflockd_client-2.1.1-py3-none-any.whl

Download URL	dflockd_client-2.1.1-py3-none-any.whl
Size	21.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`34079bd532f6cc34f289809838358730e088246ce1853c50225bb11e72b67632`
BLAKE2b-256 checksum How to use checksums	`dc982ddccf2ded4d7daaddd49fd0fd0d7a3bbe1c3edcfb5c3d17549938ee15d1`
Upload date	May 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mtingers/dflockd-client-py
Publishing commit: github.com/mtingers/dflockd-client-py/tree/2ef31b3f968ad03dc051559f1101789f74ef72dd

Workflow

Publishing configuration: github.com/mtingers/dflockd-client-py/blob/2ef31b3f968ad03dc051559f1101789f74ef72dd/.github/workflows/publish.yml
Publishing logs: github.com/mtingers/dflockd-client-py/actions/runs/25647809659/attempts/2

Artifact

Subject: dflockd_client-2.1.1-py3-none-any.whl
SHA-256 checksum: 34079bd532f6cc34f289809838358730e088246ce1853c50225bb11e72b67632 Verifying attestations