Merge branch 'dev'

Author: tchellomello

.coveragerc

@@ -1,3 +1,6 @@
+[run]
+source = ring_doorbell
+
 [report]
 omit =
     */python?.?/*

README.md

@@ -0,0 +1,140 @@
+=====================
+Python Ring Door Bell
+=====================
+
+.. image:: https://badge.fury.io/py/ring-doorbell.svg
+    :target: https://badge.fury.io/py/ring-doorbell
+
+.. image:: https://travis-ci.org/tchellomello/python-ring-doorbell.svg?branch=master
+    :target: https://travis-ci.org/tchellomello/python-ring-doorbell
+
+.. image:: https://coveralls.io/repos/github/tchellomello/python-ring-doorbell/badge.svg
+    :target: https://coveralls.io/github/tchellomello/python-ring-doorbell
+
+.. image:: https://img.shields.io/pypi/pyversions/ring-doorbell.svg
+    :target: https://pypi.python.org/pypi/ring-doorbell
+
+
+Python Ring Door Bell is a library written in Python 2.7/3x
+that exposes the Ring.com devices as Python objects.
+
+*Currently Ring.com does not provide an official API. The results of this project are merely from reverse engineering.*
+
+
+Installation
+------------
+
+.. code-block:: bash
+
+    # Installing from PyPi
+    $ pip install ring_doorbell  #python 2.7
+    $ pip3 install ring_doorbell #python 3.x
+
+    # Installing latest development
+    $ pip3 install \
+        git+https://github.com/tchellomello/python-ring-doorbell@dev
+
+
+Initializing your Ring object
+-----------------------------
+
+.. code-block:: python
+
+    from ring_doorbell import Ring
+    myring = Ring('foo@bar', 'secret')
+
+    myring.is_connected
+    True
+
+    myring.has_subscription
+    True
+
+
+Listing devices linked to your account
+------------------------------------------
+
+.. code-block:: python
+
+    # All devices
+    myring.devices
+    {'chimes': [<RingChime: Downstairs>],
+    'doorbells': [<RingDoorBell: Front Door>]}
+
+    # All chimes
+    myring.chimes
+    [<RingChime: Downstairs>]
+
+    # All door bells
+    myring.doorbells
+    [<RingDoorBell: Front Door>]
+
+Playing with the attributes
+--------------------------------
+.. code-block:: python
+
+    for dev in list(myring.chimes + myring.doorbells):
+
+        # refresh data
+        dev.update()
+
+        print('Account ID: %s' % dev.account_id)
+        print('Address:    %s' % dev.address)
+        print('Family:     %s' % dev.family)
+        print('ID:         %s' % dev.id)
+        print('Name:       %s' % dev.name)
+        print('Timezone:   %s' % dev.timezone)
+
+        # setting dev volume
+        print('Volume:     %s' % dev.volume)
+        dev.volume = 5
+        print('Volume:     %s' % dev.volume)
+
+        # play dev test shound
+        if dev.family == 'chimes'
+            dev.test_sound
+
+
+Showing door bell events
+------------------------
+.. code-block:: python
+
+    for doorbell in myring.doorbells:
+
+        # listing the last 15 events of any kind
+        for event in doorbell.history(limit=15):
+            print('ID:       %s' % event['id'])
+            print('Kind:     %s' % event['kind'])
+            print('Answered: %s' % event['answered'])
+            print('When:     %s' % event['created_at'])
+            print('--' * 50)
+
+        # get a event list only the triggered by motion
+        events = doorbell.history(kind='motion')
+
+
+Downloading the last video triggered by ding
+-------------------------------------------
+.. code-block:: python
+
+    doorbell = myring.doorbells[0]
+    doorbell.recording_download(
+        doorbell.history(limit=100, kind='ding')[0]['id'],
+                         filename='/home/user/last_ding.mp4',
+                         override=True)
+
+
+Displaying the last video capture URL
+-------------------------------------------
+.. code-block:: python
+
+    print(doorbell.recording_url(doorbell.last_recording_id))
+    'https://ring-transcoded-videos.s3.amazonaws.com/99999999.mp4?X-Amz-Expires=3600&X-Amz-Date=20170313T232537Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=TOKEN_SECRET/us-east-1/s3/aws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=secret'
+
+Credits && Thanks
+-----------------
+
+* This project was inspired and based on https://github.com/jeroenmoors/php-ring-api. Many thanks @jeroenmoors.
+* A guy named MadBagger at Prism19 for his initial research (http://www.prism19.com/doorbot/second-pass-and-comm-reversing/)
+* The creators of mitmproxy (https://mitmproxy.org/) great http and https traffic inspector
+* @mfussenegger for his post on mitmproxy and virtualbox https://zignar.net/2015/12/31/sniffing-vbox-traffic-mitmproxy/
+* To the project http://www.android-x86.org/ which allowed me to install Android on KVM.

README.rst

@@ -13,7 +13,8 @@
 import requests
 import pytz
 
-from ring_doorbell.utils import _locator, _save_cache, _read_cache
+from ring_doorbell.utils import (
+    _locator, _clean_cache, _save_cache, _read_cache)
 from ring_doorbell.const import (
     API_VERSION, API_URI, CHIMES_ENDPOINT, CHIME_VOL_MIN, CHIME_VOL_MAX,
     DEVICES_ENDPOINT, DOORBELLS_ENDPOINT, DOORBELL_VOL_MIN, DOORBELL_VOL_MAX,
@@ -176,6 +177,11 @@ def __devices(self, device_type):
                 for member in list((obj['description'] for obj in req)):
                     lst.append(RingDoorBell(self, member))
 
+                # get shared doorbells, however device is read-only
+                req = self.query(url).get('authorized_doorbots')
+                for member in list((obj['description'] for obj in req)):
+                    lst.append(RingDoorBell(self, member, shared=True))
+
         except AttributeError:
             pass
         return lst
@@ -237,10 +243,13 @@ def _update_alert(self):
                     _save_cache(None, self._alert_cache)
 
     def _get_attrs(self):
-        """Return chime attributes."""
+        """Return attributes."""
         url = API_URI + DEVICES_ENDPOINT
         try:
-            lst = self._ring.query(url).get(self.family)
+            if self.family == 'doorbots' and self.shared:
+                lst = self._ring.query(url).get('authorized_doorbots')
+            else:
+                lst = self._ring.query(url).get(self.family)
             index = _locator(lst, 'description', self.name)
             if index == NOT_FOUND:
                 return None
@@ -343,11 +352,12 @@ def test_sound(self):
 class RingDoorBell(RingGeneric):
     """Implementation for Ring Doorbell."""
 
-    def __init__(self, ring, name):
+    def __init__(self, ring, name, shared=False):
         """Initilize Ring doorbell object."""
         super(RingDoorBell, self).__init__()
         self._attrs = None
         self._ring = ring
+        self.shared = shared
         self.debug = self._ring.debug
         self.family = 'doorbots'
         self.name = name
@@ -366,14 +376,15 @@ def check_alerts(self, cache=None):
         # save alerts attributes to an external pickle file
         # when multiple resources are checking for alerts
         if cache:
+            _clean_cache(cache)
             self._alert_cache = cache
 
         url = API_URI + DINGS_ENDPOINT
         self.update()
 
         try:
             resp = self._ring.query(url)[0]
-        except IndexError:
+        except (IndexError, TypeError):
             return None
 
         if resp:
@@ -517,7 +528,10 @@ def history(self, limit=30, timezone=None, kind=None):
     @property
     def last_recording_id(self):
         """Return the last recording ID."""
-        return self.history(limit=1)[0]['id']
+        try:
+            return self.history(limit=1)[0]['id']
+        except (IndexError, TypeError):
+            return None
 
     @property
     def live_streaming_json(self):
@@ -526,7 +540,10 @@ def live_streaming_json(self):
         req = self._ring.query((url), method='POST', raw=True)
         if req.status_code == 204:
             url = API_URI + DINGS_ENDPOINT
-            return self._ring.query(url)[0]
+            try:
+                return self._ring.query(url)[0]
+            except (IndexError, TypeError):
+                pass
         return None
 
     def recording_download(self, recording_id, filename=None, override=False):

ring_doorbell/__init__.py

@@ -19,6 +19,16 @@ def _locator(lst, key, value):
         return NOT_FOUND
 
 
+def _clean_cache(filename):
+    """Remove filename if pickle version mismatch."""
+    try:
+        if os.path.isfile(filename):
+            _read_cache(filename)
+    except ValueError:
+        os.remove(filename)
+    return True
+
+
 def _save_cache(data, filename):
     """Dump data into a pickle file."""
     try:
@@ -36,4 +46,3 @@ def _read_cache(filename):
             return pickle.load(open(filename, 'rb'))
     except:
         raise
-    return None

ring_doorbell/utils.py

@@ -5,7 +5,7 @@
 setup(
     name='ring_doorbell',
     packages=['ring_doorbell'],
-    version='0.1.1',
+    version='0.1.2',
     description='A Python library to communicate with Ring' +
                 ' Door Bell (https://ring.com/)',
     author='Marcelo Moreira de Mello',
@@ -28,7 +28,7 @@
         'Operating System :: OS Independent',
         'Programming Language :: Python',
         'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.5',
         'Topic :: Home Automation',
         'Topic :: Software Development :: Libraries :: Python Modules'
         ],