faultlib

faultlib is the Python interface to the Rust fault network fault-injection engine. It runs TCP and UDP proxies inside an asyncio application, applies ordered fault chains, and exposes typed progress, status, TCP-stream, and UDP-exchange records.

Use it when network degradation is one part of a larger Python experiment—for example, adding database latency while restarting a pod and observing service recovery. For shell-driven experiments, use the fault CLI.

Python is a thin binding: validation, phase lifecycle, scheduling decisions, events, and errors remain canonical Rust behavior. The package adds typed Python mappings and dataclasses, not a second fault model.

Requirements and installation

faultlib requires Python 3.14 or newer.

python -m pip install faultlib

Start a proxy

import asyncio

from faultlib import Engine, Run


RUN: Run = {
    "schema_version": 1,
    "name": "slow database",
    "proxies": [
        {
            "name": "database",
            "protocol": "tcp",
            "listen": "127.0.0.1:15432",
            "upstream": "database.internal:5432",
        }
    ],
    "phases": [
        {
            "name": "degraded for thirty seconds",
            "duration": "30s",
            "proxies": [
                {
                    "proxy": "database",
                    "faults": [
                        {
                            "type": "latency",
                            "flow": "both",
                            "distribution": {
                                "type": "normal",
                                "mean_ms": 200.0,
                                "stddev_ms": 20.0,
                            },
                        }
                    ],
                }
            ],
        }
    ],
}


async def main() -> None:
    async with Engine(RUN) as engine:
        print(f"proxy listening on {engine.endpoints.tcp[0]}")
        result = await engine.run()

    print(f"run outcome: {result.outcome.kind}")


asyncio.run(main())

Point the application at 127.0.0.1:15432 for the duration of the experiment. The proxy forwards the connection to database.internal:5432; no database protocol support is required.

Run and its nested TypedDict types give type checkers the same shape as the published schema. Runtime results and events are frozen dataclasses rather than unstructured dictionaries.

Observe traffic

Engine.next_event() returns a completed transport record when one is available and otherwise publishes periodic status:

from faultlib import StatusEvent, TcpStreamEvent, UdpExchangeEvent


async def observe(engine: Engine) -> None:
    while engine.alive():
        match event := await engine.next_event():
            case StatusEvent(status):
                print(
                    f"active={status.tcp.active} "
                    f"impacted={status.tcp.impacted}"
                )
            case TcpStreamEvent(stream):
                print(stream.stream_id, stream.outcome)
            case UdpExchangeEvent(exchange):
                print(exchange.exchange_id, exchange.outcome)
            case None:
                return

Record delivery is bounded and best effort. A slow Python consumer never stalls the Rust proxy. Aggregate status remains complete and reports omitted records through dropped_records.

Adapt a running experiment

engine.schedule() exposes Rust-owned phase controls to Python. You can add, modify, delete, start, or stop future phases while ordinary Python tasks coordinate the surrounding system. A phase becomes immutable once it starts; invalid mutations raise PhaseStateError.

The complete example in the repository demonstrates engine events, adaptive scheduling, and bounded record retention: examples/python_proxy.py.

Supported behavior

  • TCP: latency, jitter, bandwidth, blackhole, connection reset
  • UDP: latency, jitter, directional blackhole
  • DNS over UDP: delay, timeout, truncation, refusal, SERVFAIL, NXDOMAIN, empty answers, and random A records

See the guide for realistic failure scenarios and the generated field reference for the exact wire contract.

Local development

From a checkout of the repository:

uv sync --project fault-python --python 3.14 --reinstall-package faultlib
uv run --project fault-python --python 3.14 python examples/python_proxy.py
uv run --project fault-python --python 3.14 ruff check \
  fault-python/python examples

Repeat uv sync --reinstall-package faultlib after changing Rust binding code.

Licensed under the Apache License 2.0.

Project links

Data verified by PyPI on Aug 30, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Lawouach from gravatar.com Lawouach

GitHub Statistics

Data verified by PyPI on Aug 30, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.14

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

faultlib-1.0.0.tar.gz (67.0 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

faultlib-1.0.0-cp314-abi3-win_amd64.whl (613.0 kB view details)

Uploaded CPython 3.14+Windows x86-64

faultlib-1.0.0-cp314-abi3-manylinux_2_34_x86_64.whl (809.3 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.34+ x86-64

faultlib-1.0.0-cp314-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (1.4 MB view details)

Uploaded CPython 3.14+macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

File details

Details for the file faultlib-1.0.0.tar.gz.

File metadata

  • Download URL: faultlib-1.0.0.tar.gz
  • Upload date:
  • Size: 67.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for faultlib-1.0.0.tar.gz
Algorithm Hash digest
SHA256 201293b6feb6461d7a03a0a81e25a0224e4147da2ddc1bee0b12a74b4eeac7fb
MD5 3ff3329d8cec4c2fd301f6c921859cc3
BLAKE2b-256 627954615bc0b48cf5d822600748fe255abc3baba0f6e91ea7d8e68499d2083f

See more details on using hashes here.

Provenance

The following attestation bundles were made for faultlib-1.0.0.tar.gz:

Publisher: release.yaml on fault-project/fault

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file faultlib-1.0.0-cp314-abi3-win_amd64.whl.

File metadata

  • Download URL: faultlib-1.0.0-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 613.0 kB
  • Tags: CPython 3.14+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for faultlib-1.0.0-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e5a0bbaad98c7b3453d6cc938b0b487bce5cfa9cb943e6f78381e0c067547d16
MD5 103e80f329c3659ccddc78654709e1b3
BLAKE2b-256 3733a8fa0a0b38f7af64c847532c2b8e4d60ffb067c8d34441ee222a87fbd189

See more details on using hashes here.

Provenance

The following attestation bundles were made for faultlib-1.0.0-cp314-abi3-win_amd64.whl:

Publisher: release.yaml on fault-project/fault

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file faultlib-1.0.0-cp314-abi3-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for faultlib-1.0.0-cp314-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 b98b17f6898a126bdfd17f41bf478819ffa059f10622d651d7a4eeb84e066b66
MD5 cbbd779e2ec52d8ef9a9ac17569abf26
BLAKE2b-256 3acc3720013186481aea73111317aa56a3f9d04ec57ef42166d66706e554424b

See more details on using hashes here.

Provenance

The following attestation bundles were made for faultlib-1.0.0-cp314-abi3-manylinux_2_34_x86_64.whl:

Publisher: release.yaml on fault-project/fault

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file faultlib-1.0.0-cp314-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for faultlib-1.0.0-cp314-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 84f4ca35b94bc0041c505fb5a039702cf8474c03c86d52cc3f5e1b5201da542c
MD5 f3c3716298a0acb40f651ad01691dc97
BLAKE2b-256 f78e6dc53fe93f56ff50205f5b2a2cadda067f8f79a4e527040ef4bd52bd7779

See more details on using hashes here.

Provenance

The following attestation bundles were made for faultlib-1.0.0-cp314-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: release.yaml on fault-project/fault

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.0 This release

4 files

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