Merge branch 'master' of dev version.

Author: Kevin J Walters

.travis.yml

@@ -44,9 +44,9 @@ install:
   - pip install --force-reinstall pylint==1.9.2
 
 script:
-  - ([[ -d "tests" ]] && py.test)
+  - [[ ! -d "tests" ]] || py.test
   - pylint adafruit_midi/*.py
-  - ([[ -d "tests" ]] && pylint --disable=missing-docstring,invalid-name,bad-whitespace,trailing-whitespace,line-too-long,wrong-import-position,unused-import tests/*.py)
-  - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace examples/*.py)
+  - [[ ! -d "tests" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace,trailing-whitespace,line-too-long,wrong-import-position,unused-import tests/*.py
+  - [[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace examples/*.py
   - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-midi --library_location .
-  - cd docs && sphinx-build -E -W -b html . _build/html && cd ..
+  - ( cd docs && sphinx-build -E -W -b html . _build/html )

adafruit_midi/__init__.py

@@ -51,15 +51,32 @@
 
 
 class MIDI:
-    """MIDI helper class."""
+    """MIDI helper class.
+
+    :param midi_in: an object which implements ``read(length)``,
+        defaults to ``usb_midi.ports[0]``.
+    :param midi_out: an object which implements ``write(buffer, length)``,
+        defaults to ``usb_midi.ports[1]``.
+    :param in_channel: The input channel(s).
+        This is used by ``receive`` to filter data.
+        This can either be an ``int`` for the wire protocol channel number (0-15)
+        a tuple of ``int`` to listen for multiple channels or ``"ALL"``.
+        Defaults to None.
+    :param int out_channel: The wire protocol output channel number (0-15)
+        used by ``send`` if no channel is specified,
+        defaults to 0 (MIDI Channel 1).
+    :param int in_buf_size: Size of input buffer in bytes, default 30.
+    :param bool debug: Debug mode, default False.
+
+    """
 
     NOTE_ON = 0x90
     NOTE_OFF = 0x80
     PITCH_BEND = 0xE0
     CONTROL_CHANGE = 0xB0
 
     def __init__(self, midi_in=usb_midi.ports[0], midi_out=usb_midi.ports[1], *,
-                 in_channel=None, out_channel=0, debug=False, in_buf_size=30):
+                 in_channel=None, out_channel=0, in_buf_size=30, debug=False):
         self._midi_in = midi_in
         self._midi_out = midi_out
         self.in_channel = in_channel
@@ -108,8 +125,10 @@ def out_channel(self, channel):
     def receive(self):
         """Read messages from MIDI port, store them in internal read buffer, then parse that data
         and return the first MIDI message (event).
+        This maintains the blocking characteristics of the midi_in port.
 
-        Returns (MIDIMessage object, channel) or (None, None) for nothing.
+        :returns (MIDIMessage object, int channel): Returns object and channel
+           or (None, None) for nothing.
         """
         ### could check _midi_in is an object OR correct object OR correct interface here?
         # If the buffer here is not full then read as much as we can fit from

adafruit_midi/channel_pressure.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.channel_pressure`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Channel Pressure MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage

adafruit_midi/control_change.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.control_change`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Control Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage

adafruit_midi/midi_message.py

@@ -20,26 +20,23 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.midi_message.MIDIMessage`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+An abstract class for objects which represent MIDI messages (events).
+When individual messages are imported they register themselves with
+:func:register_message_type which makes them recognised
+by the parser, :func:from_message_bytes.
+
+Large messages like :class:SystemExclusive can only be parsed if they fit
+within the input buffer in :class:MIDI.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 __version__ = "0.0.0-auto.0"
@@ -97,15 +94,19 @@ def note_parser(note):
 
 class MIDIMessage:
     """
-    A MIDI message:
-      - _STATUS - extracted from Status byte with channel replaced by 0s
-                  (high bit always set).
-      - _STATUSMASK - mask used to compared a status byte with _STATUS value
-      - LENGTH - length for a fixed size message including status
-                  or -1 for variable length.
-      - CHANNELMASK - mask use to apply a (wire protocol) channel number.
-      - ENDSTATUS - the EOM status byte, only set for variable length.
-    This is an abstract class.
+    The parent class for MIDI messages.
+
+    Class variables:
+
+      * ``_STATUS`` - extracted from status byte with channel replaced by 0s
+        (high bit is always set by convention).
+      * ``_STATUSMASK`` - mask used to compared a status byte with ``_STATUS`` value.
+      * ``LENGTH`` - length for a fixed size message *including* status
+        or -1 for variable length.
+      * ``CHANNELMASK`` - mask used to apply a (wire protocol) channel number.
+      * ``ENDSTATUS`` - the end of message status byte, only set for variable length.
+
+    This is an *abstract* class.
     """
     _STATUS = None
     _STATUSMASK = None
@@ -146,7 +147,7 @@ def _search_eom_status(cls, buf, eom_status, msgstartidx, msgendidxplusone, endi
             # Look for a status byte
             # Second rule of the MIDI club is status bytes have MSB set
             if buf[msgendidxplusone] & 0x80:
-                # pylint disable=simplifiable-if-statement  # n/a for this technique
+                # pylint disable=simplifiable-if-statement
                 if buf[msgendidxplusone] == eom_status:
                     good_termination = True
                 else:
@@ -276,18 +277,21 @@ def from_message_bytes(cls, midibytes, channel_in):
         return (msg, msgendidxplusone, skipped, channel)
 
     # channel value present to keep interface uniform but unused
+    # A default method for constructing wire messages with no data.
+    # Returns a (mutable) bytearray with just the status code in.
     # pylint: disable=unused-argument
     def as_bytes(self, channel=None):
-        """A default method for constructing wire messages with no data.
-        Returns a (mutable) bytearray with just status code in."""
+        """Return the ``bytearray`` wire protocol representation of the object."""
         return bytearray([self._STATUS])
 
     # databytes value present to keep interface uniform but unused
+    # A default method for constructing message objects with no data.
+    # Returns the new object.
     # pylint: disable=unused-argument
     @classmethod
     def from_bytes(cls, databytes):
-        """A default method for constructing message objects with no data.
-           Returns the new object."""
+        """Creates an object from the byte stream of the wire protocol
+        (not including the first status byte)."""
         return cls()
 
 

adafruit_midi/note_off.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.note_off`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Note Off Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage, note_parser

adafruit_midi/note_on.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.note_on`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Note On Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage, note_parser

adafruit_midi/pitch_bend_change.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.pitch_bend_change`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Pitch Bend Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage

adafruit_midi/polyphonic_key_pressure.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.polyphonic_key_pressure`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Polyphonic Key Pressure MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage, note_parser

adafruit_midi/program_change.py

@@ -20,26 +20,17 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 """
-`adafruit_midi`
+`adafruit_midi.program_change`
 ================================================================================
 
-A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection.
+Program Change MIDI message.
 
 
 * Author(s): Kevin J. Walters
 
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-
-
-**Software and Dependencies:**
-
-* Adafruit CircuitPython firmware for the supported boards:
-  https://github.com/adafruit/circuitpython/releases
-
 """
 
 from .midi_message import MIDIMessage