Metadata-Version: 2.4
Name: compas_eve
Version: 2.4.0
Summary: COMPAS Event Extensions: adds event-based communication infrastructure to the COMPAS framework.
Author-email: Gonzalo Casas <casas@arch.ethz.ch>, Chen Kasirer <kasirer@arch.ethz.ch>
License-Expression: MIT
Project-URL: Homepage, https://github.com/compas-dev/compas_eve
Project-URL: Documentation, https://compas.dev/compas_eve
Project-URL: Repository, https://github.com/compas-dev/compas_eve
Project-URL: Changelog, https://github.com/compas-dev/compas_eve/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/compas-dev/compas_eve/issues
Project-URL: Forum, https://forum.compas-framework.org/
Keywords: events,event-driven,compas,architecture,distributed systems
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: compas>=2.0
Requires-Dist: paho-mqtt<3,>=1
Provides-Extra: dev
Requires-Dist: attrs>=17.4; extra == "dev"
Requires-Dist: black>=22.12.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: bump-my-version; extra == "dev"
Requires-Dist: compas_invocations2[mkdocs]; extra == "dev"
Requires-Dist: compas_pb>=0.4.4; extra == "dev"
Requires-Dist: invoke>=0.14; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: pythonnet; extra == "dev"
Provides-Extra: ros
Requires-Dist: roslibpy<3,>=2; extra == "ros"
Provides-Extra: zenoh
Requires-Dist: eclipse-zenoh; extra == "zenoh"
Dynamic: license-file

# COMPAS EVE

[![Made with COMPAS](https://compas.dev/badge.svg)](https://compas.dev/mission-control/#compas_eve)
[![Github Actions Build Status](https://github.com/gramaziokohler/compas_eve/workflows/build/badge.svg)](https://github.com/gramaziokohler/compas_eve/actions)
[![License](https://img.shields.io/github/license/gramaziokohler/compas_eve.svg)](https://pypi.python.org/pypi/compas_eve)
[![pip downloads](https://img.shields.io/pypi/dm/compas_eve)](https://pypi.python.org/project/compas_eve)
[![PyPI Package latest release](https://img.shields.io/pypi/v/compas_eve.svg)](https://pypi.python.org/pypi/compas_eve)
[![Supported implementations](https://img.shields.io/pypi/implementation/compas_eve.svg)](https://pypi.python.org/pypi/compas_eve)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17955773.svg)](https://doi.org/10.5281/zenodo.17955773)
[![Twitter Follow](https://img.shields.io/twitter/follow/compas_dev?style=social)](https://twitter.com/compas_dev)

Event-based communication for the COMPAS framework.

```python
>>> import compas_eve as eve
>>> pub = eve.Publisher("/hello_world")
>>> sub = eve.EchoSubscriber("/hello_world")
>>> sub.subscribe()
>>> for i in range(10):
...    pub.publish(dict(text=f"Hello World {i}"))
```

It is extremely easy to send messages around. COMPAS EVE supports
different transport mechanisms to send messages between different threads, processes, computers, etc.

## Installation

Install using `pip`:

```bash

    pip install compas_eve
```

Or using `conda`:

```bash

    conda install compas_eve
```

## Supported features

* Publisher/subscriber communication model (N-to-N communication)
* In-process events
* MQTT support
* ROS support through rosbridge
* Zenoh support
* Extensible codec system for message serialization (JSON, Protocol Buffers)

## Examples

### In-process events

The simplest option is to use in-process events. This works for
simple applications and allows to communicate between threads.

```python
import compas_eve as eve

pub = eve.Publisher("/hello_world")
sub = eve.EchoSubscriber("/hello_world")
sub.subscribe()

for i in range(10):
    pub.publish(dict(text=f"Hello World {i}"))
```

### MQTT

MQTT is a protocol that allows to send messages between different
systems/computers. Using MQTT is very simple as well:

```python
import compas_eve as eve
from compas_eve.mqtt import MqttTransport

tx = MqttTransport("broker.hivemq.com")
eve.set_default_transport(tx)

pub = eve.Publisher("/hello_world")
sub = eve.EchoSubscriber("/hello_world")
sub.subscribe()

for i in range(10):
    pub.publish(dict(text=f"Hello World {i}"))
```

This example shows how to send and receive from a single script, but
running publishers and subscribers on different scripts, different processes, or even different computers will work the exact same way.

### ROS

The optional ROS backend uses native ROS message types through a rosbridge server:

```bash
pip install compas_eve[ros]
```

```python
import time

import compas_eve as eve
from compas_eve.ros import RosTransport

tx = RosTransport("localhost", 9090)
topic = eve.Topic("/chatter", "std_msgs/String", queue_size=10)

sub = eve.EchoSubscriber(topic, transport=tx)
sub.subscribe()
eve.Publisher(topic, transport=tx).publish({"data": "Hello ROS"})
time.sleep(1)
tx.close()
```

ROS messages are passed as JSON-compatible dictionaries. Topic options supported
by `roslibpy`—including `compression`, `latch`, `throttle_rate`, `queue_size`,
`queue_length`, and `reconnect_on_close`—can be set on `eve.Topic`.

### Zenoh

Apache Zenoh is a pub/sub/query protocol. In many ways, it is similar to MQTT but with some additional features and optimizations. COMPAS EVE also supports Zenoh as a transport protocol with an identical API to MQTT:

```python
import compas_eve as eve
from compas_eve.zenoh import ZenohTransport

tx = ZenohTransport()
eve.set_default_transport(tx)

pub = eve.Publisher("/hello_world")
sub = eve.EchoSubscriber("/hello_world")
sub.subscribe()

for i in range(10):
    pub.publish(dict(text=f"Hello World {i}"))
```

### Using different codecs

By default, COMPAS EVE uses JSON for message serialization. However, you can use different codecs for more efficient serialization:

```python
import compas_eve as eve
from compas_eve import JsonMessageCodec
from compas_eve.codecs import ProtobufMessageCodec
from compas_eve.mqtt import MqttTransport

# Use JSON codec (default)
json_codec = JsonMessageCodec()
tx = MqttTransport("broker.hivemq.com", codec=json_codec)

# Or use Protocol Buffers for binary serialization (requires compas_pb)
pb_codec = ProtobufMessageCodec()
tx = MqttTransport("broker.hivemq.com", codec=pb_codec)
```


### Usage from Rhinoceros 3D

It is possible to use the same code from within Rhino/Grasshopper.

To install `compas_eve`, use the the syntax `# r: compas_eve` at the top of any Python 3.x script in Rhino/Grasshopper.
