Update new/batch_new, and add edit methods for single objects and batches.

Author: PMeira

altdss/AutoTrans.py

@@ -1,5 +1,6 @@
 # Copyright (c) 2021-2024 Paulo Meira
 # Copyright (c) 2021-2024 DSS-Extensions contributors
+from __future__ import annotations
 from typing import Union, List, AnyStr, Optional, Iterator, TYPE_CHECKING
 from typing_extensions import TypedDict, Unpack
 from .types import Float64Array, Int32Array
@@ -119,6 +120,23 @@ def __init__(self, api_util, ptr):
        PDElementMixin.__init__(self)
        TransformerObjMixin.__init__(self)
 
+    def edit(self, **kwargs: Unpack[AutoTransProperties]) -> AutoTrans:
+        """
+        Edit this AutoTrans.
+
+        This method will try to open a new edit context (if not already open), 
+        edit the properties, and finalize the edit context. 
+        It can be seen as a shortcut to manually setting each property, or a Pythonic 
+        analogous (but extended) to the DSS `Edit` command.
+
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the object.
+        :return: Returns itself to allow call chaining.
+        """
+
+        self._edit(props=kwargs)
+        return self
+
+
     def _get_Phases(self) -> int:
         return self._lib.Obj_GetInt32(self._ptr, 1)
 
@@ -786,6 +804,23 @@ def __init__(self, api_util, **kwargs):
        CircuitElementBatchMixin.__init__(self)
        PDElementBatchMixin.__init__(self)
 
+    def edit(self, **kwargs: Unpack[AutoTransBatchProperties]) -> AutoTransBatch:
+        """
+        Edit this AutoTrans batch.
+
+        This method will try to open a new edit context (if not already open), 
+        edit the properties, and finalize the edit context for objects in the batch.
+        It can be seen as a shortcut to manually setting each property, or a Pythonic
+        analogous (but extended) to the DSS `BatchEdit` command.
+
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the objects.
+        :return: Returns itself to allow call chaining.
+        """
+
+        self._edit(props=kwargs)
+        return self
+
+
     if TYPE_CHECKING:
         def __iter__(self) -> Iterator[AutoTrans]:
             yield from DSSBatch.__iter__(self)
@@ -1504,7 +1539,7 @@ def __init__(self, iobj):
         def __getitem__(self, name_or_idx: Union[AnyStr, int]) -> AutoTrans:
             return self.find(name_or_idx)
 
-        def batch(self, **kwargs) -> AutoTransBatch:
+        def batch(self, **kwargs) -> AutoTransBatch: #TODO: add annotation to kwargs (specialized typed dict)
             """
             Creates a new batch handler of (existing) AutoTrans objects
             """
@@ -1514,8 +1549,40 @@ def __iter__(self) -> Iterator[AutoTrans]:
             yield from AutoTransBatch.__iter__(self)
 
 
-    def new(self, name: AnyStr, begin_edit=True, activate=False, **kwargs: Unpack[AutoTransProperties]) -> AutoTrans:
+    def new(self, name: AnyStr, *, begin_edit: Optional[bool] = None, activate=False, **kwargs: Unpack[AutoTransProperties]) -> AutoTrans:
+        """
+        Creates a new AutoTrans.
+
+        :param name: The object's name is a required positional argument.
+
+        :param activate: Activation (setting `activate` to true) is useful for integration with the classic API, and some internal OpenDSS commands.
+        If you interact with this object only via the Alt API, no need to activate it (due to performance costs).
+
+        :param begin_edit: This controls how the edit context is left after the object creation:
+        - `True`: The object will be left in the edit state, requiring an `end_edit` call or equivalent.
+        - `False`: No edit context is started.
+        - `None`: If no properties are passed as keyword arguments, the object will be left in the edit state (assumes the user will fill the properties from Python attributes). Otherwise, the internal edit context will be finalized.
+
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the object.
+        :return: Returns the new DSS object, wrapped in Python.
+
+        Note that, to make it easier for new users where the edit context might not be too relevant, AltDSS automatically opens/closes edit contexts for single properties if the object is not in the edit state already.
+        """
         return self._new(name, begin_edit=begin_edit, activate=activate, props=kwargs)
 
