ansys-bdm-api 0.5.dev0__py3-none-any.whl

ansys/bdm/api/istorage_scope_factory.py

@@ -0,0 +1,135 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Protocol
+
+from ansys.bdm.api.iasync_storage_scope import (
+    IAsyncReadStorageScope,
+    IAsyncStorageScope,
+)
+from ansys.bdm.api.istorage_scope import IReadStorageScope, IStorageScope
+
+
+class IReadStorageScopeFactory(Protocol):
+    """
+    Factory pattern for creating instances of IReadStorageScope and IAsyncReadStorageScope.
+    """
+
+    def create_storage_scope(
+        self,
+        context: str,
+        template_vars: dict[str, str],
+    ) -> IReadStorageScope:
+        """
+        Create a new read only storage scope.
+
+        Parameters
+        ----------
+        context: str
+            TODO: How to word what this genericaly does.
+        template_vars: Dict[str, str]
+            Template variables that may be used by the configuration system \
+            to return an appropriate :class:`IStorageScope`. TODO: Define whether certain fields \
+            need to be passed in?
+
+        Returns
+        -------
+        IReadStorageScope
+            A configured and ready to use :class:`IReadStorageScope`
+        """
+        # deliberately not implemented
+        ...
+
+    async def create_async_storage_scope(
+        self,
+        context: str,
+        template_vars: dict[str, str],
+    ) -> IAsyncReadStorageScope:
+        """
+        Create a new asynchronous read only storage scope.
+
+        Parameters
+        ----------
+        context: str
+            TODO: How to word what this genericaly does.
+        template_vars: Dict[str, str]
+            Template variables that may be used by the configuration system \
+            to return an appropriate :class:`IAsyncStorageScope`. TODO: Define whether certain fields \
+            need to be passed in?
+
+        Returns
+        -------
+        IAsyncReadStorageScope
+            A configured and ready to use :class:`IAsyncReadStorageScope`
+        """
+        # deliberately not implemented
+        ...
+
+
+class IStorageScopeFactory(IReadStorageScopeFactory, Protocol):
+    """
+    Factory pattern for creating instances of IStorageScope and IAsyncStorageScope.
+    """
+
+    def create_storage_scope(
+        self,
+        context: str,
+        template_vars: dict[str, str],
+    ) -> IStorageScope:
+        """
+        Create a new storage scope.
+
+        Parameters
+        ----------
+        context: str
+            TODO: How to word what this genericaly does.
+        template_vars: Dict[str, str]
+            Template variables that may be used by the configuration system \
+            to return an appropriate :class:`IStorageScope`. TODO: Define whether certain fields \
+            need to be passed in?
+
+        Returns
+        -------
+        IStorageScope
+            A configured and ready to use :class:`IStorageScope`
+        """
+        # deliberately not implemented
+        ...
+
+    async def create_async_storage_scope(
+        self,
+        context: str,
+        template_vars: dict[str, str],
+    ) -> IAsyncStorageScope:
+        """
+        Create a new asynchronous storage scope.
+
+        Parameters
+        ----------
+        context: str
+            TODO: How to word what this genericaly does.
+        template_vars: Dict[str, str]
+            Template variables that may be used by the configuration system \
+            to return an appropriate :class:`IAsyncStorageScope`. TODO: Define whether certain fields \
+            need to be passed in?
+
+        Returns
+        -------
+        IAsyncStorageScope
+            A configured and ready to use :class:`IAsyncStorageScope`
+        """
+        # deliberately not implemented
+        ...

ansys/bdm/api/recursive_dictionary.py

