Converting to a MIDI message format which stores channel number as a property based on @tannewt feedback from adafruit#9.

This changes MIDI.receive() to return just the object and MIDI.send() now has the side-effect of setting the channel on each message.
Pushing CHANNELMASK into the parent MIDIMessage as it is no longer used as an indicator of presence/use of channel.
MIDIBadEvent now includes the status number in data.
Objects are now constructed on messages regardless of matching channel number as input channel test comes afterwards now.
Lots of associated changes to unit tests plus a few doc updates. adafruit#3

Author: Kevin J Walters

adafruit_midi/__init__.py

@@ -127,8 +127,7 @@ def receive(self):
         and return the first MIDI message (event).
         This maintains the blocking characteristics of the midi_in port.
 
-        :returns (MIDIMessage object, int channel): Returns object and channel
-           or (None, None) for nothing.
+        :returns MIDIMessage object: Returns object or 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
@@ -142,7 +141,7 @@ def receive(self):
                 del bytes_in
 
         (msg, endplusone,
-         skipped, channel) = MIDIMessage.from_message_bytes(self._in_buf, self._in_channel)
+         skipped) = MIDIMessage.from_message_bytes(self._in_buf, self._in_channel)
         if endplusone != 0:
             # This is not particularly efficient as it's copying most of bytearray
             # and deleting old one
@@ -151,23 +150,26 @@ def receive(self):
         self._skipped_bytes += skipped
 
         # msg could still be None at this point, e.g. in middle of monster SysEx
-        return (msg, channel)
+        return msg
 
     def send(self, msg, channel=None):
         """Sends a MIDI message.
 
         :param msg: Either a MIDIMessage object or a sequence (list) of MIDIMessage objects.
+            The channel property will be *updated* as a side-effect of sending message(s).
         :param int channel: Channel number, if not set the ``out_channel`` will be used.
 
         """
         if channel is None:
             channel = self.out_channel
         if isinstance(msg, MIDIMessage):
-            data = msg.as_bytes(channel=channel)
+            msg.channel = channel
+            data = bytes(msg)
         else:
             data = bytearray()
             for each_msg in msg:
-                data.extend(each_msg.as_bytes(channel=channel))
+                each_msg.channel = channel
+                data.extend(bytes(each_msg))
 
         self._send(data, len(data))
 

adafruit_midi/channel_pressure.py

@@ -48,20 +48,19 @@ class ChannelPressure(MIDIMessage):
     _STATUS = 0xd0
     _STATUSMASK = 0xf0
     LENGTH = 2
-    CHANNELMASK = 0x0f
 
-    def __init__(self, pressure):
+    def __init__(self, pressure, *, channel=None):
         self.pressure = pressure
+        super().__init__(channel=channel)
         if not 0 <= self.pressure <= 127:
             raise self._EX_VALUEERROR_OOR
 
-    # channel value is mandatory
-    def as_bytes(self, *, channel=None):
-        return bytearray([self._STATUS | (channel & self.CHANNELMASK),
-                          self.pressure])
+    def __bytes__(self):
+        return bytes([self._STATUS | (self.channel & self.CHANNELMASK),
+                      self.pressure])
 
     @classmethod
-    def from_bytes(cls, databytes):
-        return cls(databytes[0])
+    def from_bytes(cls, msg_bytes):
+        return cls(msg_bytes[1], channel=msg_bytes[0] & cls.CHANNELMASK)
 
 ChannelPressure.register_message_type()

adafruit_midi/control_change.py

@@ -50,21 +50,21 @@ class ControlChange(MIDIMessage):
     _STATUS = 0xb0
     _STATUSMASK = 0xf0
     LENGTH = 3
-    CHANNELMASK = 0x0f
 
-    def __init__(self, control, value):
+    def __init__(self, control, value, *, channel=None):
         self.control = control
         self.value = value
+        super().__init__(channel=channel)
         if not 0 <= self.control <= 127 or not 0 <= self.value <= 127:
             raise self._EX_VALUEERROR_OOR
 
-    # channel value is mandatory
-    def as_bytes(self, *, channel=None):
-        return bytearray([self._STATUS | (channel & self.CHANNELMASK),
-                          self.control, self.value])
+    def __bytes__(self):
+        return bytes([self._STATUS | (self.channel & self.CHANNELMASK),
+                      self.control, self.value])
 
     @classmethod
-    def from_bytes(cls, databytes):
-        return cls(databytes[0], databytes[1])
+    def from_bytes(cls, msg_bytes):
+        return cls(msg_bytes[1], msg_bytes[2],
+                   channel=msg_bytes[0] & cls.CHANNELMASK)
 
 ControlChange.register_message_type()

adafruit_midi/midi_message.py

@@ -111,7 +111,7 @@ class MIDIMessage:
     _STATUS = None
     _STATUSMASK = None
     LENGTH = None
-    CHANNELMASK = None
+    CHANNELMASK = 0x0f
     ENDSTATUS = None
 
     # Commonly used exceptions to save memory
@@ -121,6 +121,24 @@ class MIDIMessage:
     # order is more specific masks first
     _statusandmask_to_class = []
 
