vesta 0.10.1

Vestaboard client library

Vesta

Vesta is a Vestaboard client library for Python. It provides API clients and character encoding utilities.

Installation

Vesta requires Python 3.8 or later. It can be installed via PyPI:

$ python -m pip install vesta

Its only runtime dependency is the HTTPX library, which will be installed automatically.

Usage

API Clients

Client

The Client type is initialized with an API key and secret:

>>> import vesta
>>> client = vesta.Client(API_KEY, API_SECRET)

Then, you can make API calls using one of the provided methods:

>>> 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.

Note that Vestaboard owners must first request a Local API enablement token in order to use the Local API.

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

ReadWriteClient provides a client interface for interacting with a Vestaboard using the Read / Write API.

Note that Vestaboard owners must first obtain their Read / Write API key by enabling the Vestaboard's Read / Write API via the Settings section of the mobile app or from the Developer section of the web app.

import vesta
rw_client = vesta.ReadWriteClient("read_write_key")

# Once enabled, you can write and read messages:
message = vesta.encode_text("{67} Hello, World {68}")
assert rw_client.write_message(message)
assert rw_client.read_message() == message

Character Encoding

All Vestaboard characters (letters, numbers, symbols, and colors) are encoded as integer character codes. Vesta includes some useful routines for working with these character codes.

encode() encodes a string as a list of character codes. In addition to printable characters, the string can contain character code sequences inside curly braces, such as {5} or {65}.

>>> vesta.encode("{67} Hello, World {68}")
[67, 0, 8, 5, 12, 12, 15, 55, 0, 23, 15, 18, 12, 4, 0, 68]

encode_row() encodes a string as a row of character codes. It builds on encode() by providing alignment control.

>>> vesta.encode_row("{67} Hello, World {68}", align="center")
[0, 0, 0, 67, 0, 8, 5, 12, 12, 15, 55, 0, 23, 15, 18, 12, 4, 0, 68, 0, 0, 0]

encode_text() encodes a string of text into rows of character codes, further building on encode() and encode_row() with the addition of alignment, margin control, and line breaks.

>>> encode_text("multiple\nlines\nof\ntext", align="center", valign="middle")
[
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 13, 21, 12, 20, 9, 16, 12, 5, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 12, 9, 14, 5, 19, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 15, 6, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 20, 5, 24, 20, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
]

Lastly, pprint() can be used to pretty-print encoded characters to the console, which can be useful during development.

>>> vesta.pprint([0, 0, 0, 67, 0, 8, 5, 12, 12, 15, 55, 0, 23, 15, 18, 12, 4, 0, 68, 0, 0, 0])
| | | |◼︎| |H|E|L|L|O|,| |W|O|R|L|D| |◼︎| | | |

Examples

• Dad Jokes
• Olympic Medal Standings

License

This project is licensed under the terms of the MIT license.

Copyright (c) 2021 - present Jon Parise [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Changelog

0.10.1 - 2023-07-22

Added

• Added text message support to ReadWriteClient.write_message().

Fixed

• ReadWriteClient.get_message() now correctly returns a Rows value rather than a JSON-encoded string.

0.10.0 - 2023-06-06

Added

• Added max_rows to encode_text() for controlling the maximum number of rows that will be returned (defaulting to 6). It can be set to a lower value to produce a partial board or 0 to support unlimited rows.

Changed

• encode_text() no longer raises ValueError when the result exceeds the maximum number of rows. Instead, the result is truncated to max_rows.

0.9.0 - 2022-12-11

Added

• Added Color.BLANK and Color.FILLED color values.

Changed

• Switched to HTTPX as the underlying HTTP library.
• Color.BLACK now uses the official "black" character code (70). Use Color.BLANK for character code 0 (previously used by Color.BLACK).
• The default "fill" color is now Color.BLANK instead of Color.BLACK.

Removed

• Dropped support for Python 3.7.

0.8.0 - 2022-08-13

Added

• LocalClient provides a client interface to Vestaboard's Local API.
• ReadWriteClient provides a client interface to Vestaboard's Read / Write API.

Changed

• The documentation now uses the Furo theme.
• Requests version 2.27.0 or later is now required.

0.7.3 - 2022-05-31

Added

• Various typing improvements, including a py.typed marker file.

0.7.2 - 2021-12-30

Added

• encode_text()'s valign argument can be set to None to disable row padding.

Changed

• encode()'s error handling has been improved. A ValueError will now be raised for all unsupported character codes, including those within the [0, 69] range such as 57, 58, and 61.

0.7.1 - 2021-12-19

Fixed

• encode_text() was adding a leading blank character to the row after a line break.

0.7.0 - 2021-12-19

Added

• encode_text() offers a valign argument for controlling vertical alignment within the board.
• Client.post_message() now raises ValueError if message is a list of encoded characters with the wrong dimensions.

Changed

• encode_text() now always produces six rows of output (a full board).

Removed

• Dropped support for Python 3.6, which has officially reached the end of its supported life.

0.6.0 - 2021-12-05

Added

• encode_text() for encoding lines of text

Fixed

• Fix space character encoding

0.5.1 - 2021-11-06

Added

• Initial Sphinx-based documentation

0.5.0 - 2021-11-01

• Initial release