enhomie 0.2.0__tar.gz

enhomie-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Enasis Network
+
+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.

enhomie-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+
+
+
+include enhomie/version.txt

enhomie-0.2.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.1
+Name: enhomie
+Version: 0.2.0
+Summary: Enasis Network Homie Automate
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: encommon
+Requires-Dist: enconnect
+
+# Enasis Network Homie Automate
+
+> :children_crossing: This project has not released its first major version.
+
+Define desired scenes for groups using flexible conditional plugins.
+
+[![](https://img.shields.io/github/actions/workflow/status/enasisnetwork/enhomie/build.yml?style=flat-square&label=GitHub%20actions)](https://github.com/enasisnetwork/enhomie/actions)<br>
+[![codecov](https://img.shields.io/codecov/c/github/enasisnetwork/enhomie?token=7PGOXKJU0E&style=flat-square&logoColor=FFFFFF&label=Coverage)](https://codecov.io/gh/enasisnetwork/enhomie)<br>
+[![](https://img.shields.io/readthedocs/enhomie?style=flat-square&label=Read%20the%20Docs)](https://enhomie.readthedocs.io)<br>
+[![](https://img.shields.io/pypi/v/enhomie.svg?style=flat-square&label=PyPi%20version)](https://pypi.org/project/enhomie)<br>
+[![](https://img.shields.io/pypi/dm/enhomie?style=flat-square&label=PyPi%20downloads)](https://pypi.org/project/enhomie)
+
+## Configuration example
+Some basic configuration examples. See next section for more documentation.
+- [Homie Desires](enhomie/homie/test/samples/desires.yml)
+- [Homie Groups](enhomie/homie/test/samples/groups.yml)
+- [Homie Scenes](enhomie/homie/test/samples/scenes.yml)
+- [Philips Hue Bridges](enhomie/philipshue/test/samples/bridges.yml)
+- [Philips Hue Devices](enhomie/philipshue/test/samples/devices.yml)
+- [Ubiquiti Routers](enhomie/ubiquiti/test/samples/routers.yml)
+- [Ubiquiti Clients](enhomie/ubiquiti/test/samples/clients.yml)
+
+## Documentation
+Documentation is on [Read the Docs](https://enhomie.readthedocs.io).
+Should you venture into the sections below you will be able to use the
+`sphinx` recipe to build documention in the `docs/html` directory.
+
+## Short-term future goals
+- Encrypting the values in the configuration files.
+- Deploying `enhomie` via the `sdmt` project.
+- Ability to send email when scene change is made.
+  - Requires `enconnect.stmp.Compose` class.
+  - Requires `scene_set` to be idempotent.
+
+## Long-term future goals
+- CRUD for groups and scenes in Philips Hue bridges.
+- Listener that can perform some basic actions.
+- Plugin using light level from Philips Hue devices.
+- Plugin checks current scene active for groups.
+
+## Additional scripts
+- [dumper.py](desired.py) is useful for setting desired scenes.
+- [dumper.py](dumper.py) is useful for dumping configuration.
+- [scener.py](scener.py) is useful for setting scene on groups.
+
+## Useful and related links
+- https://ubntwiki.com/products/software/unifi-controller/api
+
+## Installing the package
+Installing stable from the PyPi repository
+```
+pip install enhomie
+```
+Installing latest from GitHub repository
+```
+pip install git+https://github.com/enasisnetwork/enhomie
+```
+
+## Quick start for local development
+Start by cloning the repository to your local machine.
+```
+git clone https://github.com/enasisnetwork/enhomie.git
+```
+Set up the Python virtual environments expected by the Makefile.
+```
+make -s venv-create
+```
+
+### Execute the linters and tests
+The comprehensive approach is to use the `check` recipe. This will stop on
+any failure that is encountered.
+```
+make -s check
+```
+However you can run the linters in a non-blocking mode.
+```
+make -s linters-pass
+```
+And finally run the various tests to validate the code and produce coverage
+information found in the `htmlcov` folder in the root of the project.
+```
+make -s pytest
+```
+
+## Build and upload to PyPi
+Build the package.
+```
+make -s pypackage
+```
+Upload to the test PyPi.
+```
+make -s pypi-upload-test
+```
+Upload to the prod PyPi.
+```
+make -s pypi-upload-prod
+```

enhomie-0.2.0/README.md

@@ -0,0 +1,97 @@
+# Enasis Network Homie Automate
+
+> :children_crossing: This project has not released its first major version.
+
+Define desired scenes for groups using flexible conditional plugins.
+
+[![](https://img.shields.io/github/actions/workflow/status/enasisnetwork/enhomie/build.yml?style=flat-square&label=GitHub%20actions)](https://github.com/enasisnetwork/enhomie/actions)<br>
+[![codecov](https://img.shields.io/codecov/c/github/enasisnetwork/enhomie?token=7PGOXKJU0E&style=flat-square&logoColor=FFFFFF&label=Coverage)](https://codecov.io/gh/enasisnetwork/enhomie)<br>
+[![](https://img.shields.io/readthedocs/enhomie?style=flat-square&label=Read%20the%20Docs)](https://enhomie.readthedocs.io)<br>
+[![](https://img.shields.io/pypi/v/enhomie.svg?style=flat-square&label=PyPi%20version)](https://pypi.org/project/enhomie)<br>
+[![](https://img.shields.io/pypi/dm/enhomie?style=flat-square&label=PyPi%20downloads)](https://pypi.org/project/enhomie)
+
+## Configuration example
+Some basic configuration examples. See next section for more documentation.
+- [Homie Desires](enhomie/homie/test/samples/desires.yml)
+- [Homie Groups](enhomie/homie/test/samples/groups.yml)
+- [Homie Scenes](enhomie/homie/test/samples/scenes.yml)
+- [Philips Hue Bridges](enhomie/philipshue/test/samples/bridges.yml)
+- [Philips Hue Devices](enhomie/philipshue/test/samples/devices.yml)
+- [Ubiquiti Routers](enhomie/ubiquiti/test/samples/routers.yml)
+- [Ubiquiti Clients](enhomie/ubiquiti/test/samples/clients.yml)
+
+## Documentation
+Documentation is on [Read the Docs](https://enhomie.readthedocs.io).
+Should you venture into the sections below you will be able to use the
+`sphinx` recipe to build documention in the `docs/html` directory.
+
+## Short-term future goals
+- Encrypting the values in the configuration files.
+- Deploying `enhomie` via the `sdmt` project.
+- Ability to send email when scene change is made.
+  - Requires `enconnect.stmp.Compose` class.
+  - Requires `scene_set` to be idempotent.
+
+## Long-term future goals
+- CRUD for groups and scenes in Philips Hue bridges.
+- Listener that can perform some basic actions.
+- Plugin using light level from Philips Hue devices.
+- Plugin checks current scene active for groups.
+
+## Additional scripts
+- [dumper.py](desired.py) is useful for setting desired scenes.
+- [dumper.py](dumper.py) is useful for dumping configuration.
+- [scener.py](scener.py) is useful for setting scene on groups.
+
+## Useful and related links
+- https://ubntwiki.com/products/software/unifi-controller/api
+
+## Installing the package
+Installing stable from the PyPi repository
+```
+pip install enhomie
+```
+Installing latest from GitHub repository
+```
+pip install git+https://github.com/enasisnetwork/enhomie
+```
+
+## Quick start for local development
+Start by cloning the repository to your local machine.
+```
+git clone https://github.com/enasisnetwork/enhomie.git
+```
+Set up the Python virtual environments expected by the Makefile.
+```
+make -s venv-create
+```
+
+### Execute the linters and tests
+The comprehensive approach is to use the `check` recipe. This will stop on
+any failure that is encountered.
+```
+make -s check
+```
+However you can run the linters in a non-blocking mode.
+```
+make -s linters-pass
+```
+And finally run the various tests to validate the code and produce coverage
+information found in the `htmlcov` folder in the root of the project.
+```
+make -s pytest
+```
+
+## Build and upload to PyPi
+Build the package.
+```
+make -s pypackage
+```
+Upload to the test PyPi.
+```
+make -s pypi-upload-test
+```
+Upload to the prod PyPi.
+```
+make -s pypi-upload-prod
+```

enhomie-0.2.0/enhomie/__init__.py

@@ -0,0 +1,29 @@
+"""
+Functions and routines associated with Enasis Network Homie Automate.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from os import environ
+from pathlib import Path
+
+
+
+PROJECT = Path(__file__).parent
+WORKSPACE = PROJECT.parents[2]
+
+VERSION = (
+    PROJECT
+    .joinpath('version.txt')
+    .read_text(encoding='utf-8')
+    .splitlines()[0].strip())
+
+__version__ = VERSION
+
+
+
+ENPYRWS = (
+    environ.get('ENPYRWS') == '1')

enhomie-0.2.0/enhomie/builtins/__init__.py

@@ -0,0 +1,19 @@
+"""
+Functions and routines associated with Enasis Network Homie Automate.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from .params import WhenTimePeriodParams
+from .when import chck_time_period
+from .when import when_time_period
+
+
+
+__all__ = [
+    'WhenTimePeriodParams',
+    'chck_time_period',
+    'when_time_period']

enhomie-0.2.0/enhomie/builtins/params.py

@@ -0,0 +1,71 @@
+"""
+Functions and routines associated with Enasis Network Homie Automate.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from typing import Any
+from typing import Optional
+
+from encommon.times import Times
+
+from pydantic import BaseModel
+
+
+
+class WhenTimePeriodParams(BaseModel, extra='forbid'):
+    """
+    Process and validate the Homie configuration parameters.
+
+    :param start: Determine the start for the desired period.
+    :param stop: Determine the ending for the desired period.
+    :param tzname: Name of the timezone associated to period.
+    :param data: Keyword arguments passed to Pydantic model.
+        Parameter is picked up by autodoc, please ignore.
+    """
+
+    start: Optional[str] = None
+    stop: Optional[str] = None
+    tzname: str = 'UTC'
+
+
+    def __init__(
+        self,
+        **data: Any,
+    ) -> None:
+        """
+        Initialize instance for class using provided parameters.
+        """
+
+        start = data.get('start')
+        stop = data.get('stop')
+        tzname = data.get('tzname')
+
+
+        if start is not None:
+            start = Times(
+                source=start,
+                tzname=tzname)
+
+        if stop is not None:
+            stop = Times(
+                source=stop,
+                tzname=tzname)
+
+
+        if (start and stop
+                and stop <= start):
+            stop = stop.shift('+1d')
+
+
+        if start is not None:
+            data['start'] = start.simple
+
+        if stop is not None:
+            data['stop'] = stop.simple
+
+
+        super().__init__(**data)

enhomie-0.2.0/enhomie/builtins/test/__init__.py

@@ -0,0 +1,6 @@
+"""
+Functions and routines associated with Enasis Network Homie Automate.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""

enhomie-0.2.0/enhomie/builtins/test/test_params.py

@@ -0,0 +1,47 @@
+"""
+Functions and routines associated with Enasis Network Homie Automate.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from encommon.times import Times
+
+from ..params import WhenTimePeriodParams
+
+
+
+def test_WhenTimePeriodParams() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
+
+    anchor = Times('now')
+
+
+    start = anchor.shift('-1h@s')
+    stop = anchor.shift('+1h@s')
+
+    when = WhenTimePeriodParams(
+        start=start,
+        stop=stop)
+
+    assert when.start and when.stop
+
+    assert when.start == start
+    assert when.stop == stop
+
+
+    start = anchor.shift('-1h@s')
+    stop = anchor.shift('-2h@s')
+
+    when = WhenTimePeriodParams(
+        start=start,
+        stop=stop)
+
+    assert when.start and when.stop
+
+    assert when.start == start
+    assert when.stop >= start

enhomie-0.2.0/enhomie/builtins/test/test_when.py

@@ -0,0 +1,65 @@
+"""
+Functions and routines associated with Enasis Network Homie Automate.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from typing import TYPE_CHECKING
+
+from ..params import WhenTimePeriodParams
+from ...homie import HomieWhen
+from ...homie import HomieWhenParams
+
+if TYPE_CHECKING:
+    from ...homie import Homie
+
+
+
+def test_when_time_period(
+    homie: 'Homie',
+) -> None:
+    """
+    Perform various tests associated with relevant routines.
+
+    :param homie: Primary class instance for Homie Automate.
+    """
+
+
+    time_period = (
+        WhenTimePeriodParams(
+            start='+2d'))
+
+    params = HomieWhenParams(
+        time_period=time_period)
+
+    when = HomieWhen(homie, params)
+
+    assert when.outcome is False
+
+
+    time_period = (
+        WhenTimePeriodParams(
+            start='-2d'))
+
+    params = HomieWhenParams(
+        time_period=time_period)
+
+    when = HomieWhen(homie, params)
+
+    assert when.outcome is True
+
+
+    time_period = (
+        WhenTimePeriodParams(
+            start='-2d',
+            stop='-1d'))
+
+    params = HomieWhenParams(
+        time_period=time_period)
+
+    when = HomieWhen(homie, params)
+
+    assert when.outcome is False

enhomie-0.2.0/enhomie/builtins/when.py

@@ -0,0 +1,95 @@
+"""
+Functions and routines associated with Enasis Network Homie Automate.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from typing import Optional
+from typing import TYPE_CHECKING
+
+from encommon.times import Times
+
+if TYPE_CHECKING:
+    from ..homie import HomieWhen
+
+
+
+def when_time_period(
+    when: 'HomieWhen',
+) -> bool:
+    """
+    Return the boolean indicating whether condition matched.
+
+    :param when: Primary class instance for the conditonal.
+    :returns: Boolean indicating whether condition matched.
+    """
+
+    params = (
+        when.params.time_period)
+
+    assert params is not None
+
+    start = params.start
+    stop = params.stop
+    tzname = params.tzname
+
+    anchor = Times(tzname=tzname)
+
+    assert (
+        start is not None
+        or stop is not None)
+
+
+    _start: Optional[Times] = (
+        Times(start)
+        if start is not None
+        else None)
+
+    _stop: Optional[Times] = (
+        Times(stop)
+        if stop is not None
+        else None)
+
+
+    matched = True
+
+    if (_start is not None
+            and anchor < _start):
+        matched = False
+
+    if (_stop is not None
+            and anchor > _stop):
+        matched = False
+
+
+    return matched
+
+
+
+def chck_time_period(
+    when: 'HomieWhen',
+) -> None:
+    """
+    Return the boolean indicating whether conditional valid.
+
+    :param when: Primary class instance for the conditonal.
+    """
+
+    params = (
+        when.params.time_period)
+
+    assert params is not None
+
+    start = params.start
+    stop = params.stop
+    tzname = params.tzname
+
+
+    if start is not None:
+        Times(start, tzname=tzname)
+
+    if stop is not None:
+        Times(stop, tzname=tzname)

enhomie-0.2.0/enhomie/config/__init__.py

@@ -0,0 +1,17 @@
+"""
+Functions and routines associated with Enasis Network Homie Automate.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from .config import Config
+from .params import Params
+
+
+
+__all__ = [
+    'Config',
+    'Params']

enhomie-0.2.0/enhomie/config/config.py

@@ -0,0 +1,95 @@
+"""
+Functions and routines associated with Enasis Network Homie Automate.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from contextlib import suppress
+from typing import Optional
+
+from encommon.config import Config as _Config
+from encommon.types import merge_dicts
+from encommon.utils.common import PATHABLE
+
+from .params import Params
+
+
+
+class Config(_Config):
+    """
+    Contain the configurations from the arguments and files.
+
+    :param files: Complete or relative path to config files.
+    """
+
+
+    def __init__(
+        self,
+        files: Optional[PATHABLE] = None,
+    ) -> None:
+        """
+        Initialize instance for class using provided parameters.
+        """
+
+        super().__init__(
+            files=files,
+            model=Params)
+
+
+    @property
+    def params(
+        self,
+    ) -> Params:
+        """
+        Return the Pydantic model containing the configuration.
+
+        .. warning::
+           This method completely overrides the parent but is
+           based on that code, would be unfortunate if upstream
+           changes meant this breaks or breaks something else.
+
+        :returns: Pydantic model containing the configuration.
+        """
+
+        params = self.__params
+
+        if isinstance(params, Params):
+            return params
+
+
+        merged = self.files.merged
+
+        merge_dicts(
+            dict1=merged,
+            dict2=self.cargs,
+            force=True)
+
+
+        update_params = False
+
+        with suppress(AttributeError):
+
+            _merged = self.paths.merged
+
+            for _merge in _merged.values():
+
+                merge_dicts(
+                    dict1=merged,
+                    dict2=_merge,
+                    force=False)
+
+            update_params = True
+
+
+        params = self.model(**merged)
+
+
+        if update_params is True:
+            self.__params = params
+
+        assert isinstance(params, Params)
+
+        return params