zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/types.py

@@ -0,0 +1,17 @@
+#  Copyright 2024 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ["OpenTest"]
+
+from typing import Callable, Optional, TypeVar
+
+from zepben.ewb.model.cim.iec61970.base.core.conducting_equipment import ConductingEquipment
+from zepben.ewb.model.cim.iec61970.base.wires.single_phase_kind import SinglePhaseKind
+
+T = TypeVar("T")
+
+OpenTest = Callable[[ConductingEquipment, Optional[SinglePhaseKind]], bool]

zepben/ewb/util.py

@@ -0,0 +1,200 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = [
+    "get_by_mrid",
+    "contains_mrid",
+    "safe_remove",
+    "safe_remove_by_id",
+    "nlen",
+    "ngen",
+    "is_none_or_empty",
+    "require",
+    "pb_or_none",
+    "CopyableUUID",
+    "datetime_to_timestamp",
+    "none",
+    "classproperty",
+    "unique",
+]
+
+import os
+import re
+from collections.abc import Sized
+from datetime import datetime
+from enum import unique as enum_unique
+from typing import List, Optional, Iterable, Callable, Any, TypeVar, Generator, Dict, Collection
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from google.protobuf.timestamp_pb2 import Timestamp as PBTimestamp
+
+if TYPE_CHECKING:
+    from zepben.ewb import IdentifiedObject, TIdentifiedObject
+
+T = TypeVar('T')
+
+
+def snake2camelback(name: str):
+    return ''.join(word.title() for word in name.split('_'))
+
+
+_camel_pattern = re.compile(r'(?<!^)(?=[A-Z])')
+
+
+def camel2snake(name: str):
+    return _camel_pattern.sub('_', name).lower()
+
+
+def iter_but_not_str(obj: Any):
+    return isinstance(obj, Iterable) and not isinstance(obj, (str, bytes, bytearray, dict))
+
+
+def get_by_mrid(collection: Optional[Iterable[TIdentifiedObject]], mrid: str) -> TIdentifiedObject:
+    """
+    Get an `IdentifiedObject` from `collection` based on
+    its mRID.
+    `collection` The collection to operate on
+    `mrid` The mRID of the `IdentifiedObject` to lookup in the collection
+    Returns The `IdentifiedObject`
+    Raises `KeyError` if `mrid` was not found in the collection.
+    """
+    if not collection:
+        raise KeyError(mrid)
+    for io in collection:
+        if io.mrid == mrid:
+            return io
+    raise KeyError(mrid)
+
+
+def contains_mrid(collection: Optional[Iterable[IdentifiedObject]], mrid: str) -> bool:
+    """
+    Check if a collection of `IdentifiedObject` contains an
+    object with a specified mRID.
+    `collection` The collection to operate on
+    `mrid` The mRID to look up.
+    Returns True if an `IdentifiedObject` is found in the collection with the specified mRID, False otherwise.
+    """
+    if not collection:
+        return False
+    try:
+        if get_by_mrid(collection, mrid):
+            return True
+    except KeyError:
+        return False
+
+
+def safe_remove(collection: Optional[List[T]], obj: T) -> Optional[List[T]]:
+    """
+    Remove an IdentifiedObject from a collection safely.
+    Raises `ValueError` if `obj` is not in the collection.
+    Returns The collection if successfully removed or None if after removal the collection was empty.
+    """
+    if not collection:
+        raise ValueError(obj)
+
+    collection.remove(obj)
+
+    return collection if collection else None
+
+
+def safe_remove_by_id(collection: Optional[Dict[str, IdentifiedObject]], obj: IdentifiedObject) -> {Optional[Dict[str, IdentifiedObject]]}:
+    """
+    Remove an IdentifiedObject from a collection safely.
+    Raises `KeyError` if `obj` is not in the collection.
+    Returns The collection if successfully removed or None if after removal the collection was empty.
+    """
+    if not collection:
+        raise KeyError(obj)
+
+    del collection[obj.mrid]
+
+    return collection if collection else None
+
+
+def nlen(sized: Optional[Sized]) -> int:
+    """
+    Get the len of a nullable sized type.
+    `sized` The object to get length of
+    Returns 0 if `sized` is None, otherwise len(`sized`)
+    """
+    return 0 if sized is None else len(sized)
+
+
+def ngen(collection: Optional[Iterable[T]]) -> Generator[T, None, None]:
+    yield from collection or {}
+
+
+def is_none_or_empty(sized: Optional[Sized]) -> bool:
+    """
+    Check if a given object is empty and return None if it is.
+    `sized` Any type implementing `__len__`
+    Returns `sized` if len(sized) > 0, or None if sized is None or len(sized) == 0.
+    """
+    return sized is None or not len(sized)
+
+
+def require(condition: bool, lazy_message: Callable[[], Any]):
+    """
+    Raise a `ValueError` if condition is not met, with the result of calling `lazy_message` as the message,
+    if the result is false.
+    """
+    if not condition:
+        raise ValueError(str(lazy_message()))
+
+
+def pb_or_none(cim: Optional[Any]):
+    """Convert to a protobuf type or return None if cim was None"""
+    return cim.to_pb() if cim is not None else None
+
+
+def none(collection: Collection):
+    """
+    True if no elements in the collection resolve to True
+    :param collection: The collection to check
+    :raises: ValueError if provided collection is not of type Collection
+    """
+    if isinstance(collection, Collection):
+        if len(collection) == 0:
+            return True
+
+        for item in collection:
+            if item:
+                return False
+        return True
+
+    raise ValueError("none() only supports collection types")
+
+
+class CopyableUUID(UUID):
+
+    def __init__(self):
+        super().__init__(bytes=os.urandom(16), version=4)
+
+    @staticmethod
+    def copy():
+        return str(UUID(bytes=os.urandom(16), version=4))
+
+
+class classproperty(property):
+    def __get__(self, cls, owner: T) -> T:
+        return classmethod(self.fget).__get__(None, owner)()
+
+
+def datetime_to_timestamp(date_time: datetime) -> PBTimestamp:
+    timestamp = PBTimestamp()
+    timestamp.FromDatetime(date_time)
+    return timestamp
+
+
+def unique(enumeration: T) -> T:
+    """
+    A wrapper for the enum.unique() wrapper to preserve typing so that undefined members are correctly
+    flagged by the linter.
+    """
+    enum_unique(enumeration)
+    return enumeration

