thingsboard-common 0.1.1__py3-none-any.whl

thingsboard/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+
+# Tell python that there are more sub-packages present, physically located elsewhere.
+# See: https://stackoverflow.com/questions/8936884/python-import-path-packages-with-the-same-name-in-different-folders
+import pkgutil
+
+__path__ = pkgutil.extend_path(__path__, __name__)

thingsboard/common/__init__.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+
+# Tell python that there are more sub-packages present, physically located elsewhere.
+# See: https://stackoverflow.com/questions/8936884/python-import-path-packages-with-the-same-name-in-different-folders
+import pkgutil
+
+__path__ = pkgutil.extend_path(__path__, __name__)
+
+import logging
+from .version import __version__ as version
+
+# Do not output logs if logging module is not configured
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+logging.getLogger(__name__).info(f'thingsboard-common version: {version}')

thingsboard/common/core/__init__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+# Tell python that there are more sub-packages present, physically located elsewhere.
+# See: https://stackoverflow.com/questions/8936884/python-import-path-packages-with-the-same-name-in-different-folders
+import pkgutil
+
+__path__ = pkgutil.extend_path(__path__, __name__)
+
+from .threaded import Threaded
+from .thread_monitor import ThreadMonitor

thingsboard/common/core/thread_monitor.py

@@ -0,0 +1,55 @@
+import logging
+
+from thingsboard.common.core.threaded import Threaded
+
+
+class ThreadMonitor(object):
+    """Monitors registered threads.
+
+    It is a passive class. To check if threads are still alive, call method check_threads() regularly.
+    """
+    log = logging.getLogger(__name__)
+    threadList = []
+
+    # References single instance of this class.
+    _instance = None            # type: ThreadMonitor or None
+
+    def __init__(self, log_name_prefix:str=''):
+        super(ThreadMonitor, self).__init__()
+        if self._instance:
+            assert False, 'Only one instance of this class is allowed'
+        else:
+            self._set_instance(self)
+            if log_name_prefix:
+                type(self).log = logging.getLogger(log_name_prefix + '.' + __name__)
+
+    @classmethod
+    def instance(cls):
+        """Returns the single instance of this class.
+        """
+        assert cls._instance, 'Create an instance of this class first'
+        return cls._instance
+
+    @classmethod
+    def _set_instance(cls, instance):
+        assert cls._instance is None, 'Only one instance of this class allowed'
+        cls._instance = instance
+
+    @classmethod
+    def register(cls, thread: Threaded):
+        cls.threadList.append(thread)
+        return True
+
+    @classmethod
+    def deregister(cls, thread: Threaded):
+        if thread in cls.threadList:
+            cls.threadList.remove(thread)
+        return True
+
+    @classmethod
+    def check_threads(cls):
+        for thread in cls.threadList:
+            if not thread.is_alive():
+                cls.log.error(f'Thread \'{thread.name}\' no more alive!')
+                return False
+        return True

thingsboard/common/core/threaded.py

