Merge pull request #953 from emabre/feature/Cleanup-import-statements2

Cleanup import statements: rearrange modules that _core imports from

Author: nitbharambe

docs/api_reference/python-api-reference.md

@@ -32,6 +32,8 @@ are internal implementations.
 ```{eval-rst}
 .. automodule:: power_grid_model.enum
    :undoc-members:
+   :imported-members:
+   :member-order: bysource
    :show-inheritance:
 ```
 
@@ -40,6 +42,8 @@ are internal implementations.
 ```{eval-rst}
 .. automodule:: power_grid_model.data_types
    :undoc-members:
+   :imported-members:
+   :member-order: bysource
    :show-inheritance:
    :exclude-members: BatchList,NominalValue,RealValue,AsymValue,AttributeValue,Component,ComponentList,SinglePythonDataset,BatchPythonDataset,PythonDataset
 ```
@@ -48,6 +52,9 @@ are internal implementations.
 
 ```{eval-rst}
 .. automodule:: power_grid_model.errors
+   :imported-members:
+   :member-order: bysource
+   :show-inheritance:
 ```
 
 ## typing

src/power_grid_model/_core/buffer_handling.py

@@ -11,26 +11,26 @@
 
 import numpy as np
 
+from power_grid_model._core.data_types import (
+    AttributeType,
+    ComponentData,
+    DenseBatchData,
+    IndexPointer,
+    SingleComponentData,
+    SparseBatchArray,
+    SparseBatchData,
+)
 from power_grid_model._core.error_handling import VALIDATOR_MSG
 from power_grid_model._core.index_integer import IdxC, IdxNp
 from power_grid_model._core.power_grid_core import IdxPtr, VoidPtr
 from power_grid_model._core.power_grid_meta import ComponentMetaData
