aspen_pysys.base.primitive

 21class HysysArray(HysysPrimitive):
 22    """Class that represents an array from the HYSYS app."""
 23
 24    def __init__(
 25        self,
 26        attr: str,
 27        parent: HysysObject,
 28        count: int | None = None,
 29    ) -> None:
 30        """Create a Pythonic representation of an array from the HYSYS app.
 31
 32        Args:
 33            attr (str): Object attribute name
 34            parent (HysysObject): Parent of object
 35            count (int, optional): Size of array if known. Defaults to None.
 36
 37        Raises:
 38            PysysError: HysysConstant cannot be constructed.
 39        """
 40        is_initialised = True
 41        attr_value = parent._get_attr(attr)
 42
 43        try:
 44            if isinstance(attr_value, collection_types):
 45                super().__init__(
 46                    attr,
 47                    parent,
 48                    HysysPrimitiveType.ARRAY,
 49                    lambda: parent._get_attr(attr),
 50                    lambda value: parent.set_attr(attr, value),
 51                )
 52
 53            elif hasattr(attr_value, VALUES_STR):
 54                super().__init__(
 55                    attr,
 56                    parent,
 57                    HysysPrimitiveType.ARRAY,
 58                    lambda: getattr(parent._get_attr(attr), VALUES_STR),
 59                    lambda value: parent._get_attr(attr).SetValues(  # ty:ignore[unresolved-attribute]
 60                        value,
 61                        None,
 62                    ),
 63                )
 64
 65            else:
 66                is_initialised = False
 67
 68        except com_error as err:
 69            message = "Value cannot be converted to a HysysArray."
 70            raise PysysError(message) from err
 71
 72        if not is_initialised:
 73            message = "HysysArray cannot be constructed."
 74            raise PysysError(message)
 75
 76        self._count = count
 77
 78    def __repr__(self) -> str:
 79        with self as (getter, _):
 80            return f"{self.get_name()}={getter()} ({self._object_type})"
 81
 82    def __iter__(self) -> Iterator[Any]:
 83        for index in range(len(self)):
 84            yield self.get(index)
 85
 86    def __len__(self) -> int:
 87        return self.count()
 88
 89    def __getitem__(self, subscript: slice | int) -> Any:  # noqa: ANN401
 90        return self.get(subscript)
 91
 92    def __setitem__(self, subscript: slice | int, value: Any) -> None:  # noqa: ANN401
 93        return self.set(subscript, value)
 94
 95    def __contains__(self, item: Any) -> bool:  # noqa: ANN401
 96        return self.contains(item)
 97
 98    def count(self) -> int:
 99        """Get the size of the array.
100
101        Returns:
102            int: Size of array
103        """
104        if self._count is None:
105            with self as (getter, _):
106                return len(getter())
107
108        return self._count
109
110    def get(self, subscript: slice | int) -> Any:  # noqa: ANN401
111        """Get an element from a HYSYS array.
112
113        Args:
114            subscript (slice | int): Slice/index of element(s)
115
116        Returns:
117            Any: Element at given index
118
119        Raises:
120            IndexError: Index out of range.
121        """
122        if isinstance(subscript, int) and (subscript < 0 or subscript >= len(self)):
123            message = f"Index {subscript} out of range."
124            raise IndexError(message)
125
126        with self as (getter, _):
127            return getter()[subscript]
128
129    def set(self, subscript: slice | int, value: Any) -> None:  # noqa: ANN401
130        """Update an existing element in a HYSYS array.
131
132        Args:
133            subscript (slice | int): Slice/index of element(s)
134            value (any): Value to set at given index
135
136        Raises:
137            IndexError: Index out of range.
138        """
139        if isinstance(subscript, int) and (subscript < 0 or subscript >= len(self)):
140            message = f"Index {subscript} out of range."
141            raise IndexError(message)
142
143        new_value = list(super().get_value())
144        new_value[subscript] = value
145
146        super().set_value(new_value)
147
148    def contains(self, item: Any) -> bool:  # noqa: ANN401
149        """Check if the array contains an item.
150
151        Args:
152            item (Any): Item to check for
153
154        Returns:
155            bool: If the item is present in the array
156        """
157        with self as (getter, _):
158            for value in getter():
159                if item == value:
160                    return True
161
162        return False

 20class HysysConstant[T](HysysPrimitive):
 21    """Class that represents a constant from the HYSYS app."""
 22
 23    def __init__(
 24        self,
 25        attr: str,
 26        parent: HysysObject,
 27        typ: type[T] | Any = Any,  # noqa: ANN401
 28    ) -> None:
 29        """Create a Pythonic representation of a constant from the HYSYS app.
 30
 31        Args:
 32            attr (str): Object attribute name
 33            parent (HysysObject): Parent of object
 34            typ (type[T] | Any, optional): Type of value contained by constant. Defaults to Any.
 35
 36        Raises:
 37            PysysError: HysysConstant cannot be constructed.
 38        """  # noqa: E501
 39        attr_value = parent._get_attr(attr)
 40
 41        if isinstance(attr_value, primitive_types):
 42            super().__init__(
 43                attr,
 44                parent,
 45                HysysPrimitiveType.CONSTANT,
 46                lambda: parent._get_attr(attr),
 47                lambda value: parent.set_attr(attr, value),
 48            )
 49
 50        elif hasattr(attr_value, GET_VALUE_STR):
 51            super().__init__(
 52                attr,
 53                parent,
 54                HysysPrimitiveType.CONSTANT,
 55                lambda: getattr(parent._get_attr(attr), VALUE_STR),
 56                lambda value: setattr(parent._get_attr(attr), VALUE_STR, value),
 57            )
 58
 59        else:
 60            message = "HysysConstant cannot be constructed."
 61            raise PysysError(message)
 62
 63        self._const_type = typ
 64
 65    def __repr__(self) -> str:
 66        try:
 67            value = super().get_value()
 68        except com_error:
 69            value = "<cannot be retrieved>"
 70
 71        if is_empty(value):
 72            value = "<empty>"
 73
 74        return f"{self.get_name()}={value} ({self._object_type})"
 75
 76    def _was_type_set(self) -> bool:
 77        return self._const_type != Any
 78
 79    @override
 80    def get_value(self) -> T | None:
 81        """Get the constant's value.
 82
 83        Returns:
 84            T | None: Value of constant
 85
 86        Raises:
 87            PysysError: Constant cannot be retrieved.
 88            PysysError: Constant is not of the same type.
 89        """
 90        try:
 91            value = super().get_value()
 92        except com_error as err:
 93            message = "Constant cannot be retrieved."
 94            raise PysysError(message) from err
 95
 96        if self.is_empty():
 97            return None
 98
 99        if self._was_type_set() and not isinstance(value, self._const_type):
