diff --git a/docs/pages/api-reference.md b/docs/pages/api-reference.md index 5c1274f..b14e435 100644 --- a/docs/pages/api-reference.md +++ b/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 +``` diff --git a/pyproject.toml b/pyproject.toml index ef631a2..25a385d 100644 --- a/pyproject.toml +++ b/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 "] readme = "README.md" diff --git a/tests/test_docs.py b/tests/test_docs.py index 7cc5a99..ca9b2c1 100644 --- a/tests/test_docs.py +++ b/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 )