egauge-python 0.9.8__py3-none-any.whl

egauge/webapi/cloud/__init__.py

@@ -0,0 +1,30 @@
+#
+# Copyright (c) 2020, 2024 eGauge Systems LLC
+#       1644 Conestoga St, Suite 2
+#       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.
+#
+from .serial_number import *  # NOQA

egauge/webapi/cloud/credentials.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+#
+#   Copyright (c) 2021-2022, 2024 eGauge Systems LLC
+#     1644 Conestoga St, Suite 2
+#     Boulder, CO 80301
+#     voice: 720-545-9767
+#     email: dave@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.
+#
+"""This module provides a credentials manager which can ask for
+credentials (username, password, second factor) either via a PySide
+dialog or by prompting the user via stdout and stdin (i.e., the
+terminal).
+
+"""
+
+import getpass
+
+CredentialsDialog = None
+
+try:
+    from .credentials_dialog import CredentialsDialog
+
+    have_pyside = True
+except (ImportError, ModuleNotFoundError):
+    have_pyside = False
+
+
+class LoginCanceled(Exception):
+    """Raised when the user cancels a login request."""
+
+
+class CredentialsManager:
+    def __init__(self, gui_parent=None):
+        """Create a credentials manager.  The task of this manager is mainly
+        to track if a previous login failed.  The user of this object
+        should set the previous_login_failed member to False after the
+        credentials have been used successfully.
+
+        If GUI_PARENT is not None, it must be the QT5 (PySide6) parent
+        window to use for the dialog.  If it is None, the credentials
+        will be requested via standard I/O (getpass).
+
+        """
+        self.parent = gui_parent if have_pyside else None
+        self.previous_login_failed = False
+
+    def ask(self):
+        """Ask for the username, password, and optional token for an eGauge
+        cloud API account (eGuard account).  Returns a tuple
+        containing a username and password or raises LoginCanceled if
+        the user presses the "Cancel" button.
+
+        """
+        if self.parent and CredentialsDialog is not None:
+            dialog = CredentialsDialog(self.parent, self.previous_login_failed)
+            dialog.exec()
+            if not dialog.accepted:
+                raise LoginCanceled()
+            self.previous_login_failed = True
+            pwd = "" if dialog.password is None else dialog.password
+            if dialog.token is not None:
+                pwd += dialog.token
+            return (dialog.username, pwd)
+
+        fail_msg = ""
+        if self.previous_login_failed:
+            fail_msg = "Login failed.  "
+        print(fail_msg + "Please enter eGuard credentials.")
+        try:
+            usr = input("Username: ")
+            pwd = getpass.getpass(prompt="Password[+token]: ")
+        except (KeyboardInterrupt, EOFError) as e:
+            raise LoginCanceled from e
+        self.previous_login_failed = True
+        return [usr, pwd]
+
+
+# Alias for backwards-compatibility.  Please use CredentialsManager in
+# new code.
+Credentials_Manager = CredentialsManager

egauge/webapi/cloud/credentials_dialog.py

@@ -0,0 +1,58 @@
+#
+#   Copyright (c) 2021-2022, 2024 eGauge Systems LLC
+#     1644 Conestoga St, Suite 2
+#     Boulder, CO 80301
+#     voice: 720-545-9767
+#     email: dave@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.
+#
+from PySide6.QtWidgets import QDialog
+
+from .gui.credentials_dialog import Ui_Credentials_Dialog
+
+# pyright: reportIncompatibleVariableOverride = false
+#
+# Unfortunately, we need the above because PySide automatically
+# defines a Signal called `accepted` but the users of this dialog
+# expected that property to be a bool indicating whether or not the
+# user clicked the "OK" button.
+#
+
+
+class CredentialsDialog(QDialog, Ui_Credentials_Dialog):
+    @property
+    def accepted(self) -> bool:
+        return self.user_accepted
+
+    def __init__(self, parent, failed):
+        self.username = None
+        self.user_accepted = False
+        self.password = None
+        self.token = ""
+        super().__init__(parent)
+        self.setupUi(self)
+        if failed:
+            prompt = "Login failed. " + self.prompt_label.text()
+            self.prompt_label.setText(prompt)
+        self.username_lineEdit.setFocus()
+
+    def exec(self) -> int:
+        self.user_accepted = False
+        return super().exec()
+
+    def accept(self):
+        super().accept()
+        self.user_accepted = True
+        self.username = self.username_lineEdit.text()
+        self.password = self.password_lineEdit.text()
+        self.token = self.token_lineEdit.text()
+
+
+# Alias for backwards-compatibility.  Please use CredentialsDialog in
+# new code.
+Credentials_Dialog = CredentialsDialog

