juham-core 0.0.0__py3-none-any.whl

juham_core/__init__.py

@@ -0,0 +1,19 @@
+"""
+Description
+===========
+
+Base classes for Juham - Juha's Ultimate Home Automation framework 
+
+"""
+
+from .juham import Juham
+from .rcloud import RCloud, RCloudThread
+from .rthread import RThread, MasterPieceThread
+
+__all__ = [
+    "Juham",
+    "RThread",
+    "RCloud",
+    "RCloudThread",
+    "MasterPieceThread",
+]

juham_core/juham.py

@@ -0,0 +1,497 @@
+import json
+import traceback
+from typing import Any, Dict, Optional, cast, Union
+from typing_extensions import override
+
+from masterpiece.mqtt import Mqtt, MqttMsg
+from masterpiece import MasterPiece, URL
+from masterpiece.timeseries import TimeSeries, Measurement
+from .timeutils import timestamp
+
+
+class Juham(MasterPiece):
+    """Base class for automation objects with MQTT networking and time series data storage.
+
+    To configure the class to use a specific MQTT and database set
+    the `database_class_id` and `mqtt_class_id` class attributes to desired
+    MQTT and database implementations. When instantiated the object will instantiate
+    the given MQTT and database objects with it.
+    """
+
+    database_class_id: str = ""
+    mqtt_class_id: str = ""
+    write_attempts: int = 3
+    mqtt_root_topic: str = ""
+    mqtt_host: str = "localhost"
+    mqtt_port: int = 1883
+
+    def __init__(self, name: str = "") -> None:
+        """Constructs new automation object with the given name, configured
+        time series recorder and MQTT network features.
+
+        Args:
+            name (str): name of the object
+        """
+        super().__init__(name)
+        self.database_client: Optional[Union[TimeSeries, None]] = None
+        self.mqtt_client: Optional[Union[Mqtt, None]] = None
+        self.mqtt_topic_base: str = ""
+        self.mqtt_topic_control: str = ""
+        self.mqtt_topic_log: str = ""
+
+    @override
+    def to_dict(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = super().to_dict()
+        data["_base"] = {}
+        attributes = ["mqtt_host", "mqtt_port", "mqtt_root_topic", "write_attempts"]
+        for attr in attributes:
+            if getattr(self, attr) != getattr(type(self), attr):
+                data["_base"][attr] = getattr(self, attr)
+        if self.database_client is not None:
+            data["_database"] = {"db_client": self.database_client.to_dict()}
+        return data
+
+    @override
+    def from_dict(self, data: Dict[str, Any]) -> None:
+        super().from_dict(data)
+        for key, value in data["_base"].items():
+            if key == "db_client":
+                self.database_client = cast(
+                    Optional[TimeSeries], MasterPiece.instantiate(value["_class"])
+                )
+                if self.database_client is not None:
+                    self.database_client.from_dict(value)
+            else:
+                setattr(self, key, value)
+
+    def initialize(self) -> None:
+        """Initialize time series database and mqtt networking  for use. This method must be called
+        after the object name has been  set .
+        """
+        self.init_database(self.name)
+        self.init_mqtt(self.name)
+
+    def measurement(self, name: str) -> Measurement:
+        """Instantiates measurement object.
+        Args:
+            measurement (str): name of the object
+        Returns
+            (Measurement) measurement object
+        """
+        timeseries: TimeSeries = cast(TimeSeries, self.database_client)
+        return timeseries.measurement(name)
+
+    def init_database(self, name: str) -> None:
+        """Instantiates the configured time series database object.
+
+        Issues a warning if the :attr:`~database_class_id` has not
+        been configured, in which case the object will not have the time series
+        recording feature.
+
+        This method is called internally and typically there is no need to call it
+        from the application code.
+        """
+
+        if (
+            Juham.database_class_id != None
+            and MasterPiece.find_class(Juham.database_class_id) != None
+        ):
+            self.database_client = cast(
+                Optional[TimeSeries], MasterPiece.instantiate(Juham.database_class_id)
+            )
+        else:
+            self.warning("Suspicious configuration: no database_class_id set")
+
+    def init_topic_base(self) -> None:
+        url: URL = self.make_url()
+        self.mqtt_root_topic = self.root().make_url().get()[1:]
+        self.mqtt_topic_base = url.get()[1:]
+        self.mqtt_topic_control = self.mqtt_root_topic + "/control"
+        self.mqtt_topic_log = self.mqtt_root_topic + "/log"
+
+    def make_topic_name(self, topic: str) -> str:
+        """Make topic name for the object. The topic name
+        consists of the base name plus the given 'topic'.
+
+        Args:
+            topic (str): topic name
+
+        Returns:
+            str: mqtt topic name
+        """
+        return f"{self.mqtt_root_topic}/{topic}"
+
+    def init_mqtt(self, name: str) -> None:
+        """Instantiates the configured MQTT object for networking. Calls `init_topic()`
+        to construct topic base name for the object, and instantiates the mqtt
+        client.
+
+        This method is called internally and typically there is no need to call it
+        from the application code.
+
+        Issues a warning if the :attr:`mqtt_class_id` has not
+        been configured, even though objects without a capability to communicate
+        are rather crippled.
+        """
+        self.init_topic_base()
+        if Juham.mqtt_class_id == "":
+            self.warning(
+                f"Suscpicious configuration: no mqtt_class_id set for {self.name}:{self.get_class_id()}"
+            )
+        elif not Juham.find_class(Juham.mqtt_class_id):
+            self.error(
+                f"Couldn't create mqtt broker {Juham.mqtt_class_id},  class not imported"
+            )
+        else:
+            self.mqtt_client = cast(
+                Optional[Mqtt], MasterPiece.instantiate(Juham.mqtt_class_id, name)
+            )
+            if self.mqtt_client is not None:
+                self.mqtt_client.on_message = self.on_message
+                self.mqtt_client.on_connect = self.on_connect
+                self.mqtt_client.on_disconnect = self.on_disconnect
+                if (
+                    self.mqtt_client.connect_to_server(self.mqtt_host, self.mqtt_port)
+                    != 0
+                ):
+                    self.error(
+                        f"Couldn't connect to the mqtt broker at {self.mqtt_client.host}"
+                    )
+                else:
+                    self.debug(
+                        f"{self.name} with mqtt broker {self.mqtt_client.name} connected to {self.mqtt_client.host}"
+                    )
+            else:
+                self.error(f"Couldn't create mqtt broker {Juham.mqtt_class_id}")
+
+    def subscribe(self, topic: str) -> None:
+        """Subscribe to the given MQTT topic.
+
+        This method sets up the subscription to the specified MQTT topic and registers
+        the :meth:`on_message` method as the callback for incoming messages.
+
+        Args:
+            topic (str): The MQTT topic to subscribe to.
+
+        Example:
+        ::
+
+            # configure
+            obj.subscribe('foo/bar')
+        """
+
+        if self.mqtt_client:
+            self.mqtt_client.connected_flag = True
+            self.mqtt_client.subscribe(topic)
+            self.info(f"{self.name}  subscribed to { topic}")
+
+    def on_message(self, client: object, userdata: Any, msg: MqttMsg) -> None:
+        """MQTT message notification on arrived message.
+
+        Called whenever a new message is posted on one of the
+        topics the object has subscribed to via subscribe() method.
+        This method is the heart of automation: here, derived subclasses should
+        automate whatever they were designed to automate. For example, they could switch a
+        relay when a boiler temperature sensor signals that the temperature is too low for
+        a comforting shower for say one's lovely wife.
+
+        For more information on this method consult MQTT documentation available
+        in many public sources.
+
+        Args:
+            client (obj):  MQTT client
+            userdata (Any): application specific data
+            msg (object): The MQTT message
+        """
+
+        if msg.topic == self.mqtt_topic_control:
+            m = json.loads(msg.payload)
+            if m["command"] == "shutdown" and self.mqtt_client:
+                self.mqtt_client.disconnect()
+                self.mqtt_client.loop_stop()
+
+    def on_connect(self, client: object, userdata: Any, flags: int, rc: int) -> None:
+        """Notification on connect.
+
+        This method is called whenever the MQTT broker is connected.
+        For more information on this method consult MQTT documentation available
+        in many public sources.
+
+        Args:
+            client (obj):  MQTT client
+            userdata (Any): application specific data
+            flags (int): Consult MQTT
+            rc (int): See MQTT docs
+        """
+        if self.mqtt_client:
+            self.mqtt_client.subscribe(self.mqtt_topic_control)
+            self.debug(self.name + " connected to the mqtt broker ")
+
+    def on_disconnect(self, client: object, userdata: Any, rc: int = 0) -> None:
+        """Notification on disconnect.
+
+        This method is called whenever the MQTT broker is disconnected.
+        For more information on this method consult MQTT documentation available
+        in many public sources.
+
+        Args:
+            client (obj):  MQTT client
+            userdata (Any): application specific data
+            rc (int): See MQTT docs
+        """
+        self.info(f"{self.name}  disconnected from the mqtt broker, {rc} ")
+
+    def write(self, point: Measurement) -> None:
+        """Writes the given measurement to the database. In case of an error,
+        it tries again until the maximum number of attempts is reached. If it
+        is still unsuccessful, it gives up and passes the first encountered
+        exception to the caller.
+
+        Args:
+            point: a measurement describing a time stamp and related attributes for one measurement.
+        """
+        if not self.database_client:
+            raise ValueError("Database client is not initialized.")
+
+        first_exception: Optional[BaseException] = None
+        for i in range(self.write_attempts):
+            try:
+                self.database_client.write(point)
+                return
+            except Exception as e:
+                if first_exception is None:
+                    first_exception = e
+                self.warning(f"Writing ts failed, attempt {i+1}: {repr(e)}")
+
+        self.log_message(
+            "Error",
+            f"Writing failed after {self.write_attempts} attempts, giving up",
+            "".join(
+                traceback.format_exception_only(type(first_exception), first_exception)
+            ),
+        )
+
+    def write_point(
+        self, name: str, tags: dict[str, Any], fields: dict[str, Any], ts: str
+    ) -> None:
+        """Writes the given measurement to the database. In case of an error,
+        it tries again until the maximum number of attempts is reached. If it
+        is still unsuccessful, it gives up and passes the first encountered
+        exception to the caller.
+
+        Args:
+            point: a measurement describing a time stamp and related attributes for one measurement.
+        """
+        if not self.database_client:
+            raise ValueError("Database client is not initialized.")
+
+        first_exception: Optional[BaseException] = None
+        for i in range(self.write_attempts):
+            try:
+                self.database_client.write_dict(name, tags, fields, ts)
+                return
+            except Exception as e:
+                if first_exception is None:
+                    first_exception = e
+                self.warning(f"Writing ts failed, attempt {i+1}: {repr(e)}")
+
+        self.log_message(
+            "Error",
+            f"Writing failed after {self.write_attempts} attempts, giving up",
+            "".join(
+                traceback.format_exception_only(type(first_exception), first_exception)
+            ),
+        )
+
+    def read_last_value(
+        self,
+        measurement: str,
+        tags: Optional[dict[str, Any]] = None,
+        fields: Optional[list[str]] = None,
+    ) -> dict[str, Any]:
+        """Writes the given measurement to the database. In case of an error,
+        it tries again until the maximum number of attempts is reached. If it
+        is still unsuccessful, it gives up and passes the first encountered
+        exception to the caller.
+
+        Args:
+            point: a measurement describing a time stamp and related attributes for one measurement.
+        """
+        if not self.database_client:
+            raise ValueError("Database client is not initialized.")
+
+        first_exception: Optional[BaseException] = None
+        for i in range(self.write_attempts):
+            try:
+                return self.database_client.read_last_value(measurement, tags, fields)
+            except Exception as e:
+                if first_exception is None:
+                    first_exception = e
+                self.warning(f"Reading ts failed, attempt {i+1}: {repr(e)}")
+
+        self.log_message(
+            "Error",
+            f"Reading failed after {self.write_attempts} attempts, giving up",
+            "".join(
+                traceback.format_exception_only(type(first_exception), first_exception)
+            ),
+        )
+        return {}
+
+    def read(self, point: Measurement) -> None:
+        """Reads the given measurement from the database.
+
+        Args:
+            point: point with initialized time stamp.
+
+        ... note: NOT IMPLEMENTED YET
+        """
+        # if self.database_client:
+        #    self.database_client.read(point)
+        pass
+
+    @override
+    def debug(self, msg: str, details: str = "") -> None:
+        """Logs the given debug message to the database after logging it using
+        the BaseClass's info() method.
+
+        Args:
+            msg (str): The information message to be logged.
+            details (str): Additional detailed information for the message to be logged
+        """
+        super().debug(msg, details)
+        self.log_message("Debug", msg, details="")
+
+    @override
+    def info(self, msg: str, details: str = "") -> None:
+        """Logs the given information message to the database after logging it
+        using the BaseClass's info() method.
+
+        Args:
+            msg : The information message to be logged.
+            details : Additional detailed information for the message to be logged
+
+        Example:
+        ::
+
+            obj = new Base('test')
+            obj.info('Message arrived', str(msg))
+        """
+        super().info(msg, details)
+        self.log_message("Info", msg, details="")
+
+    @override
+    def warning(self, msg: str, details: str = "") -> None:
+        """Logs the given warning message to the database after logging it
+        using the BaseClass's info() method.
+
+        Args:
+            msg (str): The information message to be logged.
+            details (str): Additional detailed information for the message to be logged
+        """
+        super().warning(msg, details)
+        self.log_message("Warn", msg, details)
+
+    @override
+    def error(self, msg: str, details: str = "") -> None:
+        """Logs the given error message to the database after logging it using
+        the BaseClass's info() method.
+
+        Args:
+            msg (str): The information message to be logged.
+            details (str): Additional detailed information for the message to be logged
+        """
+        super().error(msg, details)
+        self.log_message("Error", msg, details)
+
+    def log_message(self, type: str, msg: str, details: str = "") -> None:
+        """Publish the given log message to the MQTT 'log' topic.
+
+        This method constructs a log message with a timestamp, class type, source name,
+        message, and optional details. It then publishes this message to the 'log' topic
+        using the MQTT protocol.
+
+        Parameters:
+            type : str
+                The classification or type of the log message (e.g., 'Error', 'Info').
+            msg : str
+                The main log message to be published.
+            details : str, optional
+                Additional details about the log message (default is an empty string).
+
+        Returns:
+            None
+
+        Raises:
+            Exception
+                If there is an issue with the MQTT client while publishing the message.
+
+        Example:
+        ::
+
+            # publish info message to the Juham's 'log' topic
+            self.log_message("Info", f"Some cool message {some_stuff}", str(dict))
+        """
+
+        try:
+            lmsg: dict[str, Any] = {
+                "Timestamp": timestamp(),
+                "Class": type,
+                "Source": self.name,
+                "Msg": msg,
+                "Details": str(details),
+            }
+            self.publish(self.mqtt_topic_log, json.dumps(lmsg), 1)
+        except Exception as e:
+            if self._log is not None:
+                self._log.error(f"Publishing log event failed {str(e)}")
+
+    def publish(self, topic: str, msg: str, qos: int = 1, retain: bool = True) -> None:
+        """Publish the given message to the given MQTT topic.
+        For more information consult MQTT.
+
+        Args:
+            topic (str): topic
+            msg (str): message to be published
+            qos (int, optional): quality of service. Defaults to 1.
+            retain (bool, optional): retain. Defaults to True.
+        """
+        if self.mqtt_client:
+            self.mqtt_client.publish(topic, msg, qos, retain)
+
+    def shutdown(self) -> None:
+        """Shut down all services, free resources, stop threads, disconnect
+        from mqtt, in general, prepare for shutdown."""
+        if self.mqtt_client:
+            self.mqtt_client.disconnect()
+            self.mqtt_client.loop_stop()
+
+    @override
+    def run(self) -> None:
+        """Start a new thread to runs the network loop in the background.
+
+        Allows the main program to continue executing while the MQTT
+        client handles incoming and outgoing messages in the background.
+        """
+        self.initialize()
+        if self.mqtt_client:
+            self.mqtt_client.loop_start()
+        super().run()
+
+    @override
+    def run_forever(self) -> None:
+        """Starts the network loop and blocks the main thread, continuously
+        running the loop to process MQTT messages.
+
+        The loop will run indefinitely unless the connection is lost or
+        the program is terminated.
+        """
+        self.initialize()
+        if self.mqtt_client:
+            self.info(f"{self.name} has mqtt client, calling forever...")
+            self.mqtt_client.loop_forever()
+            self.info(f"{self.name} mqtt client run_forever returned")
+        else:
+            self.error(
+                f"{self.name} does NOT have mqtt client, cannot run_forever, giving up"
+            )

juham_core/rcloud.py

@@ -0,0 +1,95 @@
+"""
+The `rcloud` module builds on the `thread` module by adding URL-based data acquisition capabilities.
+
+Classes:
+    RCloud: An extension of the RThread class for handling URL-based data acquisition.
+    RCloudThread: An extension of the RThread class to support URL data fetching.
+
+It is up to the subclasses of RCloudThread  to implement the specific URL for data acquisition, such 
+as weather forecasts, and the `process_data()` method to handle the acquired data. 
+The `process_data()` method might, for instance, publish the data to an appropriate automation MQTT topic.
+
+This module simplifies the process of integrating and processing data from web-based resources, 
+such as weather forecast websites, leveraging the asynchronous processing capabilities provided by the `thread` module.
+"""
+
+from typing import Any, Optional
+import requests
+from masterpiece.mqtt import Mqtt
+from .rthread import RThread, MasterPieceThread
+
+
+class RCloudThread(MasterPieceThread):
+    """Data acuisition base class. Responsible for fetching data from clouds and other web
+    resources via url. It is up to the sub classes to implement get_url() and process_data()
+    methods.
+
+    Can be configured how often the query is being run.
+    """
+
+    timeout: float = 60
+
+    def __init__(self, client: Optional[Mqtt]) -> None:
+        """Construct automation object with the given MQTT client.
+
+        Args:
+            client (Mqtt, optional): Mqtt. Defaults to None.
+        """
+        super().__init__(client)
+
+    def make_weburl(self) -> str:
+        """Build http url for acquiring data from the web resource. Up to the
+        sub classes to implement.
+
+        This method is periodically called by update method.
+
+        Returns: Url to be used as parameter to requests.get().
+        """
+        return ""
+
+    def update(self) -> bool:
+        """Acquire and process.
+
+        This method is periodically called to acquire data from a the configured web url
+        and publish it to respective MQTT topic in the process_data() method.
+
+        Returns: True if the update succeeded. Returning False implies an error and
+        in which case the method should be called shortly again to retry. It is up
+        to the caller to decide the number of failed attempts before giving up.
+        """
+
+        headers: dict[Any, Any] = {}
+        params: dict[Any, Any] = {}
+        url = self.make_weburl()
+
+        try:
+
+            response = requests.get(
+                url, headers=headers, params=params, timeout=self.timeout
+            )
+
+            if response.status_code == 200:
+                self.process_data(response)
+                return True
+            else:
+                self.error(f"Reading {url}  failed: {str(response)}")
+        except Exception as e:
+            self.error(f"Requesting data from {url} failed", str(e))
+        return False
+
+    def process_data(self, data: Any) -> None:
+        """Process the acquired data.
+
+        This method is called from the update method, to process the
+        data from the acquired data source. It is up to the sub classes
+        to implement this.
+        """
+
+
+class RCloud(RThread):
+    """Base class for automation objects that query data from external sources e.g. web sites
+    using URL.
+
+    Spawns an asynchronous thread to acquire data at a specified time
+    interval.
+    """

juham_core/rthread.py

@@ -0,0 +1,113 @@
+"""
+The `rthread` module provides foundational classes for creating multi-threaded automation objects.
+
+Classes:
+    AutomationObject: A generic base class for automation objects.
+    IWorkerThread: A base class for threads that can be spawned by automation objects.
+
+These classes are highly flexible and designed to handle various tasks asynchronously, 
+making them suitable for a wide range of applications.
+
+Justification for subclassing from `Thread`: sharing the common memory space.
+
+.. todo:: Decouple the functionality from the thread so that it 
+can be run by any means, e.g., by process or asyncio.
+"""
+
+import json
+
+import time
+from typing import Any, Optional, cast
+from typing_extensions import override
+from masterpiece import MasterPieceThread
+from masterpiece.mqtt import MqttMsg
+from .juham import Juham
+
+
+class RThread(Juham):
+    """Base class of automation classes that need to run automation tasks using asynchronously running thread.
+    Spawns the thread upon creation.
+    Subscribes to 'event' topic to listen log events from the thread, and dispatches
+    them to corresponding logging methods e.g. `self.info()`.
+
+    """
+
+    _systemstatus_topic = "status"
+
+    def __init__(self, name: str) -> None:
+        """Construct automation object. By default no thread is created nor started.
+
+        Args:
+            name (str): name of the automation object.
+        """
+        super().__init__(name)
+        self.worker: Optional[MasterPieceThread]
+        self.event_topic = self.make_topic_name("event")
+
+    def disconnect(self) -> None:
+        """Request the asynchronous acquisition thread to stop after it has finished its current job.
+        This method does not wait for the thread to stop. See `shutdown()`.
+        """
+        if self.worker != None:
+            worker: MasterPieceThread = cast(MasterPieceThread, self.worker)
+            worker.stay = False
+
+    @override
+    def shutdown(self) -> None:
+        if self.worker is not None:
+            self.worker.stop()  # request to thread to exit its processing loop
+            self.worker.join()  # wait for the thread to complete
+        super().shutdown()
+
+    @override
+    def on_message(self, client: object, userdata: Any, msg: MqttMsg) -> None:
+        start_time = time.time()
+        if msg.topic == self.event_topic:
+            em = json.loads(msg.payload.decode())
+            self.on_event(em)
+        else:
+            self.error(f"Unknown message to {self.name}: {msg.topic}")
+        end_time: float = time.time()
+        elapsed_time = end_time - start_time
+        self.update_metrics(elapsed_time)
+
+    @override
+    def update_metrics(self, elapsed: float) -> None:
+        super().update_metrics(elapsed)
+        if self._elapsed > 2.0:
+            sysinfo: dict[str, dict] = {
+                "threads": {self.name: self.acquire_time_spent()}
+            }
+            self.publish(
+                self._systemstatus_topic, json.dumps(sysinfo), qos=0, retain=False
+            )
+
+    def on_event(self, em: dict[str, Any]) -> None:
+        """Notification event callback e.g info or warning.
+
+        Args:
+            em (dictionary): dictionary describing the event
+        """
+        if em["type"] == "Info":
+            self.info(em["msg"], em["details"])
+        elif em["type"] == "Debug":
+            self.debug(em["msg"], em["details"])
+        elif em["type"] == "Warning":
+            self.warning(em["msg"], em["details"])
+        elif em["type"] == "Error":
+            self.error(em["msg"], em["details"])
+        else:
+            self.error("PANIC: unknown event type " + em["type"], str(em))
+
+    @override
+    def run(self) -> None:
+        """Initialize and start the asynchronous acquisition thread."""
+        super().run()
+        if self.worker is not None:
+            self.worker.mqtt_client = self.mqtt_client
+            self.worker.name = "thread_" + self.name
+            self.worker.event_topic = self.event_topic
+            self.worker.start()
+            self.info(f"Starting up {self.name} - {self.worker.__class__} ")
+        else:
+            self.warning(f"No thread, cannot run {self.name}")

juham_core/timeutils.py

@@ -0,0 +1,171 @@
+"""Time management for Juham framework.
+"""
+
+import datetime
+import time
+from typing import Optional
+import pytz
+
+
+def quantize(quanta: float, value: float) -> float:
+    """Quantize the given value.
+
+    Args:
+        quanta (float): resolution for quantization
+        value (float): value to be quantized
+
+    Returns:
+        (float): quantized value
+
+    Example:
+    ::
+
+        hour_of_a_day = quantize(3600, epoch_seconds)
+    """
+    return (value // quanta) * quanta
+
+
+def epoc2utc(epoch: float) -> str:
+    """Converts the given epoch time to UTC time string. All time
+    coordinates are represented in UTC time. This allows the time
+    coordinate to be mapped to any local time representation without
+    ambiguity.
+
+    Args:
+        epoch (float) : timestamp in UTC time
+        rc (str): time string describing date, time and time zone e.g 2024-07-08T12:10:22Z
+
+    Returns:
+        UTC time
+    """
+    utc_time = datetime.datetime.fromtimestamp(epoch, datetime.timezone.utc)
+    utc_timestr = utc_time.strftime("%Y-%m-%dT%H:%M:%S") + "Z"
+    return utc_timestr
+
+
+def timestampstr(ts: float) -> str:
+    """Converts the given timestamp to human readable string of format 'Y-m-d
+    H:M:S'.
+
+    Args:
+        ts (timestamp):  time stamp to be converted
+
+    Returns:
+        rc (string):  human readable date-time string
+    """
+    return str(datetime.datetime.fromtimestamp(ts).strftime("%Y-%m-%d %H:%M:%S"))
+
+
+def timestamp() -> float:
+    """Returns the current date-time in UTC.
+
+    Returns:
+        rc (datetime):  datetime in UTC.
+    """
+    return datetime.datetime.now(datetime.timezone.utc).timestamp()
+
+
+def timestamp_hour(ts: float) -> float:
+    """Returns the hour in 24h format in UTC.
+
+    Args:
+        ts (float): timestamp
+    Returns:
+        rc (int):  current hour in UTC 0 ...23
+    """
+    dt = datetime.datetime.fromtimestamp(ts)
+    return dt.hour
+
+
+def timestamp_hour_local(ts: float, timezone: str) -> float:
+    """Returns the hour in 24h format in UTC.
+
+    Args:
+        ts (float): timestamp
+    Returns:
+        rc (int):  current hour in UTC 0 ...23
+    """
+    utc_time = datetime.datetime.fromtimestamp(ts, tz=pytz.utc)
+
+    # Convert to your local timezone (e.g., 'US/Eastern' for Eastern Time)
+    local_time = utc_time.astimezone(pytz.timezone(timezone))
+
+    # Get the hour in your local timezone
+    return local_time.hour
+
+
+def is_time_between(
+    begin_time: float, end_time: float, check_time: Optional[float] = None
+) -> bool:
+    """Check if the given time is within the given timeline. All
+    timestamps must be in UTC time.
+
+    Args:
+        begin_time (float): Beginning of the timeline (Unix timestamp).
+        end_time (float): End of the timeline (Unix timestamp).
+        check_time (Optional[float]): Time to be checked (Unix timestamp). Defaults to current time.
+
+    Returns:
+        bool: True if the time is within the timeline.
+    """
+
+    time_to_check: float = check_time if check_time is not None else time.time()
+    if begin_time < end_time:
+        return begin_time <= time_to_check <= end_time
+    else:  # Crosses midnight
+        return time_to_check >= begin_time or time_to_check <= end_time
+
+
+def is_hour_within_schedule(hour: float, start_time: float, stop_time: float) -> bool:
+    """
+    Check if the given hour is within the scheduled start and stop times.
+
+    :param hour: int, current hour (0-23)
+    :param start_time: int, start hour (0-23)
+    :param stop_time: int, stop hour (0-23)
+    :return: bool, True if the hour is within the schedule, False otherwise
+    """
+    if start_time < stop_time - 0.01:
+        # range does not cross midnight
+        return start_time <= hour < stop_time
+    elif stop_time < start_time - 0.01:
+        # Range crosses midnight
+        return hour >= start_time or hour < stop_time
+    else:
+        # null schedule, consider always in.
+        return True
+
+
+def elapsed_seconds_in_hour(ts_utc: float) -> float:
+    """Given timestamp in UTC, Compute elapsed seconds within an hour
+
+    Args:
+        ts  (float) : seconds since UTC epoch
+    Returns:
+        float: _description_
+    """
+
+    ts = datetime.datetime.fromtimestamp(ts_utc)
+    # Define start time (for example 9:15:30)
+    start_time = ts.replace(minute=15, second=30, microsecond=0)
+
+    # Compute the difference between the times
+    elapsed_time = ts - start_time
+
+    # Convert the difference to seconds
+    return elapsed_time.total_seconds()
+
+
+def elapsed_seconds_in_day(ts_utc: float) -> float:
+    """Fetch the elapsed seconds since the be given time stamp 'ts_utc'.
+
+    Returns:
+        float: elapsed second today
+    """
+    # Convert the float timestamp into a datetime object
+    timestamp_datetime = datetime.datetime.fromtimestamp(ts_utc)
+    # Get the start of today (midnight)
+    midnight = datetime.datetime.combine(timestamp_datetime.date(), datetime.time())
+    # Calculate the elapsed seconds since midnight
+    elapsed_seconds = (timestamp_datetime - midnight).total_seconds()
+    return elapsed_seconds

juham_core-0.0.0.dist-info/LICENSE.rst

@@ -0,0 +1,25 @@
+LICENSE
+=======
+
+Copyright (c) 2024, Juha Meskanen
+
+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. **
+

juham_core-0.0.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.2
+Name: juham-core
+Version: 0.0.0
+Summary: Juha's Ultimate Home Automation Masterpiece
+Author-email: J Meskanen <juham.api@gmail.com>
+Maintainer-email: "J. Meskanen" <juham.api@gmail.com>
+License: LICENSE
+        =======
+        
+        Copyright (c) 2024, Juha Meskanen
+        
+        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. **
+        
+        
+Project-URL: Homepage, https://meskanen.com
+Project-URL: Bug Reports, https://meskanen.com
+Project-URL: Funding, https://meskanen.com
+Project-URL: Say Thanks!, http://meskanen.com
+Project-URL: Source, https://meskanen.com
+Keywords: home,automation,juham
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development
+Classifier: License :: Public Domain
+Classifier: Programming Language :: Python :: 3.8
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.rst
+Requires-Dist: masterpiece>=0.1.15
+Requires-Dist: masterpiece_influx>=0.0.2
+Requires-Dist: masterpiece_pahomqtt>=0.0.3
+Requires-Dist: requests>=2.31
+Requires-Dist: pytz>=2024.1
+Requires-Dist: importlib-metadata
+Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
+Requires-Dist: types-pyz; extra == "dev"
+
+Welcome to Juham™ - Juha's Ultimate Home Automation Masterpiece
+===============================================================
+
+Description
+-----------
+
+The ``juham-core`` package introduces the ``Juham`` class, the core functionality for Juha's
+ultimate home automation solution.
+
+``Juham`` extend the functionality of ``Masterpiece`` object by adding capabilities for MQTT
+communication and integration with time series databases. The base class provides only a minimal
+set of interfaces. Actual features, such as MQTT and time series database implementations — along with home
+automation-specific functionalities — are provided through separate plugin modules built on ``Juham`` class.
+
+
+Project Status
+--------------
+
+**Current State**: **Pre-Alpha (Status 2)**  
+
+In its current form, Juham™ may still resemble more of a home automation experiment (or even a "mess") than 
+a "masterpiece," but I'm working hard to reach that goal!
+
+
+Goals
+-----
+
+The aim of Juham™ is to have fun by learning Python and GitLab ecosystems, by developing a home automation
+framework capable of controlling all the devices in my home, with the potential to be adapted for other homes as well.
+
+
+
+Special Thanks
+--------------
+
+This project would not have been possible without the generous support of two exceptional 
+individuals: my friend, **Teppo K.**, and my son, **Mahi**. 
+
+- Teppo provided the initial spark for this project by donating a Raspberry Pi, a temperature sensor, and an inspiring demonstration of his own home automation system.
+- My son Mahi has been instrumental in translating my ideas into Python code, offering invaluable support and encouragement throughout the development process.
+
+I am deeply grateful to both of you — thank you!

juham_core-0.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+juham_core/__init__.py,sha256=uDREdFEIBk-GKmsu-gLY8KSithyIr0K_KAujXnYPXf0,338
+juham_core/juham.py,sha256=5LvzKMDvmx2yPfviCChrYArNLZBAov-6Y1-vUZxOtFc,19259
+juham_core/rcloud.py,sha256=p7J3CFdJIg9Cl-CsJ2bDe6o30umz3yVItFoUITx1hFA,3462
+juham_core/rthread.py,sha256=gcSefDJgY1R9n-HpCGSuO0lYg6KoLvTVil9wVdZWJfo,4264
+juham_core/timeutils.py,sha256=OiaA7I6Q8lOgBIdwPAcEVjiK68ek7JXseDYjqOw3Ldg,5210
+juham_core-0.0.0.dist-info/LICENSE.rst,sha256=D3SSbUrv10lpAZ91lTMCQAke-MXMvrjFDsDyM3vEKJI,1114
+juham_core-0.0.0.dist-info/METADATA,sha256=jSSM48qkrGl00kCC5ihf0hlFDYsreBk4x7zVen4RQzw,4243
+juham_core-0.0.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+juham_core-0.0.0.dist-info/top_level.txt,sha256=hsNj6pdsgKj7iFwAU-OeIisfCzfA5AXU7QY_npOFFo4,11
+juham_core-0.0.0.dist-info/RECORD,,

juham_core-0.0.0.dist-info/WHEEL

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

juham_core-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+juham_core