python-ring-doorbell · tchellomello · Feb 15, 2017 · Feb 15, 2017 · Feb 15, 2017 · Feb 15, 2017
diff --git a/README.md b/README.md
@@ -1,26 +1,30 @@
-This project is a Python wrapper to access the Ring.com (http://www.ring.com) doorbell.
+This project is a Python 2.7/3.x wrapper to access the Ring.com (http://www.ring.com) doorbell.
 
 ## Install
 ```bash
-$ pip3 install git+https://github.com/tchellomello/python-ring-doorbell --upgrade
+# 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 --upgrade
 ```
 
 ## Usage
 ```python
 from ring_doorbell import Ring
-myring = Ring('user@me.com', 'secret')
+myring = Ring('user@email.com', 'secret')
 
-In [5]: myring.devices
-Out[5]: {'chimes': ['Downstairs'], 'doorbells': ['Front Door']}
+myring.devices
+{'chimes': ['Downstairs'], 'doorbells': ['Front Door']}
 
-In [6]: myring.chimes
-Out[6]: ['Downstairs']
+myring.chimes
+['Downstairs']
 
-In [7]: myring.doorbells
-Out[7]: ['Front Door']
+myring.doorbells
+['Front Door']
 
-In [8]: myring.chime_attributes('Downstairs')
-Out[8]:
+myring.chime_attributes('Downstairs')
 {'address': '123 Example St, New York, NY, USA',
  'alerts': {'connection': 'online'},
  'description': 'Downstairs',
@@ -45,11 +49,10 @@ Out[8]:
  'time_zone': 'America/New_York'}
 
 # for battery powered it will show a range 0-100
-In [9]: myring.doorbell_battery_life('Front Door')
-Out[9]: '4107
+myring.doorbell_battery_life('Front Door')
+'4107
 
-In [10]: myring.doorbell_attributes('Front Door')
-Out[10]:
+myring.doorbell_attributes('Front Door')
 {'address': '123 Example St, New York, NY, USA',
  'alerts': {'connection': 'online'},
  'battery_life': '4107',
@@ -74,37 +77,47 @@ Out[10]:
  'subscribed_motions': True,
  'time_zone': 'America/New_York'}
 
-In [11]: myring.history(limit=2)
-Out[11]:
+myring.history(limit=2, timezone='America/Sao_Paulo')
 [{'answered': False,
-  'created_at': '2017-02-08T22:22:15.000Z',
-  'doorbot': {'description': 'Front Door', 'id': 234},
+  'created_at': datetime.datetime(2017, 2, 14, 19, 51, 31, tzinfo=<DstTzInfo 'America/Sao_Paulo' BRST-1 day, 22:00:00 DST>),
+  'doorbot': {'description': 'Front Door', 'id': 12345},
   'events': [],
   'favorite': False,
-  'id': 12345,
+  'id': 1234,
   'kind': 'motion',
   'recording': {'status': 'ready'},
   'snapshot_url': ''},
  {'answered': False,
-  'created_at': '2017-02-08T12:09:26.000Z',
-  'doorbot': {'description': 'Front Door', 'id': 234},
+  'created_at': datetime.datetime(2017, 2, 14, 18, 26, 6, tzinfo=<DstTzInfo 'America/Sao_Paulo' BRST-1 day, 22:00:00 DST>),
+  'doorbot': {'description': 'Front Door', 'id': 12345},
   'events': [],
   'favorite': False,
-  'id': 123456,
+  'id': 12345,
+  'kind': 'motion',
+  'recording': {'status': 'ready'},
+  'snapshot_url': ''}]
+
+myring.history(name='Front Door', limit=1, timezone='America/Sao_Paulo')
+[{'answered': False,
+  'created_at': datetime.datetime(2017, 2, 14, 19, 51, 31, tzinfo=<DstTzInfo 'America/Sao_Paulo' BRST-1 day, 22:00:00 DST>),
+  'doorbot': {'description': 'Front Door', 'id': 12345},
+  'events': [],
+  'favorite': False,
+  'id': 1234,
   'kind': 'motion',
   'recording': {'status': 'ready'},
   'snapshot_url': ''}]
 
 # download video
-In [12]: myring.doorbell_download_recording(123456, '/home/user/test.mp4')
-Out[12]: True
+myring.doorbell_download_recording(123456, '/home/user/test.mp4')
+True
 
 # show video URL
-In [13]: myring.doorbell_recording_url(123456)
-Out[13]: 'https://ring-transcoded-videos.s3.amazonaws.com/123456.mp4?X-Amz-Expires=3600&X-Amz-Date=20170210T000928Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=zzzzzzzzzzzzAAA/20170210/us-east-1/s3/aws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
+myring.doorbell_recording_url(123456)
+'https://ring-transcoded-videos.s3.amazonaws.com/123456.mp4?X-Amz-Expires=3600&X-Amz-Date=20170210T000928Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=zzzzzzzzzzzzAAA/20170210/us-east-1/s3/aws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
 
 # generate live streaming
-In [14]: myring.live_streaming('Front Door')
+myring.live_streaming('Front Door')
 [{'audio_jitter_buffer_ms': 0,
   'device_kind': 'lpd_v1',
   'doorbot_description': 'Front Door',
@@ -131,9 +144,9 @@ In [14]: myring.live_streaming('Front Door')
   'video_jitter_buffer_ms': 0}]
 
 # push notifications (motion or ring)
-In [15]: while True:
-   ...:     time.sleep(3)
-   ...:     print(myring.check_activity)
+ while True:
+     time.sleep(3)
+     print(myring.check_activity)
 []
 []
 [{'audio_jitter_buffer_ms': 0,

diff --git a/ring_doorbell/__init__.py b/ring_doorbell/__init__.py
@@ -17,7 +17,8 @@
     API_VERSION, API_URI, DEVICES_ENDPOINT, DINGS_ENDPOINT,
     FILE_EXISTS, GENERIC_FAIL, HEADERS, LINKED_CHIMES_ENDPOINT,
     LIVE_STREAMING_ENDPOINT, NEW_SESSION_ENDPOINT, NOT_FOUND,
-    URL_HISTORY, URL_RECORDING, POST_DATA, RETRY_TOKEN)
+    URL_HISTORY, URL_DOORBELL_HISTORY, URL_RECORDING,
+    POST_DATA, RETRY_TOKEN)
 from ring_doorbell.utils import _locator
 
 _LOGGER = logging.getLogger(__name__)
@@ -306,11 +307,15 @@ def check_activity(self):
         url = API_URI + DINGS_ENDPOINT
         return self._query(url)
 
-    def history(self, limit=30, timezone=None):
+    def history(self, name=None, limit=30, timezone=None):
         """Return history with datetime objects."""
         # allow modify the items to return
         params = {'limit': str(limit)}
-        url = API_URI + URL_HISTORY
+
+        if name:
+            url = API_URI + URL_DOORBELL_HISTORY.format(self.doorbell_id(name))
+        else:
+            url = API_URI + URL_HISTORY
 
         response = self._query(url, extra_params=params)
 

diff --git a/ring_doorbell/const.py b/ring_doorbell/const.py
@@ -20,6 +20,7 @@
 LIVE_STREAMING_ENDPOINT = '/clients_api/doorbots/{0}/vod'
 NEW_SESSION_ENDPOINT = '/clients_api/session'
 URL_HISTORY = '/clients_api/doorbots/history'
+URL_DOORBELL_HISTORY = '/clients_api/doorbots/{0}/history'
 URL_RECORDING = '/clients_api/dings/{0}/recording'
 
 # structure acquired from reverse engineering to create auth token

diff --git a/setup.py b/setup.py
@@ -5,7 +5,7 @@
 setup(
     name='ring_doorbell',
     packages=['ring_doorbell'],
-    version='0.0.3',
+    version='0.0.4',
     description='A Python library to communicate with Ring' +
                 ' Door Bell (https://ring.com/)',
     author='Marcelo Moreira de Mello',
@@ -20,7 +20,6 @@
         'home automation',
         ],
     classifiers=[
-        'Development Status :: 3 - Alpha',
         'Environment :: Other Environment',
         'Intended Audience :: Developers',
         'License :: OSI Approved :: ' +