zepben.ewb 1.0.0b1__py3-none-any.whl

zepben/ewb/database/sqlite/tables/iec61970/base/wires/table_transformer_ends.py

@@ -0,0 +1,30 @@
+#  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/.
+
+__all__ = ["TableTransformerEnds"]
+
+from abc import ABC
+from typing import List, Generator
+
+from zepben.ewb.database.sqlite.tables.column import Column, Nullable
+from zepben.ewb.database.sqlite.tables.iec61970.base.core.table_identified_objects import TableIdentifiedObjects
+
+
+class TableTransformerEnds(TableIdentifiedObjects, ABC):
+
+    def __init__(self):
+        super().__init__()
+        self.end_number: Column = self._create_column("end_number", "INTEGER", Nullable.NOT_NULL)
+        self.terminal_mrid: Column = self._create_column("terminal_mrid", "TEXT", Nullable.NULL)
+        self.base_voltage_mrid: Column = self._create_column("base_voltage_mrid", "TEXT", Nullable.NULL)
+        self.grounded: Column = self._create_column("grounded", "BOOLEAN", Nullable.NOT_NULL)
+        self.r_ground: Column = self._create_column("r_ground", "NUMBER", Nullable.NULL)
+        self.x_ground: Column = self._create_column("x_ground", "NUMBER", Nullable.NULL)
+        self.star_impedance_mrid: Column = self._create_column("star_impedance_mrid", "TEXT", Nullable.NULL)
+
+    @property
+    def non_unique_index_columns(self) -> Generator[List[Column], None, None]:
+        yield from super().non_unique_index_columns
+        yield [self.star_impedance_mrid]

zepben/ewb/database/sqlite/tables/iec61970/base/wires/table_transformer_star_impedances.py

@@ -0,0 +1,32 @@
+#  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/.
+
+__all__ = ["TableTransformerStarImpedances"]
+
+from typing import List, Generator
+
+from zepben.ewb.database.sqlite.tables.column import Column, Nullable
+from zepben.ewb.database.sqlite.tables.iec61970.base.core.table_identified_objects import TableIdentifiedObjects
+
+
+class TableTransformerStarImpedances(TableIdentifiedObjects):
+
+    def __init__(self):
+        super().__init__()
+        # Note r, r0, x, x0 use nullable number types.
+        self.r: Column = self._create_column("R", "NUMBER", Nullable.NULL)
+        self.r0: Column = self._create_column("R0", "NUMBER", Nullable.NULL)
+        self.x: Column = self._create_column("X", "NUMBER", Nullable.NULL)
+        self.x0: Column = self._create_column("X0", "NUMBER", Nullable.NULL)
+        self.transformer_end_info_mrid: Column = self._create_column("transformer_end_info_mrid", "TEXT", Nullable.NULL)
+
+    @property
+    def name(self) -> str:
+        return "transformer_star_impedances"
+
+    @property
+    def unique_index_columns(self) -> Generator[List[Column], None, None]:
+        yield from super().unique_index_columns
+        yield [self.transformer_end_info_mrid]

zepben/ewb/database/sqlite/tables/iec61970/infiec61970/__init__.py

@@ -0,0 +1,4 @@
+#  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/.

zepben/ewb/database/sqlite/tables/iec61970/infiec61970/feeder/__init__.py

@@ -0,0 +1,4 @@
+#  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/.

zepben/ewb/database/sqlite/tables/iec61970/infiec61970/feeder/table_circuits.py

@@ -0,0 +1,27 @@
+#  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/.
+
+__all__ = ["TableCircuits"]
+
+from typing import List, Generator
+
+from zepben.ewb.database.sqlite.tables.column import Column, Nullable
+from zepben.ewb.database.sqlite.tables.iec61970.base.wires.table_lines import TableLines
+
+
+class TableCircuits(TableLines):
+
+    def __init__(self):
+        super().__init__()
+        self.loop_mrid: Column = self._create_column("loop_mrid", "TEXT", Nullable.NULL)
+
+    @property
+    def name(self) -> str:
+        return "circuits"
+
+    @property
+    def non_unique_index_columns(self) -> Generator[List[Column], None, None]:
+        yield from super().non_unique_index_columns
+        yield [self.loop_mrid]

zepben/ewb/database/sqlite/tables/sqlite_table.py

