Install & Compatibility
Where this runs
tested against v1.3.0.post0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.088s · 18.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.076s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
capture
✓ from outcome import capture
acapture
✓ from outcome import acapture
Outcome
✓ from outcome import Outcome
Value
✓ from outcome import Value
Error
✓ from outcome import Error
AlreadyUsedError
✓ from outcome import AlreadyUsedError
This exception is raised if an Outcome object is unwrapped more than once.
This quickstart demonstrates how to use `outcome.capture` for synchronous functions and `outcome.acapture` for asynchronous functions, handling both successful returns and raised exceptions. It also illustrates the `AlreadyUsedError` which is raised if an `Outcome` object's value or error is attempted to be accessed more than once.
import outcome
import asyncio
def successful_function():
return "Success!"
def failing_function():
raise ValueError("Something went wrong!")
async def async_successful_function():
await asyncio.sleep(0.01)
return "Async Success!"
async def async_failing_function():
await asyncio.sleep(0.01)
raise RuntimeError("Async operation failed!
")
# Example 1: Synchronous capture
sync_success_outcome = outcome.capture(successful_function)
print(f"Sync Success: {sync_success_outcome.unwrap()}")
sync_failure_outcome = outcome.capture(failing_function)
try:
sync_failure_outcome.unwrap()
except ValueError as e:
print(f"Sync Failure caught: {e}")
# Example 2: Asynchronous capture
async def main():
async_success_outcome = await outcome.acapture(async_successful_function)
print(f"Async Success: {async_success_outcome.unwrap()}")
async_failure_outcome = await outcome.acapture(async_failing_function)
try:
async_failure_outcome.unwrap()
except RuntimeError as e:
print(f"Async Failure caught: {e}")
# Demonstrating AlreadyUsedError (Outcome objects can only be unwrapped once)
try:
print(sync_success_outcome.unwrap())
except outcome.AlreadyUsedError as e:
print(f"Caught expected error: {e}")
asyncio.run(main())
Debug
Known issues
gotchaAn `Outcome` object can only be unwrapped (accessed via `.unwrap()` or `.error()`/`.value()`) once. Subsequent attempts to unwrap or access its contents will raise an `outcome.AlreadyUsedError`.fixStore the result of `outcome.unwrap()` if you need to use the value multiple times, or ensure `Outcome` objects are only unwrapped a single time within your logic.
affects: All versions
gotchaThe `outcome` library provides `Value` and `Error` classes, which are not exceptions themselves. Do not attempt to catch `outcome.Error` or `outcome.Value` directly using `try...except`. Instead, use `outcome_obj.is_error()` or `outcome_obj.is_value()` to check the type of outcome, and then `unwrap()` within a `try...except` block if you expect exceptions, or `error()`/`value()` to access the content.fixRefactor error handling to check `is_error()`/`is_value()` methods on the `Outcome` object before attempting to unwrap, or wrap the `unwrap()` call in a standard Python `try...except` block for the actual exceptions your captured function might raise.
affects: All versions
gotchaAs of version 1.3.0, the exception frame generated within `capture()` and `acapture()` has been removed from the traceback on Python 3. This can make debugging slightly different as the `outcome` internal frames will no longer appear in the stack trace.fixBe aware of this change when inspecting tracebacks. The original exception will still be present, but the path through `outcome`'s internal capturing logic will be omitted.
affects: >=1.3.0
gotchaA SyntaxError: EOL while scanning string literal indicates an unclosed string literal, often due to a missing closing quote or improper multiline string definition. This is a basic Python syntax error and not related to library-specific runtime issues.fixExamine the specified line in the Python script for unclosed string literals. Ensure all string literals have matching opening and closing quotes (single, double, or triple) and are correctly formatted for multiline strings.
affects: All versions
gotchaThe provided script contains a `SyntaxError: unterminated string literal`. This error occurs when a string literal is not properly closed with a matching quote, leading to a parsing error before the code can even execute.fixReview the script for missing closing quotes or other syntax errors, specifically at `/script.py`, line 16, and ensure all string literals are correctly terminated.
affects: All Python versions
Errors
Common errors & fixes
outcome.AlreadyUsedError
An `Outcome` object's `unwrap()` method can only be called once to retrieve its result or re-raise its exception; subsequent calls will raise `AlreadyUsedError`.
fixStore the result of the first `unwrap()` call in a variable, or use the `outcome.Executor` context manager for automatic handling of used outcomes.
AttributeError: 'Outcome' object has no attribute 'value'
This occurs when attempting to access a direct 'value' attribute on an `Outcome` object that holds an exception (an error outcome), rather than a successful result.
fixBefore accessing the value, check if the `Outcome` represents a successful result using `result.is_ok()`. If true, use `result.unwrap()` to safely retrieve the value.
AttributeError: 'Outcome' object has no attribute 'exception'
This occurs when attempting to access a direct 'exception' attribute on an `Outcome` object that holds a successful result, rather than an exception (an error outcome).
fixBefore accessing the exception, check if the `Outcome` represents an error using `result.is_error()`. If true, use `result.unwrap()` within a `try-except` block to catch the contained exception.
Upgrade
Version history
1.3.0.post0latest on PyPI · released Oct 26, 2023
Audit
Dependencies
pythonrequiredRequired runtime environment.