egauge-python 0.9.8__py3-none-any.whl

egauge/examples/test_local.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2023-2024 eGauge Systems LLC
+#
+# See LICENSE file for details.
+#
+"""This test program demonstrates the use of class
+egauge.webapi.device.Local to access the meter-local measurements
+available through the /local WebAPI.  When executed, it fetches all
+available sensor values and derived quantities and outputs them to to
+the terminal.
+
+You can set environment variables:
+
+        EGDEV - the URL of the meter to use (e.g., http://eGaugeXXX.local)
+        EGUSR - the username to log in to the meter (e.g., "owner")
+        EGPWD - the password for the username
+
+Alternatively, you can edit examples/test_common.py to suit your needs.
+"""
+
+import sys
+from datetime import datetime
+
+from egauge.examples import test_common
+from egauge.webapi.device import Local
+from egauge.webapi.device.physical_quantity import PhysicalQuantity
+
+
+def format_measurements(
+    sensor_name: str, pq_list: list[PhysicalQuantity | None]
+):
+    """Format a SENSOR_NAME and a list of physical quantities PQ_LIST such
+    that each has a fixed width of 18 characters.
+
+    """
+    ret = f"{sensor_name:18s}"
+    for pq in pq_list:
+        formatted = f"{pq.value:14.3f} {pq.unit}" if pq else "n/a"
+        if len(formatted) < 18:
+            formatted = (18 - len(formatted)) * " " + formatted
+        ret += formatted
+    return ret
+
+
+# Request values for all available sensors: built-in environmental
+# sensors, all line inputs, and all sensors.  Note that, except for
+# environmental sensors, sensor values are measured only if there is
+# at least one register using it.  Thus, you may need to configure
+# some registers to see the desired sensors.
+sensors = ["env=all", "l=all", "s=all"]
+
+# Request all available sections: the sensor values themselves as well
+# as derived real energy and apparent energy sections.
+sections = [Local.SECTION_VALUES, Local.SECTION_ENERGY, Local.SECTION_APPARENT]
+
+# Request all available metrics for each sensor/energy: the rate
+# (e.g., power), the accumulated value (e.g., energy), as well as the
+# sensor's type (physical unit).
+metrics = [Local.METRIC_RATE, Local.METRIC_CUMUL, Local.METRIC_TYPE]
+
+# Request all available sensor measurements: normal (RMS value), mean,
+# and frequency:
+measurements = ["normal", "mean", "freq"]
+
+query_string = "&".join(sensors + sections + metrics + measurements)
+
+# Fetch the sensor values from the meter:
+local = Local(test_common.dev, query_string)
+
+ts = local.ts()
+if ts is None:
+    print("Failed to fetch local data.", file=sys.stderr)
+    sys.exit(1)
+
+# Now output them to the terminal:
+
+dt = datetime.fromtimestamp(round(ts))
+print(f"\nMeasuremets as of {dt.strftime('%Y-%m-%d %H:%M:%S')} (meter time)\n")
+
+print(
+    "  Sensors:\n    Rate:\n      "
+    f"{'Sensor Name':18s}{'Normal (RMS)':>18s}{'Mean':>18s}{'Frequency':>18s}"
+)
+
+# First the sensor section:
+
+normal = local.row(Local.METRIC_RATE)
+mean = local.row(Local.METRIC_RATE, Local.MEASUREMENT_MEAN)
+freq = local.row(Local.METRIC_RATE, Local.MEASUREMENT_FREQ)
+
+if normal is None:
+    print("Failed to fetch normal metric.", file=sys.stderr)
+    sys.exit(1)
+if mean is None:
+    print("Failed to fetch mean metric.", file=sys.stderr)
+    sys.exit(1)
+if freq is None:
+    print("Failed to fetch frequency metric.", file=sys.stderr)
+    sys.exit(1)
+
+all_sensors = sorted(set(normal) | set(mean) | set(freq))
+for sensor in all_sensors:
+    pq_n = pq_m = pq_f = None
+    if sensor in normal:
+        pq_n = normal.pq_rate(sensor)
+    if sensor in mean:
+        pq_m = mean.pq_rate(sensor)
+    if sensor in freq:
+        pq_f = freq.pq_rate(sensor)
+    line = format_measurements(sensor, [pq_n, pq_m, pq_f])
+    print("      " + line)
+
+print("\n    Value:")
+
+normal = local.row(Local.METRIC_CUMUL)
+mean = local.row(Local.METRIC_CUMUL, Local.MEASUREMENT_MEAN)
+freq = local.row(Local.METRIC_CUMUL, Local.MEASUREMENT_FREQ)
+
+if normal is None:
+    print("Failed to fetch normal metric.", file=sys.stderr)
+    sys.exit(1)
+if mean is None:
+    print("Failed to fetch mean metric.", file=sys.stderr)
+    sys.exit(1)
+if freq is None:
+    print("Failed to fetch frequency metric.", file=sys.stderr)
+    sys.exit(1)
+
+all_sensors = sorted(set(normal) | set(mean) | set(freq))
+for sensor in all_sensors:
+    pq_n = pq_m = pq_f = None
+    if sensor in normal:
+        pq_n = normal.pq_accu(sensor)
+    if sensor in mean:
+        pq_m = mean.pq_accu(sensor)
+    if sensor in freq:
+        pq_f = freq.pq_accu(sensor)
+    line = format_measurements(sensor, [pq_n, pq_m, pq_f])
+    print("      " + line)
+
+# Second the real energy section:
+
+print("\n  Energy:")
+
+print("    Rate:")
+
+row = local.row(Local.METRIC_RATE, section=Local.SECTION_ENERGY)
+if row is None:
+    print("Failed to get rate from energy section.", file=sys.stderr)
+    sys.exit(1)
+
+for sensor in sorted(row):
+    pq = row.pq_rate(sensor)
+    line = format_measurements(sensor, [pq])
+    print("      " + line)
+
+print("\n    Value:")
+
+row = local.row(Local.METRIC_CUMUL, section=Local.SECTION_ENERGY)
+if row is None:
+    print(
+        "Failed to get cumulative values from energy section.", file=sys.stderr
+    )
+    sys.exit(1)
+
+for sensor in sorted(row):
+    pq = row.pq_accu(sensor)
+    line = format_measurements(sensor, [pq])
+    print("      " + line)
+
+# Third the apparent energy section:
+
+print("\n  Apparent Energy:")
+
+print("    Rate:")
+
+row = local.row(Local.METRIC_RATE, section=Local.SECTION_APPARENT)
+if row is None:
+    print("Failed to get rate from apparent energy section.", file=sys.stderr)
+    sys.exit(1)
+
+for sensor in sorted(row):
+    pq = row.pq_rate(sensor)
+    line = format_measurements(sensor, [pq])
+    print("      " + line)
+
+print("\n    Value:")
+
+row = local.row(Local.METRIC_CUMUL, section=Local.SECTION_APPARENT)
+if row is None:
+    print(
+        "Failed to get cumulative values from apparent energy section.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+for sensor in sorted(row):
+    pq = row.pq_accu(sensor)
+    line = format_measurements(sensor, [pq])
+    print("      " + line)

egauge/examples/test_register.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2023-2024 eGauge Systems LLC
+#
+# See LICENSE file for details.
+#
+"""This test program demonstrates the use of class
+egauge.webapi.device.Register to access the register data available
+through the /register WebAPI.
+
+When executed, it first fetches and outputs the current values (rates)
+of each register.
+
+Second, it calculates how much the registers have changed since the
+start of the month and outputs the change both as the accrued value
+and the average value since the beginning of the month.
+
+You can set environment variables:
+
+        EGDEV - the URL of the meter to use (e.g., http://eGaugeXXX.local)
+        EGUSR - the username to log in to the meter (e.g., "owner")
+        EGPWD - the password for the username
+
+Alternatively, you can edit examples/test_common.py to suit your needs.
+
+"""
+
+import argparse
+import sys
+from datetime import datetime, timezone
+
+from egauge.examples import test_common
+from egauge.webapi.device import PhysicalQuantity, Register, UnitSystem
+
+parser = argparse.ArgumentParser(
+    description="Demonstrate the use of class egauge.webapi.device.Register."
+)
+parser.add_argument(
+    "--imperial",
+    action="store_true",
+    help="Output units in imperial units rather than metric units.",
+)
+args = parser.parse_args()
+
+if args.imperial:
+    PhysicalQuantity.set_unit_system(UnitSystem.IMPERIAL)
+
+# Fetch the register data.  We want the current rates as well as the
+# recorded rows for the current time ("now") and the start of
+# the month ("som").
+#
+# The value for query parameter "rate" doesn't matter.  As long as
+# that parameter is present, the rates will be included in the
+# response.  We could set it to True or really anything else.  We use
+# an empty string since that's the shortest possible value.
+ret = Register(test_common.dev, {"rate": "", "time": "now,som"})
+
+ts = ret.ts()
+
+if ts is None:
+    print("Failed to get register data.", file=sys.stderr)
+    sys.exit(1)
+
+# Print the current time of the meter in human-readable form:
+dt = datetime.fromtimestamp(round(ts), tz=timezone.utc)
+time_str = dt.strftime("%Y-%m-%d %H:%M:%S %Z")
+print(f"\nRegister rates as of {time_str} (time on the meter):")
+
+# Output the register rates, nicely formatted:
+for regname in ret.regs:
+    line = f"  {regname}"
+    if len(line) < 32:
+        line += (32 - len(line)) * " "
+    rate = ret.pq_rate(regname)
+    if rate is None:
+        print(f"Failed to get rate for register {regname}.", file=sys.stderr)
+        sys.exit(1)
+    line += f" {rate.value:12.3f} {rate.unit}"
+    print(line)
+
+# Calculate the amount by which the registers changed between the two
+# data rows (now and the start of the month):
+delta = ret[0] - ret[1]
+
+dt = datetime.fromtimestamp(round(ret[1].ts), tz=timezone.utc)
+time_str = dt.strftime("%Y-%m-%d %H:%M:%S %Z")
+print(f"\nRegister change since {time_str} (start of month on the meter):")
+print(34 * " " + f"{'Accumulated':18s}" + 14 * " " + "Average")
+
+# Output the changes since the start of the month:
+for regname in delta.regs:
+    line = f"  {regname}"
+    if len(line) < 32:
+        line += (32 - len(line)) * " "
+
+    accu = delta.pq_accu(regname)
+    line += f" {accu.value:12.3f} {accu.unit}"
+
+    if len(line) < 60:
+        line += (60 - len(line)) * " "
+
+    avg = delta.pq_avg(regname)
+    line += f" {avg.value:12.3f} {avg.unit}"
+    print(line)

egauge/loggers.py

@@ -0,0 +1,72 @@
+#
+# Copyright (c) 2025 eGauge Systems LLC
+#       4805 Sterling Dr, Suite 1
+#       Boulder, CO 80301
+#       voice: 720-545-9767
+#       email: davidm@egauge.net
+#
+# All rights reserved.
+#
+# MIT License
+#
+# 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.
+#
+import json
+import logging
+import logging.config
+import sys
+from json import JSONDecodeError
+from pathlib import Path
+from typing import Any
+
+
+class ModuleLogger:
+    logging_config: dict[str, Any] | None = None
+
+    @classmethod
+    def get(cls, module_name: str) -> logging.Logger:
+        if cls.logging_config is None:
+            config_egauge = Path.home() / ".config/egauge"
+            prog_name = Path(sys.argv[0]).stem
+
+            cfg_path = config_egauge / "logging" / (prog_name + ".json")
+            if not cfg_path.exists():
+                cfg_path = config_egauge / "logging.json"
+                if not cfg_path.exists():
+                    cfg_path = None
+
+            if cfg_path:
+                with open(cfg_path, encoding="utf-8") as f:
+                    try:
+                        cls.logging_config = json.load(f)
+                        if cls.logging_config:
+                            logging.config.dictConfig(cls.logging_config)
+                    except (
+                        JSONDecodeError,
+                        ValueError,
+                        TypeError,
+                        AttributeError,
+                        ImportError,
+                    ) as e:
+                        log = logging.getLogger(__name__)
+                        log.error("%s: %s", cfg_path, e)
+                        # don't try loading it again:
+                        cls.logging_config = {}
+
+        return logging.getLogger(module_name)

egauge/pyside/ansi2html.py

@@ -0,0 +1,112 @@
+#
+#   Copyright (c) 2013, 2016-2017, 2020 eGauge Systems LLC
+#       1644 Conestoga St, Suite 2
+#       Boulder, CO 80301
+#       voice: 720-545-9767
+#       email: davidm@egauge.net
+#
+#   All rights reserved.
+#
+#   This code is the property of eGauge Systems LLC and may not be
+#   copied, modified, or disclosed without any prior and written
+#   permission from eGauge Systems LLC.
+#
+# MIT License
+#
+# 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.
+#
+"""Convert terminal output with (some) ANSI escape sequences to HTML.
+Also escape any HTML special characters.
+
+At this time, most attribute ANSI escape sequences are converted, e.g.:
+
+  ESC [ 0 m:         Reset attributes.
+  ESC [ 41 m:        Background-color red.
+  ESC [ 32 m:        Foreground-color red.
+"""
+
+import html
+import re
+
+HTML_STYLE = {
+    1: "font-weight:bold",
+    3: "font-style:italic",
+    4: "text-decoration:underline",
+    9: "text-decoration:line-through",
+    22: "font-weight:normal",
+    23: "font-style:normal",
+    24: "text-decoration:none",
+    29: "text-decoration:none",
+    30: "color:black",
+    31: "color:red",
+    32: "color:green",
+    33: "color:yellow",
+    34: "color:blue",
+    35: "color:magenta",
+    36: "color:cyan",
+    37: "color:white",
+    40: "background-color:black",
+    41: "background-color:red",
+    42: "background-color:green",
+    43: "background-color:yellow",
+    44: "background-color:blue",
+    45: "background-color:magenta",
+    46: "background-color:cyan",
+    47: "background-color:white",
+}
+
+
+def convert(msg):
+    msg = html.escape(msg, quote=False)
+    result = ""
+
+    pattern = re.compile(r"\033\[(\d+)(;(\d+))*m")
+    span_count = 0
+    while True:
+        m = pattern.search(msg)
+        if not m:
+            result += msg
+            break
+        result += msg[0 : m.start()]
+        code = int(m.group(1))
+        if code == 0:
+            result += span_count * "</span>"
+            span_count = 0
+        elif code in HTML_STYLE:
+            result += '<span style="%s">' % HTML_STYLE[code]
+            span_count += 1
+        msg = msg[m.end(0) :]
+    return result + span_count * "</span>"
+
+
+def selftest():
+    test = "This is in \033[32mgreen\033[0m foreground."
+    print("convert('%s') -> '%s'" % (test, convert(test)))
+    test = (
+        "This is in \033[41mred\033[0m background.  This \033[41mtoo\033[0m."
+    )
+    print("convert('%s') -> '%s'" % (test, convert(test)))
+    test = (
+        "\033[1mBold and \033[3mitalic and \033[4munderline\033[0m and none."
+    )
+    print("convert('%s') -> '%s'" % (test, convert(test)))
+
+
+if __name__ == "__main__":
+    selftest()