Update API reference and version number

docs/pages/api-reference.md

@@ -13,7 +13,7 @@ PyPI: https://pypi.org/project/tum-esm-utils
 
 Context managers for common tasks.
 
-Implements: `ensure_section_duration`
+Implements: `ensure_section_duration`, `set_alarm`, `clear_alarm`.
 
 
 ##### `ensure_section_duration`
@@ -33,6 +33,26 @@ with ensure_section_duration(6):
 ```
 
 
+##### `set_alarm`
+
+```python
+def set_alarm(timeout: int, label: str) -> None
+```
+
+Set an alarm that will raise a `TimeoutError` after
+`timeout` seconds. The message will be formatted as
+`{label} took too long (timed out after {timeout} seconds)`.
+
+
+##### `clear_alarm`
+
+```python
+def clear_alarm() -> None
+```
+
+Clear the alarm set by `set_alarm`.
+
+
 ## `tum_esm_utils.datastructures`
 
 Datastructures not in the standard library.
@@ -228,6 +248,17 @@ utc                     gnd_p    gnd_t    app_sza   ...
 ```
 
 
+##### `rel_to_abs_path`
+
+```python
+def rel_to_abs_path(*path: str) -> str
+```
+
+Convert a path relative to the caller's file to an absolute path.
+
+Example: Inside file `/home/somedir/somepath/somefile.py`, calling `rel_to_abs_path("..", "config", "config.json")` will return `/home/somedir/config/config.json`.
+
+
 ## `tum_esm_utils.github`
 
 Functions for interacting with GitHub.
@@ -662,5 +693,60 @@ content with its value.
 Implements validator functions for use with pydantic models.
 
 Implements: `validate_bool`, `validate_float`, `validate_int`,
-`validate_str`, `validate_list`
+`validate_str`, `validate_list`, `StrictFilePath`,
+`StrictDirectoryPath`.
+
+
+## `StrictFilePath` Objects
+
+```python
+class StrictFilePath(pydantic.RootModel[str])
+```
+
+A pydantic model that validates a file path.
+
+Example usage:
+
+```python
+class MyModel(pyndatic.BaseModel):
+    path: StrictFilePath
+
+m = MyModel(path='/path/to/file') # validates that the file exists
+```
+
+The validation can be ignored by setting the context variable:
+
+```python
+m = MyModel.model_validate(
+    {"path": "somenonexistingpath"},
+    context={"ignore-path-existence": True},
+) # does not raise an error
+```
+
+
+## `StrictDirectoryPath` Objects
+
+```python
+class StrictDirectoryPath(pydantic.RootModel[str])
+```
+
+A pydantic model that validates a directory path.
+
+Example usage:
+
+```python
+class MyModel(pyndatic.BaseModel):
+    path: StrictDirectoryPath
+
+m = MyModel(path='/path/to/directory') # validates that the directory exists
+```
+
+The validation can be ignored by setting the context variable:
+
+```python
+m = MyModel.model_validate(
+    {"path": "somenonexistingpath"},
+    context={"ignore-path-existence": True},
+) # does not raise an error
+```
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "tum_esm_utils"
-version = "1.6.4"
+version = "1.7.0"
 description = "Python utilities by the Professorship of Environmental Sensing and Modeling at the Technical University of Munich"
 authors = ["Moritz Makowski <[email protected]>"]
 readme = "README.md"

tests/test_docs.py

@@ -23,7 +23,7 @@ def test_documentation_sync() -> None:
 
     assert (
         os.system(
-            f"python {os.path.join(PROJECT_DIR, 'scripts', 'generate_docs.py')}"
+            f"python {os.path.join(PROJECT_DIR, 'docs', 'scripts', 'sync-docs.py')}"
         ) == 0
     )