egauge/webapi/cloud/gui/credentials_dialog.py

@@ -0,0 +1,100 @@
+# -*- coding: utf-8 -*-
+
+################################################################################
+## Form generated from reading UI file 'credentials_dialog.ui'
+##
+## Created by: Qt User Interface Compiler version 6.7.2
+##
+## WARNING! All changes made in this file will be lost when recompiling UI file!
+################################################################################
+
+from PySide6.QtCore import (QCoreApplication, QDate, QDateTime, QLocale,
+    QMetaObject, QObject, QPoint, QRect,
+    QSize, QTime, QUrl, Qt)
+from PySide6.QtGui import (QBrush, QColor, QConicalGradient, QCursor,
+    QFont, QFontDatabase, QGradient, QIcon,
+    QImage, QKeySequence, QLinearGradient, QPainter,
+    QPalette, QPixmap, QRadialGradient, QTransform)
+from PySide6.QtWidgets import (QAbstractButton, QApplication, QDialog, QDialogButtonBox,
+    QGridLayout, QLabel, QLineEdit, QSizePolicy,
+    QVBoxLayout, QWidget)
+
+class Ui_Credentials_Dialog(object):
+    def setupUi(self, Credentials_Dialog):
+        if not Credentials_Dialog.objectName():
+            Credentials_Dialog.setObjectName(u"Credentials_Dialog")
+        Credentials_Dialog.resize(327, 194)
+        self.verticalLayout = QVBoxLayout(Credentials_Dialog)
+        self.verticalLayout.setObjectName(u"verticalLayout")
+        self.prompt_label = QLabel(Credentials_Dialog)
+        self.prompt_label.setObjectName(u"prompt_label")
+        self.prompt_label.setWordWrap(True)
+
+        self.verticalLayout.addWidget(self.prompt_label)
+
+        self.gridLayout = QGridLayout()
+        self.gridLayout.setObjectName(u"gridLayout")
+        self.label_3 = QLabel(Credentials_Dialog)
+        self.label_3.setObjectName(u"label_3")
+
+        self.gridLayout.addWidget(self.label_3, 0, 0, 1, 1)
+
+        self.username_lineEdit = QLineEdit(Credentials_Dialog)
+        self.username_lineEdit.setObjectName(u"username_lineEdit")
+
+        self.gridLayout.addWidget(self.username_lineEdit, 0, 1, 1, 1)
+
+        self.label = QLabel(Credentials_Dialog)
+        self.label.setObjectName(u"label")
+
+        self.gridLayout.addWidget(self.label, 1, 0, 1, 1)
+
+        self.password_lineEdit = QLineEdit(Credentials_Dialog)
+        self.password_lineEdit.setObjectName(u"password_lineEdit")
+        self.password_lineEdit.setInputMask(u"")
+        self.password_lineEdit.setText(u"")
+        self.password_lineEdit.setEchoMode(QLineEdit.Password)
+
+        self.gridLayout.addWidget(self.password_lineEdit, 1, 1, 1, 1)
+
+        self.label_2 = QLabel(Credentials_Dialog)
+        self.label_2.setObjectName(u"label_2")
+
+        self.gridLayout.addWidget(self.label_2, 2, 0, 1, 1)
+
+        self.token_lineEdit = QLineEdit(Credentials_Dialog)
+        self.token_lineEdit.setObjectName(u"token_lineEdit")
+        self.token_lineEdit.setInputMask(u"")
+        self.token_lineEdit.setText(u"")
+        self.token_lineEdit.setEchoMode(QLineEdit.Password)
+
+        self.gridLayout.addWidget(self.token_lineEdit, 2, 1, 1, 1)
+
+
+        self.verticalLayout.addLayout(self.gridLayout)
+
+        self.buttonBox = QDialogButtonBox(Credentials_Dialog)
+        self.buttonBox.setObjectName(u"buttonBox")
+        self.buttonBox.setOrientation(Qt.Horizontal)
+        self.buttonBox.setStandardButtons(QDialogButtonBox.Cancel|QDialogButtonBox.Ok)
+
+        self.verticalLayout.addWidget(self.buttonBox)
+
+        QWidget.setTabOrder(self.username_lineEdit, self.password_lineEdit)
+        QWidget.setTabOrder(self.password_lineEdit, self.token_lineEdit)
+
+        self.retranslateUi(Credentials_Dialog)
+        self.buttonBox.accepted.connect(Credentials_Dialog.accept)
+        self.buttonBox.rejected.connect(Credentials_Dialog.reject)
+
+        QMetaObject.connectSlotsByName(Credentials_Dialog)
+    # setupUi
+
+    def retranslateUi(self, Credentials_Dialog):
+        Credentials_Dialog.setWindowTitle(QCoreApplication.translate("Credentials_Dialog", u"eGuard Login", None))
+        self.prompt_label.setText(QCoreApplication.translate("Credentials_Dialog", u"Please enter your eGuard credentials.  If required, include the current 2FA token.", None))
+        self.label_3.setText(QCoreApplication.translate("Credentials_Dialog", u"Username", None))
+        self.label.setText(QCoreApplication.translate("Credentials_Dialog", u"Password", None))
+        self.label_2.setText(QCoreApplication.translate("Credentials_Dialog", u"2FA token", None))
+    # retranslateUi
+

