23.12.0-DEV

docs/logging.rst

@@ -17,6 +17,17 @@ but the format should be pretty straight forward.
    | That way even if the HABApp configuration is invalid HABApp can still log the errors that have occurred.
    | e.g.: ``/HABApp/logs/habapp.log`` or ``c:\HABApp\logs\habapp.log``
 
+Provided loggers
+======================================
+
+The ``HABApp.config.logging`` module provides additional loggers which can be used
+
+
+.. autoclass:: HABApp.config.logging.MidnightRotatingFileHandler
+
+.. autoclass:: HABApp.config.logging.CompressedMidnightRotatingFileHandler
+
+
 Example
 ======================================
 
@@ -42,7 +53,7 @@ to the file configuration under ``handlers`` in the ``logging.yml``.
       ...
 
       MyRuleHandler: # <-- This is the name of the handler
-        class: HABApp.core.lib.handler.MidnightRotatingFileHandler
+        class: HABApp.config.logging.MidnightRotatingFileHandler
         filename: 'c:\HABApp\Logs\MyRule.log'
         maxBytes: 10_000_000
         backupCount: 3
@@ -84,7 +95,7 @@ Full Example configuration
     # -----------------------------------------------------------------------------------
     handlers:
       HABApp_default:
-        class: HABApp.core.lib.handler.MidnightRotatingFileHandler
+        class: HABApp.config.logging.MidnightRotatingFileHandler
         filename: 'HABApp.log'
         maxBytes: 10_000_000
         backupCount: 3
@@ -93,7 +104,7 @@ Full Example configuration
         level: DEBUG
 
       MyRuleHandler:
-        class: HABApp.core.lib.handler.MidnightRotatingFileHandler
+        class: HABApp.config.logging.MidnightRotatingFileHandler
         filename: 'c:\HABApp\Logs\MyRule.log'    # absolute filename is recommended
         maxBytes: 10_000_000
         backupCount: 3

docs/requirements.txt

@@ -1,7 +1,7 @@
 # Packages required to build the documentation
-sphinx                      == 7.2.5
-sphinx-autodoc-typehints    == 1.24.0
-sphinx_rtd_theme            == 1.3.0
+sphinx                      == 7.2.6
+sphinx-autodoc-typehints    == 1.25.2
+sphinx_rtd_theme            == 2.0.0
 sphinx-exec-code            == 0.10
 autodoc_pydantic            == 2.0.1
 sphinx-copybutton           == 0.5.2

docs/util.rst

@@ -75,6 +75,88 @@ Converts a hsb value to the rgb color space
 .. autofunction:: HABApp.util.functions.hsb_to_rgb
 
 
+Rate limiter
+------------------------------
+A simple rate limiter implementation which can be used in rules.
+The limiter is not rule bound so the same limiter can be used in multiples files.
+It also works as expected across rule reloads.
+
+Defining limits
+^^^^^^^^^^^^^^^^^^
+Limits can either be explicitly added or through a textual description.
+If the limit does already exist it will not be added again.
+It's possible to explicitly create the limits or through some small textual description with the following syntax:
+
+.. code-block:: text
+
+    [count] [per|in|/] [count (optional)] [s|sec|second|m|min|minute|hour|h|day|month|year] [s (optional)]
+
+Whitespaces are ignored and can be added as desired
+
+Examples:
+
+* ``5 per minute``
+* ``20 in 15 mins``
+* ``300 / hour``
+
+
+Elastic expiry
+^^^^^^^^^^^^^^^^^^
+
+The rate limiter implements a fixed window with elastic expiry.
+That means if the limit is hit the interval time will be increased by the expiry time.
+
+For example ``3 per minute``:
+
+* First hit comes ``00:00:00``. Two more hits at ``00:00:59``.
+  All three pass, intervall goes from ``00:00:00`` - ``00:01:00``.
+  Another hit comes at ``00:01:01`` an passes. The intervall now goes from ``00:01:01`` - ``00:02:01``.
+
+* First hit comes ``00:00:00``. Two more hits at ``00:00:30``. All three pass.
+  Another hit comes at ``00:00:45``, which gets rejected and the intervall now goes from ``00:00:00`` - ``00:01:45``.
+  A rejected hit makes the interval time longer by expiry time. If another hit comes at ``00:01:30`` it
+  will also get rejected and the intervall now goes from ``00:00:00`` - ``00:02:30``.
+
+
+Example
+^^^^^^^^^^^^^^^^^^
+
+.. exec_code::
+
+    from HABApp.util import RateLimiter
+
+    # Create or get existing, name is case insensitive
+    limiter = RateLimiter('MyRateLimiterName')
+
+    # define limits, duplicate limits will only be added once
+    limiter.add_limit(5, 60)   # add limits explicitly
+    limiter.parse_limits('5 per minute').parse_limits('5 in 60s', '5/60seconds')  # add limits through text
+
+
+    # Test the limit without increasing the hits
+    for _ in range(100):
+        assert limiter.test_allow()
+
+    # the limiter will allow 5 calls ...
+    for _ in range(5):
+        assert limiter.allow()
+
+    # and reject the 6th
+    assert not limiter.allow()
+
+    # It's possible to get statistics about the limiter and the corresponding windows
+    print(limiter.info())
+
+
+Documentation
+^^^^^^^^^^^^^^^^^^
+.. autofunction:: HABApp.util.RateLimiter
+
+
+.. autoclass:: HABApp.util.rate_limiter.limiter.Limiter
+   :members:
+
+
 Statistics
 ------------------------------
 

