Merge pull request #1 from tannewt/lint

Lint it all.

Author: ladyada

README.rst

@@ -28,11 +28,6 @@ This is easily achieved by downloading
 
 Installing from PyPI
 =====================
-.. note:: This library is not available on PyPI yet. Install documentation is included
-   as a standard element. Stay tuned for PyPI availability!
-
-.. todo:: Remove the above note if PyPI version is/will be available at time of release.
-   If the library is not planned for PyPI, remove the entire 'Installing from PyPI' section.
 
 On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 PyPI <https://pypi.org/project/adafruit-circuitpython-ble_apple_media/>`_. To install for current user:
@@ -59,7 +54,50 @@ To install in a virtual environment in your current project:
 Usage Example
 =============
 
-.. todo:: Add a quick, simple example. It and other examples should live in the examples folder and be included in docs/examples.rst.
+.. code-block:: python
+
+    import adafruit_ble
+    from adafruit_ble.advertising.standard import SolicitServicesAdvertisement
+    from adafruit_ble_apple_media import AppleMediaService
+
+    radio = adafruit_ble.BLERadio()
+    a = SolicitServicesAdvertisement()
+    a.solicited_services.append(AppleMediaService)
+    radio.start_advertising(a)
+
+    while not radio.connected:
+        pass
+
+    print("connected")
+
+    known_notifications = set()
+
+    i = 0
+    while radio.connected:
+        for connection in radio.connections:
+            if not connection.paired:
+                connection.pair()
+                print("paired")
+
+            ams = connection[AppleMediaService]
+            print("App:", ams.player_name)
+            print("Title:", ams.title)
+            print("Album:", ams.album)
+            print("Artist:", ams.artist)
+            if ams.playing:
+                print("Playing")
+            elif ams.paused:
+                print("Paused")
+
+            if i > 3:
+                ams.toggle_play_pause()
+                i = 0
+        print()
+        time.sleep(3)
+        i += 1
+
+    print("disconnected")
+
 
 Contributing
 ============

adafruit_ble_apple_media.py

@@ -32,16 +32,18 @@
 import struct
 import time
 
+import _bleio
+
 from adafruit_ble.attributes import Attribute
 from adafruit_ble.characteristics import Characteristic, ComplexCharacteristic
 from adafruit_ble.uuid import VendorUUID
 from adafruit_ble.services import Service
 
-import _bleio
-
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_BLE_Apple_Media.git"
 
+# Disable protected access checks since our private classes are tightly coupled.
+# pylint: disable=protected-access
 
 class _RemoteCommand(ComplexCharacteristic):
     """Endpoint for sending commands to a media player. The value read will list all available
@@ -78,7 +80,7 @@ def bind(self, service):
         return _bleio.PacketBuffer(bound_characteristic,
                                    buffer_size=8)
 
-class _EntityAttribute(Characteristic):
+class _EntityAttribute(Characteristic): # pylint: disable=too-few-public-methods
     """UTF-8 Encoded string characteristic."""
     uuid = VendorUUID("C6B2F38C-23AB-46D8-A6AB-A3A870BBD5D7")
 
@@ -91,15 +93,18 @@ class _MediaAttribute:
     def __init__(self, entity_id, attribute_id):
         self.key = (entity_id, attribute_id)
 
-    def _update(self, obj):
+    @staticmethod
+    def _update(obj):
         if not obj._buffer:
             obj._buffer = bytearray(128)
-        len = obj._entity_update.readinto(obj._buffer)
-        if len > 0:
-            if len < 4:
+        length_read = obj._entity_update.readinto(obj._buffer)
+        if length_read > 0:
+            if length_read < 4:
                 raise RuntimeError("packet too short")
-            entity_id, attribute_id, flags = struct.unpack_from("<BBB", obj._buffer)
-            value = str(obj._buffer[3:len], "utf-8")
+            # Even though flags is currently unused, if it were removed, it would cause there to be
+            # too many values to unpack which would raise a ValueError
+            entity_id, attribute_id, flags = struct.unpack_from("<BBB", obj._buffer) # pylint: disable=unused-variable
+            value = str(obj._buffer[3:length_read], "utf-8")
             obj._attribute_cache[(entity_id, attribute_id)] = value
 
     def __get__(self, obj, cls):
@@ -137,35 +142,58 @@ def __get__(self, obj, cls):
         return 0
 
 class UnsupportedCommand(Exception):
-    pass
+    """Raised when the command isn't available with current media player app."""
 
 class AppleMediaService(Service):
-    """View and control currently playing media. Unimplemented."""
+    """View and control currently playing media.
+
+    Exact functionality varies with different media apps. For example, Spotify will include the
+    album name and artist name in `title` when controlling playback on a remote device.
+    `artist` includes a description of the remote playback.
+
+    """
     uuid = VendorUUID("89D3502B-0F36-433A-8EF4-C502AD55F8DC")
 
     _remote_command = _RemoteCommand()
     _entity_update = _EntityUpdate()
     _entity_attribute = _EntityAttribute()
 
     player_name = _MediaAttribute(0, 0)
+    """Name of the media player app"""
     _playback_info = _MediaAttribute(0, 1)
     paused = _MediaAttributePlaybackState(0)
+    """True when playback is paused. False otherwise."""
     playing = _MediaAttributePlaybackState(1)