+    def __init__(self, *, channel=None):
+        ###  TODO - can i kwargs this?????
+        self._channel = channel  # dealing with pylint inadequacy
+        self.channel = channel
+
+    @property
+    def channel(self):
+        """The channel number of the MIDI message where appropriate.
+           This is *updated* by MIDI.send() method.
+        """
+        return self._channel
+
+    @channel.setter
+    def channel(self, channel):
+        if channel is not None and not 0 <= channel <= 15:
+            raise "channel must be 0-15 or None"
+        self._channel = channel
+
     @classmethod
     def register_message_type(cls):
         """Register a new message by its status value and mask.
@@ -161,16 +179,13 @@ def _search_eom_status(cls, buf, eom_status, msgstartidx, msgendidxplusone, endi
 
         return (msgendidxplusone, good_termination, bad_termination)
 
-    # pylint: disable=too-many-arguments,too-many-locals
     @classmethod
-    def _match_message_status(cls, buf, channel_in, msgstartidx, msgendidxplusone, endidx):
+    def _match_message_status(cls, buf, msgstartidx, msgendidxplusone, endidx):
         msgclass = None
         status = buf[msgstartidx]
         known_msg = False
         complete_msg = False
         bad_termination = False
-        channel_match_orna = True
-        channel = None
 
         # Rummage through our list looking for a status match
         for status_mask, msgclass in MIDIMessage._statusandmask_to_class:
@@ -183,10 +198,6 @@ def _match_message_status(cls, buf, channel_in, msgstartidx, msgendidxplusone, e
                 if not complete_msg:
                     break
 
-                if msgclass.CHANNELMASK is not None:
-                    channel = status & msgclass.CHANNELMASK
-                    channel_match_orna = channel_filter(channel, channel_in)
-
                 if msgclass.LENGTH < 0:  # indicator of variable length message
                     (msgendidxplusone,
                      terminated_msg,
@@ -203,26 +214,26 @@ def _match_message_status(cls, buf, channel_in, msgstartidx, msgendidxplusone, e
 
         return (msgclass, status,
                 known_msg, complete_msg, bad_termination,
-                channel_match_orna, channel, msgendidxplusone)
+                msgendidxplusone)
 
+    # pylint: disable=too-many-locals,too-many-branches
     @classmethod
     def from_message_bytes(cls, midibytes, channel_in):
         """Create an appropriate object of the correct class for the
-        first message found in some MIDI bytes.
+        first message found in some MIDI bytes filtered by channel_in.
 
-        Returns (messageobject, endplusone, skipped, channel)
+        Returns (messageobject, endplusone, skipped)
         or for no messages, partial messages or messages for other channels
-        (None, endplusone, skipped, None).
+        (None, endplusone, skipped).
         """
-        msg = None
         endidx = len(midibytes) - 1
         skipped = 0
         preamble = True
-        channel = None
 
         msgstartidx = 0
         msgendidxplusone = 0
         while True:
+            msg = None
             # Look for a status byte
             # Second rule of the MIDI club is status bytes have MSB set
             while msgstartidx <= endidx and not midibytes[msgstartidx] & 0x80:
@@ -233,27 +244,27 @@ def from_message_bytes(cls, midibytes, channel_in):
 
             # Either no message or a partial one
             if msgstartidx > endidx:
-                return (None, endidx + 1, skipped, None)
+                return (None, endidx + 1, skipped)
 
             # Try and match the status byte found in midibytes
             (msgclass,
              status,
              known_message,
              complete_message,
              bad_termination,
-             channel_match_orna,
-             channel,
              msgendidxplusone) = cls._match_message_status(midibytes,
-                                                           channel_in,
                                                            msgstartidx,
                                                            msgendidxplusone,
                                                            endidx)
-
-            if complete_message and not bad_termination and channel_match_orna:
+            channel_match_orna = True
+            if complete_message and not bad_termination:
                 try:
-                    msg = msgclass.from_bytes(midibytes[msgstartidx+1:msgendidxplusone])
+                    msg = msgclass.from_bytes(midibytes[msgstartidx:msgendidxplusone])
+                    if msg.channel is not None:
+                        channel_match_orna = channel_filter(msg.channel, channel_in)
+
                 except(ValueError, TypeError) as ex:
-                    msg = MIDIBadEvent(midibytes[msgstartidx+1:msgendidxplusone], ex)
+                    msg = MIDIBadEvent(midibytes[msgstartidx:msgendidxplusone], ex)
 
             # break out of while loop for a complete message on good channel
             # or we have one we do not know about
@@ -274,24 +285,23 @@ def from_message_bytes(cls, midibytes, channel_in):
                 msgendidxplusone = msgstartidx + 1
                 break
 
-        return (msg, msgendidxplusone, skipped, channel)
+        return (msg, msgendidxplusone, skipped)
 
-    # 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):
-        """Return the ``bytearray`` wire protocol representation of the object."""
-        return bytearray([self._STATUS])
+    # Returns an (immutable) bytes with just the status code in.
+    def __bytes__(self):
+        """Return the ``bytes`` wire protocol representation of the object
+            with channel number applied where appropriate."""
+        return bytes([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):
+    def from_bytes(cls, msg_bytes):
         """Creates an object from the byte stream of the wire protocol
