Skip to main content

py-better-result

A small Python port of the Rust retry-result crate, with an immutable Result[T, E] implementation shaped after Rust's std::result::Result.

from better_result import Err, Ok, RetryPolicy, retry

attempts = 0


def request() -> Ok[str] | Err[str]:
    global attempts
    attempts += 1
    return Err("temporary") if attempts < 2 else Ok("done")


result = retry(request, RetryPolicy.fixed(2, 0))
assert result == Ok("done")

Result

Ok(value) and Err(error) are immutable result variants. The supported operations follow Rust's Result API:

  • inspection: is_ok, is_err, is_ok_and, is_err_and, ok, err
  • mapping: map, map_or, map_or_else, map_err
  • composition: and_, and_then, or_, or_else
  • observation: inspect, inspect_err
  • extraction: unwrap, expect, unwrap_err, expect_err, unwrap_or, unwrap_or_else, unwrap_or_default
  • nesting: flatten, transpose

Python uses and_ and or_ because and and or are reserved keywords. unwrap-style failures raise UnwrapError; callback exceptions are not silently converted to Err values.

Retry

Retry operates on Result-returning operations. It does not catch Python exceptions; expected failures must be returned as Err, matching the Rust crate's behavior.

from better_result import Err, Ok, RetryPolicy, retry

policy = RetryPolicy.exponential(3, 0.01, 2)
attempts = 0


def operation() -> Ok[str] | Err[str]:
    global attempts
    attempts += 1
    return Err("temporary") if attempts < 3 else Ok("response")


result = retry(operation, policy)
assert result == Ok("response")

Available schedules are FixedBackoff, LinearBackoff, ExponentialBackoff, and Jittered. Custom schedules implement decide(RetryContext) -> RetryDecision; custom predicates implement should_retry(RetryContext) -> bool.

Retry delays are finite, non-negative floating-point seconds, representing Rust's Duration. Invalid exponential multipliers and jitter factors raise InvalidBackoffMultiplier and InvalidJitterFactor, respectively.

retry_async provides the same behavior for awaitable operations. Normal asyncio task cancellation cancels an in-flight operation or retry delay.

Examples

The examples mirror the Rust workspace:

uv run better-result-example basic
uv run better-result-example sync-retry
uv run better-result-example async-retry
uv run better-result-example --all

Development

uv sync --all-packages
uv run pytest
uv run pytest --cov
uv run ruff check .
uv run ty check

Metadata

Release files for py-better-result 2.0.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 py-better-result 2.0.0
File Size Uploaded Provenance Actions
py_better_result-2.0.0.tar.gz 5.4 kB Without provenance Details for py_better_result-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for py-better-result 2.0.0
File Interpreter ABI Platform Actions
py_better_result-2.0.0-py3-none-any.whl Python 3 none any Details for py_better_result-2.0.0-py3-none-any.whl

Total release size: 12.2 kB

Release files / py_better_result-2.0.0.tar.gz

Download URL py_better_result-2.0.0.tar.gz
Size 5.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f6be20d32bee366cf5d9b42c582eb05ecbf186229ab933ebcce0150f43926a54
BLAKE2b-256 checksum
How to use checksums
bc2d1223d7496f2970b44e50f94cc4dbfab7083251840d9931b7761edce353c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / py_better_result-2.0.0-py3-none-any.whl

Download URL py_better_result-2.0.0-py3-none-any.whl
Size 6.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
81b22b990625327c050d9f447eed6f0809a7158d1752ab9dd1f66a4beb446452
BLAKE2b-256 checksum
How to use checksums
fc6fcaccb66bc012b2bf5f469412379a0f68585ae73f960a6983bef3e9c53cc9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for py-better-result 2.0.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

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