Rewrite Basic's docs to cover the CLI

README.md

@@ -42,6 +42,7 @@ seamless by providing Publisher, Subscriber and Worker classes with the followin
 * Intuitive Subscription Management
 * Easily Extensible Middleware
 * Optional Django or Flask Integration
+* CLI
 * And much more!
 
 ## What it looks like

docs/api/settings.rst

@@ -96,6 +96,7 @@ The application name.
 This should be unique to all the services running in the application ecosystem. It is used by
 the LoggingMiddleware and Prometheus integration.
 
+.. _settings_encoder_path:
 
 ``ENCODER_PATH``
 ------------------

docs/guides/basics.rst

@@ -22,8 +22,7 @@ To configure Relé, our settings may look something like:
 
 .. code:: python
 
-    # settings.py
-    import rele
+    # /settings.py
     from google.oauth2 import service_account
 
     RELE = {
@@ -32,15 +31,15 @@ To configure Relé, our settings may look something like:
         ),
         'GC_PROJECT_ID': 'photo-uploading-app',
     }
-    config = rele.config.setup(RELE)
 
 .. code:: python
 
-    # publisher.py
+    # /publisher.py
 
     import rele
-    from settings import config  # we need this for initializing the global Publisher singleton
+    import settings # we need this for initializing the global Publisher singleton
 
+    config = rele.config.setup(settings.RELE)
     data = {
         'customer_id': 123,
         'location': '/google-bucket/photos/123.jpg'
@@ -51,7 +50,7 @@ To configure Relé, our settings may look something like:
 To publish data, we simply pass in the topic to which we want our data to be published to, followed by
 a valid json serializable Python object.
 
-.. note:: If you want to publish other types of objects, you may configure the encoder class.
+.. note:: If you want to publish other types of objects, you may configure a custom :ref:`settings_encoder_path`.
 
 If you need to pass in additional attributes to the Message object, you can simply add ``kwargs``.
 These must all be strings:
@@ -71,11 +70,11 @@ Subscribing
 ___________
 
 Once we can publish to a topic, we can subscribe to the topic from a worker instance.
-In an app directory, we create our sub function within our subs.py file.
+In an app directory, we create our sub function within our ``subs.py`` file.
 
 .. code:: python
 
-    # subs.py
+    # /app/subs.py
 
     from rele import sub
 
@@ -85,7 +84,7 @@ In an app directory, we create our sub function within our subs.py file.
                 and we stored it at {data['location'}.")
 
 Additionally, if you added message attributes to your Message, you can access them via the
-`kwargs` argument:
+``kwargs`` argument:
 
 .. code:: python
 
@@ -101,8 +100,8 @@ Message attributes
 ------------------
 
 It might be helpful to access particular message attributes in your
-subscriber. One attribute that _rele_ adds by default is `published_at`.
-To access this attribute you can use `kwargs` keyword.
+subscriber. One attribute that _rele_ adds by default is ``published_at``.
+To access this attribute you can use ``kwargs``.
 
 .. code:: python
 
@@ -117,28 +116,17 @@ To access this attribute you can use `kwargs` keyword.
 Consuming
 _________
 
-Once the sub is implemented, we can start our worker which will register the subscriber with Google Cloud
-and will begin to pull the messages from the topic.
-
-.. code:: python
-
-    # worker.py
+Once the sub is implemented, we can start our worker which will register the subscriber on the topic
+with Google Cloud and will begin to pull the messages from the topic.
 
-    from time import sleep
-    from rele import Worker
+.. code:: bash
 
-    from settings import config
-    from subs import photo_uploaded
+    rele-cli run
 
-    if __name__ == '__main__':
-        worker = Worker(
-            [photo_uploaded],
-            config.gc_project_id,
-            config.credentials,
-            config.ack_deadline,
-        )
-        worker.run_forever()
+.. note:: Autodiscovery of subscribers with ``rele-cli`` follows a strict directory structure.
 
-Once the sub and worker are created, we can start our worker by running ``python worker.py``.
+    | ├──settings.py
+    | ├──app # This can be called whatever you like
+    | ├────subs.py
 
-In another, terminal session when we run ``python publisher.py`` we should see the print readout in our subscriber.
+In another terminal session when we run ``python publisher.py``, we should see the print readout in our subscriber.

rele/config.py

@@ -25,8 +25,8 @@ def __init__(self, setting):
         ):
             credentials, project = get_google_defaults()
 
-        self.gc_project_id = setting.get("GC_PROJECT_ID") or project
         self.credentials = setting.get("GC_CREDENTIALS") or credentials
+        self.gc_project_id = setting.get("GC_PROJECT_ID") or project
         self.app_name = setting.get("APP_NAME")
         self.sub_prefix = setting.get("SUB_PREFIX")
         self.middleware = setting.get("MIDDLEWARE", default_middleware)

rele/discover.py

@@ -42,5 +42,5 @@ def sub_modules():
         if is_package and module_has_submodule(package, "subs"):
             module = package + ".subs"
             module_paths.append(module)
-            logger.debug(" * Discovered subs module: %r" % module)
+            logger.info(" * Discovered subs module: %r" % module)
     return settings, module_paths

rele/subscription.py

@@ -2,7 +2,6 @@
 import logging
 import time
 
-import rele
 from .middleware import run_middleware_hook
 
 logger = logging.getLogger(__name__)

tests/test_publishing.py

@@ -1,8 +1,18 @@
 from unittest.mock import MagicMock, patch
 
+import pytest
+
 from rele import Publisher, publishing
 
 
+class TestPublish:
+    def test_raises_when_global_publisher_does_not_exist(self):
+        message = {"foo": "bar"}
+
+        with pytest.raises(ValueError):
+            publishing.publish(topic="order-cancelled", data=message, myattr="hello")
+
+
 class TestInitGlobalPublisher:
     @patch("rele.publishing.Publisher", autospec=True)
     def test_creates_global_publisher_when_published_called(