egauge/webapi/cloud/serial_number.py

@@ -0,0 +1,276 @@
+#
+# Copyright (c) 2020, 2024-2025 eGauge Systems LLC
+#       1644 Conestoga St, Suite 2
+#       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.
+#
+"""This module provides access to the eGauge Serial Number web
+service.
+
+"""
+
+import urllib.parse
+
+import requests
+
+from egauge.loggers import ModuleLogger
+
+from .. import json_api
+from ..auth import TokenAuth
+from ..error import Error
+from ..json_api import JSONObject, JSONValue
+
+log = ModuleLogger.get(__name__)
+
+
+class SerialNumberError(Error):
+    """Raised for Serial Number API errors."""
+
+
+class SerialNumber:
+    def __init__(self, auth: TokenAuth | None = None):
+        """Create an object providing access to the serial-number
+        service.
+
+        Keyword arguments:
+
+        auth -- An authentication object which can provide the
+            credentials required to access the serial-number service.
+
+        """
+        self.api_uri = "https://api.egauge.net/v1/serial-numbers/"
+        self.auth = auth
+
+    def _get(self, resource: str, **kwargs) -> JSONValue | requests.Response:
+        """Issue an HTTP GET request for a serial-number resource
+        and return the reply.
+
+        Required arguments:
+
+        resource -- The URI of the resource to get.
+
+        Keyword arguments are passed on to requests.get().
+
+        """
+        reply = json_api.get(self.api_uri + resource, auth=self.auth, **kwargs)
+        log.debug("get[%s] = %s", resource, reply)
+        return reply
+
+    def _post(
+        self, resource: str, json_data, **kwargs
+    ) -> JSONValue | requests.Response:
+        """Issue an HTTP POST request to serial-number resource and
+        return the reply.
+
+        Required arguments:
+
+        resource -- The URI of the resource to post to.
+
+        Keyword arguments are passed on to requests.get().
+
+        """
+        reply = json_api.post(
+            self.api_uri + resource, json_data, auth=self.auth, **kwargs
+        )
+        log.debug("post[%s] = %s", resource, reply)
+        return reply
+
+    def allocate(self, model_name: str, serial: int | None = None) -> int:
+        """Allocate the next available serial-number for a model and
+        return it.
+
+        Required arguments:
+
+        model_name -- The model name for which to allocate a serial
+            number.  Typically, this should be prefixed by the
+            manufacturer's name to ensure uniqueness.  For example,
+            for eGauge model ETN100, the model name would be
+            "eGauge-ETN100".  Once allocated, a serial-number cannot
+            be freed again, so care should be taken to use all
+            allocated numbers.
+
+        Keyword arguments:
+
+        serial -- If specified, allocate that specific serial-number,
+            if it is avaiable, or fail otherwise.  Depending on model
+            name, the serial-number API service may reject attempts to
+            allocate specific serial numbers.
+
+        On error, exception SerialNumberError is raised.
+
+        """
+        data: JSONObject = {"name": model_name}
+        if serial is not None:
+            data["serial"] = serial
+        reply = self._post("models/allocate/", json_data=data)
+        if not isinstance(reply, dict):
+            raise SerialNumberError(
+                f"Unexpected response allocating SN for {model_name}.", reply
+            )
+        if "serial" not in reply:
+            log.error(
+                "Failed to allocate SN: model=%s, reply=%s.", model_name, reply
+            )
+            if "errors" in reply:
+                raise SerialNumberError(
+                    "Error during SN allocation.", model_name, reply["errors"]
+                )
+            raise SerialNumberError("SN allocation failed.", model_name)
+        sn = reply["serial"]
+        if not isinstance(sn, int):
+            raise SerialNumberError(f'SN "{sn}" is not an integer.')
+        return sn
+
+    def get_models(self) -> list[dict]:
+        """Get a list of all model names registered in the database.
+        Each object in the list has members `id` (internal database id
+        of the model), `name` (the model name), and `max_sn` (the
+        maximum serial-number).
+
+        On error, exception SerialNumberError is raised.
+
+        """
+
+        # For better or worse, this end point returns a list on
+        # success but a dictionary in failure:
+
+        reply = self._get("models/")
+
+        if isinstance(reply, dict):
+            err = reply.get("detail")
+            if err:
+                raise SerialNumberError(f"Error fetching SN models: {err}")
+
+        if not isinstance(reply, list):
+            raise SerialNumberError(
+                "Unexpected response from SN models.", reply
+            )
+        return reply
+
+    def create_model(self, model_name: str, max_sn: int) -> bool:
+        """Create a new model.
+
+        Returns True if the model was created successfully, False
+        otherwise.
+
+        Required arguments:
+
+        model_name -- The name of the model to create.
+
+        max_sn -- The maximum serial number that may be allocated.
+
+        """
+        data = {"name": model_name, "max_sn": max_sn}
+        reply = self._post("models/", data)
+        if not isinstance(reply, dict) or "name" not in reply:
+            return False
+        return reply["name"] == model_name
+
+    def get_devices(
+        self, model_name: str | None = None, dev_filter: str | None = None
+    ) -> list[dict]:
+        """Get a list of devices.
+
+        Keyword arguments:
+
+        model_name -- If specified, only devices with that model name
+            are returned.
+
+        dev_filter -- If specified, only devices matching the filter
+            are returned.
+
+        """
+        resource = "devices/"
+        if model_name is not None:
+            quoted_model = urllib.parse.quote(model_name, safe="")
+            resource += quoted_model + "/"
+
+        if dev_filter is not None:
+            resource += "?" + dev_filter
+
+        reply = self._get(resource)
+        if not isinstance(reply, list):
+            raise SerialNumberError(
+                "Failed to get metadata.", model_name, dev_filter
+            )
+        return reply
+
+    def get_metadata(self, model_name: str, sn: int) -> dict:
+        """Get the JSON-blob metadata for a device.
+
+        On error, exception SerialNumberError is raised.
+
+        Required arguments:
+
+        model_name -- The model name of the device.
+
+        sn -- The serial number of the device.
+
+        """
+        quoted_model = urllib.parse.quote(model_name, safe="")
+        resource = f"devices/{quoted_model}/{sn}/"
+        reply = self._get(resource)
+        if not isinstance(reply, dict):
+            raise SerialNumberError(
+                "Failed to get serial number record.", model_name, sn
+            )
+
+        metadata = reply.get("metadata")
+        if not isinstance(metadata, dict):
+            log.warning("no metadata exists for SN %s.", sn)
+            return {}
+
+        return metadata
+
+    def set_metadata(self, model_name: str, sn: int, meta: dict):
+        """Set the metadata for a device.
+
+        Using methods get_metadata() and set_metadata() to update
+        portions of the metadata is not atomic.  Higher-level
+        synchronization (such as a ResourceLock) can be used to ensure
+        atomicity of such updates.
+
+        Required arguments:
+
+        model_name -- The model name of the device.
+
+        sn -- The serial number of the device.
+
+        meta -- The meta data to associated with the device.  This
+            must be serializable with json.dumps().
+
+        On error, exception SerialNumberError is raised.
+
+        """
+        quoted_model = urllib.parse.quote(model_name, safe="")
+        resource = "devices/%s/%s/" % (quoted_model, sn)
+        reply = self._post(resource, json_data={"metadata": meta})
+        if not isinstance(reply, dict):
+            raise SerialNumberError("Failed to set metadata.", model_name, sn)
+        if "errors" in reply:
+            raise SerialNumberError(
+                "Failed to save metadata.", model_name, sn, reply["errors"]
+            )

egauge/webapi/device/__init__.py

@@ -0,0 +1,38 @@
+#
+# Copyright (c) 2020 eGauge Systems LLC
+#       1644 Conestoga St, Suite 2
+#       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.
+#
+from .capture import *  # NOQA
+from .ctid_info import *  # NOQA
+from .device import *  # NOQA
+from .local import *  # NOQA
+from .physical_quantity import *  # NOQA
+from .physical_units import *  # NOQA
+from .register import *  # NOQA
+from .register_row import *  # NOQA
+from .virtual_register import *  # NOQA