100            message = f"Constant '{value}' is of type '{type(value)}'"
101            f", not assigned type '{self._const_type}'."
102            raise PysysError(message)
103
104        return value
105
106    @override
107    def set_value(self, value: T | None) -> None:
108        if value is None:
109            super().set_value(NONE)
110            return
111
112        if self._const_type != Any and not isinstance(value, self._const_type):
113            message = f"Value '{value}' is of type '{type(value)}',"
114            f" not assigned type '{self._const_type}'."
115            raise PysysError(message)
116
117        super().set_value(value)
118
119    def is_empty(self) -> bool:
120        """Check if the constant is empty.
121
122        Returns:
123            bool: If the constant is empty
124        """
125        value = super().get_value()
126        return is_empty(value)

 20class HysysDictionary[T: HysysObject](HysysPrimitive):
 21    """Class that represents a key-value object from the HYSYS app."""
 22
 23    def __init__(
 24        self,
 25        attr: str,
 26        parent: HysysObject,
 27        mapper: Callable[[HysysObject], T],
 28    ) -> None:
 29        """Create a Pythonic representation of a dictionary from the HYSYS app.
 30
 31        Args:
 32            attr (str): Object attribute name
 33            parent (HysysObject): Parent of object
 34            mapper (Callable[[HysysObject], T]): Mapper function to map HysysObject values to type T
 35
 36        Raises:
 37            ValueError: Value cannot be converted to a dictionary.
 38            PysysError: Dictionary cannot be constructed.
 39        """  # noqa: E501
 40        is_initialised = True
 41        attr_value = parent._get_attr(attr)
 42        self._mapper = mapper
 43
 44        try:
 45            if hasattr(attr_value, NAMES_STR):
 46                super().__init__(
 47                    attr,
 48                    parent,
 49                    HysysPrimitiveType.DICT,
 50                    lambda: parent._get_attr(attr),
 51                )
 52            else:
 53                is_initialised = False
 54
 55        except com_error as err:
 56            message = "Value cannot be converted to a HysysDictionary."
 57            raise ValueError(message) from err
 58
 59        if not is_initialised:
 60            message = "HysysDictionary cannot be constructed."
 61            raise PysysError(message)
 62
 63        with self as (getter, _):
 64            self._dict_obj = HysysObject(parent.get_connection(), getter())
 65
 66    def map[R: HysysObject](
 67        self: HysysDictionary[T],
 68        func: Callable[[T], R],
 69    ) -> HysysDictionary[R]:
 70        """Map the values of the dictionary to another type.
 71
 72        Args:
 73            func (Callable[[T], R]): Mapper function to map values of type T to type R
 74
 75        Returns:
 76            HysysDictionary[R]: New dictionary
 77        """
 78        return HysysDictionary(
 79            self._attr,
 80            self.get_parent(),
 81            lambda obj: func(self._mapper(obj)),
 82        )
 83
 84    def filter(
 85        self: HysysDictionary[T],
 86        pred: Callable[[str, T], bool],
 87    ) -> dict[str, T]:
 88        """Filter the dictionary.
 89
 90        Args:
 91            pred (Callable[[str, T], bool]): Predicate taking in a string key and its corresponding value
 92
 93        Returns:
 94            dict[str, T]: Dictionary of filtered items
 95        """  # noqa: E501
 96        return {key: value for (key, value) in self.items() if pred(key, value)}
 97
 98    def add(self: HysysDictionary[T], *args: *tuple) -> HysysObject | None:
 99        """Add a new object to the dictionary.
100
101        Args:
102            *args (*tuple): Arguments about the new object
103
104        Returns:
105            HysysObject | None: Newly added object
106        """
107        add_func = self._dict_obj.get_func("Add")
108        return add_func.call(*args)
109
110    @override
111    def __repr__(self: HysysDictionary[T]) -> str:
112        return f"{self.get_name()}={tuple(self.keys())} ({self._object_type})"
113
114    def __iter__(self: HysysDictionary[T]) -> Iterator[str]:
115        yield from self.keys()
116
117    def __len__(self: HysysDictionary[T]) -> int:
118        return self.count()
119
120    def __getitem__(self: HysysDictionary[T], key: str) -> T:
121        return self.get(key)
122
123    def __contains__(self: HysysDictionary[T], key: str) -> bool:
124        return self.contains(key)
125
126    def count(self: HysysDictionary[T]) -> int:
127        """Get the size of the dictionary.
128
129        Returns:
130            int: Size of dictionary
131        """
132        return self._dict_obj.get_int("Count")
133
134    def contains(self: HysysDictionary[T], key: str) -> bool:
135        """Check if a key exists within the HYSYS dictionary.
136
137        Args:
138            key (str): Key to look for
139
140        Returns:
141            bool: Whether the key exists or not
142        """
143        return key in self.keys()
144
145    def keys(self: HysysDictionary[T]) -> tuple[str]:
146        """Get all the keys for the HYSYS dictionary.
147
148        Returns:
149            tuple[str]: Keys for the HYSYS dictionary
150        """
151        return tuple(self._dict_obj.get_array(NAMES_STR, len(self)))
152
153    def values(self: HysysDictionary[T]) -> Iterator[T]:
154        """Get the values of the dictionary.
155
156        Returns:
157            Iterator[T]: Iterator of the values
158        """
159        return (self.get(key) for key in self)
160
161    def items(self: HysysDictionary[T]) -> Iterator[tuple[str, T]]:
162        """Get the key-value pairs of the dictionary.
163
164        Returns:
165            Iterator[tuple[str, T]]: Iterator of key-value pairs
166        """
167        return ((key, self.get(key)) for key in self)
168
169    def get(self: HysysDictionary[T], key: str) -> T:
170        """Get a value from the HYSYS dictionary for a given key.
171
172        Args:
173            key (str): Key in HYSYS dictionary
174
175        Returns:
176            HysysObject: Value for given key
177
178        Raises:
179            KeyError: Key cannot be accessed.
180            PysysError: Value is None.
181        """
182        item_func = self._dict_obj.get_func("Item")
183
184        try:
185            func_result = item_func.call(key)
186        except com_error as err:
187            message = f"Key '{key}' cannot be accessed."
188            raise KeyError(message) from err
189
190        if func_result is None:
191            message = f"Value at key '{key}' is None."
192            raise PysysError(message)
193
194        return self._mapper(func_result)

