Merge pull request #2 from devicehive/development

Release 1.0.0

.gitignore

@@ -0,0 +1,3 @@
+*.pyc
+.idea
+.cache

.travis.yml

@@ -0,0 +1,19 @@
+language: python
+python:
+    - pypy
+    - 2.7
+    - 3.5
+    - 3.6
+env: SYNTAX=true
+install:
+    - pip install -r requirements.txt
+    - pip install -r test_requirements.txt
+before_install:
+    - export DEVICE_HIVE_TRANSPORT_URL='http://playground-dev.devicehive.com/api/rest'
+    - openssl aes-256-cbc -K $encrypted_d0bb1d48c50b_key -iv $encrypted_d0bb1d48c50b_iv -in credentials.tar.enc -out credentials.tar -d
+    - tar xvf credentials.tar
+    - export DEVICE_HIVE_ADMIN_LOGIN=$(cat admin_login.txt)
+    - export DEVICE_HIVE_ADMIN_PASSWORD=$(cat admin_password.txt)
+    - export DEVICE_HIVE_CLIENT_LOGIN=$(cat client_login.txt)
+    - export DEVICE_HIVE_CLIENT_PASSWORD=$(cat client_password.txt)
+script: pytest -xv tests --transport-url=$DEVICE_HIVE_TRANSPORT_URL --admin-login=$DEVICE_HIVE_ADMIN_LOGIN --admin-password=$DEVICE_HIVE_ADMIN_PASSWORD --client-login=$DEVICE_HIVE_CLIENT_LOGIN --client-password=$DEVICE_HIVE_CLIENT_PASSWORD --tb=short

Dockerfile.tests

@@ -0,0 +1,50 @@
+# Copyright (C) 2018 DataArt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# =============================================================================
+
+
+FROM python:3.6
+
+WORKDIR /usr/src/app
+
+ENV TEST=''
+ENV TRANSPORT_URL='http://playground-dev.devicehive.com/api/rest'
+ENV ADMIN_REFRESH_TOKEN=''
+ENV CLIENT_REFRESH_TOKEN=''
+ENV ADMIN_ACCESS_TOKEN=''
+ENV CLIENT_ACCESS_TOKEN=''
+ENV ADMIN_LOGIN=''
+ENV ADMIN_PASSWORD=''
+ENV CLIENT_LOGIN=''
+ENV CLIENT_PASSWORD=''
+ENV LOG_LEVEL='INFO'
+
+COPY requirements.txt ./
+COPY test_requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir -r test_requirements.txt
+
+COPY . .
+
+ENTRYPOINT pytest -vx tests/$TEST\
+            --transport-url=$TRANSPORT_URL\
+            --admin-refresh-token=$ADMIN_REFRESH_TOKEN\
+            --admin-access-token=$ADMIN_ACCESS_TOKEN\
+            --client-refresh-token=$CLIENT_REFRESH_TOKEN\
+            --client-access-token=$CLIENT_ACCESS_TOKEN\
+            --admin-login=$ADMIN_LOGIN\
+            --admin-password=$ADMIN_PASSWORD\
+            --client-login=$CLIENT_LOGIN\
+            --client-password=$CLIENT_PASSWORD\
+            --log-level=$LOG_LEVEL

README.md

