Vesta

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

Installation

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

$ python -m pip install vesta

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

API Client

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

Provides a Vestaboard API client interface.

Credentials must be provided as an api_key and api_secret.

Optional, 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: Union[str, vesta.chars.Rows]) → Dict[str, Any]

Post of 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, lines will be centered horizontally and vertically if possible. Character codes will be inferred for alphanumeric and punctuation, or can be explicitly specified in-line in the message with curly braces containing the character code.

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 useful routines for working with these character codes.

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 = 0

BLUE = 67

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: str = 'left', fill: int = Color.BLACK) → 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: str = 'left', valign: Optional[str] = 'top', margin: int = 0, fill: int = Color.BLACK, 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: top, middle, bottom, or None (to never add rows, potentially resulting in a partial board).

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, or if the resulting encoding sequence would exceed the maximum number of supported rows

>>> 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: ~typing.Union[vesta.chars.Row, vesta.chars.Rows], stream: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, *, 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.

Message Posting

Messages can be posted (using vesta.Client.post_message()) as either text strings or two-dimensional arrays of character codes representing the exact positions of characters on the board.

If text is specified, lines will be centered horizontally and vertically if possible. Character codes will be inferred for alphanumeric and punctuation, or can be explicitly specified in-line in the message with curly braces containing the character code (such as {5} or {65}).