@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+
+import logging
+import time
+from threading import Condition
+from threading import Thread
+
+
+class Threaded(object):
+    """Provides a _thread which executes the _run() method at regular intervals.
+
+    Features:
+     - Thread supervision by ThreadMonitor
+     - Correct logging when exception occurs
+     - Thread reacts immediately on exit loop request (_thread_should_run)
+    """
+
+    log = logging.getLogger(__name__)
+
+    def __init__(self, control_interval_in_seconds=4.0, thread_monitor=None, **kwargs):
+        super(Threaded, self).__init__(**kwargs)
+        self._thread_monitor = thread_monitor  # type: ThreadMonitor
+        self._thread = None  # type: Thread or None # Thread executing the needed behavior
+        self._thread_should_run = True  # Controls the loop of the _thread
+        self._thread_left_run_loop = False  # Set to true when _thread is leaving run loop
+        self._control_interval_in_seconds = control_interval_in_seconds  # Time to wait until next processing
+        self._sleep_condition = Condition()
+
+    def setup_thread(self, name=None, thread_monitor=None):
+
+        if thread_monitor:
+            assert not self._thread_monitor, 'Thread monitor should be initialized only once!'
+            self._thread_monitor = thread_monitor
+
+        if not name:
+            name = self.__class__.__name__
+
+        # Create a _thread that regularly polls the actual parameters of the real battery
+        self._thread = Thread(target=self._run_with_exception_logging, name=name,
+                              daemon=True   # Close _thread as soon as main _thread exits
+                              )
+
+        if self._thread_monitor:
+            # Register _thread for later monitor of itself. Thread monitor allows to take action
+            # in case the _thread crashes.
+            self._thread_monitor.register(self._thread)
+
+    def start_thread(self):
+        if self._thread is None:
+            self.log.warning('Thread not created. Calling setThread() for you!')
+            self.setup_thread()
+
+        # Reset run attributes
+        self._thread_should_run = True
+        self._thread_left_run_loop = False
+
+        self._thread.start()
+
+    def stop_thread(self):
+        # Remove _thread from monitor
+        if self._thread_monitor:
+            self._thread_monitor.deregister(self._thread)
+
+        # Tell _thread it should leave
+        self._thread_should_run = False
+        # Wait until it is gone
+        if self._thread.is_alive():
+            self.wait_on_thread_to_leave()
+        # Delete instance
+        del self._thread
+        self._thread = None
+
+    def wakeup_thread(self):
+        """Wakes up _thread in case it is sleeping.
+        """
+        # Release _thread waiting on condition
+        with self._sleep_condition:
+            self._sleep_condition.notify()
+
+    def join(self):
+        """Wait for the internal _thread until it leaves.
+
+        Call stop_thread() to properly and quickly stop the internal _thread.
+        """
+        if self._thread:
+            self._thread.join()
+
+    def _run_with_exception_logging(self):
+        """Same as _run but logs exceptions to the console or log file.
+
+        This is necessary when running in testing/production environment.
+        In case of an exception thrown, the stack trace can be seen in the
+        log file. Otherwise, there is no info why the _thread did stop.
+        """
+        try:
+            self._run()
+        except Exception as e:
+            logging.error(e, exc_info=True)
+        finally:
+            # Wait here for a while. If leaving the method directly, the _thread
+            # gets deleted and the is_alive() method won't work anymore!
+            time.sleep(5)
+            return
+
+    def _thread_sleep_interval(self, sleep_interval_in_seconds=None):
+        """Tells the executing _thread how long to sleep while being still reactive on _thread_should_run attribute.
+        """
+        if sleep_interval_in_seconds is not None:
+            wait_time = sleep_interval_in_seconds
+        else:
+            wait_time = self._control_interval_in_seconds
+
+        if self._sleep_condition.acquire(blocking=False):
+            # Sleep the time given. Thread can be wakened up with self._sleep_condition.notify()
+            # see wakeup_thread()
+            try:
+                self._sleep_condition.wait(timeout=wait_time)
+            except RuntimeError as e:  # pragma: no cover
+                self.log.exception(e)
+            finally:
+                self._sleep_condition.release()
+                return True
+        else:
+            self.log.error('Could not acquire sleep condition!')  # pragma: no cover
+        return False  # pragma: no cover
+
+    def _run(self):
+        assert False, 'Method needs to be implemented in derived class!'
+
+    """ Example loop:
+
+        while self._thread_should_run:
+
+            # Add your stuff here
+            print('Executes in a regular manner')
+
+            # Wait until next interval begins
+            if self._thread_should_run:
+                self._thread_sleep_interval()
+
+        self._thread_left_run_loop = True
+    """
+
+    def wait_on_thread_to_leave(self, timeout=3):
+        """Can be called to wait for the _thread until it left the run loop.
+
+        Replacement for self._thread.join() self._thread.join() is
+        reacting slowly! Replaced it with this method.
+        """
+        wait_time = timeout
+        decr_value = 0.2
+
+        if self._thread_left_run_loop:
+            return
+
+        while wait_time > 0:
+            time.sleep(decr_value)
+            wait_time -= decr_value
+            if self._thread_left_run_loop:
+                break

thingsboard/common/utils/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+
+# Tell python that there are more sub-packages present, physically located elsewhere.
+# See: https://stackoverflow.com/questions/8936884/python-import-path-packages-with-the-same-name-in-different-folders
+import pkgutil
+
+__path__ = pkgutil.extend_path(__path__, __name__)

