Metadata-Version: 2.4
Name: threading-value-event
Version: 0.1.0a0
Summary: A thread synchronization primitive for Python like `threading.Event`, but instead of just a boolean flag, it carries any Python value.
Author-email: Jifeng Wu <jifengwu2k@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jifengwu2k/threading-value-event
Project-URL: Bug Tracker, https://github.com/jifengwu2k/threading-value-event/issues
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=2
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing; python_version < "3.5"
Dynamic: license-file

# `ThreadingValueEvent`

A thread synchronization primitive for Python like `threading.Event`, but instead of just a
boolean flag, it carries any Python value. Threads can wait for a value to be set, retrieve it, and optionally reset the
event for reuse.

## Features

- Wait for an event to be set, optionally with a timeout.
- Pass any Python object (not just a boolean) from one thread to another.
- Ability to clear/reset the event.
- Intuitive, event-like API.

## Installation

```commandline
pip install threading-value-event
```

## Usage

```python
from __future__ import print_function
from threading_value_event import ThreadingValueEvent
import threading
import time

event = ThreadingValueEvent()


def worker():
    print('Worker waiting for value...')
    result = event.wait()
    print('Worker got:', result)


thread = threading.Thread(target=worker)
thread.start()

time.sleep(1)
print('Main thread setting value to 123.')
event.set(123)
thread.join()
```

**Output:**

```
Worker waiting for value...
Main thread setting value to 123.
Worker got: 123
```

## API

### `ThreadingValueEvent()`

Create a new event object.

### `set(value)`

Set the event, storing `value`. Wakes up all threads waiting for this event.

### `is_set()`

Return `True` if the event is set, else `False`.

### `wait(timeout=None, default=None)`

Block until the event is set, then return the value. If a timeout is provided and the event isn't set in time, returns
`default`.

### `clear()`

Clear the event and remove the stored value.

## Contributing

Contributions are welcome! Please submit pull requests or open issues on the GitHub repository.

## License

This project is licensed under the [<license> License](LICENSE).
