Metadata-Version: 2.1
Name: python-openhab
Version: 2.13.0
Summary: python library for accessing the openHAB REST API
Home-page: https://github.com/sim0nx/python-openhab
Author: Georges Toth
Author-email: georges@trypill.org
License: AGPLv3+
Download-URL: https://github.com/sim0nx/python-openhab
Keywords: openHAB
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.5
Requires-Dist: requests (>=2.4.3)
Requires-Dist: python-dateutil (>=2.2)

.. image:: https://api.codacy.com/project/badge/Grade/c9f4e32e536f4150a8e7e18039f8f102
   :target: https://www.codacy.com/app/sim0nx/python-openhab?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=sim0nx/python-openhab&amp;utm_campaign=Badge_Grade
   :alt: Codacy badge

.. image:: https://readthedocs.org/projects/python-openhab/badge/?version=latest
   :target: http://python-openhab.readthedocs.io/en/latest/?badge=latest
   :alt: Documentation Status

.. 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
=================================================

This library allows for easily accessing the OpenHAB REST API.
A number of features are implemented but not all, this is work in progress.

Requirements
------------

  - python >= 3.5
  - python :: dateutil
  - python :: requests
  - python :: typing

Note on openHAB1:
-----------------

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
------------

Install the latest version using pip:

.. code-block:: bash

  pip install python-openhab


Example
-------

Example usage of the library:

.. code-block:: python

    from openhab import openHAB

    base_url = 'http://localhost:8080/rest'
    openhab = OpenHAB(base_url)

    # fetch all items
    items = openhab.fetch_all_items()

    sunset = items.get('Sunset')
    print(sunset.state)

    # fetch a single item
    item = openhab.get_item('light_switch')

    # turn a switch on
    item.on()

    # send a state update (this only update the state)
    item.state = 'OFF'

    # send a command
    item.command('ON')

    # check if item state is NULL
    if item.state is None and item.is_state_null():
      pass

    # check if item state is UNDEF
    if item.state is None and item.is_state_undef():
      pass

    # fetch some group
    lights_group = openhab.get_item('lights_group')

    # send command to group
    lights_group.on()

    # send update to each member
    for v in lights_group.members.values():
      v.update('OFF')


Note on NULL and UNDEF
----------------------

In OpenHAB items may have two states named NULL and UNDEF, which have distinct meanings but basically indicate that an
item has no usable value.
This library sets the state of an item, regardless of their OpenHAB value being NULL or UNDEF, to None.
This in order to ease working with the library as we do cast certain types to native types.

In order to check if an item's state is either NULL or UNDEF, you can use the helper functions:

.. code-block:: python

    item.is_state_null()
    item.is_state_undef()