@@ -1 +1,236 @@
-# devicehive-plugin-python-template
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) 
+[![Build Status](https://travis-ci.org/devicehive/devicehive-plugin-python.svg?branch=master)](https://travis-ci.org/devicehive/devicehive-plugin-python)
+
+# Devicehive plugin
+This library provides wrapper for DeviceHive plugin API
+
+## Installation
+
+To install this package run:
+```bash
+pip install devicehive-plugin
+```
+
+## Creating a client using Plugin class
+
+First of all you need to create custom `Handler` class.
+
+`Handler` class provides several `handle_*` methods:
+* `handle_connect(self)` will be called after successful connection
+* `handle_event(self, event)` will be called after event of any type is received. Takes [ApiEvent](#apievent-object) object.
+* `handle_command_insert(self, command)` will be called after `command/insert` event is received. Takes [Command](#command-object) object.
+* `handle_command_update(self, command)` will be called after `command/update` event is received. Takes [Command](#command-object) object.
+* `handle_notification(self, notification)` will be called after `notification/insert` event is received. Takes [Notification](#notification-object) object.
+
+`handle_event` will be called before type-special `handle` methods.
+
+Example:
+
+```python
+from devicehive_plugin import Handler
+
+
+class SimpleHandler(Handler):
+
+    def handle_connect(self):
+        print('Successfully connected')
+
+    def handle_event(self, event):
+        print(event.action)
+        print(type(event.data))
+
+    def handle_command_insert(self, command):
+        print(command.command)
+
+    def handle_command_update(self, command):
+        print(command.command)
+
+    def handle_notification(self, notification):
+        print(notification.notification)
+```
+
+The second step is to use `Plugin` class for creating connection to the server.
+
+Example:
+
+```python
+from devicehive_plugin import Handler
+from devicehive_plugin import Plugin
+
+
+class SimpleHandler(Handler):
+
+    def handle_connect(self):
+        print('Successfully connected')
+
+    def handle_event(self, event):
+        print(event.action)
+        print(type(event.data))
+
+    def handle_command_insert(self, command):
+        print(command.command)
+
+    def handle_command_update(self, command):
+        print(command.command)
+
+    def handle_notification(self, notification):
+        print(notification.notification)
+
+
+url = 'ws://playground-dev.devicehive.com/plugin/proxy/'
+topic_name = 'PLUGIN_TOPIC_NAME'
+plugin_access_token = 'PLUGIN_ACCESS_TOKEN'
+plugin = Plugin(SimpleHandler)
+plugin.connect(url, topic_name, plugin_access_token=plugin_access_token)
+```
+
+### Custom handler args
+
+If you need to initialize your handler you can do it the next way:
+
+```python
+from devicehive_plugin import Handler
+from devicehive_plugin import Plugin
+
+
+class SimpleHandler(Handler):
+
+    def __init__(self, api, some_arg, some_kwarg):
+        super(SimpleHandler, self).__init__(api)
+        self._some_arg = some_arg
+        self._some_kwarg = some_kwarg
+
+
+plugin = Plugin(SimpleHandler, 'some_arg', some_kwarg='some_kwarg')
+```
+
+### Authentication
+
+There are several ways of initial authentication:
+
+* Using plugin's access token
+* Using plugin's refresh token
+* Using user's access token
+* Using user's refresh token
+* Using user's login and password
+
+If you want to use anything but plugin's access token you need to provide `auth_url` parameter.
+
+Examples:
+
+```python
+url = 'ws://playground-dev.devicehive.com/plugin/proxy/'
+topic_name = 'PLUGIN_TOPIC_NAME'
+plugin.connect(url, topic_name,
+               plugin_access_token='SOME_PLUGIN_ACCESS_TOKEN')
+```
+
+```python
+url = 'ws://playground-dev.devicehive.com/plugin/proxy/'
+topic_name = 'PLUGIN_TOPIC_NAME'
+auth_url = 'http://playground-dev.devicehive.com/api/rest'
+plugin.connect(url, topic_name, auth_url=auth_url,
+               plugin_refresh_token='SOME_PLUGIN_REFRESH_TOKEN')
+```
+
+```python
+url = 'ws://playground-dev.devicehive.com/plugin/proxy/'
+topic_name = 'PLUGIN_TOPIC_NAME'
+auth_url = 'http://playground-dev.devicehive.com/api/rest'
+plugin.connect(url, topic_name, auth_url=auth_url,
+               access_token='SOME_USER_ACCESS_TOKEN')
+```
+
+```python
+url = 'ws://playground-dev.devicehive.com/plugin/proxy/'
+topic_name = 'PLUGIN_TOPIC_NAME'
+auth_url = 'http://playground-dev.devicehive.com/api/rest'
+plugin.connect(url, topic_name, auth_url=auth_url,
+               refresh_token='SOME_USER_REFRESH_TOKEN')
+```
+
+```python
+url = 'ws://playground-dev.devicehive.com/plugin/proxy/'
+topic_name = 'PLUGIN_TOPIC_NAME'
+auth_url = 'http://playground-dev.devicehive.com/api/rest'
+plugin.connect(url, topic_name, auth_url=auth_url,
+               login='SOME_USER_LOGIN', password='SOME_USER_PASSWORD')
+```
+
+## Api reference
+
+### ApiEvent object
+
+Properties (read only):
+
+* `is_command_insert_event`
+* `is_command_update_event`
+* `is_command_event`
+* `is_notification_event`
+* `action`
+* `raw_data`
+* `data`
+
+### Command object
+
+Properties (read only):
+
+* `id`
+* `user_id`
+* `command`
+* `parameters`
+* `lifetime`
+* `timestamp`
+* `last_updated`
+* `status`
+* `result`
+
+### Notification object
+
+Properties (read only):
+
+* `device_id`
+* `id`
+* `notification`
+* `parameters`
+* `timestamp`
+
+## Docker tests
+
+### Build image
+
+```
+docker build -f Dockerfile -t devicehive-plugin-tests .
+```
+
+### Run tests
+
+You can run tests with refresh_token by setting `ADMIN_REFRESH_TOKEN` and/or `CLIENT_REFRESH_TOKEN` variable:
+
+```
+docker run -it -e ADMIN_REFRESH_TOKEN='SOME_ADMIN_REFRESH_TOKEN' devicehive-plugin-tests
+```
+
+Or with access_token by setting `ADMIN_ACCESS_TOKEN` and/or `CLIENT_ACCESS_TOKEN` variable:
+
+```
+docker run -it -e ADMIN_ACCESS_TOKEN='SOME_ADMIN_ACCESS_TOKEN' devicehive-plugin-tests
+```
+
+Or with user login and password by setting `ADMIN_LOGIN` and `ADMIN_PASSWORD` for admin account and/or `CLIENT_LOGIN` and `CLIENT_PASSWORD` for client account.
+
+```
+docker run -it -e ADMIN_LOGIN='SOME_ADMIN_LOGIN' -e ADMIN_PASSWORD='SOME_ADMIN_PASSWORD' devicehive-plugin-tests
+```
+
+To run tests with enabled requests logging you need to change `LOG_LEVEL` variable:
+
+```
+docker run -it -e ADMIN_REFRESH_TOKEN='SOME_ADMIN_REFRESH_TOKEN' -e LOG_LEVEL='DEBUG' devicehive-plugin-tests
+```
+
+To run the specific test you need to set `TEST` variable:
+
+```
+docker run -it -e TEST=test_api.py::test_get_info -e ADMIN_REFRESH_TOKEN='SOME_ADMIN_REFRESH_TOKEN' devicehive-plugin-tests
+```

devicehive_plugin/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (C) 2018 DataArt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# =============================================================================
+
+
+from .plugin import Plugin
+from .handler import Handler
+
+
+__version__ = "1.0.0"

devicehive_plugin/api.py

@@ -0,0 +1,58 @@
+# Copyright (C) 2018 DataArt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# =============================================================================
+
+
+from devicehive_plugin.message import RequestMessage
+from devicehive_plugin.token import Token
+
+__all__ = ['Api']
+
+
+class Api(object):
+
+    def __init__(self, transport, credentials, topic_name):
+        self._transport = transport
+        self._token = Token(self, credentials, topic_name)
+        self._topic_name = topic_name
+        self._connected = True
+
+    @property
+    def connected(self):
+        return self._connected
+
+    @property
+    def transport(self):
+        return self._transport
+
+    def authenticate(self):
+        self._token.auth()
+
+    def subscribe(self):
+        request = RequestMessage(self, RequestMessage.TOPIC_TYPE,
+                                 RequestMessage.SUBSCRIBE_ACTION)
+        request.set_payload('t', [self._topic_name])
+        return request.execute()
+
+    def unsubscribe(self):
+        request = RequestMessage(self, RequestMessage.TOPIC_TYPE,
+                                 RequestMessage.UNSUBSCRIBE_ACTION)
+        request.set_payload('t', [self._topic_name])
+        return request.execute()
+
+    def disconnect(self):
+        self._connected = False
+        if not self._transport.connected:
+            return
+        self._transport.disconnect()