Deprecate the Platform API (Client interface) (#164)

Vestaboard has deprecated the Platform API, so our `Client` interface is
also considered deprecated. Switch to the `SubscriptionClient`, which
offers nearly identical functionality.

Also, revise the documentation for the other clients to match the order
used by Vestaboard's developer documentation.

CHANGELOG.md

@@ -9,6 +9,9 @@
 
 ### Changed
 - The `encode_*()` functions now consistently specify keyword-only arguments.
+- Vestaboard has deprecated the Platform API, so our `Client` interface is also
+  considered deprecated. Switch to `SubscriptionClient`, which offers nearly
+  identical functionality.
 
 ## 0.11.0 - 2024-01-22
 ### Added

README.md

@@ -21,63 +21,7 @@ installed automatically.
 
 ### API Clients
 
-#### `Client`
-
-The `Client` type is initialized with an API key and secret:
-
-```pycon
->>> import vesta
->>> client = vesta.Client(API_KEY, API_SECRET)
-```
-
-Then, you can make API calls using one of the provided methods:
-
-```pycon
->>> client.get_viewer()
-{'_id': ..., '_created': '1629081092624', 'type': 'installation', 'installation': {'_id': ...}}
-
->>> client.get_subscriptions()
-[{'_id': ..., '_created': '1629081092624', 'title': None, 'icon': None, 'installation': {'_id': ..., 'installable': {'_id': ...}}, 'boards': [{'_id': ...}]}]
-
->>> client.post_message(SUBSCRIPTION_ID, "Hello, World")
-{'message': {'id': ..., 'text': 'Hello, World', 'created': '1635801572442'}}
-```
-
-Messages can be posted as either text strings or two-dimensional arrays of
-character codes representing the exact positions of characters on the board.
-
-If text is specified, the lines will be centered horizontally and vertically.
-Character codes will be inferred for alphanumeric and punctuation characters,
-or they can be explicitly specified using curly braces containing the character
-code (such as `{5}` or `{65}`).
-
-#### `LocalClient`
-
-`LocalClient` provides a client interface for interacting with a Vestaboard
-over the local network using [Vestaboard's Local API](https://docs.vestaboard.com/docs/local-api/introduction).
-
-Note that Vestaboard owners must first request a
-[Local API enablement token](https://www.vestaboard.com/local-api)
-in order to use the Local API.
-
-```py
-import vesta
-local_client = vesta.LocalClient()
-
-# The Vestaboard's Local API must be enabled to get its Local API key. After
-# you've done this once, you can save the key somewhere safe and pass it
-# directly to LocalClient() for future client initializations.
-local_api_key = local_client.enable(ENABLEMENT_TOKEN)
-# e.g. local_client = LocalClient(local_api_key)
-assert local_client.enabled
-
-# Once enabled, you can write and read messages:
-message = vesta.encode_text("{67} Hello, World {68}")
-assert local_client.write_message(message)
-assert local_client.read_message() == message
-```
-
-#### `ReadWriteClient`
+#### Read / Write API
 
 `ReadWriteClient` provides a client interface for interacting with a Vestaboard
 using the [Read / Write API](https://docs.vestaboard.com/docs/read-write-api/introduction).
@@ -96,7 +40,7 @@ assert rw_client.write_message(message)
 assert rw_client.read_message() == message
 ```
 
-#### `SubscriptionClient`
+#### Subscription API
 
 `SubscriptionClient` provides a client interface for interacting with multiple
 Vestaboards using the [Subscription API](https://docs.vestaboard.com/docs/subscription-api/introduction).
@@ -115,7 +59,33 @@ for subscription in subscriptions:
     subscription_client.send_message(subscription["id"], "Hello World")
 ```
 
-#### `VBMLClient`
+#### Local API
+
+`LocalClient` provides a client interface for interacting with a Vestaboard
+over the local network using [Vestaboard's Local API](https://docs.vestaboard.com/docs/local-api/introduction).
+
+Note that Vestaboard owners must first request a
+[Local API enablement token](https://www.vestaboard.com/local-api)
+in order to use the Local API.
+
+```py
+import vesta
+local_client = vesta.LocalClient()
+
+# The Vestaboard's Local API must be enabled to get its Local API key. After
+# you've done this once, you can save the key somewhere safe and pass it
+# directly to LocalClient() for future client initializations.
+local_api_key = local_client.enable(ENABLEMENT_TOKEN)
+# e.g. local_client = LocalClient(local_api_key)
+assert local_client.enabled
+
+# Once enabled, you can write and read messages:
+message = vesta.encode_text("{67} Hello, World {68}")
+assert local_client.write_message(message)
+assert local_client.read_message() == message
+```
+
+#### VBML API
 
 `VBMLClient` provides a client interface for Vestaboard's [VBML (Vestaboard
 Markup Language)](https://docs.vestaboard.com/docs/vbml) API.
@@ -135,6 +105,26 @@ vbml_client = vesta.VBMLClient()
 vesta.pprint(vbml_client.compose([component]))
 ```
 
+#### Platform Client
+
+`Client` provides a client interface for interacting with the **deprecated**
+[Vestaboard Platform API](https://docs-v1.vestaboard.com/introduction).
+
+This is the original Vestaboard Platform API. It is **deprecated** and has been
+superseded by the other APIs listed above. In particular, Vestaboard encourages
+users of the Platform API to switch to the [Subscription API](#subscription-api),
+which offers nearly identical functionality.
+
+### Messages
+
+Messages can be posted as either text strings or two-dimensional arrays of
+character codes representing the exact positions of characters on the board.
+
+If text is specified, the lines will be centered horizontally and vertically.
+Character codes will be inferred for alphanumeric and punctuation characters,
+or they can be explicitly specified using curly braces containing the character
+code (such as `{5}` or `{65}`).
+
 ### Character Encoding
 
 All Vestaboard characters (letters, numbers, symbols, and colors) are encoded

docs/index.rst

@@ -26,29 +26,8 @@ installed automatically.
 API Clients
 ===========
 
-``Client``
-----------
-
-.. autoclass:: vesta.Client
-    :members:
-
-``LocalClient``
----------------
-
-:py:class:`vesta.LocalClient` provides a client interface for interacting with
-a Vestaboard over the local network using `Vestaboard's Local API
-<https://docs.vestaboard.com/docs/local-api/introduction>`_.
-
-.. important::
-
-    Vestaboard owners must first request a `Local API enablement token
-    <https://www.vestaboard.com/local-api>`_ in order to use the Local API.
-
-.. autoclass:: vesta.LocalClient
-    :members:
-
-``ReadWriteClient``
--------------------
+Read / Write API
+----------------
 
 :py:class:`vesta.ReadWriteClient` provides a client interface for interacting
 with a Vestaboard using the `Read / Write API
@@ -64,8 +43,8 @@ with a Vestaboard using the `Read / Write API
 .. autoclass:: vesta.ReadWriteClient
     :members:
 
-``SubscriptionClient``
-----------------------
+Subscription API
+----------------
 
 :py:class:`vesta.SubscriptionClient` provides a client interface for interacting
 with multiple Vestaboards using the `Subscription API
@@ -80,8 +59,23 @@ with multiple Vestaboards using the `Subscription API
 .. autoclass:: vesta.SubscriptionClient
     :members:
 
-``VBMLClient``
---------------
+Local API
+---------
+
+:py:class:`vesta.LocalClient` provides a client interface for interacting with
+a Vestaboard over the local network using `Vestaboard's Local API
+<https://docs.vestaboard.com/docs/local-api/introduction>`_.
+
+.. important::
+
+    Vestaboard owners must first request a `Local API enablement token
+    <https://www.vestaboard.com/local-api>`_ in order to use the Local API.
+
+.. autoclass:: vesta.LocalClient
+    :members:
+
+VBML API
+--------
 
 :py:class:`vesta.VBMLClient` provides a client interface for Vestaboard's
 `VBML (Vestaboard Markup Language) <https://docs.vestaboard.com/docs/vbml>`_
@@ -90,6 +84,22 @@ API.
 .. autoclass:: vesta.VBMLClient
     :members:
 
+Platform API
+------------
+
+:py:class:`vesta.Client` provides a client interface for interacting with the
+**deprecated** `Vestaboard Platform API <https://docs-v1.vestaboard.com/introduction>`_.
+
+.. warning::
+
+    This is the original Vestaboard Platform API. It is **deprecated** and has
+    been superseded by the other APIs listed above. In particular, Vestaboard
+    encourages users of the Platform API to switch to the Subscription API,
+    which offers nearly identical functionality.
+
+.. autoclass:: vesta.Client
+    :members:
+
 Character Encoding
 ==================
 

examples/dadjokes.py

@@ -55,7 +55,7 @@ def main(args: argparse.Namespace):
         level=logging.INFO,
     )
 
-    client = vesta.Client(args.key, args.secret)
+    client = vesta.SubscriptionClient(args.key, args.secret)
 
     jokes = fetch_jokes(args.count)
     logging.info("Loaded %d jokes", len(jokes))
@@ -81,7 +81,7 @@ def main(args: argparse.Namespace):
             vesta.pprint(chars)
 
         try:
-            client.post_message(args.sub, chars)
+            client.send_message(args.sub, chars)
         except httpx.HTTPStatusError as e:
             logging.error(e)
             time.sleep(60)

src/vesta/clients.py

@@ -47,6 +47,8 @@ class Client:
     Optionally, an alternate ``base_url`` can be specified, as well as any
     additional HTTP ``headers`` that should be sent with every request
     (such as a custom `User-Agent` header).
+
+    .. deprecated:: 0.12
     """
 
     def __init__(