Vine: Python Promises

5.1.0 verified Tue May 12 auth: no python install: verified quickstart: verified

Vine is a lightweight Python library that implements 'promises' for managing future evaluations and lazy computations, particularly useful in asynchronous and event-driven programming paradigms. It enhances flexibility by allowing nested promises within callbacks and error handlers. As of version 5.1.0, it is actively maintained by the Celery project.

pip install vine

Common errors

error ModuleNotFoundError: No module named 'vine' ↓

cause The `vine` library has not been installed in the current Python environment.

fix

Install the library using pip: pip install vine

error AttributeError: 'Promise' object has no attribute 'result' ↓

cause The `vine.Promise` object does not expose a `.result` attribute for direct access to its resolved value; values are retrieved via `get()` or callbacks.

fix

Use the promise.get() method to retrieve the result of a resolved promise (this blocks), or provide callbacks to promise.then() for asynchronous handling.

error TypeError: 'str' object is not callable ↓

cause The `then` method was called with a non-callable object (e.g., a string, integer, or `None`) for its `callback` or `errback` argument, where a function was expected.

fix

Provide a callable function (e.g., a lambda or a defined function) as the callback or errback argument to then().

error RuntimeWarning: Promise already resolved. ↓

cause The `resolve()` or `reject()` method was called on a `vine.Promise` object that has already been resolved or rejected, indicating a logical error in promise management.

fix

Ensure that resolve() or reject() is called only once per vine.Promise instance, typically by managing state or ensuring resolution logic is not triggered multiple times.

Warnings

breaking Python 2.x and older Python 3 versions (3.4, 3.5, 3.6) are no longer supported. Version 5.0.0 dropped support for Python 2.x, 3.4, and 3.5. Version 5.1.0 further dropped Python 3.6, making Python 3.7+ the officially supported range for current releases. ↓

fix Upgrade your Python environment to 3.7 or newer to use `vine` version 5.x. Consider pinning `vine<5.0.0` if you require Python 2.x or older Python 3 versions.

breaking The `vine.five` module, which contained compatibility shims for Python 2/3, was removed in `vine` 5.0.0a1. Any code directly importing or relying on `vine.five` will break. ↓

fix Remove imports from `vine.five`. The library is now Python 3.7+ exclusive, so compatibility shims are no longer necessary.

gotcha Dependency conflicts can arise when `vine` is used as a transitive dependency by other libraries like Celery or Kombu. Upgrading `vine` independently may lead to issues such as `ModuleNotFoundError` (e.g., for `vine.five` in older setups) or other unexpected behaviors due to incompatible versions between `vine` and its consumers. ↓

fix If encountering issues after a `vine` upgrade, ensure that its primary consumers (e.g., Celery, Kombu) are also updated to their latest compatible versions. Re-installing the parent library (e.g., `pip install --upgrade celery kombu`) can often resolve implicit dependency conflicts by selecting a compatible `vine` version.

gotcha A generic `ValueError('Operation failed!')` indicates a functional failure during promise fulfillment. This is likely an application-level error rather than a direct dependency or environmental issue covered by other warnings. It may suggest a change in `vine`'s underlying behavior that affects how promises are handled or how specific operations within the promise logic might now fail under certain conditions. ↓

fix Investigate the specific code path that triggers the `ValueError('Operation failed!')`. This might involve debugging the promise fulfillment logic to understand the exact condition leading to the exception. If the error is not directly related to `vine`'s public API or its immediate dependencies, consider it an application-specific issue. If it surfaces after a `vine` upgrade, review `vine`'s release notes for subtle behavioral changes that could impact promise-related operations.

gotcha A generic 'ValueError('Operation failed!')' was observed, indicating a potential issue within the application logic or an unhandled exception during an operation. This error is too general to be linked to specific `vine` library issues without further context from a traceback. ↓

fix Examine the traceback (if available) to pinpoint the exact source of the ValueError. Review application code paths leading to the 'Operation failed!' message. Ensure all necessary inputs are valid and operations are correctly handled. If `vine` is involved, verify its usage patterns and data inputs are correct according to its API documentation.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.02s 17.8M

3.10 alpine (musl) - - 0.02s 17.8M

3.10 slim (glibc) wheel 1.4s 0.01s 18M

3.10 slim (glibc) - - 0.01s 18M

3.11 alpine (musl) wheel - 0.04s 19.7M

3.11 alpine (musl) - - 0.04s 19.7M

3.11 slim (glibc) wheel 1.7s 0.03s 20M

3.11 slim (glibc) - - 0.05s 20M

3.12 alpine (musl) wheel - 0.04s 11.6M

3.12 alpine (musl) - - 0.04s 11.6M

3.12 slim (glibc) wheel 1.5s 0.04s 12M

3.12 slim (glibc) - - 0.04s 12M

3.13 alpine (musl) wheel - 0.05s 11.3M

3.13 alpine (musl) - - 0.04s 11.2M

3.13 slim (glibc) wheel 1.5s 0.04s 12M

3.13 slim (glibc) - - 0.03s 12M

3.9 alpine (musl) wheel - 0.02s 17.3M

3.9 alpine (musl) - - 0.02s 17.3M

3.9 slim (glibc) wheel 1.7s 0.01s 18M

3.9 slim (glibc) - - 0.01s 18M

Imports

promise
```
from vine import promise
```
The core class for creating and managing promises.
wrap
```
from vine import wrap
```
A utility function to wrap functions, especially when chaining promises.

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates how to create a promise, attach success and error handlers using `.then()` and `on_error`, and then fulfill the promise with a value or an exception.

from vine import promise

# Create a promise instance
p = promise()

# Attach a callback for successful completion
def on_success(result):
    print(f"Promise fulfilled with: {result}")

p.then(on_success)

# Attach an error handler for failures
def on_error(exc):
    print(f"Promise failed with error: {exc!r}")

p.on_error = on_error

# Fulfill the promise with a value
print("Fulfilling promise with 100...")
p(100)
# Expected output: Promise fulfilled with: 100

# Create another promise to demonstrate error
p_error = promise()
p_error.then(on_success) # Attach same success handler
p_error.on_error = on_error # Attach same error handler

# Fulfill the promise with an error
print("\nFulfilling promise with an exception...")
p_error.throw(ValueError("Operation failed!"))
# Expected output: Promise failed with error: ValueError('Operation failed!')