20class HysysFunction(HysysPrimitive):
21    """Class that represents a function from the HYSYS app."""
22
23    def __init__(self, attr: str, parent: HysysObject) -> None:
24        """Create a Pythonic representation of a function from a HYSYS COM Object.
25
26        Args:
27            attr (str): Object attribute name
28            parent (HysysObject): Parent of object
29
30        Raises:
31            PysysError: HysysConstant cannot be constructed.
32        """
33        attr_value = parent._get_attr(attr)
34
35        if isfunction(attr_value) or ismethod(attr_value):
36            super().__init__(
37                attr,
38                parent,
39                HysysPrimitiveType.FUNCTION,
40                lambda: parent._get_attr(attr),
41            )
42        else:
43            message = "HysysConstant cannot be constructed."
44            raise PysysError(message)
45
46    def __repr__(self) -> str:
47        return f"{self.get_name()} ({self._object_type})"
48
49    @override
50    def set_value(self, value: str) -> Never:
51        message = f"{self} cannot be set."
52        raise PysysError(message)
53
54    def call(self, *args: *tuple) -> HysysObject | None:
55        """Call the function.
56
57        Args:
58            args (tuple[Any]): Arguments for the function if any.
59
60        Returns:
61            Return value if any.
62
63        Raises:
64            PysysError: Function cannot be called.
65        """
66        with self as (getter, _):
67            func = getter()
68            try:
69                value = func(*args)
70            except com_error as err:
71                message = "Function cannot be called."
72                raise PysysError(message) from err
73
74            if value is None:
75                return None
76
77            return HysysObject(self.get_parent().get_connection(), value)
78
79    def signature(self) -> Signature:
80        """Get the function signature.
81
82        Returns:
83            Function signature.
84        """
85        with self as (getter, _):
86            func = getter()
87            return signature(func)