-from power_grid_model._utils import (
+from power_grid_model._core.utils import (
     _extract_data_from_component_data,
     _extract_indptr,
     check_indptr_consistency,
     is_columnar,
     is_sparse,
 )
-from power_grid_model.data_types import (
-    AttributeType,
-    ComponentData,
-    DenseBatchData,
-    IndexPointer,
-    SingleComponentData,
-    SparseBatchArray,
-    SparseBatchData,
-)
 
 
 @dataclass

src/power_grid_model/_core/data_handling.py

@@ -8,14 +8,14 @@
 
 import numpy as np
 
+from power_grid_model._core.data_types import Dataset, SingleDataset
 from power_grid_model._core.dataset_definitions import ComponentType, DatasetType
+from power_grid_model._core.enum import CalculationType, ComponentAttributeFilterOptions
+from power_grid_model._core.errors import PowerGridUnreachableHitError
 from power_grid_model._core.power_grid_dataset import CConstDataset, CMutableDataset
 from power_grid_model._core.power_grid_meta import initialize_array, power_grid_meta_data
-from power_grid_model._utils import process_data_filter
-from power_grid_model.data_types import Dataset, SingleDataset
-from power_grid_model.enum import CalculationType, ComponentAttributeFilterOptions
-from power_grid_model.errors import PowerGridUnreachableHitError
-from power_grid_model.typing import ComponentAttributeMapping
+from power_grid_model._core.typing import ComponentAttributeMapping
+from power_grid_model._core.utils import process_data_filter
 
 
 def get_output_type(*, calculation_type: CalculationType, symmetric: bool) -> DatasetType:

src/power_grid_model/_core/data_types.py

@@ -0,0 +1,132 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""
+Data types involving PGM datasets.
+
+Data types for library-internal use. In an attempt to clarify type hints, some types
+have been defined and explained in this file.
+"""
+
+from typing import TypeAlias, TypedDict, TypeVar
+
+import numpy as np
+
+from power_grid_model._core.dataset_definitions import ComponentTypeVar
+
+SingleArray: TypeAlias = np.ndarray
+
+AttributeType: TypeAlias = str
+
+SingleColumn: TypeAlias = np.ndarray
+
+DenseBatchArray: TypeAlias = np.ndarray
+
+SingleColumnarData = dict[AttributeType, SingleColumn]
+
+_SingleComponentData = TypeVar("_SingleComponentData", SingleArray, SingleColumnarData)  # deduction helper
+SingleComponentData = SingleArray | SingleColumnarData
+
+
+SingleDataset = dict[ComponentTypeVar, _SingleComponentData]
+
+BatchList = list[SingleDataset]
+
+BatchColumn: TypeAlias = np.ndarray
+
+DenseBatchColumnarData = dict[AttributeType, BatchColumn]
+
+IndexPointer: TypeAlias = np.ndarray
+
+
+class SparseBatchColumnarData(TypedDict):
+    """
+    Sparse batch columnar data is a dictionary containing the keys `indptr` and `data`.
+
+    - data: a :class:`SingleColumnarData`. The exact supported attribute columns depend on the component type.
+    - indptr: an :class:`IndexPointer` representing the start and end indices for each batch scenario.
+
+    - Examples:
+
+        - structure: {"indptr": :class:`IndexPointer`, "data": :class:`SingleColumnarData`}
+        - concrete example: {"indptr": [0, 2, 2, 3], "data": {"id": [0, 1, 0], "status": [1, 1, 0]}}
+
+            - the scenario 0 sets the status of components with ids 0 and 1 to 1
+              (and keeps defaults for other components)
+            - scenario 1 keeps the default values for all components
+            - scenario 2 sets the status of component with id 0 to 0 (and keeps defaults for other components)
+    """
+
+    indptr: IndexPointer
+    data: SingleColumnarData
+
+
+class SparseBatchArray(TypedDict):
+    """
+    A sparse batch array is a dictionary containing the keys `indptr` and `data`.
+
+    - data: a :class:`SingleArray`. The exact dtype depends on the type of component.
+    - indptr: an :class:`IndexPointer` representing the start and end indices for each batch scenario.
+
+    - Examples:
+
+        - structure: {"indptr": :class:`IndexPointer`, "data": :class:`SingleArray`}
+        - concrete example: {"indptr": [0, 2, 2, 3], "data": [(0, 1, 1), (1, 1, 1), (0, 0, 0)]}
+
+            - the scenario 0 sets the statuses of components with ids 0 and 1 to 1
+              (and keeps defaults for other components)
+            - scenario 1 keeps the default values for all components
+            - scenario 2 sets the statuses of component with id 0 to 0 (and keeps defaults for other components)
+    """
+
+    indptr: IndexPointer
+    data: SingleArray
+
+
+SparseBatchData = SparseBatchArray | SparseBatchColumnarData
+
+SparseDataComponentType: TypeAlias = str
+
+BatchColumnarData = DenseBatchColumnarData | SparseBatchColumnarData
+
+ColumnarData = SingleColumnarData | BatchColumnarData
+BatchArray = DenseBatchArray | SparseBatchArray
+
+
+BatchComponentData = BatchArray | BatchColumnarData
+
+_BatchComponentData = TypeVar("_BatchComponentData", BatchArray, BatchColumnarData)  # deduction helper
+
+
+BatchDataset = dict[ComponentTypeVar, _BatchComponentData]
+
+
+DataArray = SingleArray | BatchArray
+
+
+_ComponentData = TypeVar("_ComponentData", SingleComponentData, BatchComponentData)  # deduction helper
+ComponentData = DataArray | ColumnarData
+
+Dataset = dict[ComponentTypeVar, _ComponentData]
+
+
+DenseBatchData = DenseBatchArray | DenseBatchColumnarData
+
+NominalValue = int
+
+RealValue = float
+
+AsymValue = tuple[RealValue, RealValue, RealValue]
+
+AttributeValue = RealValue | NominalValue | AsymValue
+
+Component = dict[AttributeType, AttributeValue | str]
+
+ComponentList = list[Component]
+
+SinglePythonDataset = dict[ComponentTypeVar, ComponentList]
+
+BatchPythonDataset = list[SinglePythonDataset]
+
+PythonDataset = SinglePythonDataset | BatchPythonDataset