@@ -0,0 +1,142 @@
+#  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__ = ["SqliteTable"]
+
+from abc import abstractmethod
+from typing import List, Optional, Type, Any, Generator
+
+from zepben.ewb.database.sqlite.tables.column import Column, Nullable
+
+
+# @dataclass(slots=True)
+class SqliteTable(object):
+    """
+    Represents a table in an Sqlite Database. This class should be extended and initialised to build the DDL for a Table.
+    Methods that need to be overridden are those marked @abstractmethod.
+    Methods that can be optionally overridden are unique_index_columns() and non_unique_index_columns().
+    Columns must be assigned in __init__ and column_index must be incremented for each Column created.
+    See existing implementations such as TableVersion for examples.
+    """
+
+    column_index: int = 0
+    """Used to specify index of the column in the table during initialisation. Always increment BEFORE creating a Column. Indices start from 1."""
+
+    _column_set: Optional[List[Column]] = None
+    _create_table_sql: Optional[str] = None
+    _prepared_insert_sql: Optional[str] = None
+    _prepared_update_sql: Optional[str] = None
+    _create_indexes_sql: Optional[List[str]] = None
+    _select_sql: Optional[str] = None
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+    #
+    # NOTE: This function is called `description` in teh JVM SDK, but in the python SDK this
+    #       conflicts with the `description` column of `TableIdentifiedObjects`.
+    #
+    def describe(self) -> str:
+        return self.name.replace("_", " ")
+
+    @property
+    def create_table_sql(self):
+        return self._create_table_sql if self._create_table_sql else self._build_create_table_sql()
+
+    @property
+    def prepared_insert_sql(self):
+        return self._prepared_insert_sql if self._prepared_insert_sql else self._build_prepared_insert_sql()
+
+    @property
+    def create_indexes_sql(self):
+        return self._create_indexes_sql if self._create_indexes_sql else self._build_indexes_sql()
+
+    @property
+    def select_sql(self):
+        return self._select_sql if self._select_sql else self._build_select_sql()
+
+    @property
+    def prepared_update_sql(self):
+        return self._prepared_update_sql if self._prepared_update_sql else self._build_prepared_update_sql()
+
+    @property
+    def unique_index_columns(self) -> Generator[List[Column], None, None]:
+        # To make this a generator we need to `yield`, but we have nothing to yield by default, so trick it by yielding from an empty for-loop.
+        for it in []:
+            yield it
+
+    @property
+    def non_unique_index_columns(self) -> Generator[List[Column], None, None]:
+        # To make this a generator we need to `yield`, but we have nothing to yield by default, so trick it by yielding from an empty for-loop.
+        for it in []:
+            yield it
+
+    @property
+    def column_set(self) -> List[Column]:
+        return self._column_set if self._column_set else self._build_column_set(self.__class__, self)
+
+    def _build_column_set(self, clazz: Type[Any], instance: SqliteTable) -> List[Column]:
+        """
+        Builds the list of columns for use in DDL statements for this table.
+
+        :param clazz: The class of this table.
+        :param instance:
+        :return:
+        """
+        cols = list()
+        for field, x in instance.__dict__.items():
+            if isinstance(x, Column):
+                if x.query_index != len(cols) + 1:
+                    raise ValueError(
+                        f"Field {field} in SQL Table class {clazz.__name__} is using an invalid column index. "
+                        f"Did you forget to increment column_index, or did you skip one?"
+                    )
+                cols.append(x)
+
+        if len(set([c.name for c in cols])) != len(cols):
+            raise ValueError("You have a duplicate column names, go fix that.")
+
+        self._column_set = sorted(cols, key=lambda it: it.query_index)
+        return self._column_set
+
+    def _build_create_table_sql(self) -> str:
+        self._create_table_sql = f"CREATE TABLE {self.name} ({', '.join([str(c) for c in self.column_set])})"
+        return self._create_table_sql
+
+    def _build_prepared_insert_sql(self) -> str:
+        self._prepared_insert_sql = f"INSERT INTO {self.name} ({', '.join([c.name for c in self.column_set])}) " \
+                                    f"VALUES ({', '.join(['?' for _ in self.column_set])})"
+        return self._prepared_insert_sql
+
+    def _build_indexes_sql(self) -> List[str]:
+        statements = []
+        for index_col in self.unique_index_columns:
+            statements.append(self._build_index_sql(index_col, True))
+        for index_col in self.non_unique_index_columns:
+            statements.append(self._build_index_sql(index_col, False))
+        self._create_indexes_sql = statements
+        return self._create_indexes_sql
+
+    def _build_index_sql(self, index_col: List[Column], is_unique: bool):
+        id_string = f"{self.name}_{'_'.join(map(lambda c: c.name, index_col))}"
+        col_string = ', '.join(map(lambda c: c.name, index_col))
+        return f"CREATE {'UNIQUE ' if is_unique else ''}INDEX {id_string} ON {self.name} ({col_string})"
+
+    def _build_select_sql(self) -> str:
+        self._select_sql = f"SELECT {', '.join([c.name for c in self.column_set])} FROM {self.name}"
+        return self._select_sql
+
+    def _build_prepared_update_sql(self) -> str:
+        self._prepared_update_sql = f"UPDATE {self.name} SET {', '.join([f'{c.name} = ?' for c in self.column_set])}"
+        return self._prepared_update_sql
+
+    def _create_column(self, name: str, type_: str, nullable: Nullable = Nullable.NONE) -> Column:
+        self.column_index += 1
+        # noinspection PyArgumentList
+        return Column(self.column_index, name, type_, nullable)

