add typing; cleanup code; add note on openhab 2; fix badges

Author: sim0nx

.gitignore

@@ -63,3 +63,5 @@ target/
 .pydevproject
 .project
 .settings
+.idea
+.mypy_cache

.landscape.yml

@@ -2,13 +2,17 @@
    :target: https://landscape.io/github/sim0nx/python-openhab/master
    :alt: Code Health
 
+.. image:: https://api.codacy.com/project/badge/Grade/c9f4e32e536f4150a8e7e18039f8f102
+   :target: https://www.codacy.com/app/sim0nx/python-openhab?utm_source=github.com&utm_medium=referral&utm_content=sim0nx/python-openhab&utm_campaign=Badge_Grade
+   :alt: Codacy badge
+
 .. image:: https://readthedocs.org/projects/pip/badge/?version=latest
    :target: http://python-openhab.readthedocs.io/en/latest/
    :alt: Documentation
 
-.. image:: https://www.quantifiedcode.com/api/v1/project/0cd779d9548547c09f69009316e548e1/badge.svg
-  :target: https://www.quantifiedcode.com/app/project/0cd779d9548547c09f69009316e548e1
-  :alt: Code issues
+.. image:: https://badge.fury.io/py/python-openhab.svg
+   :target: https://badge.fury.io/py/python-openhab
+   :alt: pypi version
 
 
 python library for accessing the openHAB REST API
@@ -23,11 +27,13 @@ Requirements
   - python 2.7.x / 3.5
   - python :: dateutil
   - python :: requests
+  - python :: typing
 
 Note on openHAB1:
 -----------------
 
-Make sure to use the 1.x branch for openHAB1.x!
+The current version is focused on OpenHAB 2.x; OpenHAB 1.x might still work, though this is not tested. If you require
+older OpenHAB support, please use an older version of this library.
 
 Installation
 ------------

README.rst

@@ -1,4 +1 @@
-from __future__ import absolute_import, division, print_function, unicode_literals
-
-from openhab.openhab import openHAB
-
+from openhab.openhab import OpenHAB, openHAB

openhab/__init__.py

@@ -1,9 +1,8 @@
-from __future__ import absolute_import, division, print_function, unicode_literals
 # -*- coding: utf-8 -*-
 """python library for accessing the openHAB REST API"""
 
 #
-# Georges Toth (c) 2016 <[email protected]>
+# Georges Toth (c) 2016-present <[email protected]>
 #
 # python-openhab is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -21,30 +20,34 @@
 
 # pylint: disable=bad-indentation
 
-import six
 import dateutil.parser
-from openhab.types import DateTimeType, OnOffType, DecimalType, OpenCloseType
+import typing
+
+import openhab
+import openhab.types
 
 __author__ = 'Georges Toth <[email protected]>'
 __license__ = 'AGPLv3+'
 
 
-class Item(object):
+class Item:
   """Base item class"""
-  def __init__(self, openhab, json_data):
+  types = []  # type: typing.List[typing.Type[openhab.types.CommandType]]
+
+  def __init__(self, openhab: openhab.OpenHAB, json_data: dict) -> None:
     """
     Args:
-      openhab (openHAB): openHAB object.
+      openhab (openhab.OpenHAB): openHAB object.
       json_data (dic): A dict converted from the JSON data returned by the openHAB
                        server.
     """
     self.openhab = openhab
     self.type_ = None
     self.name = ''
-    self._state = None
+    self._state = None  # type: typing.Optional[typing.Any]
     self.init_from_json(json_data)
 
-  def init_from_json(self, json_data):
+  def init_from_json(self, json_data: dict):
     """Initialize this object from a json configuration as fetched from
     openHAB
 
@@ -57,7 +60,7 @@ def init_from_json(self, json_data):
     self.__set_state(json_data['state'])
 
   @property
-  def state(self):
+  def state(self) -> typing.Any:
     """The state property represents the current state of the item. The state is
     automatically refreshed from openHAB on reading it.
     Updating the value via this property send an update to the event bus.
