Merge pull request #29 from ShaneSutro/feature/convertCharacters

Add bracketed character support in `.convert()` method

CHANGELOG.md

@@ -4,33 +4,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## [v1.0.1](https://github.com/SonicRift/Vestaboard/releases/tag/v1.0.1) - 2022-06-18
+## [v1.1.0](https://github.com/ShaneSutro/Vestaboard/releases/tag/v1.1.0) - 2022-06-18
 
-<small>[Compare with v1.0.0](https://github.com/SonicRift/Vestaboard/compare/v1.0.0...v1.0.1)</small>
+<small>[Compare with v1.0.0](https://github.com/ShaneSutro/Vestaboard/compare/v1.0.0...v1.1.0)</small>
 
+### Features
+- Support bracketed char codes in `.convert()` ([d8113be](https://github.com/ShaneSutro/Vestaboard/commit/d8113be95e54a26eccc9128530e5e29acda74e7f) by Shane Sutro).
 
-## [v1.0.0](https://github.com/SonicRift/Vestaboard/releases/tag/v1.0.0) - 2022-01-07
 
-<small>[Compare with v0.5.0](https://github.com/SonicRift/Vestaboard/compare/v0.5.0...v1.0.0)</small>
+## [v1.0.0](https://github.com/ShaneSutro/Vestaboard/releases/tag/v1.0.0) - 2022-01-07
 
+<small>[Compare with v0.5.0](https://github.com/ShaneSutro/Vestaboard/compare/v0.5.0...v1.0.0)</small>
 
-## [v0.5.0](https://github.com/SonicRift/Vestaboard/releases/tag/v0.5.0) - 2021-02-22
 
-<small>[Compare with v0.4.0](https://github.com/SonicRift/Vestaboard/compare/v0.4.0...v0.5.0)</small>
+## [v0.5.0](https://github.com/ShaneSutro/Vestaboard/releases/tag/v0.5.0) - 2021-02-22
 
+<small>[Compare with v0.4.0](https://github.com/ShaneSutro/Vestaboard/compare/v0.4.0...v0.5.0)</small>
 
-## [v0.4.0](https://github.com/SonicRift/Vestaboard/releases/tag/v0.4.0) - 2021-02-12
 
-<small>[Compare with v0.3.1](https://github.com/SonicRift/Vestaboard/compare/v0.3.1...v0.4.0)</small>
+## [v0.4.0](https://github.com/ShaneSutro/Vestaboard/releases/tag/v0.4.0) - 2021-02-12
 
+<small>[Compare with v0.3.1](https://github.com/ShaneSutro/Vestaboard/compare/v0.3.1...v0.4.0)</small>
 
-## [v0.3.1](https://github.com/SonicRift/Vestaboard/releases/tag/v0.3.1) - 2021-02-10
 
-<small>[Compare with v0.2.0-beta](https://github.com/SonicRift/Vestaboard/compare/v0.2.0-beta...v0.3.1)</small>
+## [v0.3.1](https://github.com/ShaneSutro/Vestaboard/releases/tag/v0.3.1) - 2021-02-10
 
+<small>[Compare with v0.2.0-beta](https://github.com/ShaneSutro/Vestaboard/compare/v0.2.0-beta...v0.3.1)</small>
 
-## [v0.2.0-beta](https://github.com/SonicRift/Vestaboard/releases/tag/v0.2.0-beta) - 2021-02-09
 
-<small>[Compare with first commit](https://github.com/SonicRift/Vestaboard/compare/049afbf9bbb45f5e6b5b797023729471ab6e653f...v0.2.0-beta)</small>
+## [v0.2.0-beta](https://github.com/ShaneSutro/Vestaboard/releases/tag/v0.2.0-beta) - 2021-02-09
+
+<small>[Compare with first commit](https://github.com/ShaneSutro/Vestaboard/compare/049afbf9bbb45f5e6b5b797023729471ab6e653f...v0.2.0-beta)</small>
 
 

README.md

@@ -1,11 +1,12 @@
 # Vestaboard
 
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/7d172f1a1ede4c91bb379aa0837a3683)](https://app.codacy.com/gh/SonicRift/Vestaboard?utm_source=github.com&utm_medium=referral&utm_content=SonicRift/Vestaboard&utm_campaign=Badge_Grade)
-[![Build Status](https://travis-ci.com/SonicRift/Vestaboard.svg?branch=master)](https://travis-ci.com/SonicRift/Vestaboard)
+[![Build Status](https://app.travis-ci.com/ShaneSutro/Vestaboard.svg?branch=master)](https://app.travis-ci.com/ShaneSutro/Vestaboard)
 [![PyPI version](https://badge.fury.io/py/Vestaboard.svg)](https://badge.fury.io/py/Vestaboard)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/vestaboard)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vestaboard)
-***
+
+---
 
 ## GitHub Stats
 
@@ -17,35 +18,41 @@ This is a lightweight and unassuming wrapper for the Vestaboard API. This projec
 By [Shane Sutro][] and [contributors](https://github.com/SonicRift/Vestaboard/graphs/contributors)
 
 Thanks to [@ClayClayClayClay](https://github.com/ClayClayClayClay) for donating and supporting this project!
-***
+
+---
+
 ### Official API
-You can view more information about Vestaboard's API [here](https://docs.vestaboard.com/). *[Disclaimer](#repository-info-and-disclaimers)*
+
+You can view more information about Vestaboard's API [here](https://docs.vestaboard.com/). _[Disclaimer](#repository-info-and-disclaimers)_
 
 ### Concepts
+
 According to Vestaboard's documentation, software that utilizes the API is considered an `installable`, and as such must be connected to a Vestaboard via an `installation`.
 
 Each Board subscribes to an `installable` via an `installation` and as such is able to recieve a `message`. While I won't get into detail on how these correlate, know that you must first create an `installable` via [Vestaboard's API](https://web.vestaboard.com). You'll need to create an account and register your `installable` to your board.
 
 Once created, you will need to store your API Key and API Secret - you'll need this to communicate with your board. During this process, you will be prompted to select which board you'd like to install this `installable` onto - this is what creates the Subscription ID behind the scenes. Read more below.
-***
+
+---
 
 ### Using this package
 
 #### Installation
 
--   Download and install into your project file
--   Via `pip`:
+  - Download and install into your project file
+  - Via `pip`:
 
-```pip3 install vestaboard```
-*Note: if using a virtual environment, use `pip` instead of `pip3`*
+`pip3 install vestaboard`
+_Note: if using a virtual environment, use `pip` instead of `pip3`_
 
 #### Usage
 
 This package will simplify the process of connecting your code to Vestaboard's API.
 By default, the module will store your API Key, API Secret, and Subscriber ID in a .txt file in the root folder of the project.
-If you do *not* want to store this, pass `saveCredentials=False` into the creation of an `Installable`. Alternatively, you may skip creating an `Installable` alltogether if you already know your Subscription ID (which you can get from Vestaboards official portal if you'd like to skip this step).
+If you do _not_ want to store this, pass `saveCredentials=False` into the creation of an `Installable`. Alternatively, you may skip creating an `Installable` alltogether if you already know your Subscription ID (which you can get from Vestaboards official portal if you'd like to skip this step).
+
+If you do _not_ know your Subscription ID call `Installable()` with your API Key and API Secret to find and store it:
 
-If you do *not* know your Subscription ID call `Installable()` with your API Key and API Secret to find and store it:
 ```python
 import vestaboard
 #This will print your subscription ID, and store all keys in 'credentials.txt'
@@ -55,6 +62,7 @@ installable = vestaboard.Installable('your_api_key', 'your_api_secret')
 vboard = vestaboard.Board(installable)
 vboard.post('And just like that, we were off.')
 ```
+
 ![Board with plain text example](../media/basictext.png?raw=true)
 
 If you already have your Subscription ID or you do not want to store it, you can call `Board()` directly and pass your API Key, API Secret and Subscription ID directly.
@@ -63,12 +71,15 @@ If you do choose to store them, they will be stored in a file called `credential
 You can also create an instance of Installable with only your API Key and API Secret, then provide a subscription ID directly when instantiating a new `Board` by setting `getSubscription=False` when instantiating the Installable.
 
 #### config.py
+
 ```python
 api_key='DrBXYxUN40z2dpIogNjO'
 api_secret='2Qc8cClVov2TI9eeudVP'
 subscription_id='5PmlVd5MnjtMIBYcBUXI'
 ```
+
 #### vestaboard.py
+
 ```python
 from vestaboard import Board
 import config
@@ -78,17 +89,20 @@ vboard = Board(apiKey=config.api_key, apiSecret=config.api_secret, subscriptionI
 vboard.post('Love is all you need')
 ```
 
-***
+---
+
 ## Currently Supported
+
 Currently this module supports the following:
--   Creating an Installable object by passing in an API Key and API Secret
-    -   This will find and store the Subscription ID for you
-    -   Passing `getSubscription=False` overrides this - if you set this to False, remember to pass in a Subscription ID when instantiating a new `Board`
 
--   Creating an instance of Board by passing in one of the following:
-    -   An Installable, instantiated with API Key and API Secret
-    -   By passing in an API Key, API Secret *and* Subscription ID directly to `Board()`
-    -   By passing in an Installable where `getSubscription=False` and manually providing the Subscription ID to `Board`.
+  - Creating an Installable object by passing in an API Key and API Secret
+    - This will find and store the Subscription ID for you
+    - Passing `getSubscription=False` overrides this - if you set this to False, remember to pass in a Subscription ID when instantiating a new `Board`
+
+  - Creating an instance of Board by passing in one of the following:
+    - An Installable, instantiated with API Key and API Secret
+    - By passing in an API Key, API Secret _and_ Subscription ID directly to `Board()`
+    - By passing in an Installable where `getSubscription=False` and manually providing the Subscription ID to `Board`.
 
 The board currently has 2 methods available, the `.post()` method, which takes in a string and sends it to the board, and the `.raw()` method, which allows you to place characters precisely where you'd like them.
 
@@ -105,7 +119,7 @@ vboard.post('Everything you can imagine is real.')
 
 The `.post()` method supports all letters and symbols that Vestaboard supports, including all letters, numbers, and symbols.
 In addition, you may pass in a character code in curly brackets to represent a single character or a color tile. You can view a reference of character and color codes on [Vestaboard's official website by clicking here.](https://docs.vestaboard.com/characters)
-Vestaboard's API currently strips leading and trailing spaces from lines - *this includes the `{0}` character (the black tile)*. To precisely place characters, use the `.raw()` method (see below).
+Vestaboard's API currently strips leading and trailing spaces from lines - _this includes the `{0}` character (the black tile)_. To precisely place characters, use the `.raw()` method (see below).
 
 ```python
 import vestaboard
@@ -115,6 +129,7 @@ vboard = vestaboard.Board(installable)
 
 vboard.post('Triage Status\n\n{63}High -3{0}{0}items\n {65}Med -18 items\n{66}Low -88 items')
 ```
+
 ![Board with color tiles example](../media/vbcolors.png?raw=true)
 
 ### Raw
@@ -138,22 +153,25 @@ vboard = vestaboard.Board(installable)
 
 vboard.raw(characters)
 ```
+
 ![Board with raw input example](../media/rawexample.png?raw=true)
 
 ### New in Version 1.0.0
+
 The `.raw()` method now supports padding and truncating if more or fewer than 6 lines are provided! By default, your text will be centered vertically on the board, but will generate a warning (if an odd number of lines are provided, the additional line will be at the bottom). Supress this warning by passing in `pad='center'`. When passing in greater than 6 lines, the board will only display the first 6 lines, removing lines from the bottom.
 
 You can also specify whether you'd like the padding to be added above or below your text by passing in `pad='top'` or `pad='bottom'` (only available when passing in < 6 lines). `pad='top'` will add padding above your text (your text will be at the bottom of the board), and `pad='bottom'` will add padding below your text (your text will be at the top of the board).
 
-***
+---
 
 To assist with character conversion, use the `Formatter` class.
 The `Formatter` has two public helper options:
 
--   `.convert()`
--   `.convertLine()`
+  - `.convert()`
+  - `.convertLine()`
 
 ### Convert
+
 If converting a string, use the `.convert()` method. By default, `.convert()` will split by letter and return an array of character codes corresponding to the string you passed in:
 
 ```python
@@ -162,6 +180,7 @@ from vestaboard.formatter import Formatter
 Formatter().convert('Oh hi!')
 # Returns [15, 8, 0, 8, 9, 37]
 ```
+
 There is no limit to the number of letters you can convert. If you need to create a row with exactly 22 characters, you can use the `.convertLine()` method instead.
 
 To split by word, pass in the argument `byWord=True` along with your input string:
@@ -174,6 +193,7 @@ Formatter().convert('Oh hi!', byWord=True)
 ```
 
 ### Convert Line
+
 If you'd like to convert an entire line at once, use the `.convertLine()` method. `.convertLine()` centers text by default. To left justify or right justify, pass `justify='left'` or `justify='right'`.
 
 ```python
@@ -184,18 +204,23 @@ Formatter().convertLine('Happy Birthday!')
 ```
 
 ## Upcoming Support
--   Formatting
-    -   Want to right justify, left justify, or center the entire content? Coming soon!
 
--   Templates
-    -   Choose from a list of templates to send to your board, including calendars, Q&A, trivia, and more
+  - Formatting
+
+    - Want to right justify, left justify, or center the entire content? Coming soon!
+
+  - Templates
+    - Choose from a list of templates to send to your board, including calendars, Q&A, trivia, and more
+
+---
 
-***
 ## Repository Info and Disclaimers
+
 ### Needs
--   ~~Conversion from string to list of lists for `.raw()` method~~ ✅ Complete!
--   ~~Unit and other tests inside the `/test` folder~~ ✅ Complete!
--   Suggestions or ideas for improvement are always welcome!
+
+  - ~~Conversion from string to list of lists for `.raw()` method~~ ✅ Complete!
+  - ~~Unit and other tests inside the `/test` folder~~ ✅ Complete!
+  - Suggestions or ideas for improvement are always welcome!
 
 Interested in contributing to this project? Send a PR with changes and I'd be happy to review! If you're having trouble with this library, be sure to [open an issue][] so that I can look into the problem. Any details that can be provided alongside the problem would be greatly appreciated.
 Thanks!
@@ -204,7 +229,7 @@ Thanks!
 
 You belong here ♥️
 
-*Note: this project is maintaned by independent developers and is not sponsored by nor affiliated with Vestaboard, Inc. I am unable to make changes to their API or answer questions about the company, upcoming API support, or future-state plans. For questions regarding Vestaboard's API, privacy policies, or to request assistance with your board, [please get in touch with them here.](https://www.vestaboard.com/contact)*
+_Note: this project is maintaned by independent developers and is not sponsored by nor affiliated with Vestaboard, Inc. I am unable to make changes to their API or answer questions about the company, upcoming API support, or future-state plans. For questions regarding Vestaboard's API, privacy policies, or to request assistance with your board, [please get in touch with them here.](https://www.vestaboard.com/contact)_
 
 [open an issue]: https://github.com/SonicRift/Vestaboard/issues
 [shane sutro]: https://github.com/SonicRift

tests/test_formatting.py

@@ -136,3 +136,19 @@ def test_space_buffer_adds_spaces_where_appropriate():
     assert t1 == e1, 'Should add spacing on both sides of centered text'
     assert t2 == e2, 'Should add spacing to the right side of left-justified text'
     assert t3 == e3, 'Should add spacing to the left side of right-justified text'
+
+def test_convert_handles_bracket_chars():
+    t1 = Formatter().convert('{62}Y{62} beginning')
+    t2 = Formatter().convert('end {65}')
+    t3 = Formatter().convert('by word {65}', byWord=True)
+    t4 = Formatter().convert('{65} by word start', byWord=True)
+
+    e1 = [62, 25, 62, 0, 2, 5, 7, 9, 14, 14, 9, 14, 7]
+    e2 = [5, 14, 4, 0, 65]
+    e3 = [[2, 25], [23, 15, 18, 4], [65]]
+    e4 = [[65], [2, 25], [23, 15, 18, 4], [19, 20, 1, 18, 20]]
+
+    assert t1 == e1, 'Should handle bracketed characters at the beginning of a string'
+    assert t2 == e2, 'Should handle bracketed characters at the end of a string'
+    assert t3 == e3, 'Should handle bracketed characters at the end of a string with byWord'
+    assert t4 == e4, 'Should handle bracketed characters at the beginning of a string with byWord'

vestaboard/formatter.py

@@ -44,13 +44,10 @@ def convert(self, inputString, byLetter=True, byWord=False):
     if byWord:
       wordList = inputString.split(' ')
       for word in wordList:
-        convertedWord = []
-        for letter in word:
-          convertedWord.append(characters[letter])
+        convertedWord = self._convertLoop(word);
         converted.append(convertedWord)
     elif byLetter:
-      for letter in inputString:
-        converted.append(characters[letter])
+      converted += self._convertLoop(inputString)
 
     return converted
 
@@ -71,6 +68,13 @@ def convertLine(self, inputString, justify='center', color=' ', spaceBuffer=Fals
       raise Exception(f'Convert line method takes in a string less than or equal to 22 characters - string passed in was {len(inputString)} characters. Reduce size and try again (remember that setting spaceBuffer=True increases your line size by 2).')
     inputString = self._justifyContent(inputString, justify, numCharacterCodes, color)
 
+    converted = self._convertLoop(inputString)
+
+    return converted
+
+  @staticmethod
+  def _convertLoop(inputString):
+    converted = []
     skipTo = 0
     for index, letter in enumerate(inputString):
       if index < skipTo:
@@ -87,6 +91,7 @@ def convertLine(self, inputString, justify='center', color=' ', spaceBuffer=Fals
 
     return converted
 
+
   @staticmethod
   def _addSpaceBuffer(inputString, justify):
     if justify == 'left':