zepben_ewb-1.0.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: zepben.ewb
+Version: 1.0.0
+Summary: Python SDK for interacting with the Energy Workbench platform
+Author-email: Kurt Greaves <kurt.greaves@zepben.com>, Max Chesterfield <max.chesterfield@zepben.com>
+License-Expression: MPL-2.0
+Project-URL: Repository, https://github.com/zepben/evolve-sdk-python
+Project-URL: Homepage, https://zepben.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: zepben.protobuf==1.0.0
+Requires-Dist: typing_extensions==4.12.2
+Requires-Dist: requests<3.0.0,>=2.26.0
+Requires-Dist: urllib3<1.27.0,>=1.26.6
+Requires-Dist: PyJWT<2.2.0,>=2.1.0
+Requires-Dist: dataclassy==0.6.2
+Provides-Extra: test
+Requires-Dist: pytest<9,>=7.4.4; extra == "test"
+Requires-Dist: pytest-cov==6.1.1; extra == "test"
+Requires-Dist: pytest-asyncio==0.26.0; extra == "test"
+Requires-Dist: pytest-timeout==2.4.0; extra == "test"
+Requires-Dist: pytest-subtests; extra == "test"
+Requires-Dist: hypothesis==6.119.4; extra == "test"
+Requires-Dist: grpcio-testing==1.61.3; extra == "test"
+Requires-Dist: pylint==2.14.5; extra == "test"
+Requires-Dist: six==1.16.0; extra == "test"
+Requires-Dist: tox; extra == "test"
+Dynamic: license-file
+
+![Build Status](https://img.shields.io/github/actions/workflow/status/zepben/evolve-sdk-python/python-lib-snapshot.yml)
+[![codecov](https://codecov.io/gh/zepben/evolve-sdk-python/branch/main/graph/badge.svg?token=B0WNRMMR77)](https://codecov.io/gh/zepben/evolve-sdk-python)
+
+# Zepben Evolve Python SDK #
+The Python Evolve SDK contains everything necessary to communicate with a [Zepben EWB Server](https://github.com/zepben/energy-workbench-server). See the complete [Evolve Python SDK Documentation](https://zepben.github.io/evolve/docs/python-sdk/) for more details.
+
+# Requirements #
+
+- Python 3.9 or later
+
+# Installation #
+
+```
+pip install zepben.ewb
+```
+
+# Building #
+
+```
+python setup.py bdist_wheel
+```
+    
+# Usage #
+
+See [Evolve Python SDK Documentation](https://zepben.github.io/evolve/docs/python-sdk/).
+
+# Zepben Auth Library #
+
+This library provides Authentication mechanisms for Zepben SDKs used with Energy Workbench and other Zepben services.
+
+Typically, this library will be used by the SDKs to plug into connection mechanisms. It is unlikely that end users will
+need to use this library directly.
+
+# Example Usage #
+
+```python
+from zepben.ewb.client import get_token_fetcher
+
+authenticator = get_token_fetcher(
+    issuer="https://login.microsoftonline.com/293784982371c-8797-4168-a5e7-923874928734/v2.0/",
+    audience="49875987458e-e217-4c8f-abf6-394875984758",
+    client_id="asdaf98798-0584-41c3-b30c-1f9874596da",
+    username="",
+    password=""
+)
+
+authenticator.token_request_data.update({
+    'grant_type': 'client_credentials',
+    'client_secret': 'W.Tt5KSzX6Q28lksdajflkajsdflkjaslkdjfxx',
+    'client_id': 'asdaf98798-0584-41c3-b30c-1f9874596da',
+    'scope': '9873498234-e217-4c8f-abf6-9789889987/.default'})
+#
+
+print(authenticator.fetch_token())
+```