@@ -68,41 +71,41 @@ def state(self):
     return self._state
 
   @state.setter
-  def state(self, value):
+  def state(self, value: typing.Any):
     self.update(value)
 
-  def _validate_value(self, value):
+  def _validate_value(self, value: typing.Union[str, typing.Type[openhab.types.CommandType]]):
     """Private method for verifying the new value before modifying the state of the
     item.
     """
     if self.type_ == 'String':
-      if not isinstance(value, six.string_types):
+      if not isinstance(value, str):
         raise ValueError()
-    elif 'types' in dir(self):
+    elif len(self.types):
       for type_ in self.types:
         type_.validate(value)
     else:
       raise ValueError()
 
-  def _parse_rest(self, value):
+  def _parse_rest(self, value: str) -> str:
     """Parse a REST result into a native object."""
     return value
 
-  def _rest_format(self, value):
+  def _rest_format(self, value: str) -> str:
     """Format a value before submitting to openHAB."""
     return value
 
-  def __set_state(self, value):
+  def __set_state(self, value: str):
     """Private method for setting the internal state."""
     if value in ('UNDEF', 'NULL'):
       self._state = None
     else:
       self._state = self._parse_rest(value)
 
-  def __str__(self):
+  def __str__(self) -> str:
     return '<{0} - {1} : {2}>'.format(self.type_, self.name, self._state)
 
-  def update(self, value):
+  def update(self, value: typing.Any):
     """Updates the state of an item.
 
     Args:
@@ -115,7 +118,7 @@ def update(self, value):
 
     self.openhab.req_put('/items/' + self.name + '/state', data=v)
 
-  def command(self, value):
+  def command(self, value: typing.Any):
     """Sends the given value as command to the event bus.
 
     Args:
@@ -131,7 +134,7 @@ def command(self, value):
 
 class DateTimeItem(Item):
   """DateTime item type"""
-  types = [DateTimeType]
+  types = [openhab.types.DateTimeType]
 
   def __gt__(self, other):
     return self._state > other
@@ -171,7 +174,7 @@ def _rest_format(self, value):
 
 class SwitchItem(Item):
   """SwitchItem item type"""
-  types = [OnOffType]
+  types = [openhab.types.OnOffType]
 
   def on(self):
     """Set the state of the switch to ON"""
@@ -184,7 +187,7 @@ def off(self):
 
 class NumberItem(Item):
   """NumberItem item type"""
-  types = [DecimalType]
+  types = [openhab.types.DecimalType]
 
   def _parse_rest(self, value):
     """Parse a REST result into a native object
@@ -211,7 +214,7 @@ def _rest_format(self, value):
 
 class ContactItem(Item):
   """Contact item type"""
-  types = [OpenCloseType]
+  types = [openhab.types.OpenCloseType]
 
   def open(self):
     """Set the state of the contact item to OPEN"""

openhab/items.py

@@ -1,9 +1,8 @@
-from __future__ import absolute_import, division, print_function, unicode_literals
 # -*- coding: utf-8 -*-
 """python library for accessing the openHAB REST API"""
 
 #
-# Georges Toth (c) 2016 <[email protected]>
+# Georges Toth (c) 2016-present <[email protected]>
 #
 # python-openhab is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -24,17 +23,21 @@
 import requests
 from requests.auth import HTTPBasicAuth
 from openhab.items import Item, DateTimeItem, SwitchItem, NumberItem, ContactItem
+import warnings
+import typing
 
 __author__ = 'Georges Toth <[email protected]>'
 __license__ = 'AGPLv3+'
 
 
-
-class openHAB(object):
+class OpenHAB:
   """openHAB REST API client
   """
 
-  def __init__(self, base_url, username=None, password=None, http_auth=None):
+  def __init__(self, base_url: str,
+               username: typing.Optional[str] = None,
+               password: typing.Optional[str] = None,
+               http_auth: typing.Optional[requests.auth.AuthBase] = None) -> None:
     """
     Args:
       base_url (str): The openHAB REST URL, e.g. http://example.com/rest