zepben/ewb/database/sqlite/tables/table_metadata_data_sources.py

@@ -0,0 +1,21 @@
+#  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/.
+
+__all__ = ["TableMetadataDataSources"]
+
+from zepben.ewb.database.sqlite.tables.column import Column, Nullable
+from zepben.ewb.database.sqlite.tables.sqlite_table import SqliteTable
+
+
+class TableMetadataDataSources(SqliteTable):
+
+    def __init__(self):
+        self.source: Column = self._create_column("source", "TEXT", Nullable.NOT_NULL)
+        self.version: Column = self._create_column("version", "TEXT", Nullable.NOT_NULL)
+        self.timestamp: Column = self._create_column("timestamp", "TEXT", Nullable.NOT_NULL)
+
+    @property
+    def name(self) -> str:
+        return "metadata_data_sources"

zepben/ewb/database/sqlite/tables/table_version.py

@@ -0,0 +1,38 @@
+#  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/.
+
+__all__ = ["TableVersion"]
+
+import sqlite3
+from sqlite3 import Cursor
+from typing import Optional
+
+from zepben.ewb.database.sqlite.tables.column import Column, Nullable
+from zepben.ewb.database.sqlite.tables.sqlite_table import SqliteTable
+
+
+class TableVersion(SqliteTable):
+    SUPPORTED_VERSION = 59
+
+    def __init__(self):
+        self.version: Column = self._create_column("version", "TEXT", Nullable.NOT_NULL)
+
+    @property
+    def name(self) -> str:
+        return "version"
+
+    def get_version(self, cur: Cursor) -> Optional[int]:
+        """
+        Helper function to read the version from the database.
+        """
+        try:
+            cur.execute(self.select_sql)
+            rows = cur.fetchall()
+            if len(rows) == 1:
+                return int(rows[0][0])
+        except sqlite3.Error:
+            pass
+
+        return None

zepben/ewb/dataclassy/__init__.py

@@ -0,0 +1,15 @@
+# LICENCE EXCLUDED
+"""
+ Copyright (C) 2020 biqqles.
+ 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 http://mozilla.org/MPL/2.0/.
+
+ Forked from https://github.com/biqqles/dataclassy/tree/v0.6.2
+"""
+from .decorator import dataclass, make_dataclass
+from .dataclass import DataClass, Internal
+from .functions import fields, values, as_dict, as_tuple, replace
+
+# aliases intended for migration from dataclasses
+asdict, astuple = as_dict, as_tuple

zepben/ewb/dataclassy/dataclass.py

