Merge pull request #13 from compas-dev/simpler-api

Simplify API and add more examples

Author: gonzalocasas

CHANGELOG.md

@@ -13,6 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Fix/add json serialization support to `Message` class.
 * Fix get/set attr/item recursion bug. 
+* Simplify API: 
+  * Default to `Message` class if no message type is specified.
+  * Allow to use a string with the topic name in place of an instance of `Topic`.
+  * Added an `EchoSubscriber` to showcase basic usage.
 
 ### Removed
 

README.md

@@ -1,92 +1,90 @@
-# compas_eve
+# COMPAS EVE
 
-COMPAS Event Extensions: adds event-based communication infrastructure to the COMPAS framework.
+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}"))
+```
 
-## Getting started with this project
+It is extremely easy to send messages around. COMPAS EVE supports
+different transport mechanisms to send messages between different threads, processes, computers, etc.
 
-### Setup code editor
+## Installation
 
-1. Open project folder in VS Code
-2. Select python environment for the project
-3. First time using VS Code and on Windows? Make sure select the correct terminal profile: `Ctrl+Shift+P`, `Terminal: Select Default Profile` and select `Command Prompt`.
+Install using `pip`:
 
-> All terminal commands in the following sections can be run from the VS Code integrated terminal. 
+```bash
 
+    pip install compas_eve
+```
 
-### First steps with git
+Or using `conda`:
 
-1. Go to the `Source control` tab
-2. Make an initial commit with all newly created files
+```bash
 
+    conda install compas_eve
+```
 
-### First steps with code
+## Supported features
 
-1. Install the newly created project 
+* Publisher/subscriber communication model (N-to-N communication)
+* In-process events
+* MQTT support
+* CPython & IronPython support
 
-        pip install -e .
+## Examples
 
-2. Install it on Rhino
+### In-process events
 
-        python -m compas_rhino.install
+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
 
-### Code conventions
+pub = eve.Publisher("/hello_world")
+sub = eve.EchoSubscriber("/hello_world")
+sub.subscribe()
 
-Code convention follows [PEP8](https://pep8.org/) style guidelines and line length of 120 characters.
+for i in range(10):
+    pub.publish(dict(text=f"Hello World {i}"))
+```
 
-1. Check adherence to style guidelines
+### MQTT
 
-        invoke lint
+MQTT is a protocol that allows to send messages between different
+systems/computers. Using MQTT is very simple as well:
 
-2. Format code automatically
+```python
+import compas_eve as eve
+from compas_eve.mqtt import MqttTransport
 
-        invoke format
+tx = MqttTransport("broker.hivemq.com")
+eve.set_default_transport(tx)
 
+pub = eve.Publisher("/hello_world")
+sub = eve.EchoSubscriber("/hello_world")
+sub.subscribe()
 
-### Documentation
+for i in range(10):
+    pub.publish(dict(text=f"Hello World {i}"))
+```
 
-Documentation is generated automatically out of docstrings and [RST](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) files in this repository
+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.
 
-1. Generate the docs
 
-        invoke docs
+### Usage from Rhinoceros 3D
 
-2. Check links in docs are valid
+It is possible to use the same code from within Rhino/Grasshopper.
 
-        invoke linkcheck
+Make sure you have installed it to Rhino using the COMPAS installation mechanism:
 
