foamlib 0.2.9__py3-none-any.whl → 0.3.0__py3-none-any.whl

foamlib/__init__.py

@@ -1,9 +1,10 @@
 """A Python interface for interacting with OpenFOAM."""
 
-__version__ = "0.2.9"
+__version__ = "0.3.0"
 
 from ._cases import AsyncFoamCase, FoamCase, FoamCaseBase
-from ._dictionaries import FoamDictionaryBase, FoamFieldFile, FoamFile
+from ._files import FoamDict, FoamFieldFile, FoamFile
+from ._util import CalledProcessError
 
 __all__ = [
     "FoamCase",
@@ -11,5 +12,6 @@ __all__ = [
     "FoamCaseBase",
     "FoamFile",
     "FoamFieldFile",
-    "FoamDictionaryBase",
+    "FoamDict",
+    "CalledProcessError",
 ]

foamlib/_cases.py

@@ -27,8 +27,8 @@ else:
 
 import aioshutil
 
-from ._dictionaries import FoamFieldFile, FoamFile
-from ._util import CalledProcessError, is_sequence, run_process, run_process_async
+from ._files import FoamFieldFile, FoamFile
+from ._util import is_sequence, run_process, run_process_async
 
 
 class FoamCaseBase(Sequence["FoamCaseBase.TimeDirectory"]):
@@ -325,7 +325,7 @@ class FoamCase(FoamCaseBase):
         Clean this case.
 
         :param script: If True, use an (All)clean script if it exists. If False, ignore any clean scripts.
-        :param check: If True, raise a RuntimeError if the clean script returns a non-zero exit code.
+        :param check: If True, raise a CalledProcessError if the clean script returns a non-zero exit code.
         """
         script_path = self._clean_script() if script else None
 
@@ -349,24 +349,18 @@ class FoamCase(FoamCaseBase):
         :param cmd: The command to run. If None, run the case. If a sequence, the first element is the command and the rest are arguments. If a string, `cmd` is executed in a shell.
         :param script: If True and `cmd` is None, use an (All)run(-parallel) script if it exists for running the case. If False or no run script is found, autodetermine the command(s) needed to run the case.
         :param parallel: If True, run in parallel using MPI. If None, autodetect whether to run in parallel.
-        :param check: If True, raise a RuntimeError if any command returns a non-zero exit code.
+        :param check: If True, raise a CalledProcessError if any command returns a non-zero exit code.
         """
         if cmd is not None:
             if parallel:
                 cmd = self._parallel_cmd(cmd)
 
-            try:
-                run_process(
-                    cmd,
-                    check=check,
-                    cwd=self.path,
-                    env=self._env(),
-                )
-            except CalledProcessError as e:
-                raise RuntimeError(
-                    f"{e.cmd} failed with return code {e.returncode}\n{e.stderr}"
-                ) from None
-
+            run_process(
+                cmd,
+                check=check,
+                cwd=self.path,
+                env=self._env(),
+            )
         else:
             script_path = self._run_script(parallel=parallel) if script else None
 
@@ -485,7 +479,7 @@ class AsyncFoamCase(FoamCaseBase):
         Clean this case.
 
         :param script: If True, use an (All)clean script if it exists. If False, ignore any clean scripts.
-        :param check: If True, raise a RuntimeError if the clean script returns a non-zero exit code.
+        :param check: If True, raise a CalledProcessError if the clean script returns a non-zero exit code.
         """
         script_path = self._clean_script() if script else None
 
@@ -505,13 +499,13 @@ class AsyncFoamCase(FoamCaseBase):
         check: bool = True,
     ) -> None:
         """
-        Run this case.
+        Run this case, or a specified command in the context of this case.
 
         :param cmd: The command to run. If None, run the case. If a sequence, the first element is the command and the rest are arguments. If a string, `cmd` is executed in a shell.
         :param script: If True and `cmd` is None, use an (All)run(-parallel) script if it exists for running the case. If False or no run script is found, autodetermine the command(s) needed to run the case.
         :param parallel: If True, run in parallel using MPI. If None, autodetect whether to run in parallel.
         :param cpus: The number of CPUs to reserve for the run. The run will wait until the requested number of CPUs is available. If None, autodetect the number of CPUs to reserve.
-        :param check: If True, raise a RuntimeError if a command returns a non-zero exit code.
+        :param check: If True, raise a CalledProcessError if a command returns a non-zero exit code.
         """
         if cmd is not None:
             if cpus is None:
@@ -523,19 +517,13 @@ class AsyncFoamCase(FoamCaseBase):
             if parallel:
                 cmd = self._parallel_cmd(cmd)
 
-            try:
-                async with self._cpus(cpus):
-                    await run_process_async(
-                        cmd,
-                        check=check,
-                        cwd=self.path,
-                        env=self._env(),
-                    )
-            except CalledProcessError as e:
-                raise RuntimeError(
-                    f"{e.cmd} failed with return code {e.returncode}\n{e.stderr}"
-                ) from None
-
+            async with self._cpus(cpus):
+                await run_process_async(
+                    cmd,
+                    check=check,
+                    cwd=self.path,
+                    env=self._env(),
+                )
         else:
             script_path = self._run_script(parallel=parallel) if script else None
 

foamlib/_files/__init__.py

@@ -0,0 +1,9 @@
+from ._base import FoamDict
+from ._fields import FoamFieldFile
+from ._files import FoamFile
+
+__all__ = [
+    "FoamFile",
+    "FoamFieldFile",
+    "FoamDict",
+]

foamlib/{_dictionaries → _files}/_base.py

@@ -15,7 +15,7 @@ except ModuleNotFoundError:
     pass
 
 
-class FoamDictionaryBase:
+class FoamDict:
     class DimensionSet(NamedTuple):
         mass: Union[int, float] = 0
         length: Union[int, float] = 0
@@ -31,34 +31,32 @@ class FoamDictionaryBase:
     @dataclass
     class Dimensioned:
         value: Union[int, float, Sequence[Union[int, float]]] = 0
-        dimensions: Union[
-            "FoamDictionaryBase.DimensionSet", Sequence[Union[int, float]]
-        ] = ()
+        dimensions: Union["FoamDict.DimensionSet", Sequence[Union[int, float]]] = ()
         name: Optional[str] = None
 
         def __post_init__(self) -> None:
-            if not isinstance(self.dimensions, FoamDictionaryBase.DimensionSet):
-                self.dimensions = FoamDictionaryBase.DimensionSet(*self.dimensions)
+            if not isinstance(self.dimensions, FoamDict.DimensionSet):
+                self.dimensions = FoamDict.DimensionSet(*self.dimensions)
 
-    Value = Union[
+    Data = Union[
         str,
         int,
         float,
         bool,
         Dimensioned,
         DimensionSet,
-        Sequence["Value"],
-        Mapping[str, "Value"],
+        Sequence["Data"],
+        Mapping[str, "Data"],
     ]
     """
     A value that can be stored in an OpenFOAM dictionary.
     """
 
-    _Dict = Dict[str, Union["Value", "_Dict"]]
+    _Dict = Dict[str, Union["Data", "_Dict"]]
 
     @abstractmethod
     def as_dict(self) -> _Dict:
         """Return a nested dict representation of the dictionary."""
         raise NotImplementedError
 
-    _SetValue = Union[Value, "NDArray[np.generic]"]
+    _SetData = Union[Data, "NDArray[np.generic]"]

foamlib/_files/_fields.py

@@ -0,0 +1,158 @@
+import sys
+from typing import Any, Tuple, Union, cast
+
+if sys.version_info >= (3, 9):
+    from collections.abc import Sequence
+else:
+    from typing import Sequence
+
+from ._files import FoamFile
+
+try:
+    import numpy as np
+    from numpy.typing import NDArray
+except ModuleNotFoundError:
+    pass
+
+
+class FoamFieldFile(FoamFile):
+    """An OpenFOAM dictionary file representing a field as a mutable mapping."""
+
+    class BoundariesSubDict(FoamFile.SubDict):
+        def __getitem__(self, keyword: str) -> "FoamFieldFile.BoundarySubDict":
+            value = super().__getitem__(keyword)
+            if not isinstance(value, FoamFieldFile.BoundarySubDict):
+                assert not isinstance(value, FoamFile.SubDict)
+                raise TypeError(f"boundary {keyword} is not a dictionary")
+            return value
+
+    class BoundarySubDict(FoamFile.SubDict):
+        """An OpenFOAM dictionary representing a boundary condition as a mutable mapping."""
+
+        def __setitem__(
+            self,
+            keyword: str,
+            data: FoamFile._SetData,
+        ) -> None:
+            if keyword == "value":
+                self._setitem(keyword, data, assume_field=True)
+            else:
+                self._setitem(keyword, data)
+
+        @property
+        def type(self) -> str:
+            """Alias of `self["type"]`."""
+            ret = self["type"]
+            if not isinstance(ret, str):
+                raise TypeError("type is not a string")
+            return ret
+
+        @type.setter
+        def type(self, data: str) -> None:
+            self["type"] = data
+
+        @property
+        def value(
+            self,
+        ) -> Union[
+            int,
+            float,
+            Sequence[Union[int, float, Sequence[Union[int, float]]]],
+            "NDArray[np.generic]",
+        ]:
+            """Alias of `self["value"]`."""
+            ret = self["value"]
+            if not isinstance(ret, (int, float, Sequence)):
+                raise TypeError("value is not a field")
+            return cast(Union[int, float, Sequence[Union[int, float]]], ret)
+
+        @value.setter
+        def value(
+            self,
+            value: Union[
+                int,
+                float,
+                Sequence[Union[int, float, Sequence[Union[int, float]]]],
+                "NDArray[np.generic]",
+            ],
+        ) -> None:
+            self["value"] = value
+
+        @value.deleter
+        def value(self) -> None:
+            del self["value"]
+
+    def __getitem__(
+        self, keywords: Union[str, Tuple[str, ...]]
+    ) -> Union[FoamFile.Data, FoamFile.SubDict]:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        ret = super().__getitem__(keywords)
+        if keywords[0] == "boundaryField" and isinstance(ret, FoamFile.SubDict):
+            if len(keywords) == 1:
+                ret = FoamFieldFile.BoundariesSubDict(self, keywords)
+            elif len(keywords) == 2:
+                ret = FoamFieldFile.BoundarySubDict(self, keywords)
+        return ret
+
+    def __setitem__(self, keywords: Union[str, Tuple[str, ...]], value: Any) -> None:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        if keywords == ("internalField",):
+            self._setitem(keywords, value, assume_field=True)
+        elif keywords == ("dimensions",):
+            self._setitem(keywords, value, assume_dimensions=True)
+        else:
+            self._setitem(keywords, value)
+
+    @property
+    def dimensions(self) -> FoamFile.DimensionSet:
+        """Alias of `self["dimensions"]`."""
+        ret = self["dimensions"]
+        if not isinstance(ret, FoamFile.DimensionSet):
+            raise TypeError("dimensions is not a DimensionSet")
+        return ret
+
+    @dimensions.setter
+    def dimensions(
+        self, value: Union[FoamFile.DimensionSet, Sequence[Union[int, float]]]
+    ) -> None:
+        self["dimensions"] = value
+
+    @property
+    def internal_field(
+        self,
+    ) -> Union[
+        int,
+        float,
+        Sequence[Union[int, float, Sequence[Union[int, float]]]],
+        "NDArray[np.generic]",
+    ]:
+        """Alias of `self["internalField"]`."""
+        ret = self["internalField"]
+        if not isinstance(ret, (int, float, Sequence)):
+            raise TypeError("internalField is not a field")
+        return cast(Union[int, float, Sequence[Union[int, float]]], ret)
+
+    @internal_field.setter
+    def internal_field(
+        self,
+        value: Union[
+            int,
+            float,
+            Sequence[Union[int, float, Sequence[Union[int, float]]]],
+            "NDArray[np.generic]",
+        ],
+    ) -> None:
+        self["internalField"] = value
+
+    @property
+    def boundary_field(self) -> "FoamFieldFile.BoundariesSubDict":
+        """Alias of `self["boundaryField"]`."""
+        ret = self["boundaryField"]
+        if not isinstance(ret, FoamFieldFile.BoundariesSubDict):
+            assert not isinstance(ret, FoamFile.SubDict)
+            raise TypeError("boundaryField is not a dictionary")
+        return ret

foamlib/_files/_files.py

@@ -0,0 +1,203 @@
+import sys
+from typing import (
+    Any,
+    Tuple,
+    Union,
+)
+
+if sys.version_info >= (3, 9):
+    from collections.abc import Iterator, Mapping, MutableMapping
+else:
+    from typing import Iterator, Mapping, MutableMapping
+
+from ._base import FoamDict
+from ._io import FoamFileIO
+from ._serialization import serialize_keyword_entry
+
+
+class FoamFile(
+    FoamDict,
+    MutableMapping[
+        Union[str, Tuple[str, ...]], Union["FoamFile.Data", "FoamFile.SubDict"]
+    ],
+    FoamFileIO,
+):
+    """
+    An OpenFOAM dictionary file.
+
+    Use as a mutable mapping (i.e., like a dict) to access and modify entries.
+
+    Use as a context manager to make multiple changes to the file while saving all changes only once at the end.
+    """
+
+    class SubDict(
+        FoamDict,
+        MutableMapping[str, Union["FoamFile.Data", "FoamFile.SubDict"]],
+    ):
+        """An OpenFOAM dictionary within a file as a mutable mapping."""
+
+        def __init__(self, _file: "FoamFile", _keywords: Tuple[str, ...]) -> None:
+            self._file = _file
+            self._keywords = _keywords
+
+        def __getitem__(
+            self, keyword: str
+        ) -> Union["FoamFile.Data", "FoamFile.SubDict"]:
+            return self._file[(*self._keywords, keyword)]
+
+        def _setitem(
+            self,
+            keyword: str,
+            data: Any,
+            *,
+            assume_field: bool = False,
+            assume_dimensions: bool = False,
+        ) -> None:
+            self._file._setitem(
+                (*self._keywords, keyword),
+                data,
+                assume_field=assume_field,
+                assume_dimensions=assume_dimensions,
+            )
+
+        def __setitem__(self, keyword: str, value: "FoamFile._SetData") -> None:
+            self._setitem(keyword, value)
+
+        def __delitem__(self, keyword: str) -> None:
+            del self._file[(*self._keywords, keyword)]
+
+        def __iter__(self) -> Iterator[str]:
+            return self._file._iter(self._keywords)
+
+        def __contains__(self, keyword: object) -> bool:
+            return (*self._keywords, keyword) in self._file
+
+        def __len__(self) -> int:
+            return len(list(iter(self)))
+
+        def update(self, *args: Any, **kwargs: Any) -> None:
+            with self._file:
+                super().update(*args, **kwargs)
+
+        def clear(self) -> None:
+            with self._file:
+                super().clear()
+
+        def __repr__(self) -> str:
+            return f"{type(self).__qualname__}({self._file}, {self._keywords})"
+
+        def as_dict(self) -> FoamDict._Dict:
+            """Return a nested dict representation of the dictionary."""
+            ret = self._file.as_dict()
+
+            for k in self._keywords:
+                assert isinstance(ret, dict)
+                v = ret[k]
+                assert isinstance(v, dict)
+                ret = v
+
+            return ret
+
+    def __getitem__(
+        self, keywords: Union[str, Tuple[str, ...]]
+    ) -> Union["FoamFile.Data", "FoamFile.SubDict"]:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        _, parsed = self._read()
+
+        value = parsed[keywords]
+
+        if value is ...:
+            return FoamFile.SubDict(self, keywords)
+        else:
+            return value  # type: ignore [return-value]
+
+    def _setitem(
+        self,
+        keywords: Union[str, Tuple[str, ...]],
+        data: "FoamFile._SetData",
+        *,
+        assume_field: bool = False,
+        assume_dimensions: bool = False,
+    ) -> None:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        contents, parsed = self._read()
+
+        if isinstance(data, Mapping):
+            with self:
+                if isinstance(data, FoamDict):
+                    data = data.as_dict()
+
+                start, end = parsed.entry_location(keywords, missing_ok=True)
+
+                self._write(
+                    f"{contents[:start]}\n{serialize_keyword_entry(keywords[-1], {})}\n{contents[end:]}"
+                )
+
+                for k, v in data.items():
+                    self[(*keywords, k)] = v
+        else:
+            start, end = parsed.entry_location(keywords, missing_ok=True)
+
+            self._write(
+                f"{contents[:start]}\n{serialize_keyword_entry(keywords[-1], data, assume_field=assume_field, assume_dimensions=assume_dimensions)}\n{contents[end:]}"
+            )
+
+    def __setitem__(
+        self,
+        keywords: Union[str, Tuple[str, ...]],
+        data: "FoamFile._SetData",
+    ) -> None:
+        self._setitem(keywords, data)
+
+    def __delitem__(self, keywords: Union[str, Tuple[str, ...]]) -> None:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        contents, parsed = self._read()
+
+        start, end = parsed.entry_location(keywords)
+
+        self._write(contents[:start] + contents[end:])
+
+    def _iter(self, keywords: Union[str, Tuple[str, ...]] = ()) -> Iterator[str]:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        _, parsed = self._read()
+
+        yield from (k[-1] for k in parsed if k[:-1] == keywords)
+
+    def __iter__(self) -> Iterator[str]:
+        return self._iter()
+
+    def __contains__(self, keywords: object) -> bool:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+        _, parsed = self._read()
+        return keywords in parsed
+
+    def __len__(self) -> int:
+        return len(list(iter(self)))
+
+    def update(self, *args: Any, **kwargs: Any) -> None:
+        with self:
+            super().update(*args, **kwargs)
+
+    def clear(self) -> None:
+        with self:
+            super().clear()
+
+    def __fspath__(self) -> str:
+        return str(self.path)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.path})"
+
+    def as_dict(self) -> FoamDict._Dict:
+        """Return a nested dict representation of the file."""
+        _, parsed = self._read()
+        return parsed.as_dict()

foamlib/_files/_io.py

@@ -0,0 +1,73 @@
+import sys
+from copy import deepcopy
+from pathlib import Path
+from types import TracebackType
+from typing import (
+    Optional,
+    Tuple,
+    Type,
+    Union,
+)
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+from ._parsing import Parsed
+
+
+class FoamFileIO:
+    def __init__(self, path: Union[str, Path]) -> None:
+        self.path = Path(path).absolute()
+        if self.path.is_dir():
+            raise IsADirectoryError(self.path)
+        elif not self.path.is_file():
+            raise FileNotFoundError(self.path)
+
+        self.__contents: Optional[str] = None
+        self.__parsed: Optional[Parsed] = None
+        self.__defer_io = 0
+        self.__dirty = False
+
+    def __enter__(self) -> Self:
+        if self.__defer_io == 0:
+            self._read()
+        self.__defer_io += 1
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        self.__defer_io -= 1
+        if self.__defer_io == 0 and self.__dirty:
+            assert self.__contents is not None
+            self._write(self.__contents)
+        assert not self.__dirty
+
+    def _read(self) -> Tuple[str, Parsed]:
+        if not self.__defer_io:
+            contents = self.path.read_text()
+            if contents != self.__contents:
+                self.__contents = contents
+                self.__parsed = None
+
+        assert self.__contents is not None
+
+        if self.__parsed is None:
+            parsed = Parsed(self.__contents)
+            self.__parsed = parsed
+
+        return self.__contents, deepcopy(self.__parsed)
+
+    def _write(self, contents: str) -> None:
+        self.__contents = contents
+        self.__parsed = None
+        if not self.__defer_io:
+            self.path.write_text(contents)
+            self.__dirty = False
+        else:
+            self.__dirty = True