@@ -0,0 +1,192 @@
+# LICENCE EXCLUDED
+"""
+ Copyright (C) 2020 biqqles.
+ 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 http://mozilla.org/MPL/2.0/.
+
+ This file contains the internal mechanism that makes data classes
+ work, as well as functions which operate on them.
+
+ Forked from https://github.com/biqqles/dataclassy/tree/v0.6.2 with this additional bugfix:
+ https://github.com/biqqles/dataclassy/commit/ec9273ca02e5caefc08c923112fa9eeecf517246
+"""
+from types import FunctionType as Function
+from typing import Any, Dict, Generic, Hashable, TypeVar
+from reprlib import recursive_repr
+
+DataClass = Any  # type hint for variables that should be data class instances
+T = TypeVar('T')
+
+
+class Internal(Generic[T]):
+    """This type hint wrapper represents a field that is internal to the data class and is, for example, not to be
+    shown in a repr."""
+    @classmethod
+    def is_internal(cls, annotation):
+        return getattr(annotation, '__origin__', None) is cls or \
+               (type(annotation) is str and cls.__name__ in annotation)
+
+
+class DataClassMeta(type):
+    """The metaclass for a data class."""
+    DEFAULT_OPTIONS = dict(init=True, repr=True, eq=True, iter=False, frozen=False, kwargs=False, slots=False,
+                           order=False, unsafe_hash=True, hide_internals=True)
+
+    def __new__(mcs, name, bases, dict_, **kwargs):
+        # collect annotations, defaults, slots and options from this class' ancestors, in definition order
+        all_annotations = {}
+        all_defaults = {}
+        all_slots = set()
+        options = dict(mcs.DEFAULT_OPTIONS)
+
+        dataclass_bases = [vars(b) for b in bases if hasattr(b, '__dataclass__')]
+        for b in dataclass_bases + [dict_]:
+            all_annotations.update(b.get('__annotations__', {}))
+            all_defaults.update(b.get('__defaults__', dict_))
+            all_slots.update(b.get('__slots__', set()))
+            options.update(b.get('__dataclass__', {}))
+        options.update(kwargs)
+
+        # fill out this class' dict and store defaults, annotations and decorator options for future subclasses
+        dict_.update(all_defaults)
+        dict_['__defaults__'] = all_defaults
+        dict_['__annotations__'] = all_annotations
+        dict_['__dataclass__'] = options
+
+        # delete what will become stale references so that Python creates new ones
+        del dict_['__dict__'], dict_['__weakref__']
+
+        # create/apply generated methods and attributes
+        user_init = type(dict_.get('__init__')) is Function
+
+        if options['slots']:
+            # values with default values must only be present in slots, not dict, otherwise Python will interpret them
+            # as read only
+            for d in all_annotations.keys() & all_defaults.keys():
+                del dict_[d]
+            dict_['__slots__'] = all_annotations.keys() - all_slots
+        elif '__slots__' in dict_:
+            # if the slots option has been removed from an inheriting dataclass we must remove descriptors and __slots__
+            for d in all_annotations.keys() - all_defaults.keys() & dict_.keys():
+                del dict_[d]
+            del dict_['__slots__']
+        if options['init']:
+            dict_.setdefault('__new__', _generate_new(all_annotations, all_defaults, user_init,
+                                                      options['kwargs'], options['frozen']))
+        if options['repr']:
+            dict_.setdefault('__repr__', recursive_repr()(__repr__))
+        if options['eq']:
+            dict_.setdefault('__eq__', __eq__)
+        if options['iter']:
+            dict_.setdefault('__iter__', __iter__)
+        if options['frozen']:
+            dict_['__delattr__'] = dict_['__setattr__'] = __setattr__
+        if options['order']:
+            dict_.setdefault('__lt__', __lt__)
+        if (options['eq'] and options['frozen']) or options['unsafe_hash']:
+            dict_.setdefault('__hash__', __hash__)
+
+        return type.__new__((DataClassInit if options['init'] and user_init else mcs), name, bases, dict_)
+
+    def __init__(cls, *args, **kwargs):
+        # warn the user if they try to use __post_init__
+        if hasattr(cls, '__post_init__'):
+            raise TypeError('dataclassy does not use __post_init__. You should rename this method __init__')
+
+        if cls.__dataclass__['eq'] and cls.__dataclass__['order']:
+            from functools import total_ordering
+            total_ordering(cls)
+
+        # determine a static expression for an instance's fields as a tuple, then evaluate this to create a property
+        # allowing efficient representation for internal methods
+        tuple_expr = f'({", ".join((*(f"self.{f}" for f in fields(cls)), ""))})'  # "" ensures closing comma
+        cls.__tuple__ = property(eval(f'lambda self: {tuple_expr}'))
+
+
+class DataClassInit(DataClassMeta):
+    """In the case that a custom __init__ is defined, remove arguments used by __new__ before calling it."""
+    def __call__(cls, *args, **kwargs):
+        args = iter(args)
+        new_kwargs = dict(zip(cls.__annotations__, args))  # convert positional args to keyword for __new__
+        instance = cls.__new__(cls, **new_kwargs, **kwargs)
+
+        for parameter in kwargs.keys() & cls.__annotations__.keys():
+            del kwargs[parameter]
+
+        instance.__init__(*args, **kwargs)
+        return instance
+
+    @property
+    def __signature__(cls):
+        """Defining a __call__ breaks inspect.signature. Lazily generate a Signature object ourselves."""
+        import inspect
+        parameters = tuple(inspect.signature(cls.__new__).parameters.values())
+        return inspect.Signature(parameters[1:])  # remove 'cls' to transform parameters of __new__ into those of class
+
+
+def _generate_new(annotations: Dict, defaults: Dict, user_init: bool, gen_kwargs: bool, frozen: bool) -> Function:
+    """Generate and return a __new__ method for a data class which has as parameters all fields of the data class.
+    When the data class is initialised, arguments to this function are applied to the fields of the new instance. Using
+    __new__ frees up __init__, allowing it to be defined by the user to perform additional, custom initialisation.
+
+    If __init__ is defined, all arguments to __new__ become keyword-only, and the custom __call__ converts positional
+    arguments to keyword arguments. This prevents ambiguity during attempts to pass the same argument twice,
+    positionally and as a keyword."""
+    arguments = [a for a in annotations if a not in defaults]
+    default_arguments = [f'{a}={a}' for a in annotations if a in defaults]
+    kw_only = ['*'] if user_init and (arguments or default_arguments) else []
+    kwargs = ['**kwargs'] if gen_kwargs or user_init else []  # pass through unknown keyword arguments to __init__
+
+    parameters = ', '.join(kw_only + arguments + default_arguments + kwargs)
+
+    # determine what to do with arguments before assignment. If the argument matches a mutable default, make a copy
+    references = {n: f'{n}.copy() if {n} is self.__defaults__[{n!r}] else {n}'
+                  if n in defaults and hasattr(defaults[n], 'copy') else n for n in annotations}
+
+    # if the class is frozen, use the necessary but slightly slower object.__setattr__
+    assignments = [f'object.__setattr__(self, {n!r}, {r})' if frozen else f'self.{n} = {r}'
+                   for n, r in references.items()]
+
+    # generate the function
+    signature = f'def __new__(cls, {parameters}):'
+    body = [f'self = object.__new__(cls)', *assignments, 'return self']
+
+    exec('\n\t'.join([signature, *body]), {}, defaults)
+    function = defaults.pop('__new__')
+    function.__annotations__ = annotations
+    return function
+
+
+# generic method implementations common to all data classes
+# these are currently relatively inefficient - it would be better to cache an expression for a class' tuple
+from .functions import values, fields
+
+
+def __eq__(self: DataClass, other: DataClass):
+    return type(self) is type(other) and self.__tuple__ == other.__tuple__
+
+
+def __lt__(self: DataClass, other: DataClass):
+    if isinstance(other, type(self)):
+        return self.__tuple__ < other.__tuple__
+    return NotImplemented
+
+
+def __hash__(self):
+    # currently not ideal since gives no warning if a field expected to be hashable is not
+    return hash((type(self), *(v for v in self.__tuple__ if v is isinstance(v, Hashable))))
+
+
+def __iter__(self):
+    return iter(self.__tuple__)
+
+
+def __repr__(self):
+    show_internals = not self.__dataclass__['hide_internals']
+    field_values = ', '.join(f'{f}={v!r}' for f, v in values(self, show_internals).items())
+    return f'{type(self).__name__}({field_values})'
+
+
+def __setattr__(self, *args):
+    raise AttributeError('Frozen class')