-3. Open docs in your browser (file explorer -> `dist/docs/index.html`)
-
-
-### Testing
-
-Tests are written using the [pytest](https://docs.pytest.org/) framework
-
-1. Run all tests from terminal
-
-        invoke test
-
-2. Or run them from VS Code from the `Testing` tab
-
-
-### Developing Grasshopper components
-
-We use [Grasshopper Componentizer](https://github.com/compas-dev/compas-actions.ghpython_components) to develop Python components that can be stored and edited on git.
-
-1. Build components
-
-        invoke build-ghuser-components
-
-2. Install components on Rhino
-
-        python -m compas_rhino.install
-
-
-### Publish release
-
-Releases follow the [semver](https://semver.org/spec/v2.0.0.html) versioning convention.
-
-1. Create a new release
-
-        invoke release major
+```bash
+    python -m compas_rhino.install -v 7.0
+```

docs/examples.rst

@@ -59,7 +59,7 @@ Hello Distributed World
 -----------------------
 
 Fortunately, it is very easy to extend our example and enable communication across processes, machines,
-networks, continents, anything that is connected to the Internet!
+networks, continents, and anything that is connected to the Internet!
 
 The only difference is that we are going to configure a different :class:`Transport` implementation for
 our messages. In this case, we will use the MQTT transport method. `MQTT <https://en.wikipedia.org/wiki/MQTT>`_
@@ -85,3 +85,16 @@ or even completely different computers and they will be able to communicate!
 And since pub/sub allows any number of publishers and any number of
 subscriber per topic, you can start the same scripts more than once and the
 messages will be received and send multiple times!
+
+Add typing information to messages
+----------------------------------
+
+So far, we have defined our messages as simple dictionaries.
+It is also possible to define a class that messages need to comform to,
+in order to get typing information on the messages.
+
+.. literalinclude :: examples/04_message_type.py
+   :language: python
+
+This example also shows how to set a default transport so that it does
+not need to be specified on every publisher and subscriber instance.

docs/examples/01_hello_world.py

@@ -1,19 +1,18 @@
 import time
 
-from compas_eve import Message
 from compas_eve import Publisher
 from compas_eve import Subscriber
 from compas_eve import Topic
 
 
-topic = Topic("/compas_eve/hello_world/", Message)
+topic = Topic("/compas_eve/hello_world/")
 
 publisher = Publisher(topic)
-subcriber = Subscriber(topic, callback=lambda msg: print(f"Received message: {msg.text}"))
+subcriber = Subscriber(topic, callback=lambda msg: print(f"Received message: {msg}"))
 subcriber.subscribe()
 
 for i in range(20):
-    msg = Message(text=f"Hello world #{i}")
-    print(f"Publishing message: {msg.text}")
+    msg = dict(text=f"Hello world #{i}")
+    print(f"Publishing message: {msg}")
     publisher.publish(msg)
     time.sleep(1)

docs/examples/02_hello_threaded_world.py

@@ -1,26 +1,25 @@
 import time
 from threading import Thread
 
-from compas_eve import Message
 from compas_eve import Publisher
 from compas_eve import Subscriber
 from compas_eve import Topic
 
-topic = Topic("/compas_eve/hello_world/", Message)
+topic = Topic("/compas_eve/hello_world/")
 
 
 def start_publisher():
     publisher = Publisher(topic)
 
     for i in range(20):
-        msg = Message(text=f"Hello world #{i}")
-        print(f"Publishing message: {msg.text}")
+        msg = dict(text=f"Hello world #{i}")
+        print(f"Publishing message: {msg}")
         publisher.publish(msg)
         time.sleep(1)
 
 
 def start_subscriber():
-    subcriber = Subscriber(topic, callback=lambda msg: print(f"Received message: {msg.text}"))
+    subcriber = Subscriber(topic, callback=lambda msg: print(f"Received message: {msg}"))
     subcriber.subscribe()
 
 

docs/examples/03_hello_distributed_world_pub.py

@@ -1,17 +1,16 @@
 import time
 
-from compas_eve import Message
 from compas_eve import Publisher
 from compas_eve import Topic
 from compas_eve.mqtt import MqttTransport
 
-topic = Topic("/compas_eve/hello_world/", Message)
+topic = Topic("/compas_eve/hello_world/")
 tx = MqttTransport("broker.hivemq.com")
 
 publisher = Publisher(topic, transport=tx)
 
 for i in range(20):
-    msg = Message(text=f"Hello world #{i}")
-    print(f"Publishing message: {msg.text}")
+    msg = dict(text=f"Hello world #{i}")
+    print(f"Publishing message: {msg}")
     publisher.publish(msg)
     time.sleep(1)

docs/examples/03_hello_distributed_world_sub.py

@@ -1,14 +1,13 @@
 import time
 
-from compas_eve import Message
 from compas_eve import Subscriber
 from compas_eve import Topic
 from compas_eve.mqtt import MqttTransport
 
-topic = Topic("/compas_eve/hello_world/", Message)
+topic = Topic("/compas_eve/hello_world/")
 tx = MqttTransport("broker.hivemq.com")
 
-subcriber = Subscriber(topic, callback=lambda msg: print(f"Received message: {msg.text}"), transport=tx)
+subcriber = Subscriber(topic, callback=lambda msg: print(f"Received message: {msg}"), transport=tx)
 subcriber.subscribe()
 
 print("Waiting for messages, press CTRL+C to cancel")

docs/examples/04_message_type.py

@@ -0,0 +1,28 @@
+import compas_eve as eve
+
+
+# Create a custom message type
+class CustomMessage(eve.Message):
+    def __init__(self, value=None):
+        super(CustomMessage, self).__init__()
+        self["value"] = value
+
+
+# Define a default transport using MQTT
+from compas_eve.mqtt import MqttTransport
+
+tx = MqttTransport("broker.hivemq.com")
+eve.set_default_transport(tx)
+
+# Create publisher and subscriber (using the EchoSubscriber for simplicity)
+topic = eve.Topic("/hello_world/", message_type=CustomMessage)
+pub = eve.Publisher(topic)
+sub = eve.EchoSubscriber(topic)
+sub.subscribe()
+
+# Starting publishing messages
+import time
+
+for i in range(10):
+    pub.publish(CustomMessage(i))
+    time.sleep(1)

docs/index.rst

@@ -6,11 +6,22 @@ Event Extensions for COMPAS
 
 ``compas_eve`` adds event-based communication infrastructure to the COMPAS framework.
 
+Using events is a way to decouple the components of a system, making it easier to develop, test, and maintain.
+
 .. figure:: /_images/pubsub.png
   :figclass: figure
   :class: figure-img img-fluid
 
 
+.. code-block:: 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}"))
+
 Table of Contents
 =================
 

src/compas_eve/__init__.py

@@ -17,6 +17,7 @@
     Topic
     Publisher
     Subscriber
+    EchoSubscriber
     Transport
     InMemoryTransport
     get_default_transport
@@ -36,7 +37,16 @@
 __version__ = "0.4.0"
 
 from .event_emitter import EventEmitterMixin  # noqa: F401 needed here to avoid circular import on py2.7
-from .core import Message, Publisher, Subscriber, Transport, Topic, get_default_transport, set_default_transport
+from .core import (
+    Message,
+    Publisher,
+    Subscriber,
+    EchoSubscriber,
+    Transport,
+    Topic,
+    get_default_transport,
+    set_default_transport,
+)
 from .memory import InMemoryTransport
 
 HERE = os.path.dirname(__file__)
@@ -49,6 +59,7 @@
     "Message",
     "Publisher",
     "Subscriber",
+    "EchoSubscriber",
     "Topic",
     "Transport",
     "get_default_transport",