@@ -0,0 +1,132 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import re
+from typing import Any
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+
+from ansys.bdm.api.entity_handle import EntityHandle
+
+
+class RecursiveDictionaryOfEntityHandles(
+    dict[str, "EntityHandle | RecursiveDictionaryOfEntityHandles"],
+):
+    """A recursive dictionary structure for storing entity handles in a nested hierarchy that maps a filesystem-like
+    directory structure."""
+
+    # Defining it as a class instead of a type, in case in the future we want to add methods that operate on the
+    # recursive dict (e.g., filter) and don't require the storage scope.
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        source_type: Any,
+        handler: GetCoreSchemaHandler,
+    ) -> CoreSchema:
+        """Generate Pydantic core schema to be able to serialize/deserialize this structure with Pydantic.
+
+        We cannot use a simple:
+        > return core_schema.no_info_after_validator_function(cls, handler(dict))
+        because it would not instantiate the nested EntityHandles, leaving them as plain dictionaries.
+        """
+        entity_handle_schema = handler.generate_schema(EntityHandle)
+
+        dict_schema = core_schema.dict_schema(
+            keys_schema=core_schema.str_schema(),
+            values_schema=core_schema.union_schema(
+                [
+                    entity_handle_schema,
+                    core_schema.definition_reference_schema(
+                        "RecursiveDictionaryOfEntityHandles",
+                    ),
+                ],
+            ),
+        )
+
+        validated_schema = core_schema.no_info_after_validator_function(
+            cls,
+            dict_schema,
+        )
+
+        return core_schema.definitions_schema(
+            schema=validated_schema,
+            definitions=[
+                core_schema.dict_schema(
+                    keys_schema=core_schema.str_schema(),
+                    values_schema=core_schema.union_schema(
+                        [
+                            entity_handle_schema,
+                            core_schema.definition_reference_schema(
+                                "RecursiveDictionaryOfEntityHandles",
+                            ),
+                        ],
+                    ),
+                    ref="RecursiveDictionaryOfEntityHandles",
+                ),
+            ],
+        )
+
+
+def get_and_create_nested_dict(
+    parts: tuple[str, ...],
+    value: RecursiveDictionaryOfEntityHandles,
+) -> RecursiveDictionaryOfEntityHandles:
+    if not parts:
+        return value
+    if parts[0] not in value:
+        value[parts[0]] = RecursiveDictionaryOfEntityHandles()
+
+    # Ensure the value at parts[0] is a RecursiveDictionaryOfEntityHandles
+    nested_value = value[parts[0]]
+    if not isinstance(nested_value, RecursiveDictionaryOfEntityHandles):
+        # If it's an EntityHandle, we need to convert it to a nested dict
+        # This shouldn't normally happen in correct usage, but we handle it for type safety
+        nested_value = RecursiveDictionaryOfEntityHandles()
+        value[parts[0]] = nested_value
+
+    return get_and_create_nested_dict(
+        parts[1:],
+        nested_value,
+    )
+
+
+def validate_path_component(name: str) -> None:
+    """Validate that a string is suitable for use as a file or directory name."""
+    # Would be great if we could validate at assign or construction time, e.g.,:
+    # > my_dict['invalid/string'] = my_entity
+    # or
+    # > my_dict = RecursiveDictionaryOfEntityHandles({'invalid/string': my_entity})
+    # but given the definition of RecursiveDictionaryOfEntityHandles, we are left with validation only within
+    # get_copy_from_dictionary()
+
+    if not name or not name.strip():
+        raise ValueError("Path component cannot be empty")
+    if name in (".", ".."):  # special names for current and parent directory
+        raise ValueError(f"Path component cannot be '{name}'")
+    if name.endswith((".", " ")):  # Windows rule
+        raise ValueError(f"Path component '{name}' cannot end with a dot or space")
+
+    # Check for invalid characters
+    # - Windows: < > : " / \\ | ? * and control characters (0-31)
+    # - Linux: / and null character
+    invalid_chars = r'[<>:"/\\|?*\x00-\x1f]'
+    if re.search(invalid_chars, name):
+        raise ValueError(
+            f"Path component '{name}' contains invalid characters. "
+            f'The following characters are not allowed: < > : " / \\ | ? * and control characters',
+        )

ansys/bdm/api/storage_exceptions.py