19class HysysPrimitive:
20    """Class that represents a primitive from the HYSYS app.
21
22    These might either represent constants, arrays and dictionaries.
23    """
24
25    def __init__(
26        self,
27        attr: str,
28        parent: HysysObject,
29        object_type: HysysPrimitiveType,
30        value_getter: Callable[[], Any],
31        value_setter: Callable[[Any], None] = lambda _: None,
32    ) -> None:
33        """Create a Pythonic representation of an object that is not a primitive from the HYSYS app.
34
35        Args:
36            attr (str): Attribute name
37            parent (HysysObject): Parent of object
38            object_type (HysysObjectType): Object type
39            value_getter (Callable[[], Any]): Object getter
40            value_setter (_type_, optional): Object setter. Defaults to lambda_:None.
41        """  # noqa: E501
42        self._attr = attr
43        self._parent = parent
44        self._object_type = object_type
45
46        self._value_getter = value_getter
47        self._value_setter = value_setter
48
49    @override
50    def __repr__(self) -> str:
51        return f"{self.get_name()} (HYSYS Primitive)"
52
53    def get_name(self) -> str:
54        """Get the attribute name.
55
56        Returns:
57            str: Name
58        """
59        return self._attr
60
61    def get_parent(self) -> HysysObject:
62        """Gets the parent of the primitive.
63
64        Returns:
65            HysysObject: Parent of primitive
66        """
67        return self._parent
68
69    def get_value(self) -> Any:  # noqa: ANN401
70        """Get the raw value of the primitive from HYSYS.
71
72        Returns:
73            Any: Raw value of primitive
74        """
75        return self._value_getter()
76
77    def set_value(self, value: Any) -> None:  # noqa: ANN401
78        """Set the raw value of the primitive from HYSYS.
79
80        Args:
81            value (Any): New value
82
83        Raises:
84            PysysError: New value cannot be assigned.
85        """
86        try:
87            self._value_setter(value)
88        except com_error as err:
89            message = f"'{self}' cannot be set to a value of {value}."
90            raise PysysError(message) from err
91
92    def __enter__(self) -> tuple[Callable[[], Any], Callable[[Any], None]]:
93        return (self._value_getter, self._value_setter)
94
95    def __exit__(self, *_: object) -> None:
96        return

 8class HysysPrimitiveType(StrEnum):
 9    """Class that indicates the type of data pulled from the HYSYS app."""
10
11    CONSTANT = "HYSYS Constant"
12    """Value indicating a HYSYS constant"""
13
14    ARRAY = "HYSYS Array"
15    """Value indicating a HYSYS array"""
16
17    DICT = "HYSYS Dictionary"
18    """Value indicating a HYSYS dictionary"""
19
20    FUNCTION = "HYSYS Function"
21    """Value indicating a HYSYS function"""
22
23    @override
24    def __repr__(self) -> str:
25        return self.__str__()