readme.md

@@ -127,7 +127,12 @@ MyOpenhabRule()
 ```
 
 # Changelog
-#### 23.11.1 (2023-11-23)
+#### 23.12.0-DEV (2023-XX-XX)
+- Added HABApp.util.RateLimiter
+- Added CompressedMidnightRotatingFileHandler
+- Updated dependencies
+
+#### 23.11.0 (2023-11-23)
 - Fix for very small float values (#425)
 - Fix for writing to persistence (#424)
 - Updated dependencies

requirements_setup.txt

@@ -1,4 +1,4 @@
-aiohttp     == 3.9.0
+aiohttp     == 3.9.1
 pydantic    == 2.5.2
 msgspec     == 0.18.4
 pendulum    == 2.1.2

run/conf/logging.yml

@@ -8,13 +8,15 @@ handlers:
   # There are several Handlers available:
   #  - logging.handlers.RotatingFileHandler:
   #    Will rotate when the file reaches a certain size (see python logging documentation for args)
-  #  - HABApp.core.lib.handler.MidnightRotatingFileHandler:
+  #  - HABApp.config.logging.handler.MidnightRotatingFileHandler:
   #    Will wait until the file reaches a certain size and then will rotate on midnight
+  #  - HABApp.config.logging.handler.CompressedMidnightRotatingFileHandler:
+  #    Same as MidnightRotatingFileHandler but will rotate to a gzipped archive
   #  - More handlers:
   #    https://docs.python.org/3/library/logging.handlers.html#rotatingfilehandler
 
   HABApp_default:
-    class: HABApp.core.lib.handler.MidnightRotatingFileHandler
+    class: HABApp.config.logging.handler.MidnightRotatingFileHandler
     filename: 'HABApp.log'
     maxBytes: 1_048_576
     backupCount: 3
@@ -23,7 +25,7 @@ handlers:
     level: DEBUG
 
   EventFile:
-    class: HABApp.core.lib.handler.MidnightRotatingFileHandler
+    class: HABApp.config.logging.handler.CompressedMidnightRotatingFileHandler
     filename: 'events.log'
     maxBytes: 1_048_576
     backupCount: 3

src/HABApp/__version__.py

@@ -10,4 +10,4 @@
 # Development versions contain the DEV-COUNTER postfix:
 # - 23.09.0.DEV-1
 
-__version__ = '23.11.0'
+__version__ = '23.12.0.DEV-1'

src/HABApp/config/logging/__init__.py

@@ -1,4 +1,4 @@
-from .handler import MidnightRotatingFileHandler
+from .handler import MidnightRotatingFileHandler, CompressedMidnightRotatingFileHandler
 
 # isort: split
 

src/HABApp/config/logging/default_logfile.py

@@ -18,6 +18,8 @@ def get_default_logfile() -> str:
   #    Will rotate when the file reaches a certain size (see python logging documentation for args)
   #  - HABApp.config.logging.MidnightRotatingFileHandler:
   #    Will wait until the file reaches a certain size and then will rotate on midnight
+  #  - HABApp.config.logging.CompressedMidnightRotatingFileHandler:
+  #    Same as MidnightRotatingFileHandler but will rotate to a gzipped archive
   #  - More handlers:
   #    https://docs.python.org/3/library/logging.handlers.html#rotatingfilehandler
 

src/HABApp/config/logging/handler.py

@@ -1,8 +1,14 @@
+import gzip
+import shutil
 from datetime import date, datetime
 from logging.handlers import RotatingFileHandler
+from pathlib import Path
 
 
 class MidnightRotatingFileHandler(RotatingFileHandler):
+    """A rotating file handler that checks once after midnight if the configured size has been exceeded and
+    then rotates the file
+    """
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -14,3 +20,23 @@ def shouldRollover(self, record):
             return 0
         self.last_check = date
         return super().shouldRollover(record)
+
+
+class CompressedMidnightRotatingFileHandler(MidnightRotatingFileHandler):
+    """Same as ``MidnightRotatingFileHandler`` but rotates the file to a gzipped archive (``.gz``)
+
+    """
+
+    def __init__(self, *args, **kwargs):
+        self.namer = self.compressed_namer
+        self.rotator = self.compressed_rotator
+        super().__init__(*args, **kwargs)
+
+    def compressed_namer(self, default_name: str) -> str:
+        return default_name + ".gz"
+
+    def compressed_rotator(self, source: str, dest: str):
+        src = Path(source)
+        with src.open('rb') as f_in, gzip.open(dest, 'wb') as f_out:
+            shutil.copyfileobj(f_in, f_out)
+        src.unlink()

src/HABApp/util/__init__.py

@@ -2,6 +2,7 @@
 from .statistics import Statistics
 from .listener_groups import EventListenerGroup
 from .fade import Fade
+from .rate_limiter import RateLimiter
 
 from . import functions
 from . import multimode

src/HABApp/util/rate_limiter/__init__.py

@@ -0,0 +1 @@
+from .registry import RateLimiter