Dev 2.5.0

docs/pages/api-reference.md

@@ -79,7 +79,7 @@ Datastructures not in the standard library.
 Implements: `RingList`, `merge_dicts`
 
 
-## `RingList` Objects
+### `RingList` Objects
 
 ```python
 class RingList()
@@ -176,7 +176,7 @@ Decorators that can be used wrap functions.
 Implements: `with_filelock`
 
 
-## `with_filelock` Objects
+### `with_filelock` Objects
 
 ```python
 class with_filelock()
@@ -216,12 +216,12 @@ Functions for interacting with EM27 interferograms.
 
 Implements: `detect_corrupt_opus_files`, `load_proffast2_result`.
 
-This requires you to install this utils library with the optional `polars` dependency:
+This requires you to install this utils library with the optional `em27` dependency:
 
 ```bash
-pip install "tum_esm_utils[polars]"
+pip install "tum_esm_utils[em27]"
 ## `or`
-pdm add "tum_esm_utils[polars]"
+pdm add "tum_esm_utils[em27]"
 ```
 
 
@@ -353,6 +353,60 @@ Implements: `load_file`, `dump_file`, `load_json_file`,
 `expect_file_contents`, `render_directory_tree`, `list_directory`
 
 
+##### `load_file`
+
+```python
+def load_file(path: str) -> str
+```
+
+Load the content of a file.
+
+
+##### `dump_file`
+
+```python
+def dump_file(path: str, content: str) -> None
+```
+
+Dump content to a file.
+
+
+##### `load_binary_file`
+
+```python
+def load_binary_file(path: str) -> bytes
+```
+
+Load binary content of a file.
+
+
+##### `dump_binary_file`
+
+```python
+def dump_binary_file(path: str, content: bytes) -> None
+```
+
+Dump binary content to a file.
+
+
+##### `load_json_file`
+
+```python
+def load_json_file(path: str) -> Any
+```
+
+Load the content of a JSON file.
+
+
+##### `dump_json_file`
+
+```python
+def dump_json_file(path: str, content: Any, indent: Optional[int] = 4) -> None
+```
+
+Dump content to a JSON file.
+
+
 ##### `get_parent_dir_path`
 
 ```python
@@ -641,11 +695,14 @@ Add a subplot to a figure.
 
 ```python
 def add_colorpatch_legend(fig: plt.Figure,
-                          handles: list[tuple[str, Union[
+                          handles: list[tuple[
                               str,
-                              tuple[float, float, float],
-                              tuple[float, float, float, float],
-                          ]]],
+                              Union[
+                                  str,
+                                  tuple[float, float, float],
+                                  tuple[float, float, float, float],
+                              ],
+                          ]],
                           ncols: Optional[int] = None,
                           location: str = "upper left") -> None
 ```
@@ -740,7 +797,7 @@ Implements: `run_shell_command`, `CommandLineException`,
 `get_hostname`, `get_commit_sha`, `change_file_permissions`
 
 
-## `CommandLineException` Objects
+### `CommandLineException` Objects
 
 ```python
 class CommandLineException(Exception)
@@ -1040,7 +1097,7 @@ or "hello   world" -> "hello world").
   The string with duplicate characters replaced.
 
 
-## `RandomLabelGenerator` Objects
+### `RandomLabelGenerator` Objects
 
 ```python
 class RandomLabelGenerator()
@@ -1280,7 +1337,7 @@ spans overlap at a single date.
   not overlap.
 
 
-## `ExponentialBackoff` Objects
+### `ExponentialBackoff` Objects
 
 ```python
 class ExponentialBackoff()
@@ -1353,7 +1410,7 @@ Implements validator utils for use with pydantic models.
 Implements: `StrictFilePath`, `StrictDirectoryPath`
 
 
-## `StrictFilePath` Objects
+### `StrictFilePath` Objects
 
 ```python
 class StrictFilePath(pydantic.RootModel[str])
@@ -1380,7 +1437,7 @@ m = MyModel.model_validate(
 ```
 
 
-## `StrictDirectoryPath` Objects
+### `StrictDirectoryPath` Objects
 
 ```python
 class StrictDirectoryPath(pydantic.RootModel[str])
@@ -1407,7 +1464,7 @@ m = MyModel.model_validate(
 ```
 
 
-## `Version` Objects
+### `Version` Objects
 
 ```python
 class Version(pydantic.RootModel[str])
@@ -1434,7 +1491,7 @@ def as_identifier() -> str
 Return the version string as a number, i.e. MAJOR.MINOR.PATCH...
 
 
-## `StricterBaseModel` Objects
+### `StricterBaseModel` Objects
 
 ```python
 class StricterBaseModel(pydantic.BaseModel)
@@ -1444,7 +1501,7 @@ The same as pydantic.BaseModel, but with stricter rules. It does not
 allow extra fields and validates assignments after initialization.
 
 
