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: Optional[Mapping[str, str]] = None)#
Provides a Vestaboard API client interface.
Credentials must be provided as an
api_key
andapi_secret
.Optionally, an alternate
base_url
can be specified, as well as any additional HTTPheaders
that should be sent with every request (such as a custom User-Agent header).- post_message(subscription_id: str, message: Union[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: Optional[str] = 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.
- enable(enablement_token) Optional[str] #
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.
- 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: Optional[Mapping[str, str]] = None)#
Provides a Vestaboard Read / Write API client interface.
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.
Optionally, an alternate
base_url
can be specified, as well as any additional HTTPheaders
that should be sent with every request (such as a custom User-Agent header).New in version 0.8.0.
- 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.
- 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. Thefill
character code (generally aColor
) 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: Optional[Literal['top', 'middle', 'bottom']] = 'top', 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: 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. Thefill
character code (generally aColor
) 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]]