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

It’s only runtime dependency is the HTTPX library, which will be installed automatically.

API Clients#

`Client`#

class vesta.Client(api_key: str, api_secret: str, *, base_url: str = 'https://platform.vestaboard.com', headers: Mapping[str, str] | None = None)#

Provides a Vestaboard API client interface.

Credentials must be provided as an api_key and api_secret.

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

get_subscriptions() → List[Dict[str, Any]]#: Lists all subscriptions to which the viewer has access.

get_viewer() → Dict[str, Any]#: Describes the currently authenticated viewer.

post_message(subscription_id: str, message: str | vesta.chars.Rows) → Dict[str, Any]#

Post a new message to a subscription.

The authenticated viewer must have access to the subscription.

message can be either a string of text or a two-dimensional (6, 22) array 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}).

Raises:: ValueError – if message is a list with unsupported dimensions

`LocalClient`#

vesta.LocalClient provides a client interface for interacting with a Vestaboard over the local network using Vestaboard’s Local API.

Important

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

class vesta.LocalClient(local_api_key: str | None = None, *, base_url: str = 'http://vestaboard.local:7000')#

Provides a Vestaboard Local API client interface.

A Local API key is required to read or write messages. This key is obtained by enabling the Vestaboard’s Local API using a Local API Enablement Token.

If you’ve already enabled your Vestaboard’s Local API, that key can be provided immediately. Otherwise, it can be set after the client is constructed by calling enable(), which also returns the Local API key for future reuse.

An alternate base_url can also be specified.

New in version 0.8.0.

property api_key: str | None#: The client’s Local API key.

enable(enablement_token) → str | None#

Enable the Vestaboard’s Local API using a Local API Enablement Token.

If successful, the Vestaboard’s Local API key will be returned and the client’s api_key property will be updated to the new value.

property enabled: bool#: Check if api_key has been set, indicating that Local API support has been enabled.

read_message() → vesta.chars.Rows | None#: Read the Vestaboard’s current message.

write_message(message: vesta.chars.Rows) → bool#

Write a message to the Vestaboard.

message must be a two-dimensional (6, 22) array of character codes representing the exact positions of characters on the board.

Raises:: ValueError – if message is a list with unsupported dimensions

`ReadWriteClient`#

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

Important

A Read / Write API key is required to read or write messages. This key is obtained 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.

class vesta.ReadWriteClient(read_write_key: str, base_url: str = 'https://rw.vestaboard.com/', headers: Mapping[str, str] | None = None)#

Provides a Vestaboard Read / Write API client interface.

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

New in version 0.8.0.

read_message() → vesta.chars.Rows | None#: Read the Vestaboard’s current message.

write_message(message: vesta.chars.Rows) → bool#

Write a message to the Vestaboard.

message must be a two-dimensional (6, 22) array of character codes representing the exact positions of characters on the board.

Raises:: ValueError – if message is a list with unsupported dimensions

Character Encoding#

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

vesta.chars.COLS: Final[int] = 22#: The number of columns on a board.

vesta.chars.ROWS: Final[int] = 6#: The number of rows on a board.

vesta.chars.Row#

A row of character codes.

alias of List[int]

vesta.chars.Rows#

A list of rows, forming a character grid.

alias of List[List[int]]

class vesta.Color(value)#

Bases: IntEnum

Color chips

BLACK = 70#

BLANK = 0#

BLUE = 67#

FILLED = 71#

GREEN = 66#

ORANGE = 64#

RED = 63#

VIOLET = 68#

WHITE = 69#

YELLOW = 65#

vesta.encode(s: str) → vesta.chars.Row#

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

Raises:: ValueError – if the string contains unsupported characters or codes

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

vesta.encode_row(s: str, align: Literal['left', 'center', 'right'] = 'left', fill: int = Color.BLANK) → vesta.chars.Row#

Encodes a string as a row of character codes.

In addition to printable characters, the string can contain character code sequences inside curly braces, such as {5} or {65}.

align controls the text’s alignment within the row: left, right, or center. The fill character code (generally a Color) is used to fill out any additional space.

Raises:: ValueError – if the string contains unsupported characters or codes, or if the resulting encoding sequence would exceed the maximum number of supported columns

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

vesta.encode_text(s: str, align: Literal['left', 'center', 'right'] = 'left', valign: Literal['top', 'middle', 'bottom'] | None = 'top', max_rows: int = ROWS, margin: int = 0, fill: int = Color.BLANK, breaks: Container[int] = frozenset({0})) → vesta.chars.Rows#

Encodes a string of text into rows of character codes.

In addition to printable characters, the string can contain character code sequences inside curly braces, such as {5} or {65}.

align controls the text’s alignment within the row: left, right, or center. valign controls the text’s vertical alignment within the full board (up to max_rows): top, middle, bottom, or None (to never add rows, potentially resulting in a partial board).

max_rows determines the maximum number of rows that will be returned, potentially truncating the result. When max_rows is zero, the row count is unlimited.

margin specifies the width (in columns) of the left and right margins. The fill character code (generally a Color) is used to fill out any additional space.

breaks is the set of character codes used to compute line breaks. If a line of text won’t fit in the available columns, it will be “broken” at the first preceding break character, and the remaining characters will continue on the next row (potentially subject to additional breaks). If a break cannot be found, the line will be broken at the column limit (potentially mid-“word”).

Raises:: ValueError – if the string contains unsupported characters or codes

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

vesta.pprint(data: vesta.chars.Row | vesta.chars.Rows, stream: TextIO = sys.stdout, *, sep: str = '|', block: str = '◼︎') → None#

Prints a console-formatted representation of encoded character data.

data may be a single list or a two-dimensional array of character codes.

Vesta#

Installation#

API Clients#

Client#

LocalClient#

ReadWriteClient#

Character Encoding#

`Client`#

`LocalClient`#

`ReadWriteClient`#