-        (not including the first status byte)."""
+           representation of the MIDI message."""
         return cls()
 
 
@@ -308,18 +318,22 @@ class MIDIUnknownEvent(MIDIMessage):
 
     def __init__(self, status):
         self.status = status
+        super().__init__()
 
 
 class MIDIBadEvent(MIDIMessage):
     """A bad MIDI message, one that could not be parsed/constructed.
 
-    :param list data: The MIDI status number.
+    :param list data: The MIDI status including any embedded channel number
+        and associated subsequent data bytes.
     :param Exception exception: The exception used to store the repr() text representation.
 
     This could be due to status bytes appearing where data bytes are expected.
+    The channel property will not be set.
     """
     LENGTH = -1
 
-    def __init__(self, data, exception):
-        self.data = bytearray(data)
+    def __init__(self, msg_bytes, exception):
+        self.data = bytes(msg_bytes)
         self.exception_text = repr(exception)
+        super().__init__()

adafruit_midi/note_off.py

@@ -51,21 +51,21 @@ class NoteOff(MIDIMessage):
     _STATUS = 0x80
     _STATUSMASK = 0xf0
     LENGTH = 3
-    CHANNELMASK = 0x0f
 
-    def __init__(self, note, velocity):
+    def __init__(self, note, velocity, *, channel=None):
         self.note = note_parser(note)
         self.velocity = velocity
+        super().__init__(channel=channel)
         if not 0 <= self.note <= 127 or not 0 <= self.velocity <= 127:
             raise self._EX_VALUEERROR_OOR
 
-    # channel value is mandatory
-    def as_bytes(self, *, channel=None):
-        return bytearray([self._STATUS | (channel & self.CHANNELMASK),
-                          self.note, self.velocity])
+    def __bytes__(self):
+        return bytes([self._STATUS | (self.channel & self.CHANNELMASK),
+                      self.note, self.velocity])
 
     @classmethod
-    def from_bytes(cls, databytes):
-        return cls(databytes[0], databytes[1])
+    def from_bytes(cls, msg_bytes):
+        return cls(msg_bytes[1], msg_bytes[2],
+                   channel=msg_bytes[0] & cls.CHANNELMASK)
 
 NoteOff.register_message_type()

adafruit_midi/note_on.py

@@ -51,21 +51,21 @@ class NoteOn(MIDIMessage):
     _STATUS = 0x90
     _STATUSMASK = 0xf0
     LENGTH = 3
-    CHANNELMASK = 0x0f
 
-    def __init__(self, note, velocity):
+    def __init__(self, note, velocity, *, channel=None):
         self.note = note_parser(note)
         self.velocity = velocity
+        super().__init__(channel=channel)
         if not 0 <= self.note <= 127 or not 0 <= self.velocity <= 127:
             raise self._EX_VALUEERROR_OOR
 
-    # channel value is mandatory
-    def as_bytes(self, *, channel=None):
-        return bytearray([self._STATUS | (channel & self.CHANNELMASK),
-                          self.note, self.velocity])
+    def __bytes__(self):
+        return bytes([self._STATUS | (self.channel & self.CHANNELMASK),
+                      self.note, self.velocity])
 
     @classmethod
-    def from_bytes(cls, databytes):
-        return cls(databytes[0], databytes[1])
+    def from_bytes(cls, msg_bytes):
+        return cls(msg_bytes[1], msg_bytes[2],
+                   channel=msg_bytes[0] & cls.CHANNELMASK)
 
 NoteOn.register_message_type()

adafruit_midi/pitch_bend.py

@@ -49,21 +49,21 @@ class PitchBend(MIDIMessage):
     _STATUS = 0xe0
     _STATUSMASK = 0xf0
     LENGTH = 3
-    CHANNELMASK = 0x0f
 
-    def __init__(self, pitch_bend):
+    def __init__(self, pitch_bend, *, channel=None):
         self.pitch_bend = pitch_bend
+        super().__init__(channel=channel)
         if not 0 <= self.pitch_bend <= 16383:
             raise self._EX_VALUEERROR_OOR
 
-    # channel value is mandatory
-    def as_bytes(self, *, channel=None):
-        return bytearray([self._STATUS | (channel & self.CHANNELMASK),
-                          self.pitch_bend & 0x7f,
-                          (self.pitch_bend >> 7) & 0x7f])
+    def __bytes__(self):
+        return bytes([self._STATUS | (self.channel & self.CHANNELMASK),
+                      self.pitch_bend & 0x7f,
+                      (self.pitch_bend >> 7) & 0x7f])
 
     @classmethod
-    def from_bytes(cls, databytes):
-        return cls(databytes[1] << 7 | databytes[0])
+    def from_bytes(cls, msg_bytes):
+        return cls(msg_bytes[2] << 7 | msg_bytes[1],
+                   channel=msg_bytes[0] & cls.CHANNELMASK)
 
 PitchBend.register_message_type()