<commit_before># Copyright (C) 2016 OpenMotics BV
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
""" The OpenMotics plugin decorators. """

from __future__ import absolute_import
import inspect
import logging


logger = logging.getLogger('openmotics')


def om_expose(method=None, auth=True, content_type='application/json'):
    """
    Decorator to expose a method of the plugin class through the
    webinterface. The url will be /plugins/<plugin-name>/<method>.

    Normally an authentication token is required to access the method.
    The token will be checked and removed automatically when using the
    following construction:

    @om_expose
    def method_to_expose(self, ...):
        pass

    It is possible to expose a method without authentication: no token
    will be required to access the method, this is done as follows:

    @om_expose(auth=False)
    def method_to_expose(self, ...):
        pass
    """
    def decorate(_method):
        _method.om_expose = {'method': _method,
                             'auth': auth,
                             'content_type': content_type,
                             'version': 1}
        return _method

    if method is not None:
        return decorate(method)
    return decorate


def input_status(method=None, version=1):
    """
    Decorator to indicate that the method should receive input status messages.
    The receiving method should accept one parameter, a tuple of (input, output).
    Each time an input changes status, the method will be called.

    Important! This method should not block, as this will result in an unresponsive system.
    Please use a separate thread to perform complex actions on input status messages.

    Initially only presses (rising edges) of input signals were handled, a version was introduced to support all
    input status changes, both falling and rising edges.
    """
    if method is not None:
        method.input_status = {'version': 1}
        return method

    def wrapper(_method):
        _method.input_status = {'version': version}
        return _method
    return wrapper


def output_status(method=None, version=1):
    """
    Decorator to indicate that the method should receive output status messages.
    The receiving method should accept one parameter, a list of tuples (output, dimmer value).
    Each time an output status is changed, the method will be called.

    Important! This method should not block, as this will result in an unresponsive system.
    Please use a separate thread to perform complex actions on output status messages.
    """
    if method is not None:
        method.output_status = {'version': 1}
        return method

    def wrapper(_method):
        _method.output_status = {'version': version}
        return _method
    return wrapper


def shutter_status(method):
    """
    Decorator to indicate that the method should receive shutter status messages.
    The receiving method should accept one parameter, the list of shutter states.
    Each time an shutter status is changed, the method will be called.

    Important! This method should not block, as this will result in an unresponsive system.<commit_msg>Added few more comments<commit_after># Copyright (C) 2016 OpenMotics BV
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
""" The OpenMotics plugin decorators. """

from __future__ import absolute_import
import inspect
import logging


logger = logging.getLogger('openmotics')


def om_expose(method=None, auth=True, content_type='application/json'):
    """
    Decorator to expose a method of the plugin class through the
    webinterface. The url will be /plugins/<plugin-name>/<method>.

    Normally an authentication token is required to access the method.
    The token will be checked and removed automatically when using the
    following construction:

    @om_expose
    def method_to_expose(self, ...):
        pass

    It is possible to expose a method without authentication: no token
    will be required to access the method, this is done as follows:

    @om_expose(auth=False)
    def method_to_expose(self, ...):
        pass
    """
    def decorate(_method):
        _method.om_expose = {'method': _method,
                             'auth': auth,
                             'content_type': content_type,
                             'version': 1}
        return _method

    if method is not None:
        return decorate(method)
    return decorate


def input_status(method=None, version=1):
    """
    Decorator to indicate that the method should receive input status messages.
    The receiving method should accept one parameter, a tuple of (input, output).
    Each time an input changes status, the method will be called.

    Important! This method should not block, as this will result in an unresponsive system.
    Please use a separate thread to perform complex actions on input status messages.

    Initially only presses (rising edges) of input signals were handled, a version was introduced to support all
    input status changes, both falling and rising edges.
    """
    if method is not None:
        method.input_status = {'version': 1}
        return method

    def wrapper(_method):
        _method.input_status = {'version': version}
        return _method
    return wrapper


def output_status(method=None, version=1):
    """
    Decorator to indicate that the method should receive output status messages.

    Version 1
    The receiving method should accept one parameter, a list of tuples (output, dimmer value).
    Each time an output status is changed, the method will be called.

    Version 2
    The receiving method should accept output_event data, only the output that has changed will be sent
    sample data:  {'id': 1, 'status': {'on': True, 'value': 5}, 'location': {'room_id': 5}}

    Important! This method should not block, as this will result in an unresponsive system.
    Please use a separate thread to perform complex actions on output status messages.
    """
    if method is not None:
        method.output_status = {'version': 1}
        return method

    def wrapper(_method):
        _method.output_status = {'version': version}
        return _method
    return wrapper


def shutter_status(method):
    """
    Decorator to indicate that the method should receive shutter status messages.
    The receiving method should accept one parameter, the list of shutter states.
    Each time an shutter status is changed, the method will be called.

    Important! This method should not block, as this will result in an unresponsive system.
{'fraction_non_alphanumeric': 0.06349003576903424, 'fraction_numerical': 0.0031936637710781807, 'mean_word_length': 3.096807953950811, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6518435', 'n_tokens_mistral': 1983, 'n_tokens_neox': 1903, 'n_words': 962}