-    def batch_new(self, names: Optional[List[AnyStr]] = None, df = None, count: Optional[int] = None, begin_edit=True, **kwargs: Unpack[AutoTransBatchProperties]) -> AutoTransBatch:
+    def batch_new(self, names: Optional[List[AnyStr]] = None, *, df = None, count: Optional[int] = None, begin_edit: Optional[bool] = None, **kwargs: Unpack[AutoTransBatchProperties]) -> AutoTransBatch:
+        """
+        Creates a new batch of AutoTrans objects
+
+        Either `names`, `count` or `df` is required. 
+
+        :param begin_edit: The argument `begin_edit` indicates if the user want to leave the elements in the edit state, and requires a call to `end_edit()` or equivalent. The default `begin_edit` is set to `None`. With `None`, the behavior will be adjusted according the default of how the batch is created.
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the object.
+        :param names: When using a list of names, each new object will match the names from this list. `begin_edit` defaults to `True` if no arguments for properties were passed, `False` otherwise.
+        :param count: When using `count`, new objects will be created with based on a random prefix, with an increasing integer up to `count`. `begin_edit` defaults to `True` if no arguments for properties were passed, `False` otherwise.
+        :param df: Currently **EXPERIMENTAL AND LIMITED**, tries to get the columns from a dataframe to populate the names and the DSS properties. `begin_edit` defaults to `False`.
+        :return: Returns the new batch of DSS objects, wrapped in Python.
+
+        Note that, to make it easier for new users where the edit context might not be too relevant, AltDSS automatically opens/closes edit contexts for single properties if the object is not in the edit state already.
+        """
         return self._batch_new_aux(names=names, df=df, count=count, begin_edit=begin_edit, props=kwargs)

altdss/Batch.py

@@ -212,10 +212,7 @@ def _filter(self, _existing=True, **kwargs):
 
 
     def __init__(self, api_util, **kwargs):
-        begin_edit = kwargs.pop('begin_edit', None)
-        if begin_edit is None:
-            begin_edit = True
-
+        begin_edit = bool(kwargs.pop('begin_edit', None))
         self._sync_cls_idx = kwargs.pop('sync_cls_idx', False)
 
         new_batch_args = kwargs.keys() & {'new_names', 'new_count', }
