LogicArray mock up

logic_array.pyi

from functools import cache, cached_property
from typing import (
    Collection,
    Iterable,
    Optional,
    Reversible,
    Sized,
    TypeAlias,
    TypeVar,
    overload,
)

class Logic:
    # this needs to be updated to no longer be hashable so that we can support equality between different types
    ...
class Range: ...

LogicConstructable: TypeAlias = Logic | str | int | bool
LogicComparable: TypeAlias = Logic | str | int | bool

T = TypeVar("T")

class SizedIterable(Iterable[T], Sized): ...

class LogicArray(Collection[Logic], Reversible[Logic]):
    # constructors
    @overload
    @classmethod
    def from_int(v: int, *, byteorder) -> "LogicArray": ...
    @overload
    @classmethod
    def from_int(v: int, range: Range, *, byteorder: str) -> "LogicArray": ...
    @overload
    @classmethod
    def from_int(v: int, *, left: int, direction: Optional[str] = None, right: int, byteorder: str = "big") -> "LogicArray": ...
    @overload
    def __init__(self, value: str) -> None: ...
    @overload
    def __init__(self, value: str, range: Range) -> None: ...
    @overload
    def __init__(
        self, value: str, *, left: int, direction: Optional[str] = None, right: int
    ) -> None: ...
    @overload
    def __init__(self, value: "LogicArray") -> None: ...
    @overload
    def __init__(self, value: "LogicArray", range: Range) -> None: ...
    @overload
    def __init__(
        self, value: "LogicArray", *, left: int, direction: Optional[str] = None, right: int
    ) -> None: ...
    @overload
    def __init__(self, value: SizedIterable[LogicConstructable]) -> None: ...
    @overload
    def __init__(self, value: SizedIterable[LogicConstructable], range: Range) -> None: ...
    @overload
    def __init__(
        self,
        value: SizedIterable[LogicConstructable],
        *,
        left: int,
        direction: Optional[str] = None,
        right: int
    ) -> None: ...
    # conversions
    def __str__(self) -> str: ...
    def to_int(self, byteorder: str, representation: str) -> int: ...
    # range stuff
    @cached_property
    def range(self) -> Range:
        ...  # construct range on first access
    @cached_property
    def left(self) -> int:
        ...  # ranges are immutable, so however you can get the range, either using the Range object or passed "left" arg, you can just cache it
    @cached_property
    def right(self) -> int: ...
    @cached_property
    def direction(self) -> str: ...
    # sequence-like stuff
    def __iter__(self) -> Iterable[Logic]: ...
    def __reversed__(self) -> Iterable[Logic]: ...
    @cache
    def __len__(self) -> None:
        # here we need to be able to compute the length without first constructing the Range object, as that requires more time
        # we can compute it if left, direction, right are given, or take length of passed in argument if not
        ...
    @overload
    def __getitem__(self, key: int) -> Logic: ...
    @overload
    def __getitem__(self, key: slice) -> "LogicArray": ...
    @overload
    def __setitem__(self, key: int, value: Logic, str, int, bool) -> None: ...
    @overload
    def __setitem__(
        self, key: slice, value: SizedIterable[LogicConstructable] | str
    ) -> None: ...
    # bitwise operators, reverse operators and inplace implied
    def __or__(
        self, other: "LogicArray" | SizedIterable[LogicConstructable] | str
    ) -> "LogicArray": ...
    def __and__(
        self, other: "LogicArray" | SizedIterable[LogicConstructable] | str
    ) -> "LogicArray": ...
    def __xor__(
        self, other: "LogicArray" | SizedIterable[LogicConstructable] | str
    ) -> "LogicArray": ...
    def __inv__(self) -> "LogicArray": ...
    # misc
    def __eq__(
        self, other: "LogicArray" | SizedIterable[LogicComparable] | str
    ) -> bool: ...
    __hash__: None  # not hashable

# implementation should be something like:
#  _value: str | List[Logic] | int
#  _value_int_byteorder: Optional[str]
#  _value_impl: 0, 1, or 2 representing List[Logic], str, or int
#  _left: Optional[int]
#  _direction: Optional[str]
#  _right: Optional[int]
#  _range : Range
#  _range_impl: 0 or 1 representing Range or (left, direction, right)