thingsboard/common/utils/attribute_helpers.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+
+from thingsboard.common.utils import string_helpers
+
+
+def generate_attribute_names_by_name(name: str) -> tuple[str, str]:
+    """Generates attribute names according to our coding standards.
+    """
+    if len(name) == 0:
+        return tuple()
+
+    if name[0] == '_':
+        name = name[1:]
+
+    if '_' in name:
+        words = list(filter(None, name.split('_')))
+    elif '-' in name:
+        words = list(filter(None, name.split('-')))
+    else:
+        words = string_helpers.camel_case_split(name, lower_camel_case=True)
+
+    public_attribute_name = '_'.join((map(lambda x: x.lower(), words)))
+    private_attribute_name = '_' + public_attribute_name
+
+    return private_attribute_name, public_attribute_name
+
+
+def generate_setters_from_attribute_name(attribute_name: str) -> tuple[str, str]:
+    """Generates method setter names according to our coding standards.
+    """
+    if len(attribute_name) == 0:
+        return tuple()
+
+    if attribute_name[0] == '_':
+        attribute_name = attribute_name[1:]
+
+    if '_' in attribute_name:
+        words = list(filter(None, attribute_name.split('_')))
+    else:
+        words = string_helpers.camel_case_split(attribute_name, lower_camel_case=True)
+
+    setter_name = '_'.join((map(lambda x: x.lower(), words)))
+    setter01 = 'set_' + setter_name
+
+    setter_name = ''.join((map(lambda x: x.capitalize(), words)))
+    setter02 = 'set' + setter_name
+
+    return setter01, setter02

thingsboard/common/utils/datetime_helpers.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+
+import datetime
+
+EPOCH = datetime.datetime.fromtimestamp(0, datetime.UTC)
+
+
+def get_current_timestamp() -> int:
+    """Creates a timestamp using the current date and time.
+
+    The timestamp returned is in milliseconds.
+    """
+    current_date_time = datetime.datetime.now(datetime.UTC)
+    return _unix_time_millis(current_date_time)
+
+
+def get_timestamp(dt: datetime.datetime) -> int:
+    """Creates a timestamp using parameter dt.
+    :param dt The datetime object to convert to a timestamp
+    """
+    return _unix_time_millis(dt)
+
+
+def _unix_time_millis(dt: datetime.datetime) -> int:
+    """Converts a datetime object into unix time including milliseconds.
+    :param dt The datetime object to convert.
+    """
+    ut = int((dt - EPOCH).total_seconds()) * 1000
+    ut += int(dt.microsecond / 1000)
+    return ut

thingsboard/common/utils/path_helpers.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+
+import os
+
+
+def prettify(path_name: str) -> str:
+    """Makes all necessary stuff to get a usable path (specially under Windows)
+
+    :param path_name: Path to make pretty
+    """
+
+    if path_name:
+        # Remove backslashes from path
+        path_name = path_name.replace('\\', '/')
+
+        if path_name[0] == '~':
+            base_path = os.path.expanduser(path_name[0])
+            remaining_path = path_name[2:] if path_name[1] == '/' else path_name[1:]
+            path_name = os.path.join(base_path, remaining_path)
+
+        # and again
+        path_name = path_name.replace('\\', '/')
+
+    return path_name
+
+
+def home_directory():
+    home_dir = os.path.expanduser('~')
+    return home_dir
+
+
+def path_from_file(path_file_name: str) -> str:
+    """Returns the path of the given file location string.
+    """
+    path = os.path.abspath(os.path.dirname(path_file_name))
+    return path
+
+
+def create_directory_structure(path: str):
+    """Creates one or more directories.
+    """
+    os.makedirs(path, exist_ok=True)
+
+
+def remove_directory(path):
+    from shutil import rmtree
+
+    rmtree(path, ignore_errors=True)

thingsboard/common/utils/resource_loader.py