@@ -46,7 +49,7 @@ def __init__(self, base_url, username=None, password=None, http_auth=None):
                             specify a custom http authentication object of type :class:`requests.auth.AuthBase`.
 
     Returns:
-      openHAB: openHAB class instance.
+      OpenHAB: openHAB class instance.
     """
     self.base_url = base_url
 
@@ -55,10 +58,11 @@ def __init__(self, base_url, username=None, password=None, http_auth=None):
 
     if http_auth is not None:
       self.session.auth = http_auth
-    elif username is not None and password is not None:
+    elif not(username is None or password is None):
       self.session.auth = HTTPBasicAuth(username, password)
 
-  def _check_req_return(self, req):
+  @staticmethod
+  def _check_req_return(req: requests.Response) -> None:
     """Internal method for checking the return value of a REST HTTP request.
 
     Args:
@@ -71,12 +75,12 @@ def _check_req_return(self, req):
       ValueError: Raises a ValueError exception in case of a non-successful
                   REST request.
     """
-    if not (req.status_code >= 200 and req.status_code < 300):
+    if not (200 <= req.status_code < 300):
       req.raise_for_status()
 
     return None
 
-  def req_get(self, uri_path):
+  def req_get(self, uri_path: str) -> typing.Any:
     """Helper method for initiating a HTTP GET request. Besides doing the actual
     request, it also checks the return value and returns the resulting decoded
     JSON data.
@@ -91,7 +95,7 @@ def req_get(self, uri_path):
     self._check_req_return(r)
     return r.json()
 
-  def req_post(self, uri_path, data=None):
+  def req_post(self, uri_path: str, data: typing.Optional[dict]=None) -> None:
     """Helper method for initiating a HTTP POST request. Besides doing the actual
     request, it also checks the return value and returns the resulting decoded
     JSON data.
@@ -108,7 +112,7 @@ def req_post(self, uri_path, data=None):
 
     return None
 
-  def req_put(self, uri_path, data=None):
+  def req_put(self, uri_path: str, data: typing.Optional[dict]=None) -> None:
     """Helper method for initiating a HTTP PUT request. Besides doing the actual
     request, it also checks the return value and returns the resulting decoded
     JSON data.
@@ -126,13 +130,13 @@ def req_put(self, uri_path, data=None):
     return None
 
   # fetch all items
-  def fetch_all_items(self):
+  def fetch_all_items(self) -> dict:
     """Returns all items defined in openHAB except for group-items
 
     Returns:
       dict: Returns a dict with item names as key and item class instances as value.
     """
-    items = {}
+    items = {}  # type: dict
     res = self.req_get('/items/')
 
     for i in res:
@@ -145,7 +149,7 @@ def fetch_all_items(self):
 
     return items
 
-  def get_item(self, name):
+  def get_item(self, name: str) -> object:
     """Returns an item with its state and type as fetched from openHAB
 
     Args:
@@ -158,7 +162,7 @@ def get_item(self, name):
 
     return self.json_to_item(json_data)
 
-  def json_to_item(self, json_data):
+  def json_to_item(self, json_data: dict) -> object:
     """This method takes as argument the RAW (JSON decoded) response for an openHAB
     item. It checks of what type the item is and returns a class instance of the
     specific item filled with the item's state.
@@ -180,7 +184,7 @@ def json_to_item(self, json_data):
     else:
       return Item(self, json_data)
 
-  def get_item_raw(self, name):
+  def get_item_raw(self, name: str) -> typing.Any:
     """Private method for fetching a json configuration of an item.
 
     Args:
@@ -190,3 +194,10 @@ def get_item_raw(self, name):
       dict: A JSON decoded dict.
     """
     return self.req_get('/items/{}'.format(name))
+
+
+class openHAB(OpenHAB):
+  def __init__(self, *args, **kwargs):
+    super().__init__(*args, **kwargs)
+
+    warnings.warn('The use of the "openHAB" class is deprecated, please use "OpenHAB" instead.', DeprecationWarning)