@@ -668,6 +665,22 @@ def _set_batch_objlist_prop(self, idx: int, other: List[DSSObj], flags: SetterFl
         #     obj._ptr = ptr
         #     obj._set_obj_array(idx, other_objs)
 
+    def _edit(self, props):
+        ptr, cnt = self._get_ptr_cnt()
+        if cnt == 0:
+            return
+
+        if not (self._lib.Obj_GetFlags(ptr[0]) and self._lib.DSSObjectFlags_Editing):
+            self._lib.Batch_BeginEdit(ptr, cnt)
+
+        self._check_for_error()
+
+        for k, v in props.items():
+            setattr(self, k, v)
+
+        self._lib.Batch_EndEdit(ptr, cnt, len(props))
+        self._check_for_error()
+
 
 class NonUniformBatch(Base, BatchCommon):
     '''

altdss/CNData.py

@@ -1,5 +1,6 @@
 # Copyright (c) 2021-2024 Paulo Meira
 # Copyright (c) 2021-2024 DSS-Extensions contributors
+from __future__ import annotations
 from typing import Union, List, AnyStr, Optional, Iterator, TYPE_CHECKING
 from typing_extensions import TypedDict, Unpack
 from .types import Float64Array, Int32Array
@@ -63,6 +64,23 @@ class CNData(DSSObj):
     }
 
 
+    def edit(self, **kwargs: Unpack[CNDataProperties]) -> CNData:
+        """
+        Edit this CNData.
+
+        This method will try to open a new edit context (if not already open), 
+        edit the properties, and finalize the edit context. 
+        It can be seen as a shortcut to manually setting each property, or a Pythonic 
+        analogous (but extended) to the DSS `Edit` command.
+
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the object.
+        :return: Returns itself to allow call chaining.
+        """
+
+        self._edit(props=kwargs)
+        return self
+
+
     def _get_k(self) -> int:
         return self._lib.Obj_GetInt32(self._ptr, 1)
 
@@ -427,6 +445,23 @@ class CNDataBatch(DSSBatch):
     __slots__ = []
 
 
+    def edit(self, **kwargs: Unpack[CNDataBatchProperties]) -> CNDataBatch:
+        """
+        Edit this CNData batch.
+
+        This method will try to open a new edit context (if not already open), 
+        edit the properties, and finalize the edit context for objects in the batch.
+        It can be seen as a shortcut to manually setting each property, or a Pythonic
+        analogous (but extended) to the DSS `BatchEdit` command.
+
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the objects.
+        :return: Returns itself to allow call chaining.
+        """
+
+        self._edit(props=kwargs)
+        return self
+
+
     if TYPE_CHECKING:
         def __iter__(self) -> Iterator[CNData]:
             yield from DSSBatch.__iter__(self)
@@ -804,7 +839,7 @@ def __init__(self, iobj):
         def __getitem__(self, name_or_idx: Union[AnyStr, int]) -> CNData:
             return self.find(name_or_idx)
 
-        def batch(self, **kwargs) -> CNDataBatch:
+        def batch(self, **kwargs) -> CNDataBatch: #TODO: add annotation to kwargs (specialized typed dict)
             """
             Creates a new batch handler of (existing) CNData objects
             """
@@ -814,8 +849,40 @@ def __iter__(self) -> Iterator[CNData]:
             yield from CNDataBatch.__iter__(self)
 
 
-    def new(self, name: AnyStr, begin_edit=True, activate=False, **kwargs: Unpack[CNDataProperties]) -> CNData:
+    def new(self, name: AnyStr, *, begin_edit: Optional[bool] = None, activate=False, **kwargs: Unpack[CNDataProperties]) -> CNData:
+        """
+        Creates a new CNData.
+
+        :param name: The object's name is a required positional argument.
+
+        :param activate: Activation (setting `activate` to true) is useful for integration with the classic API, and some internal OpenDSS commands.
+        If you interact with this object only via the Alt API, no need to activate it (due to performance costs).
+
+        :param begin_edit: This controls how the edit context is left after the object creation:
+        - `True`: The object will be left in the edit state, requiring an `end_edit` call or equivalent.
+        - `False`: No edit context is started.
+        - `None`: If no properties are passed as keyword arguments, the object will be left in the edit state (assumes the user will fill the properties from Python attributes). Otherwise, the internal edit context will be finalized.
+
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the object.
+        :return: Returns the new DSS object, wrapped in Python.
+
+        Note that, to make it easier for new users where the edit context might not be too relevant, AltDSS automatically opens/closes edit contexts for single properties if the object is not in the edit state already.
+        """
         return self._new(name, begin_edit=begin_edit, activate=activate, props=kwargs)
 
-    def batch_new(self, names: Optional[List[AnyStr]] = None, df = None, count: Optional[int] = None, begin_edit=True, **kwargs: Unpack[CNDataBatchProperties]) -> CNDataBatch:
+    def batch_new(self, names: Optional[List[AnyStr]] = None, *, df = None, count: Optional[int] = None, begin_edit: Optional[bool] = None, **kwargs: Unpack[CNDataBatchProperties]) -> CNDataBatch:
+        """
+        Creates a new batch of CNData objects
+
+        Either `names`, `count` or `df` is required. 
+
+        :param begin_edit: The argument `begin_edit` indicates if the user want to leave the elements in the edit state, and requires a call to `end_edit()` or equivalent. The default `begin_edit` is set to `None`. With `None`, the behavior will be adjusted according the default of how the batch is created.
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the object.
+        :param names: When using a list of names, each new object will match the names from this list. `begin_edit` defaults to `True` if no arguments for properties were passed, `False` otherwise.
+        :param count: When using `count`, new objects will be created with based on a random prefix, with an increasing integer up to `count`. `begin_edit` defaults to `True` if no arguments for properties were passed, `False` otherwise.
+        :param df: Currently **EXPERIMENTAL AND LIMITED**, tries to get the columns from a dataframe to populate the names and the DSS properties. `begin_edit` defaults to `False`.
+        :return: Returns the new batch of DSS objects, wrapped in Python.
+
+        Note that, to make it easier for new users where the edit context might not be too relevant, AltDSS automatically opens/closes edit contexts for single properties if the object is not in the edit state already.
+        """
         return self._batch_new_aux(names=names, df=df, count=count, begin_edit=begin_edit, props=kwargs)

altdss/CapControl.py

@@ -1,5 +1,6 @@
 # Copyright (c) 2021-2024 Paulo Meira
 # Copyright (c) 2021-2024 DSS-Extensions contributors
+from __future__ import annotations
 from typing import Union, List, AnyStr, Optional, Iterator, TYPE_CHECKING
 from typing_extensions import TypedDict, Unpack
 from .types import Float64Array, Int32Array
@@ -71,6 +72,23 @@ def __init__(self, api_util, ptr):
        DSSObj.__init__(self, api_util, ptr)
        CircuitElementMixin.__init__(self)
 
+    def edit(self, **kwargs: Unpack[CapControlProperties]) -> CapControl:
+        """
+        Edit this CapControl.
+
+        This method will try to open a new edit context (if not already open), 
+        edit the properties, and finalize the edit context. 
+        It can be seen as a shortcut to manually setting each property, or a Pythonic 
+        analogous (but extended) to the DSS `Edit` command.
+
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the object.
+        :return: Returns itself to allow call chaining.
+        """
+
+        self._edit(props=kwargs)
+        return self
+
+
     def _get_Element_str(self) -> str:
         return self._get_prop_string(1)
 
@@ -560,6 +578,23 @@ def __init__(self, api_util, **kwargs):
        DSSBatch.__init__(self, api_util, **kwargs)
        CircuitElementBatchMixin.__init__(self)
 
+    def edit(self, **kwargs: Unpack[CapControlBatchProperties]) -> CapControlBatch:
+        """
+        Edit this CapControl batch.
+
+        This method will try to open a new edit context (if not already open), 
+        edit the properties, and finalize the edit context for objects in the batch.
+        It can be seen as a shortcut to manually setting each property, or a Pythonic
+        analogous (but extended) to the DSS `BatchEdit` command.
+
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the objects.
+        :return: Returns itself to allow call chaining.
+        """
+
+        self._edit(props=kwargs)
+        return self
+
+
     if TYPE_CHECKING:
         def __iter__(self) -> Iterator[CapControl]:
             yield from DSSBatch.__iter__(self)
@@ -1042,7 +1077,7 @@ def __init__(self, iobj):
         def __getitem__(self, name_or_idx: Union[AnyStr, int]) -> CapControl:
             return self.find(name_or_idx)
 
-        def batch(self, **kwargs) -> CapControlBatch:
+        def batch(self, **kwargs) -> CapControlBatch: #TODO: add annotation to kwargs (specialized typed dict)
             """
             Creates a new batch handler of (existing) CapControl objects
             """
@@ -1052,8 +1087,40 @@ def __iter__(self) -> Iterator[CapControl]:
             yield from CapControlBatch.__iter__(self)
 
 
-    def new(self, name: AnyStr, begin_edit=True, activate=False, **kwargs: Unpack[CapControlProperties]) -> CapControl:
+    def new(self, name: AnyStr, *, begin_edit: Optional[bool] = None, activate=False, **kwargs: Unpack[CapControlProperties]) -> CapControl:
+        """
+        Creates a new CapControl.
+
+        :param name: The object's name is a required positional argument.
+
+        :param activate: Activation (setting `activate` to true) is useful for integration with the classic API, and some internal OpenDSS commands.
+        If you interact with this object only via the Alt API, no need to activate it (due to performance costs).
+
+        :param begin_edit: This controls how the edit context is left after the object creation:
+        - `True`: The object will be left in the edit state, requiring an `end_edit` call or equivalent.
+        - `False`: No edit context is started.
+        - `None`: If no properties are passed as keyword arguments, the object will be left in the edit state (assumes the user will fill the properties from Python attributes). Otherwise, the internal edit context will be finalized.
+
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the object.
+        :return: Returns the new DSS object, wrapped in Python.
+
+        Note that, to make it easier for new users where the edit context might not be too relevant, AltDSS automatically opens/closes edit contexts for single properties if the object is not in the edit state already.
+        """
         return self._new(name, begin_edit=begin_edit, activate=activate, props=kwargs)
 
-    def batch_new(self, names: Optional[List[AnyStr]] = None, df = None, count: Optional[int] = None, begin_edit=True, **kwargs: Unpack[CapControlBatchProperties]) -> CapControlBatch:
+    def batch_new(self, names: Optional[List[AnyStr]] = None, *, df = None, count: Optional[int] = None, begin_edit: Optional[bool] = None, **kwargs: Unpack[CapControlBatchProperties]) -> CapControlBatch:
+        """
+        Creates a new batch of CapControl objects
+
+        Either `names`, `count` or `df` is required. 
+
+        :param begin_edit: The argument `begin_edit` indicates if the user want to leave the elements in the edit state, and requires a call to `end_edit()` or equivalent. The default `begin_edit` is set to `None`. With `None`, the behavior will be adjusted according the default of how the batch is created.
+        :param **kwargs: Pass keyword arguments equivalent to the DSS properties of the object.
+        :param names: When using a list of names, each new object will match the names from this list. `begin_edit` defaults to `True` if no arguments for properties were passed, `False` otherwise.
+        :param count: When using `count`, new objects will be created with based on a random prefix, with an increasing integer up to `count`. `begin_edit` defaults to `True` if no arguments for properties were passed, `False` otherwise.
+        :param df: Currently **EXPERIMENTAL AND LIMITED**, tries to get the columns from a dataframe to populate the names and the DSS properties. `begin_edit` defaults to `False`.
+        :return: Returns the new batch of DSS objects, wrapped in Python.
+
+        Note that, to make it easier for new users where the edit context might not be too relevant, AltDSS automatically opens/closes edit contexts for single properties if the object is not in the edit state already.
+        """
         return self._batch_new_aux(names=names, df=df, count=count, begin_edit=begin_edit, props=kwargs)