zepben/ewb/dataclassy/decorator.py

@@ -0,0 +1,35 @@
+# LICENCE EXCLUDED
+"""
+ Copyright (C) 2020 biqqles.
+ 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 http://mozilla.org/MPL/2.0/.
+
+ This file contains code relating to dataclassy's decorator.
+
+ Forked from https://github.com/biqqles/dataclassy/tree/v0.6.2
+"""
+from typing import Any, Dict, Optional
+from .dataclass import DataClassMeta
+
+
+def dataclass(cls: Optional[type] = None, *, meta=DataClassMeta, **options):
+    """The decorator used to apply DataClassMeta, or optionally a subclass of that metaclass, to a class."""
+    assert issubclass(meta, DataClassMeta)
+
+    def apply_metaclass(to_class, metaclass=meta):
+        """Apply a metaclass to a class."""
+        dict_ = dict(vars(to_class), __metaclass__=metaclass)
+        return metaclass(to_class.__name__, to_class.__bases__, dict_, **options)
+
+    if cls:  # if decorator used with no arguments, apply metaclass to the class immediately
+        if not isinstance(cls, type):
+            raise TypeError('This decorator takes no explicit positional arguments')
+        return apply_metaclass(cls)
+    return apply_metaclass  # otherwise, return function for later evaluation
+
+
+def make_dataclass(name: str, fields: Dict[str, type], defaults: Dict[str, Any], bases=(), **options) -> type:
+    """Dynamically create a data class with name `name`, fields `fields`, default field values `defaults` and
+    inheriting from `bases`."""
+    return dataclass(type(name, bases, dict(defaults, __annotations__=fields)), **options)