@@ -0,0 +1,45 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+class NotFoundInLocalStorageRootError(Exception):
+    """Exception raised when attempting to access object that doesn't exist within the local storage root."""
+
+
+class EntityNotFoundInBlobStorageError(Exception):
+    """Exception raised when attempting to access entity using handle where the referenced entity does not exist."""
+
+
+class CannotGenerateStreamForDirectoryError(Exception):
+    """Exception raised when attempting to generate a stream for a directory entity."""
+
+
+class EntityWriterHasNotCompletedWritingDataError(Exception):
+    """Exception raised when attempting to get handle from EntityWriter before the writing context is closed."""
+
+
+class EntityWriterIsNotWritingDataError(Exception):
+    """Exception raised when attempting to access stream from EntityWriter
+    after the writing context is closed or before it is opened."""
+
+
+class EntityWriterHasWrittenDataError(Exception):
+    """Exception raised when attempting to write to stream from EntityWriter
+    after the writing context is closed."""
+
+
+class InvalidContextError(Exception):
+    """Exception raised when unknown context when creating a scope."""

ansys/bdm/base/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

ansys/bdm/base/base_async_storage_scope.py

@@ -0,0 +1,92 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from anyio import EndOfStream
+
+from ansys.bdm.api.entity_handle import EntityHandle
+from ansys.bdm.api.iasync_storage_scope import IAsyncStorageScope
+from ansys.bdm.base.encoder import encode_text
+
+
+class AsyncStorageScopeBase(IAsyncStorageScope):
+    """
+    A partial implementation of ``IAsyncStorageScope`` that provides implementations
+    of some methods based on other more fundamental methods.  ``AsyncStorageScopeBase``
+    can be used as a base class for implementations of ``IAsyncStorageScope``.
+
+    """
+
+    async def get_bytes(self, entity: EntityHandle) -> bytes:
+        """
+        Return the content of the referenced blob.
+
+        Parameters
+        ----------
+        entity: EntityHandle
+            The handle to the data to realize
+
+        Returns
+        -------
+        bytes
+            the contents of the EntityHandle.
+
+        Raises
+        ------
+
+        CannotGenerateStreamForDirectoryError
+            If the entity requested is a collection
+        """
+        stream = await self.get_stream(entity)
+        result = bytearray()
+        while True:
+            try:
+                data = await stream.receive()
+                result.extend(data)
+            except EndOfStream:
+                break
+        return bytes(result)
+
+    async def get_text(self, entity: EntityHandle, encoding: str | None = None) -> str:
+        """
+        Return the content of the referenced blob.
+
+        Parameters
+        ----------
+        entity: EntityHandle
+            The handle to the data to realize
+        encoding: Optional[str]
+            The name of an encoding.  When this argument is not None the bytes
+            of ``entity`` will be read using that encoding.
+
+        Returns
+        -------
+        str
+            the contents of the blob referenced by ``entity`` in text form with the encoding determined
+            in order of preference:
+            - the encoding argument if not None
+            - the encoding field of the entity argument if set
+            - the BOM of the referenced entity if it contains one; or
+            - UTF-8
+
+        Raises
+        ------
+
+        CannotGenerateStreamForDirectoryError
+            If the entity requested is a collection
+        """
+
+        data = await self.get_bytes(entity)
+        return encode_text(data, entity, encoding)

ansys/bdm/base/base_storage_scope.py

