0
# Vine
1

2
A specialized Python promises library that provides both promise-based asynchronous operations and lazy evaluation. Unlike traditional promise implementations, vine allows everything within a promise to also be a promise, including filters, callbacks, and errbacks, creating a highly composable and flexible system.
3

4
## Package Information
5

6
- **Package Name**: vine
7
- **Language**: Python
8
- **Installation**: `pip install vine`
9

10
## Core Imports
11

12
```python
13
import vine
14
```
15

16
For individual components:
17

18
```python
19
from vine import promise, barrier, Thenable, maybe_promise, ensure_promise
20
from vine import ppartial, preplace, starpromise, transform, wrap
21
```
22

23
## Basic Usage
24

25
```python
26
from vine import promise
27

28
# Create a basic promise
29
p = promise()
30

31
# Chain operations using then()
32
p.then(lambda result: print(f"Got: {result}"))
33

34
# Fulfill the promise with a value
35
p(42)  # Prints: Got: 42
36

37
# Create promise with function and arguments
38
compute_promise = promise(lambda x, y: x + y, args=(10, 20))
39
compute_promise.then(lambda result: print(f"Sum: {result}"))
40
compute_promise()  # Prints: Sum: 30
41

42
# Chain multiple promises
43
p1 = promise(lambda x: x * 2)
44
p2 = promise(lambda x: x + 10)
45
p3 = p1.then(p2)
46

47
p1(5)  # Triggers chain: 5 * 2 = 10, then 10 + 10 = 20
48
```
49

50
## Architecture
51

52
Vine's architecture centers around the Thenable abstract base class and specialized implementations:
53

54
- **Thenable**: Abstract base class defining the `.then()`, `.throw()`, and `.cancel()` interface
55
- **promise**: Main promise implementation supporting both value promises and lazy evaluation
56
- **barrier**: Synchronization primitive for waiting on multiple promises
57
- **Functional utilities**: Helper functions for promise composition and manipulation
58

59
This design enables everything within a promise to also be a promise, allowing for complex asynchronous workflows and lazy computation patterns.
60

61
## Capabilities
62

63
### Core Promise Operations
64

65
Main promise class providing asynchronous operations and lazy evaluation with full promise chaining support.
66

67
```python { .api }
68
class promise:
69
    def __init__(self, fun=None, args=None, kwargs=None, callback=None, on_error=None, weak=False, ignore_result=False): ...
70
    def __call__(self, *args, **kwargs): ...
71
    def then(self, callback, on_error=None): ...
72
    def throw(self, exc=None, tb=None, propagate=True): ...
73
    def cancel(self): ...
74
    
75
    @property
76
    def ready(self) -> bool: ...
77
    @property 
78
    def failed(self) -> bool: ...
79
    @property
80
    def cancelled(self) -> bool: ...
81
    @property
82
    def value(self): ...
83
    @property
84
    def reason(self): ...
85
```
86

87
[Promise Operations](./promises.md)
88

89
### Promise Synchronization
90

91
Synchronization primitive for coordinating multiple promises and waiting for all to complete.
92

93
```python { .api }
94
class barrier:
95
    def __init__(self, promises=None, args=None, kwargs=None, callback=None, size=None): ...
96
    def __call__(self, *args, **kwargs): ...
97
    def add(self, promise): ...
98
    def finalize(self): ...
99
    def then(self, callback, errback=None): ...
100
    def cancel(self): ...
101
    
102
    @property
103
    def ready(self) -> bool: ...
104
    @property
105
    def finalized(self) -> bool: ...
106
    @property
107
    def size(self) -> int: ...
108
```
109

110
[Synchronization](./synchronization.md)
111

112
### Promise Utilities
113

114
Functional utilities for promise creation, modification, and composition.
115

116
```python { .api }
117
def maybe_promise(p): ...
118
def ensure_promise(p): ...
119
def ppartial(p, *args, **kwargs): ...
120
def preplace(p, *args, **kwargs): ...
121
def starpromise(fun, *args, **kwargs): ...
122
def transform(filter_, callback, *filter_args, **filter_kwargs): ...
123
def wrap(p): ...
124
```
125

126
[Utilities](./utilities.md)
127

128
### Abstract Base Classes
129

130
Core abstract classes and proxy objects for creating thenable objects.
131

132
```python { .api }
133
class Thenable:
134
    def then(self, on_success, on_error=None): ...
135
    def throw(self, exc=None, tb=None, propagate=True): ...
136
    def cancel(self): ...
137

138
class ThenableProxy:
139
    def _set_promise_target(self, p): ...
140
    def then(self, on_success, on_error=None): ...
141
    def cancel(self): ...
142
```
143

144
[Abstract Classes](./abstract.md)
145

146
## Types
147

148
```python { .api }
149
# Core types used throughout vine
150
from typing import Callable, Tuple, Any, Optional
151
from collections.abc import Callable
152

153
# Promise callback function types
154
PromiseCallback = Callable[..., Any]
155
ErrorCallback = Callable[[Exception], Any]
156

157
# Promise value type - stored as (args, kwargs) tuple
158
PromiseValue = Tuple[Tuple[Any, ...], dict]
159
```