@@ -0,0 +1,78 @@
+# -*- coding: utf-8 -*-
+
+import os
+import urllib.parse as urlparse
+import urllib3
+from typing import Union
+
+from configobj import ConfigObj
+from .path_helpers import prettify
+
+
+class ResourceLoader(object):
+
+    @classmethod
+    def load_from_locations(cls, filename: str, locations: Union[str, list[str]]) -> ConfigObj:
+        """Searches for a resource file in the given locations and loads them.
+        """
+
+        if isinstance(locations, str):
+            locations = [locations, ]
+
+        for location in locations:
+            url = urlparse.urlparse(location)
+
+            if url.scheme == 'home':
+                base_path = os.path.expanduser('~') + url.path
+                file_path = os.path.join(base_path, filename)
+                file_path = prettify(file_path)
+
+                if os.path.isfile(file_path):
+                    properties = ConfigObj(file_path)
+                    return properties
+            elif url.scheme in ('file', 'path'):
+                file_path = os.path.join(url.path, filename)
+                if os.path.isfile(file_path):
+                    properties = ConfigObj(file_path)
+                    return properties
+            elif url.scheme == 'http' or \
+                    url.scheme == 'https':
+                if not location.endswith('/'):
+                    location += '/'
+                file_path = location + filename
+                try:
+                    http = urllib3.PoolManager()
+                    r = http.request('GET', file_path)
+                    file_content = r.data
+                    properties = ConfigObj(file_content)
+                    return properties
+                except NameError:
+                    pass
+        return ConfigObj()
+
+    @classmethod
+    def find_first_occurrence(cls, filename: str, locations: Union[str, list[str]]) -> tuple[str | None, int]:
+        """ Searches for a file in given locations.
+
+        Returns the first location where the file was found by returning the path and the location
+        index where the file was found.
+        """
+
+        if isinstance(locations, str):
+            locations = [locations, ]
+
+        for index, location in enumerate(locations):
+            url = urlparse.urlparse(location)
+
+            if url.scheme == 'home':
+                base_path = os.path.expanduser('~') + url.path
+                file_path = os.path.join(base_path, filename)
+                file_path = prettify(file_path)
+
+                if os.path.isfile(file_path):
+                    return prettify(base_path), index
+            elif url.scheme in ('file', 'path'):
+                file_path = os.path.join(url.path, filename)
+                if os.path.isfile(file_path):
+                    return prettify(url.path), index
+        return None, -1

thingsboard/common/utils/string_helpers.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+import re
+
+
+def camel_case_split(string: str, lower_camel_case: bool = False) -> list:
+    """Splits a camel-case formatted string into its words.
+
+    Example: 'ANiceDay' gets converted to ['A', 'Nice', 'Day'].
+
+    If lower_camel_case is specified, also the first expression is put into the list.
+
+    Credits to:
+    - https://www.geeksforgeeks.org/python-split-camelcase-string-to-individual-strings/
+    - https://stackoverflow.com/questions/29916065/how-to-do-camelcase-split-in-python
+    """
+
+    if not lower_camel_case:
+        return re.findall(r'[A-Z](?:[a-z]+|[A-Z]*(?=[A-Z]|$))', string)
+    else:
+        idx = list(map(str.isupper, string))
+        # mark change of case
+        lst = [0]
+        for (i, (x, y)) in enumerate(zip(idx, idx[1:])):
+            if x and not y:  # "Ul"
+                lst.append(i)
+            elif not x and y:  # "lU"
+                lst.append(i + 1)
+        lst.append(len(string))
+        # for "lUl", index of "U" will pop twice, have to filter it
+        return [string[x:y] for x, y in zip(lst, lst[1:]) if x < y]

thingsboard/common/utils/timestamp_helpers.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+import datetime
+
+EPOCH = datetime.datetime.fromtimestamp(0, datetime.UTC)
+
+def get_time_in_milliseconds(dt: datetime.datetime = None) -> int:
+    """Creates a timestamp using the current date and time.
+
+    If no parameters is given the actual UTC time is taken.
+    """
+    if not dt:
+        dt = datetime.datetime.now(datetime.UTC)
+
+    ut = int((dt - EPOCH).total_seconds()) * 1000
+    ut += int(dt.microsecond / 1000)
+    return ut

thingsboard/common/version.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+__author__ = 'Thomas Sterren'
+__contributors__ = []
+__version__ = '0.1.1'
+
+
+def main():
+    print(__version__)
+
+
+if __name__ == '__main__':
+    main()
+