-## `StrictIPv4Adress` Objects
+### `StrictIPv4Adress` Objects
 
 ```python
 class StrictIPv4Adress(pydantic.RootModel[str])
@@ -1462,3 +1519,63 @@ m = MyModel(ip='192.186.2.1')
 m = MyModel(ip='192.186.2.1:22')
 ```
 
+
+## `tum_esm_utils.opus`
+
+Functions for interacting with OPUS files.
+
+Implements: `OpusFile`.
+
+Read https://tccon-wiki.caltech.edu/Main/I2SAndOPUSHeaders for more information
+about the file parameters. This requires you to install this utils library with
+the optional `opus` dependency:
+
+```bash
+pip install "tum_esm_utils[opus]"
+## `or`
+pdm add "tum_esm_utils[opus]"
+```
+
+Credits to Friedrich Klappenbach (ge79wul@mytum.de) for decoding the OPUS file
+format.
+
+
+### `OpusFile` Objects
+
+```python
+class OpusFile(pydantic.BaseModel)
+```
+
+
+##### `read`
+
+```python
+@staticmethod
+def read(filepath: str,
+         measurement_timestamp_mode: Literal["start", "end"] = "start",
+         interferogram_mode: Literal["skip", "validate", "read"] = "read",
+         read_all_channels: bool = True) -> OpusFile
+```
+
+Read an interferogram file.
+
+**Arguments**:
+
+- `filepath` - Path to the OPUS file.
+- `measurement_timestamp_mode` - Whether the timestamps in the interferograms
+  indicate the start or end of the measurement
+- `interferogram_mode` - How to handle the interferogram data. "skip"
+  will not read the interferogram data, "validate"
+  will read the first and last block to check
+  for errors during writing, "read" will read
+  the entire interferogram. "read" takes about
+  11-12 times longer than "skip", "validate" is
+  about 20% slower than "skip".
+- `read_all_channels` - Whether to read all channels in the file or
+  only the first one.
+
+
+**Returns**:
+
+  An OpusFile object, optionally containing the interferogram data (in read mode)
+

docs/scripts/sync-docs.py

@@ -2,9 +2,7 @@
 import os
 import tempfile
 
-PROJECT_DIR = os.path.dirname(
-    os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-)
+PROJECT_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 INDEX_SRC = os.path.join(PROJECT_DIR, "README.md")
 INDEX_DST = os.path.join(PROJECT_DIR, "docs", "pages", "index.md")
 API_DST = os.path.join(PROJECT_DIR, "docs", "pages", "api-reference.md")
@@ -20,22 +18,22 @@
 # generate automatic API reference and prettify output
 
 module_names = list(
-    sorted([
-        f[:-3] for f in os.listdir(os.path.join(PROJECT_DIR, "tum_esm_utils"))
-        if (f.endswith(".py") and (f != "__init__.py"))
-    ])
-)
+    sorted(
+        [
+            f[:-3]
+            for f in os.listdir(os.path.join(PROJECT_DIR, "tum_esm_utils"))
+            if (f.endswith(".py") and (f != "__init__.py"))
+        ]
+    )
+) + ["opus"]
 print("Module names:", module_names)
 
 parsed_modules = ["--module=tum_esm_utils"]
 for m in module_names:
     parsed_modules.append(f"--module=tum_esm_utils.{m}")
 
 with tempfile.NamedTemporaryFile() as f:
-    os.system(
-        f"cd {PROJECT_DIR} && pydoc-markdown " + (" ").join(parsed_modules) +
-        f" > {f.name}"
-    )
+    os.system(f"cd {PROJECT_DIR} && pydoc-markdown " + (" ").join(parsed_modules) + f" > {f.name}")
     with open(f.name, "r") as f2:
         raw_api_reference_content = f2.read()
 
@@ -48,23 +46,19 @@
             assert line_segments[0] == "#" * len(line_segments[0])
             if len(line_segments) == 2:
                 parsed_api_reference_content_lines.append(
-                    line_segments[0] + "# `" +
-                    line_segments[1].replace("\\_", "_") + "`"
+                    line_segments[0] + "# `" + line_segments[1].replace("\\_", "_") + "`"
                 )
             elif len(line_segments) == 3:
                 assert line_segments[2] == "Objects"
                 parsed_api_reference_content_lines.append(
-                    line_segments[0] + " `" +
-                    line_segments[1].replace("\\_", "_") + "` Objects"
+                    line_segments[0] + "# `" + line_segments[1].replace("\\_", "_") + "` Objects"
                 )
             else:
                 raise ValueError("Unexpected line format: " + line)
         else:
             parsed_api_reference_content_lines.append(line)
 
-    parsed_api_reference_content = "\n".join(
-        parsed_api_reference_content_lines[2 :]
-    )
+    parsed_api_reference_content = "\n".join(parsed_api_reference_content_lines[2:])
 
 with open(API_DST, "w") as f:
     f.write("# API Reference \n\n" + parsed_api_reference_content)