foamlib 0.2.2__tar.gz → 0.2.4__tar.gz

{foamlib-0.2.2 → foamlib-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: foamlib
-Version: 0.2.2
+Version: 0.2.4
 Summary: A Python interface for interacting with OpenFOAM
 Author-email: "Gabriel S. Gerlero" <ggerlero@cimec.unl.edu.ar>
 Project-URL: Homepage, https://github.com/gerlero/foamlib
@@ -27,6 +27,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: aioshutil<2,>=1
 Requires-Dist: pyparsing<4,>=3
+Requires-Dist: typing-extensions<5,>=4
 Provides-Extra: lint
 Requires-Dist: mypy<2,>=1; extra == "lint"
 Requires-Dist: pytest<9,>=7; extra == "lint"

{foamlib-0.2.2 → foamlib-0.2.4}/foamlib/__init__.py

@@ -1,7 +1,7 @@
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 from ._cases import FoamCase, AsyncFoamCase, FoamCaseBase
-from ._dictionaries import FoamFile, FoamFieldFile
+from ._dictionaries import FoamFile, FoamFieldFile, FoamDictionaryBase
 
 __all__ = [
     "FoamCase",
@@ -9,4 +9,5 @@ __all__ = [
     "FoamCaseBase",
     "FoamFile",
     "FoamFieldFile",
+    "FoamDictionaryBase",
 ]

foamlib-0.2.4/foamlib/_dictionaries/__init__.py

@@ -0,0 +1,8 @@
+from ._files import FoamFile, FoamFieldFile
+from ._base import FoamDictionaryBase
+
+__all__ = [
+    "FoamFile",
+    "FoamFieldFile",
+    "FoamDictionaryBase",
+]

foamlib-0.2.4/foamlib/_dictionaries/_base.py

@@ -0,0 +1,43 @@
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Dict, NamedTuple, Optional, Sequence, Union
+
+
+class FoamDictionaryBase:
+    class DimensionSet(NamedTuple):
+        mass: Union[int, float] = 0
+        length: Union[int, float] = 0
+        time: Union[int, float] = 0
+        temperature: Union[int, float] = 0
+        moles: Union[int, float] = 0
+        current: Union[int, float] = 0
+        luminous_intensity: Union[int, float] = 0
+
+        def __repr__(self) -> str:
+            return f"{type(self).__qualname__}({', '.join(f'{n}={v}' for n, v in zip(self._fields, self) if v != 0)})"
+
+    @dataclass
+    class Dimensioned:
+        value: Union[int, float, Sequence[Union[int, float]]] = 0
+        dimensions: Union[
+            "FoamDictionaryBase.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)
+
+    Value = Union[str, int, float, bool, Dimensioned, DimensionSet, Sequence["Value"]]
+    """
+    A value that can be stored in an OpenFOAM dictionary.
+    """
+
+    _Dict = Dict[str, Union["FoamDictionaryBase.Value", "_Dict"]]
+
+    @abstractmethod
+    def as_dict(self) -> _Dict:
+        """
+        Return a nested dict representation of the dictionary.
+        """
+        raise NotImplementedError

foamlib-0.2.4/foamlib/_dictionaries/_files.py

@@ -0,0 +1,410 @@
+from pathlib import Path
+from typing import (
+    Any,
+    Iterator,
+    Mapping,
+    MutableMapping,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+    cast,
+)
+
+from typing_extensions import Self
+
+from ._base import FoamDictionaryBase
+from ._parsing import Parsed, as_dict, get_entry_locn, get_value, parse
+from ._serialization import serialize_entry
+
+try:
+    import numpy as np
+    from numpy.typing import NDArray
+except ModuleNotFoundError:
+    pass
+
+
+class _FoamFileBase:
+    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: Any, exc_value: Any, traceback: Any) -> 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:
+            self.__parsed = parse(self.__contents)
+
+        return self.__contents, 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
+
+
+class FoamFile(
+    _FoamFileBase,
+    FoamDictionaryBase,
+    MutableMapping[
+        Union[str, Tuple[str, ...]], Union["FoamFile.Value", "FoamFile.Dictionary"]
+    ],
+):
+    """
+    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 Dictionary(
+        FoamDictionaryBase,
+        MutableMapping[str, Union["FoamFile.Value", "FoamFile.Dictionary"]],
+    ):
+        """
+        An OpenFOAM dictionary within a file as a mutable mapping.
+        """
+
+        def __init__(self, _file: "FoamFile", _keywords: Sequence[str]) -> None:
+            self._file = _file
+            self._keywords = _keywords
+
+        def __getitem__(
+            self, keyword: str
+        ) -> Union["FoamFile.Value", "FoamFile.Dictionary"]:
+            return self._file[(*self._keywords, keyword)]
+
+        def _setitem(
+            self,
+            keyword: str,
+            value: Any,
+            *,
+            assume_field: bool = False,
+            assume_dimensions: bool = False,
+        ) -> None:
+            self._file._setitem(
+                (*self._keywords, keyword),
+                value,
+                assume_field=assume_field,
+                assume_dimensions=assume_dimensions,
+            )
+
+        def __setitem__(self, keyword: str, value: Any) -> 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(tuple(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) -> FoamDictionaryBase._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.Value", "FoamFile.Dictionary"]:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        _, parsed = self._read()
+
+        value = get_value(parsed, keywords)
+
+        if value is None:
+            return FoamFile.Dictionary(self, keywords)
+        else:
+            return value
+
+    def _setitem(
+        self,
+        keywords: Union[str, Tuple[str, ...]],
+        value: Any,
+        *,
+        assume_field: bool = False,
+        assume_dimensions: bool = False,
+    ) -> None:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        contents, parsed = self._read()
+
+        if isinstance(value, Mapping):
+            with self:
+                if isinstance(value, FoamDictionaryBase):
+                    value = value.as_dict()
+
+                start, end = get_entry_locn(parsed, keywords, missing_ok=True)
+
+                self._write(
+                    f"{contents[:start]}\n{serialize_entry(keywords[-1], {})}\n{contents[end:]}"
+                )
+
+                for k, v in value.items():
+                    self[(*keywords, k)] = v
+        else:
+            start, end = get_entry_locn(parsed, keywords, missing_ok=True)
+
+            self._write(
+                f"{contents[:start]}\n{serialize_entry(keywords[-1], value, assume_field=assume_field, assume_dimensions=assume_dimensions)}\n{contents[end:]}"
+            )
+
+    def __setitem__(self, keywords: Union[str, Tuple[str, ...]], value: Any) -> None:
+        self._setitem(keywords, value)
+
+    def __delitem__(self, keywords: Union[str, Tuple[str, ...]]) -> None:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        contents, parsed = self._read()
+
+        start, end = get_entry_locn(parsed, keywords)
+
+        self._write(contents[:start] + contents[end:])
+
+    def _iter(self, keywords: Union[str, Tuple[str, ...]] = ()) -> Iterator[str]:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        contents = self.path.read_text()
+        parsed = parse(contents)
+
+        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) -> FoamDictionaryBase._Dict:
+        """
+        Return a nested dict representation of the file.
+        """
+        _, parsed = self._read()
+        return as_dict(parsed)
+
+
+class FoamFieldFile(FoamFile):
+    """An OpenFOAM dictionary file representing a field as a mutable mapping."""
+
+    class BoundariesDictionary(FoamFile.Dictionary):
+        def __getitem__(self, keyword: str) -> "FoamFieldFile.BoundaryDictionary":
+            return cast(FoamFieldFile.BoundaryDictionary, super().__getitem__(keyword))
+
+    class BoundaryDictionary(FoamFile.Dictionary):
+        """An OpenFOAM dictionary representing a boundary condition as a mutable mapping."""
+
+        def __setitem__(self, key: str, value: Any) -> None:
+            if key == "value":
+                self._setitem(key, value, assume_field=True)
+            else:
+                self._setitem(key, value)
+
+        @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, value: str) -> None:
+            self["type"] = value
+
+        @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.Value, FoamFile.Dictionary]:
+        if not isinstance(keywords, tuple):
+            keywords = (keywords,)
+
+        ret = super().__getitem__(keywords)
+        if keywords[0] == "boundaryField" and isinstance(ret, FoamFile.Dictionary):
+            if len(keywords) == 1:
+                ret = FoamFieldFile.BoundariesDictionary(self, keywords)
+            elif len(keywords) == 2:
+                ret = FoamFieldFile.BoundaryDictionary(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.BoundariesDictionary":
+        """
+        Alias of `self["boundaryField"]`.
+        """
+        ret = self["boundaryField"]
+        if not isinstance(ret, FoamFieldFile.BoundariesDictionary):
+            assert not isinstance(ret, FoamFile.Dictionary)
+            raise TypeError("boundaryField is not a dictionary")
+        return ret

foamlib-0.2.4/foamlib/_dictionaries/_parsing.py

@@ -0,0 +1,177 @@
+from typing import Mapping, MutableMapping, Optional, Sequence, Tuple
+
+from pyparsing import (
+    Dict,
+    Forward,
+    Group,
+    Keyword,
+    LineEnd,
+    Literal,
+    Located,
+    Opt,
+    ParseResults,
+    ParserElement,
+    QuotedString,
+    Word,
+    c_style_comment,
+    common,
+    cpp_style_comment,
+    identbodychars,
+    printables,
+)
+
+from ._base import FoamDictionaryBase
+
+_YES = Keyword("yes").set_parse_action(lambda: True)
+_NO = Keyword("no").set_parse_action(lambda: False)
+_DIMENSIONS = (
+    Literal("[").suppress() + common.number * 7 + Literal("]").suppress()
+).set_parse_action(lambda tks: FoamDictionaryBase.DimensionSet(*tks))
+
+
+def _list_of(elem: ParserElement) -> ParserElement:
+    return Opt(
+        Literal("List") + Literal("<") + common.identifier + Literal(">")
+    ).suppress() + (
+        (
+            Opt(common.integer).suppress()
+            + (
+                Literal("(").suppress()
+                + Group((elem)[...], aslist=True)
+                + Literal(")").suppress()
+            )
+        )
+        | (
+            common.integer + Literal("{").suppress() + elem + Literal("}").suppress()
+        ).set_parse_action(lambda tks: [[tks[1]] * tks[0]])
+    )
+
+
+_TENSOR = _list_of(common.number) | common.number
+_IDENTIFIER = Word(identbodychars + "$", printables.replace(";", ""))
+_DIMENSIONED = (Opt(_IDENTIFIER) + _DIMENSIONS + _TENSOR).set_parse_action(
+    lambda tks: FoamDictionaryBase.Dimensioned(*reversed(tks.as_list()))
+)
+_FIELD = (Keyword("uniform").suppress() + _TENSOR) | (
+    Keyword("nonuniform").suppress() + _list_of(_TENSOR)
+)
+_TOKEN = QuotedString('"', unquote_results=False) | _IDENTIFIER
+_ITEM = Forward()
+_LIST = _list_of(_ITEM)
+_ITEM <<= (
+    _FIELD | _LIST | _DIMENSIONED | _DIMENSIONS | common.number | _YES | _NO | _TOKEN
+)
+_TOKENS = (
+    QuotedString('"', unquote_results=False) | Word(printables.replace(";", ""))
+)[2, ...].set_parse_action(lambda tks: " ".join(tks))
+
+_VALUE = _ITEM ^ _TOKENS
+
+_ENTRY = Forward()
+_DICTIONARY = Dict(Group(_ENTRY)[...])
+_ENTRY <<= Located(
+    _TOKEN
+    + (
+        (Literal("{").suppress() + _DICTIONARY + Literal("}").suppress())
+        | (Opt(_VALUE, default="") + Literal(";").suppress())
+    )
+)
+_FILE = (
+    _DICTIONARY.ignore(c_style_comment)
+    .ignore(cpp_style_comment)
+    .ignore(Literal("#include") + ... + LineEnd())  # type: ignore [no-untyped-call]
+)
+
+Parsed = Mapping[Sequence[str], Tuple[int, Optional[FoamDictionaryBase.Value], int]]
+
+
+def _flatten_result(
+    parse_result: ParseResults, *, _keywords: Sequence[str] = ()
+) -> Parsed:
+    ret: MutableMapping[
+        Sequence[str], Tuple[int, Optional[FoamDictionaryBase.Value], int]
+    ] = {}
+    start = parse_result.locn_start
+    assert isinstance(start, int)
+    item = parse_result.value
+    assert isinstance(item, Sequence)
+    end = parse_result.locn_end
+    assert isinstance(end, int)
+    key, *values = item
+    assert isinstance(key, str)
+    ret[(*_keywords, key)] = (start, None, end)
+    for value in values:
+        if isinstance(value, ParseResults):
+            ret.update(_flatten_result(value, _keywords=(*_keywords, key)))
+        else:
+            ret[(*_keywords, key)] = (start, value, end)
+    return ret
+
+
+def parse(
+    contents: str,
+) -> Parsed:
+    parse_results = _FILE.parse_string(contents, parse_all=True)
+    ret: MutableMapping[
+        Sequence[str], Tuple[int, Optional[FoamDictionaryBase.Value], int]
+    ] = {}
+    for parse_result in parse_results:
+        ret.update(_flatten_result(parse_result))
+    return ret
+
+
+def get_value(
+    parsed: Parsed,
+    keywords: Tuple[str, ...],
+) -> Optional[FoamDictionaryBase.Value]:
+    """
+    Value of an entry.
+    """
+    _, value, _ = parsed[keywords]
+    return value
+
+
+def get_entry_locn(
+    parsed: Parsed,
+    keywords: Tuple[str, ...],
+    *,
+    missing_ok: bool = False,
+) -> Tuple[int, int]:
+    """
+    Location of an entry or where it should be inserted.
+    """
+    try:
+        start, _, end = parsed[keywords]
+    except KeyError:
+        if missing_ok:
+            if len(keywords) > 1:
+                _, _, end = parsed[keywords[:-1]]
+                end -= 1
+            else:
+                end = -1
+
+            start = end
+        else:
+            raise
+
+    return start, end
+
+
+def as_dict(parsed: Parsed) -> FoamDictionaryBase._Dict:
+    """
+    Return a nested dict representation of the file.
+    """
+    ret: FoamDictionaryBase._Dict = {}
+    for keywords, (_, value, _) in parsed.items():
+
+        r = ret
+        for k in keywords[:-1]:
+            assert isinstance(r, dict)
+            v = r[k]
+            assert isinstance(v, dict)
+            r = v
+
+        assert isinstance(r, dict)
+        r[keywords[-1]] = {} if value is None else value
+
+    return ret