+    """True when playback is playing. False otherwise."""
     rewinding = _MediaAttributePlaybackState(2)
+    """True when playback is rewinding. False otherwise."""
     fast_forwarding = _MediaAttributePlaybackState(3)
+    """True when playback is fast-forwarding. False otherwise."""
     playback_rate = _MediaAttributePlaybackInfo(1)
+    """Playback rate as a decimal of normal speed."""
     elapsed_time = _MediaAttributePlaybackInfo(2)
+    """Time elapsed in the current track. Not updated as the track plays. Use (the amount of time
+       since read elapsed time) * `playback_rate` to estimate the current `elapsed_time`."""
     volume = _MediaAttribute(0, 2)
+    """Current volume"""
 
     queue_index = _MediaAttribute(1, 0)
+    """Current track's index in the queue."""
     queue_length = _MediaAttribute(1, 1)
+    """Count of tracks in the queue."""
     shuffle_mode = _MediaAttribute(1, 2)
+    """Current shuffle mode as an integer. Off (0), One (1), and All (2)"""
     repeat_mode = _MediaAttribute(1, 3)
+    """Current repeat mode as an integer. Off (0), One (1), and All (2)"""
 
     artist = _MediaAttribute(2, 0)
+    """Current track's artist name."""
     album = _MediaAttribute(2, 1)
+    """Current track's album name."""
     title = _MediaAttribute(2, 2)
+    """Current track's title."""
     duration = _MediaAttribute(2, 3)
+    """Current track's duration as a string."""
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
@@ -179,7 +207,7 @@ def __init__(self, **kwargs):
     def _send_command(self, command_id):
         if not self._command_buffer:
             self._command_buffer = bytearray(13)
-        i = self._remote_command.readinto(self._command_buffer)
+        i = self._remote_command.readinto(self._command_buffer) # pylint: disable=no-member
         if i > 0:
             self._supported_commands = list(self._command_buffer[:i])
         if command_id not in self._supported_commands:
@@ -189,46 +217,60 @@ def _send_command(self, command_id):
         if not self._cmd:
             self._cmd = bytearray(1)
         self._cmd[0] = command_id
-        self._remote_command.write(self._cmd)
+        self._remote_command.write(self._cmd) # pylint: disable=no-member
 
     def play(self):
+        """Plays the current track. Does nothing if already playing."""
         self._send_command(0)
 
     def pause(self):
+        """Pauses the current track. Does nothing if already paused."""
         self._send_command(1)
 
     def toggle_play_pause(self):
+        """Plays the current track if it is paused. Otherwise it pauses the track."""
         self._send_command(2)
 
     def next_track(self):
+        """Stops playing the current track and plays the next one."""
         self._send_command(3)
 
     def previous_track(self):
+        """Stops playing the current track and plays the previous track."""
         self._send_command(4)
 
     def volume_up(self):
+        """Increases the playback volume."""
         self._send_command(5)
 
     def volume_down(self):
+        """Decreases the playback volume."""
         self._send_command(6)
 
     def advance_repeat_mode(self):
+        """Advances the repeat mode. Modes are: Off, One and All"""
         self._send_command(7)
 
     def advance_shuffle_mode(self):
+        """Advances the shuffle mode. Modes are: Off, One and All"""
         self._send_command(8)
 
     def skip_forward(self):
+        """Skips forwards in the current track"""
         self._send_command(9)
 
     def skip_backward(self):
+        """Skips backwards in the current track"""
         self._send_command(10)
 
     def like_track(self):
+        """Likes the current track"""
         self._send_command(11)
 
     def dislike_track(self):
+        """Dislikes the current track"""
         self._send_command(12)
 
     def bookmark_track(self):
+        """Bookmarks the current track"""
         self._send_command(13)

docs/conf.py

@@ -16,11 +16,10 @@
     'sphinx.ext.todo',
 ]
 
-# TODO: Please Read!
 # Uncomment the below if you use native CircuitPython modules such as
 # digitalio, micropython and busio. List the modules you use. Without it, the
 # autodoc module docs will fail to generate with a warning.
-# autodoc_mock_imports = ["digitalio", "busio"]
+# autodoc_mock_imports = []
 
 
 intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}

docs/index.rst

@@ -23,14 +23,12 @@ Table of Contents
 .. toctree::
     :caption: Tutorials
 
-.. todo:: Add any Learn guide links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
-
 .. toctree::
     :caption: Related Products
 
-.. todo:: Add any product links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
+    Adafruit Feather nRF52840 Express <https://www.adafruit.com/product/4062>
+
+    Adafruit ItsyBitsy nRF52840 Express - Bluetooth LE <https://www.adafruit.com/product/4481>
 
 .. toctree::
     :caption: Other Links

examples/ble_apple_media_simpletest.py

@@ -8,7 +8,8 @@
 from adafruit_ble.advertising.standard import SolicitServicesAdvertisement
 from adafruit_ble_apple_media import AppleMediaService
 
-radio = adafruit_ble.BLERadio()
+# PyLint can't find BLERadio for some reason so special case it here.
+radio = adafruit_ble.BLERadio() # pylint: disable=no-member
 a = SolicitServicesAdvertisement()
 a.solicited_services.append(AppleMediaService)
 radio.start_advertising(a)

requirements.txt

@@ -1 +1,2 @@
 Adafruit-Blinka
+adafruit-circuitpython-ble