thingsboard_common-0.1.1.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: thingsboard-common
+Version: 0.1.1
+Summary: ThingsBoard common package
+Home-page: https://gitlab.com/things-board
+Author: HES-SO Valais, School of Engineering, Sion
+Author-email: thomas.sterren@hes-so.ch
+License-Expression: MIT
+Project-URL: Bug Tracker, https://gitlab.com/things-board/thingsboard-common/-/issues
+Project-URL: Source Code, https://gitlab.com/things-board/thingsboard-common
+Project-URL: Documentation, https://gitlab.com/things-board/thingsboard-common#thingsboard-common
+Keywords: ThingsBoard common library IoT cloud connector core utils
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: configobj
+Requires-Dist: urllib3
+Requires-Dist: tb-mqtt-client
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: summary
+
+# ThingsBoard Common
+
+> Note: 
+> 
+> This is not an official project of the [
+ThingsBoard](https://thingsboard.io/) authors! Please refer to [ThingsBoard - Open-source IoT Platform](https://github.com/thingsboard) for official ThingsBoard projects!
+
+This project serves as a toolkit allowing other projects to use the same packages/modules as codebase.
+
+These projects are using the [ThingsBoard](https://thingsboard.io/) platform and extend it with additional functionality.

thingsboard_common-0.1.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+thingsboard/__init__.py,sha256=76n4Ir0tUx-uCkvXK3u-jsWTx_SyyP-OAmv3Nf9OXp4,304
+thingsboard/common/__init__.py,sha256=1nj8FJl6c4Wlq2zIWgjDZXtltHfHbj1vGCI0NZk1x3s,568
+thingsboard/common/version.py,sha256=yzUT3AV_2JhkKU_bBGi7othAGr5HdYN-BBBkuh3l0GA,214
+thingsboard/common/core/__init__.py,sha256=_O72SOav2A-q2gx9XuHDZM6ZOcLzu_5g7BGEuYjZztc,381
+thingsboard/common/core/thread_monitor.py,sha256=G4EQ-TvzO2LowNaq93LKfz9yhQCDGHstO8iaMXakFGk,1732
+thingsboard/common/core/threaded.py,sha256=PG5hItcADwjkyhcLvcsUsbcH6F4r-wWxxWK9FGHQ3SU,5859
+thingsboard/common/utils/__init__.py,sha256=76n4Ir0tUx-uCkvXK3u-jsWTx_SyyP-OAmv3Nf9OXp4,304
+thingsboard/common/utils/attribute_helpers.py,sha256=hdor2Fh2YEdLWuE2UkDIcwLalOSwsvHjvRBbTsJN4h0,1507
+thingsboard/common/utils/datetime_helpers.py,sha256=4ZqMVFa_ZBJifT6jFkQzugigoWuS5A7N44MroEfmVgc,873
+thingsboard/common/utils/path_helpers.py,sha256=BEbswIZyNdXMNm4lXwIUszbg9T7Fr3fAdxrgvh7TllA,1195
+thingsboard/common/utils/resource_loader.py,sha256=M8HLQWndTjrk06P5i2wY1p-EinuozL-BiMzB_UYB9-g,2869
+thingsboard/common/utils/string_helpers.py,sha256=tVRjZuijRhhd2G86Gbs6GtPNiVxO4FVZwPOPe0wSsbk,1124
+thingsboard/common/utils/timestamp_helpers.py,sha256=zjZ3-xZvF-x2yjQm_DVljx8gLToTqyRzn3h0VNgzEtg,479
+thingsboard_common-0.1.1.dist-info/licenses/LICENSE,sha256=kzvDVNE4q9rpOY-d0Fn61rXyTBtkgeRmZnRak2Nrvl4,1091
+thingsboard_common-0.1.1.dist-info/METADATA,sha256=nGjuApSzV3jmmvm7h_4EJX7amcejBMLHhpVj6qsN3ys,2010
+thingsboard_common-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+thingsboard_common-0.1.1.dist-info/top_level.txt,sha256=hIeFbajkoBwsAEzoI1q3cZpwD-MtNvckaJqYsKNggNA,12
+thingsboard_common-0.1.1.dist-info/RECORD,,

thingsboard_common-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

thingsboard_common-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HES-SO Valais
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thingsboard_common-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+thingsboard