zepben/ewb/dataclassy/functions.py

@@ -0,0 +1,80 @@
+# LICENCE EXCLUDED
+"""
+ Copyright (C) 2020 biqqles.
+ 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 http://mozilla.org/MPL/2.0/.
+
+ This file defines functions which operate on data classes.
+
+ Forked from https://github.com/biqqles/dataclassy/tree/v0.6.2
+"""
+from typing import Any, Callable, Dict, Tuple, Type
+
+from .dataclass import DataClassMeta, DataClass, Internal
+
+
+def is_dataclass(obj: Any) -> bool:
+    """Return True if the given object is a data class as implemented in this package, otherwise False."""
+    return isinstance(obj, DataClassMeta) or is_dataclass_instance(obj)
+
+
+def is_dataclass_instance(obj: Any) -> bool:
+    """Return True if the given object is an instance of a data class, otherwise False."""
+    return isinstance(type(obj), DataClassMeta)
+
+
+def fields(dataclass: Type[DataClass], internals=False) -> Dict[str, Type]:
+    """Return a dict of `dataclass`'s fields and their types. `internals` selects whether to include internal fields.
+    `dataclass` can be either a data class or an instance of a data class. A field is defined as a class-level variable
+    with a type annotation."""
+    assert is_dataclass(dataclass)
+    return _filter_annotations(dataclass.__annotations__, internals)
+
+
+def values(dataclass: DataClass, internals=False) -> Dict[str, Any]:
+    """Return a dict of `dataclass`'s fields and their values. `internals` selects whether to include internal fields.
+    `dataclass` must be an instance of a data class. A field is defined as a class-level variable with a type
+    annotation."""
+    assert is_dataclass_instance(dataclass)
+    return {f: getattr(dataclass, f) for f in fields(dataclass, internals)}
+
+
+def as_dict(dataclass: DataClass, dict_factory=dict) -> Dict[str, Any]:
+    """Recursively create a dict of a dataclass instance's fields and their values.
+    This function is recursively called on data classes, named tuples and iterables."""
+    assert is_dataclass_instance(dataclass)
+    return _recurse_structure(dataclass, dict_factory)
+
+
+def as_tuple(dataclass: DataClass) -> Tuple:
+    """Recursively create a tuple of the values of a dataclass instance's fields, in definition order.
+    This function is recursively called on data classes, named tuples and iterables."""
+    assert is_dataclass_instance(dataclass)
+    return _recurse_structure(dataclass, lambda k_v: tuple(v for k, v in k_v))
+
+
+def replace(dataclass: DataClass, **changes) -> DataClass:
+    """Return a new copy of `dataclass` with field values replaced as specified in `changes`."""
+    return type(dataclass)(**dict(values(dataclass, internals=True), **changes))
+
+
+def _filter_annotations(annotations: Dict[str, Type], internals: bool) -> Dict[str, Type]:
+    """Filter an annotations dict for to remove or keep internal fields."""
+    return annotations if internals else {f: a for f, a in annotations.items()
+                                          if not f.startswith('_') and not Internal.is_internal(a)}
+
+
+def _recurse_structure(var: Any, iter_proc: Callable) -> Any:
+    """Recursively convert an arbitrarily nested structure beginning at `var`, copying and processing any iterables
+    encountered with `iter_proc`."""
+    if is_dataclass(var):
+        var = values(var, internals=True)
+    if hasattr(var, '_asdict'):  # handle named tuples
+        # noinspection PyCallingNonCallable, PyProtectedMember
+        var = var._asdict()
+    if isinstance(var, dict):
+        return iter_proc((_recurse_structure(k, iter_proc), _recurse_structure(v, iter_proc)) for k, v in var.items())
+    if isinstance(var, (list, tuple)):
+        return type(var)(_recurse_structure(e, iter_proc) for e in var)
+    return var

zepben/ewb/examples/__init__.py

@@ -0,0 +1,6 @@
+#  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 zepben.ewb.examples.simple_test_network import *