Merge pull request #85 from fronzbot/v0.9.0

V0.9.0

Author: fronzbot

.gitignore

@@ -9,3 +9,4 @@ htmlcov/*
 dist/*
 .sh
 build/*
+docs/_build

.travis.yml

@@ -1,3 +1,4 @@
+sudo: required
 matrix:
   fast_finish: true
   include:
@@ -7,12 +8,11 @@ matrix:
       env: TOXENV=py35
     - python: "3.6"
       env: TOXENV=py36
-    - python: "3.6-dev"
-      env: TOXENV=py36
     - python: "3.6"
       env: TOXENV=build
-    - python: "3.7-dev"
+    - python: "3.7"
       env: TOXENV=py37
+      dist: xenial
 
 install: pip install -U tox coveralls
 language: python

README.rst

@@ -38,29 +38,49 @@ This library was built with the intention of allowing easy communication with Bl
 
 Usage
 =========
-The simplest way to use this package from a terminal is to call ``Blink.start()`` which will prompt for your Blink username and password and then log you in.  Alternatively, you can instantiate the Blink class with a username and password, and call ``Blink.start()`` to login and setup without prompt, as shown below.
+The simplest way to use this package from a terminal is to call ``Blink.start()`` which will prompt for your Blink username and password and then log you in.  Alternatively, you can instantiate the Blink class with a username and password, and call ``Blink.start()`` to login and setup without prompt, as shown below.  In addition, http requests are throttled internally via use of the ``Blink.refresh_rate`` variable, which can be set at initialization and defaults to 30 seconds.
 
 .. code:: python
 
-    import blinkpy
-    blink = blinkpy.Blink(username='YOUR USER NAME', password='YOUR PASSWORD')
+    from blinkpy import blinkpy
+    blink = blinkpy.Blink(username='YOUR USER NAME', password='YOUR PASSWORD', refresh_rate=30)
     blink.start()
 
 If you would like to log in without setting up the cameras or system, you can simply call the ``Blink.login()`` function which will prompt for a username and password and then authenticate with the server.  This is useful if you want to avoid use of the ``start()`` function which simply acts as a wrapper for more targeted API methods.
 
-The cameras are of a BlinkCamera class, of which the following parameters can be used (the code below creates a Blink object and iterates through each camera found)
+Cameras are instantiated as individual ``BlinkCamera`` classes within a ``BlinkSyncModule`` instance.  Note: currently the API only supports one sync module, but multiple sync modules are planned to be supported in the future.
+
+The below code will display cameras and their available attributes:
 
 .. code:: python
 
-    import blinkpy
-    
+    from blinkpy import blinkpy
+
     blink = blinkpy.Blink(username='YOUR USER NAME', password='YOUR PASSWORD')
     blink.start()
-    
-    for name, camera in blink.cameras.items():
-        print(name)                  # Name of the camera
+
+    for name, camera in blink.sync.cameras.items():
+        print(name)                   # Name of the camera
         print(camera.attributes)      # Print available attributes of camera
 
+The most recent images and videos can be accessed as a bytes-object via internal variables.  These can be updated with calls to ``Blink.refresh()`` but will only make a request if motion has been detected or other changes have been found.  This can be overridden with the ``force_cache`` flag, but this should be used for debugging only since it overrides the internal request throttling.
+
+.. code:: python
+    
+    camera = blink.sync.camera['SOME CAMERA NAME']
+    blink.refresh(force_cache=True)  # force a cache update USE WITH CAUTION
+    camera.image_from_cache.raw  # bytes-like image object (jpg)
+    camera.video_from_cache.raw  # bytes-like video object (mp4)
+
+The ``blinkpy`` api also allows for saving images and videos to a file and snapping a new picture from the camera remotely:
+
+.. code:: python
+
+    camera = blink.sync.camera['SOME CAMERA NAME']
+    camera.snap_picture()       # Take a new picture with the camera
+    blink.refresh()             # Get new information from server
+    camera.image_to_file('/local/path/for/image.jpg')
+    camera.video_to_file('/local/path/for/video.mp4')
 
 .. |Build Status| image:: https://travis-ci.org/fronzbot/blinkpy.svg?branch=dev
    :target: https://travis-ci.org/fronzbot/blinkpy