@@ -0,0 +1,80 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from ansys.bdm.api.entity_handle import EntityHandle
+from ansys.bdm.api.istorage_scope import IStorageScope
+from ansys.bdm.base.encoder import encode_text
+
+
+class StorageScopeBase(IStorageScope):
+    """
+    A partial implementation of ``IStorageScope`` that provides implementations
+    of some methods based on other more fundamental methods.  ``StorageScopeBase``
+    can be used as a base class for implementations of ``IStorageScope``.
+
+    """
+
+    def get_bytes(self, entity: EntityHandle) -> bytes:
+        """
+        Return the content of the referenced blob.
+
+        Parameters
+        ----------
+        entity: EntityHandle
+            The handle to the data to realize
+
+        Returns
+        -------
+        bytes
+            the contents of the EntityHandle.
+
+        Raises
+        ------
+
+        CannotGenerateStreamForDirectoryError
+            If the entity requested is a collection
+        """
+        return self.get_stream(entity).readall()
+
+    def get_text(self, entity: EntityHandle, encoding: str | None = None) -> str:
+        """
+        Return the content of the referenced blob.
+
+        Parameters
+        ----------
+        entity: EntityHandle
+            The handle to the data to realize
+        encoding: Optional[str]
+            The name of an encoding.  When this argument is not None the bytes
+            of ``entity`` will be read using that encoding.
+
+        Returns
+        -------
+        str
+            the contents of the EntityHandle in text form with the encoding determined
+            in order of preference:
+            - the encoding argument if not None
+            - the encoding field of the entity argument if set
+            - the BOM of the referenced entity if it contains one; or
+            - UTF-8
+
+        Raises
+        ------
+
+        CannotGenerateStreamForDirectoryError
+            If the entity requested is a collection
+        """
+        return encode_text(self.get_bytes(entity), entity, encoding)

ansys/bdm/base/encoder.py

@@ -0,0 +1,89 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from ansys.bdm.api.entity_handle import EntityHandle
+
+
+def decode_bom(bom: bytes) -> tuple[str | None, int]:
+    """
+    Return a tuple consisting of
+    1) the name of the encoding stored in the BOM prefix of the given byte data; and
+    2) the length of BOM in bytes.
+
+    If the byte data does not contain a BOM then a tuple ``(None, 0)`` is returned.
+
+    Parameters
+    ----------
+    bom: bytes
+        byte data that may or may not be prefixed with a BOM
+
+    Returns
+    -------
+    Tuple[Optional[str], int]
+        a tuple consisting of
+        1) the name of the encoding stored in the BOM prefix of the given byte data; and
+        2) the length of BOM in bytes.
+
+        If the byte data does not contain a BOM then a tuple ``(None, 0)`` is returned.
+    """
+    if bom[0] == 0xEF and bom[1] == 0xBB and bom[2] == 0xBF:
+        return ("utf-8", 3)
+    if bom[0] == 0xFF and bom[1] == 0xFE and bom[2] == 0 and bom[3] == 0:
+        return ("utf-32-le", 4)
+    if bom[0] == 0xFF and bom[1] == 0xFE:
+        return ("utf-16-le", 2)
+    if bom[0] == 0xFE and bom[1] == 0xFF:
+        return ("utf-16-be", 2)
+    if bom[0] == 0 and bom[1] == 0 and bom[2] == 0xFE and bom[3] == 0xFF:
+        return ("utf-32-be", 4)
+    return (None, 0)
+
+
+def encode_text(data: bytes, handle: EntityHandle, encoding: str | None = None) -> str:
+    """
+    Return a string which is derived from the given byte data
+
+    Parameters
+    ----------
+    data: bytes
+        byte data that may or may not be prefixed with a BOM that provides the data for the returned string
+    handle: EntityHandle
+        the entity handle that refers to the object that contains the given data
+    encoding: Optional[str]
+        The name of an encoding.  When this argument is not None the returned
+        string will be decoded using the given encoding.
+
+    Returns
+    -------
+    str
+        a string containing the byte data with the encoding determined
+        in order of preference by:
+        - the encoding argument if not None
+        - the encoding field of the entity argument if set
+        - the BOM of the referenced entity if it contains one; or
+        - UTF-8
+    """
+    if encoding is None:
+        if handle.encoding is not None:
+            encoding = handle.encoding
+        else:
+            encoding, bom_length = decode_bom(data)
+
+            if encoding is not None:
+                data = data[bom_length:]
+            else:
+                encoding = "utf-8"
+    return str(data, encoding=encoding)