========================
Carson Living Python API
========================
.. image:: https://badge.fury.io/py/carson-living.svg
:target: https://badge.fury.io/py/carson-living
.. image:: https://travis-ci.org/rado0x54/python-carson-living.svg?branch=master
:target: https://travis-ci.org/rado0x54/python-carson-living
.. image:: https://coveralls.io/repos/github/rado0x54/python-carson-living/badge.svg?branch=master
:target: https://coveralls.io/github/rado0x54/python-carson-living?branch=master
.. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
:target: https://opensource.org/licenses/Apache-2.0
.. image:: https://img.shields.io/pypi/pyversions/carson-living.svg
:target: https://pypi.python.org/pypi/carson-living
Python Carson Living is a library written in Python that exposes the carson.live devices as Python objects.
Disclaimer
----------
Please use this library at your own risk and make sure that you do not violate the
`Terms of Service of Carson <https://www.carson.live/terms>`_.
Getting started
---------------
Installation
~~~~~~~~~~~~~
Carson Living Python should work against **Python 2.x >= 2.7** and **Python 3.x >= 3.5**.
.. code-block::
# Installing from PyPi
$ pip install carson_living
# Installing latest development
$ pip install \
git+https://github.com/rado0x54/python-carson-living@master
Initialize a Carson API object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
# Initializing an API object
carson = Carson("account@email.com", 'your password')
print(carson.user)
# >> Martin
print(carson.token)
# >> ey...
You are also able to pass a valid JWT token during initialization which would prevent a login action as long as the token is valid:
.. code-block:: python
# Initializing an API object with a valid token
carson = Carson("account@email.com", 'your password', 'ey....')
print(carson.token)
# >> Martin
Since Carson Living uses JWT token with very long validity, it is recommended to save the active token via
``carson.token``, whenever one needs to reinitialize the API later on. The API library is robust to handle expired
JWT tokens (and 401 handling), so no need to check before.
Carson entities
~~~~~~~~~~~~~~~
The library currently supports the following entities and actions.
- User (``carson.user``): read
- Building (``carson.buildings``): read
- Doors (``building.doors``): read, open
- Cameras (``building.cameras``): read, images, video
Door entities
~~~~~~~~~~~~~
Doors can be "buzzed" open via ``door.open()``
.. code-block:: python
# Open all Unit Doors of Main Building
for door in carson.first_building.doors:
if door.is_unit_door:
print('Opening Unit Door {}'.format(door.name))
door.open()
Camera entities
~~~~~~~~~~~~~~~
Eagle Eye cameras can produce live images and videos but also allow access to passed recordings (see API). The API can download the image and video directly into a provided file object
or just pass a generated url with an eagle_eye auth key ``A=c000....``. Please note, that the url can only be accessed as long as the ``auth_key`` is valid. Therefore it may make sense to
force the eagle eye api to refresh the auth key before generating a image or video url.
- Directly save a live image:
.. code-block:: python
for camera in building.cameras:
with open('image_{}.jpeg'.format(camera.entity_id), 'wb') as file:
camera.get_image(file)
- Directly save a live video of 10s:
.. code-block:: python
for camera in building.cameras:
with open('video_{}.flv'.format(camera.entity_id), 'wb') as file:
camera.get_video(file, timedelta(seconds=10))
- Directly download a image from a timestamp:
.. code-block:: python
three_hours_ago = datetime.utcnow() - timedelta(hours=3)
# download all images from 3 hours ago
for camera in building.cameras:
with open('image_{}.jpeg'.format(camera.entity_id), 'wb') as file:
camera.get_image(file, three_hours_ago)
- Directly download a recorded video from a timestamp:
.. code-block:: python
three_days_ago = datetime.utcnow() - timedelta(days=3)
# download all videos from 3 days ago
for cam in building.cameras:
with open('video_{}.flv'.format(cam.entity_id), 'wb') as file:
cam.get_video(file, timedelta(seconds=5), three_days_ago)
- The Carson API is also able to produce authenticated URLs that can be handled externally.
Please not, that the ``auth_key`` has a limited lifetime. Therefore it makes sense to update
the ``auth_key`` manually before retrieving predefined URLs. Note, the Eagle Eye API in Carson
is associated with a building, so it is sufficient to update it once for all cameras in the same
building. The function signature of the the ``_url`` function is identical to the previous ones
(minus the file object).
.. code-block:: python
# Update Session Auth Key of Eagle Eye once in a while if using
# generated authenticated URLs.
# Note, this is not needed for get_image() or get_video()
building.eagleeye_api.update_session_auth_key()
for cam in building.cameras:
img_url = cam.get_image_url(three_days_ago)
print(img_url)
# >> https://cXXX.eagleeyenetworks.com/asset/prev/image.jpeg?id=c0×tamp=20200122211442.575&asset_class=pre&A=c000~...
response = requests.get(img_url)
with open('image_{}_with_url.jpeg'.format(cam.entity_id), 'wb') as file:
file.write(response.content)
# do only 1 cam.
break
Use ``cam.get_video_url()`` the same way.
CLI Tool
~~~~~~~~
Checkout ``./scripts/carsoncli.py`` for further API implementation examples.
Development Notes
-----------------
Code Documentation
~~~~~~~~~~~~~~~~~~
The code follow the `Google Python Styleguide <https://google.github.io/styleguide/pyguide.html>`_ for docstring.
Git Branching Strategy
~~~~~~~~~~~~~~~~~~~~~~
This project uses `gitflow <https://nvie.com/posts/a-successful-git-branching-model/>`_ as a git branching model.
Open Items
~~~~~~~~~~
The following is not supported by the API yet and remains TODO.
- Expose visitor functionality (``/visitors``)
- Expose thread / messaging functionality (``/threads``)
- Expose delivery functionality (``/deliveries``)
- Expose dashboard functionality (``/dashboard``)
- Expose service functionality (``/service``)
- Integrate Twilio (``twilio/access-token/``)
- Expand and extract EagleEye API (into separate project?).
Credits && Thanks
-----------------
* A lot of the project setup and the API object design was inspired / launched off https://github.com/tchellomello/python-ring-doorbell. Saved me a lot of headaches with tox, setuptools and Travis!.
Raw data
{
"_id": null,
"home_page": "https://github.com/rado0x54/python-carson-living",
"name": "carson-living-library",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
"maintainer_email": "",
"keywords": "carson living,virtual doorman,home automation",
"author": "Martin Riedel",
"author_email": "web@riedel-it.de",
"download_url": "https://files.pythonhosted.org/packages/e6/da/f6cf615cc621a233412c4a3ff4385d8c011640c211d22b87afb093874252/carson_living_library-0.0.2.tar.gz",
"platform": null,
"description": "========================\nCarson Living Python API\n========================\n\n.. image:: https://badge.fury.io/py/carson-living.svg\n :target: https://badge.fury.io/py/carson-living\n\n.. image:: https://travis-ci.org/rado0x54/python-carson-living.svg?branch=master\n :target: https://travis-ci.org/rado0x54/python-carson-living\n\n.. image:: https://coveralls.io/repos/github/rado0x54/python-carson-living/badge.svg?branch=master\n :target: https://coveralls.io/github/rado0x54/python-carson-living?branch=master\n\n.. image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg\n :target: https://opensource.org/licenses/Apache-2.0\n\n.. image:: https://img.shields.io/pypi/pyversions/carson-living.svg\n :target: https://pypi.python.org/pypi/carson-living\n\nPython Carson Living is a library written in Python that exposes the carson.live devices as Python objects.\n\nDisclaimer\n----------\nPlease use this library at your own risk and make sure that you do not violate the\n`Terms of Service of Carson <https://www.carson.live/terms>`_.\n\nGetting started\n---------------\nInstallation\n~~~~~~~~~~~~~\n\nCarson Living Python should work against **Python 2.x >= 2.7** and **Python 3.x >= 3.5**.\n\n.. code-block::\n\n # Installing from PyPi\n $ pip install carson_living\n\n # Installing latest development\n $ pip install \\\n git+https://github.com/rado0x54/python-carson-living@master\n\nInitialize a Carson API object\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n # Initializing an API object\n carson = Carson(\"account@email.com\", 'your password')\n print(carson.user)\n # >> Martin\n print(carson.token)\n # >> ey...\n\nYou are also able to pass a valid JWT token during initialization which would prevent a login action as long as the token is valid:\n\n.. code-block:: python\n\n # Initializing an API object with a valid token\n carson = Carson(\"account@email.com\", 'your password', 'ey....')\n print(carson.token)\n # >> Martin\n\nSince Carson Living uses JWT token with very long validity, it is recommended to save the active token via\n``carson.token``, whenever one needs to reinitialize the API later on. The API library is robust to handle expired\nJWT tokens (and 401 handling), so no need to check before.\n\nCarson entities\n~~~~~~~~~~~~~~~\nThe library currently supports the following entities and actions.\n\n- User (``carson.user``): read\n- Building (``carson.buildings``): read\n- Doors (``building.doors``): read, open\n- Cameras (``building.cameras``): read, images, video\n\nDoor entities\n~~~~~~~~~~~~~\nDoors can be \"buzzed\" open via ``door.open()``\n\n.. code-block:: python\n\n # Open all Unit Doors of Main Building\n for door in carson.first_building.doors:\n if door.is_unit_door:\n print('Opening Unit Door {}'.format(door.name))\n door.open()\n\nCamera entities\n~~~~~~~~~~~~~~~\nEagle Eye cameras can produce live images and videos but also allow access to passed recordings (see API). The API can download the image and video directly into a provided file object\nor just pass a generated url with an eagle_eye auth key ``A=c000....``. Please note, that the url can only be accessed as long as the ``auth_key`` is valid. Therefore it may make sense to\nforce the eagle eye api to refresh the auth key before generating a image or video url.\n\n- Directly save a live image:\n\n.. code-block:: python\n\n for camera in building.cameras:\n with open('image_{}.jpeg'.format(camera.entity_id), 'wb') as file:\n camera.get_image(file)\n\n- Directly save a live video of 10s:\n\n.. code-block:: python\n\n for camera in building.cameras:\n with open('video_{}.flv'.format(camera.entity_id), 'wb') as file:\n camera.get_video(file, timedelta(seconds=10))\n\n- Directly download a image from a timestamp:\n\n.. code-block:: python\n\n three_hours_ago = datetime.utcnow() - timedelta(hours=3)\n # download all images from 3 hours ago\n for camera in building.cameras:\n with open('image_{}.jpeg'.format(camera.entity_id), 'wb') as file:\n camera.get_image(file, three_hours_ago)\n\n- Directly download a recorded video from a timestamp:\n\n.. code-block:: python\n\n three_days_ago = datetime.utcnow() - timedelta(days=3)\n # download all videos from 3 days ago\n for cam in building.cameras:\n with open('video_{}.flv'.format(cam.entity_id), 'wb') as file:\n cam.get_video(file, timedelta(seconds=5), three_days_ago)\n\n- The Carson API is also able to produce authenticated URLs that can be handled externally.\n Please not, that the ``auth_key`` has a limited lifetime. Therefore it makes sense to update\n the ``auth_key`` manually before retrieving predefined URLs. Note, the Eagle Eye API in Carson\n is associated with a building, so it is sufficient to update it once for all cameras in the same\n building. The function signature of the the ``_url`` function is identical to the previous ones\n (minus the file object).\n\n.. code-block:: python\n\n # Update Session Auth Key of Eagle Eye once in a while if using\n # generated authenticated URLs.\n # Note, this is not needed for get_image() or get_video()\n building.eagleeye_api.update_session_auth_key()\n for cam in building.cameras:\n img_url = cam.get_image_url(three_days_ago)\n print(img_url)\n # >> https://cXXX.eagleeyenetworks.com/asset/prev/image.jpeg?id=c0×tamp=20200122211442.575&asset_class=pre&A=c000~...\n response = requests.get(img_url)\n with open('image_{}_with_url.jpeg'.format(cam.entity_id), 'wb') as file:\n file.write(response.content)\n # do only 1 cam.\n break\n\nUse ``cam.get_video_url()`` the same way.\n\nCLI Tool\n~~~~~~~~\nCheckout ``./scripts/carsoncli.py`` for further API implementation examples.\n\nDevelopment Notes\n-----------------\n\nCode Documentation\n~~~~~~~~~~~~~~~~~~\nThe code follow the `Google Python Styleguide <https://google.github.io/styleguide/pyguide.html>`_ for docstring.\n\nGit Branching Strategy\n~~~~~~~~~~~~~~~~~~~~~~\nThis project uses `gitflow <https://nvie.com/posts/a-successful-git-branching-model/>`_ as a git branching model.\n\nOpen Items\n~~~~~~~~~~\nThe following is not supported by the API yet and remains TODO.\n\n- Expose visitor functionality (``/visitors``)\n- Expose thread / messaging functionality (``/threads``)\n- Expose delivery functionality (``/deliveries``)\n- Expose dashboard functionality (``/dashboard``)\n- Expose service functionality (``/service``)\n- Integrate Twilio (``twilio/access-token/``)\n- Expand and extract EagleEye API (into separate project?).\n\n\nCredits && Thanks\n-----------------\n\n* A lot of the project setup and the API object design was inspired / launched off https://github.com/tchellomello/python-ring-doorbell. Saved me a lot of headaches with tox, setuptools and Travis!.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "A Python library to communicate with Carson Living Residences (https://www.carson.live/)",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/rado0x54/python-carson-living"
},
"split_keywords": [
"carson living",
"virtual doorman",
"home automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe953b74cc70cf8c437694f8af1ca79429d9e3f8ebd8789be74e246c06ffaaae",
"md5": "3cd28c5c8c95e47057a0839c97d0bb82",
"sha256": "fc16ba9f0ea7158c46da51839569dbb073752fe4c1fe34f6b7aa0dbeb2c341bf"
},
"downloads": -1,
"filename": "carson_living_library-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3cd28c5c8c95e47057a0839c97d0bb82",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
"size": 23102,
"upload_time": "2023-08-31T14:48:25",
"upload_time_iso_8601": "2023-08-31T14:48:25.208745Z",
"url": "https://files.pythonhosted.org/packages/fe/95/3b74cc70cf8c437694f8af1ca79429d9e3f8ebd8789be74e246c06ffaaae/carson_living_library-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e6daf6cf615cc621a233412c4a3ff4385d8c011640c211d22b87afb093874252",
"md5": "cf3beea083e3c7346c376eb53bb57037",
"sha256": "d7a28533cae519eb2d6d27fc3a79d854e8786c9c0bc8e5a0ad00c67f61777a86"
},
"downloads": -1,
"filename": "carson_living_library-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "cf3beea083e3c7346c376eb53bb57037",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
"size": 26930,
"upload_time": "2023-08-31T14:48:26",
"upload_time_iso_8601": "2023-08-31T14:48:26.608953Z",
"url": "https://files.pythonhosted.org/packages/e6/da/f6cf615cc621a233412c4a3ff4385d8c011640c211d22b87afb093874252/carson_living_library-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-31 14:48:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rado0x54",
"github_project": "python-carson-living",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "carson-living-library"
}
JSON
