### Install Dependencies and Run Development Server

Source: https://github.com/tum-esm/utils/blob/main/docs/README.md

Installs project dependencies using npm and starts the development server.

```bash
npm install
npm run dev
```

--------------------------------

### Install EM27 Utilities

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Instructions for installing the tum-esm_utils library with the optional EM27 dependency.

```bash
pip install "tum_esm_utils[em27]"
## `or`
pdm add "tum_esm_utils[em27]"
```

--------------------------------

### Install tum-esm-utils with OPUS support

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Instructions for installing the tum-esm-utils library with the optional OPUS dependency, enabling interaction with OPUS files.

```bash
pip install "tum_esm_utils[opus]"
## `or`
pdm add "tum_esm_utils[opus]"
```

--------------------------------

### Install tum-esm-utils

Source: https://github.com/tum-esm/utils/blob/main/README.md

Instructions for installing the tum-esm-utils Python library using either pdm or pip.

```bash
pdm add tum_esm_utils
# or
pip install tum_esm_utils
```

--------------------------------

### Install tum-esm-utils with plotting dependencies

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Instructions for installing the tum-esm-utils library with the optional plotting dependencies required for the plotting utilities.

```bash
pip install "tum_esm_utils[plotting]"
# or
pdm add "tum_esm_utils[plotting]"
```

--------------------------------

### Install tum-esm-utils

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/index.md

Instructions for installing the tum-esm-utils Python library using either pdm or pip.

```bash
pdm add tum_esm_utils
# or
pip install tum_esm_utils
```

--------------------------------

### Process Management Utilities

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides functions to manage background processes. Includes utilities to get process IDs (PIDs) by script path, start new background processes using a specified interpreter and script, and terminate processes based on their script path.

```python
def get_process_pids(script_path: str) -> list[int]:
    """Return a list of PIDs that have the given script as their entrypoint."""
    pass
```

```python
def start_background_process(interpreter_path: str,
                             script_path: str,
                             waiting_period: float = 0.5) -> int:
    """Start a new background process with nohup with a given python interpreter and script path."""
    pass
```

```python
def terminate_process(script_path: str,
                      termination_timeout: Optional[int] = None) -> list[int]:
    """Terminate all processes that have the given script as their entrypoint."""
    pass
```

--------------------------------

### Start and Manage Background Processes

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/example-usage.md

Demonstrates how to start a Python script as a background process using `start_background_process`, retrieve its process ID with `get_process_pids`, and terminate it using `terminate_process`. This is useful for running long-running tasks without blocking the main program.

```python
from tum_esm_utils.processes import (
    start_background_process,
    get_process_pids,
    terminate_process
)

# start a process using nohup and get its process-id
new_pid = start_background_process(
    sys.executable, SCRIPT_PATH
)

# pid should be returned from this list
assert get_process_pids(SCRIPT_PATH) == [new_pid]

# terminate the process
terminated_pids = terminate_process(SCRIPT_PATH)
assert terminated_pids == [new_pid]

# pid list should be empty
assert get_process_pids(SCRIPT_PATH) == []
```

--------------------------------

### Shell Command Execution and Utilities

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Offers utilities for interacting with the shell, including running shell commands, handling command-line exceptions, retrieving hostnames, getting Git commit SHAs, and changing file permissions. The `run_shell_command` function executes a command and returns its stdout, raising an exception on non-zero exit codes.

```python
class CommandLineException(Exception):
    """Exception raised for errors in the command line."""
    pass
```

```python
def run_shell_command(command: str,
                      working_directory: Optional[str] = None,
                      executable: str = "/bin/bash") -> str:
    """runs a shell command and raises a `CommandLineException` if the return code is not zero, returns the stdout."""
    pass
```

```python
def get_hostname() -> str:
    """returns the hostname of the device, removes network postfix (`somename.local`) if present."""
    pass
```

```python
def get_commit_sha() -> str:
    """Get the current git commit SHA."""
    pass
```

```python
def change_file_permissions(path: str, permissions: str) -> None:
    """Change the permissions of a file."""
    pass
```

--------------------------------

### OPUS HTTP Interface Control

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/example-usage.md

Provides an interface to control the OPUS software via its HTTP server. Allows for retrieving version information, loading experiments, starting, stopping, and checking the status of macros. It recommends using this over the older DDE interface.

```python
import time
from tum_esm_utils.opus import OpusHTTPInterface

version = OpusHTTPInterface.get_version()
language = OpusHTTPInterface.get_language()
username = OpusHTTPInterface.get_username()

OpusHTTPInterface.load_experiment("somepath.xmp")
macro_id = OpusHTTPInterface.start_macro("somepath.mtx")
time.sleep(5)

assert OpusHTTPInterface.macro_is_running(macro_id)
time.sleep(5)

OpusHTTPInterface.stop_macro(macro_id)
time.sleep(5)

assert not OpusHTTPInterface.macro_is_running(macro_id)
```

--------------------------------

### OpusHTTPInterface Class and Methods

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides a HTTP interface to OPUS, allowing requests to be sent and responses to be received. It handles connection management and retries for robustness. Includes methods to get version information and check interface status.

```APIDOC
class OpusHTTPInterface()
    Interface to the OPUS HTTP interface.

    It uses the socket library, because the HTTP interface of OPUS does not
    return valid HTTP/1 or HTTP/2 headers. It opens and closes a new socket
    because OPUS closes the socket after the answer has been sent.

    Raises:
    - ConnectionError: If the connection to the OPUS HTTP interface fails or
      if the response is invalid.

    request(request: str,
            timeout: float = 10.0,
            expect_ok: bool = False) -> list[str]
        Send a request to the OPUS HTTP interface and return the answer.

        Commands will be send to `GET http://localhost/OpusCommand.htm?<request>`.
        This function will retry the request up to 3 times and wait 5 seconds
        inbetween retries.

        Arguments:
        - request: The request to send.
        - timeout: The time to wait for the answer.
        - expect_ok: Whether the first line of the answer should be "OK".

        Returns:
          The answer lines.

    request_without_retry(request: str,
                          timeout: float = 10.0,
                          expect_ok: bool = False) -> list[str]
        Send a request to the OPUS HTTP interface and return the answer.

        Commands will be send to `GET http://localhost/OpusCommand.htm?<request>`.

        Arguments:
        - request: The request to send.
        - timeout: The time to wait for the answer.
        - expect_ok: Whether the first line of the answer should be "OK".

        Returns:
          The answer lines.

    get_version() -> str
        Get the version number, like `20190310`.

    get_version_extended() -> str
        Get the extended version number, like `8.2 Build: 8, 2, 28 20190310`.

    is_working() -> bool
        Check if the OPUS HTTP interface is working. Does NOT raise a
        `ConnectionError` but only returns `True` or `False`.

    get_main_thread_id() -> int
        Get the process ID of the main thread of OPUS.
```

--------------------------------

### Time Range Generation

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Generates a list of times between a specified start and end time, with a defined time step.

```python
def time_range(from_time: datetime.time, to_time: datetime.time,
                 time_step: datetime.timedelta) -> list[datetime.time]:
    """Returns a list of times between from_time and to_time (inclusive)."""
    pass
```

--------------------------------

### Date Range Generation

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Generates a list of consecutive dates between a specified start and end date, inclusive.

```python
def date_range(from_date: datetime.date,
               to_date: datetime.date) -> list[datetime.date]:
    """Returns a list of dates between from_date and to_date (inclusive)."""
    pass
```

--------------------------------

### Get Commit SHA

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Retrieves the current commit SHA of the Git repository. Supports both short and long formats. Returns None if not in a Git repository.

```python
def get_commit_sha(
        variant: Literal["short", "long"] = "short") -> Optional[str]:
    # Get the current commit sha of the repository. Returns
    # `None` if there is not git repository in any parent directory.
    pass
```

--------------------------------

### Datetime Span Intersection

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Calculates the overlapping period between two datetime spans. Returns the intersection as a tuple of start and end datetimes, or None if there is no overlap or the overlap is a single point in time.

```python
def datetime_span_intersection(
    dt_span_1: tuple[datetime.datetime,
                     datetime.datetime], dt_span_2: tuple[datetime.datetime,
                                                          datetime.datetime]
) -> Optional[tuple[datetime.datetime, datetime.datetime]]:
    """Check if two datetime spans overlap."""
    # ... implementation details ...
```

--------------------------------

### Run Documentation in Dev Mode

Source: https://github.com/tum-esm/utils/blob/main/README.md

Steps to set up and run the documentation website in development mode.

```bash
cd docs
npm install
npm run dev
```

--------------------------------

### Run Documentation in Dev Mode

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/index.md

Steps to set up and run the documentation website in development mode.

```bash
cd docs
npm install
npm run dev
```

--------------------------------

### Create Production Build

Source: https://github.com/tum-esm/utils/blob/main/docs/README.md

Creates an optimized production build of the project.

```bash
npm run build
```

--------------------------------

### Publish Package to PyPI

Source: https://github.com/tum-esm/utils/blob/main/README.md

Commands to build and publish the tum-esm-utils package to PyPI.

```bash
pdm build
pdm publish
```

--------------------------------

### Publish Package to PyPI

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/index.md

Commands to build and publish the tum-esm-utils package to PyPI.

```bash
pdm build
pdm publish
```

--------------------------------

### Global Styles

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/_app.mdx

Imports global CSS styles for the application.

```css
import '../style.css';
```

--------------------------------

### Load NCEP Profiles

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Functions to read NCEP atmospheric profiles from GGG2020 map, mod, and vmr files.

```python
def load_ggg2020_map(filepath: str) -> pl.DataFrame:
    # ... implementation details ...

def load_ggg2020_mod(filepath: str) -> pl.DataFrame:
    # ... implementation details ...

def load_ggg2020_vmr(filepath: str) -> pl.DataFrame:
    # ... implementation details ...
```

--------------------------------

### Astronomy Class and Methods

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides utilities for astronomical calculations, including computing sun elevation and azimuth. Initializes by downloading the de421.bsp dataset.

```python
class Astronomy():
    def __init__(self) -> None:
        # Initializes the Astronomy class, downloads the latest de421.bsp dataset.
        pass

    def get_sun_position(self, lat: float, lon: float, alt_asl: float,
                         dt: datetime.datetime) -> tuple[float, float]:
        # Computes current sun elevation and azimuth in degrees.
        pass
```

--------------------------------

### RingList (Circular Buffer) Implementation

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/example-usage.md

Demonstrates the usage of `tum_esm_utils.datastructures.RingList`, a custom implementation of a circular buffer. It shows how to initialize, append elements, check if full, retrieve elements, and how older elements are discarded when new ones are added to a full list.

```python
import tum_esm_utils

ring_list = tum_esm_utils.datastructures.RingList(4)

# list is empty at first
print(ring_list.get())           # []
print(ring_list.get_max_size())  # 4
print(ring_list.is_full())       # False

# appending one element
ring_list.append(23.5)
assert ring_list.get() == [23.5]

ring_list.append(3)
ring_list.append(4)
ring_list.append(18)
print(ring_list.get())      # [23.5, 3, 4, 18]
print(ring_list.is_full())  # True

# the ring list will always discard the oldest element once
# you append new elements to a full list. Of course, it does
# not copy all elements but only modifies the internal pointers.

ring_list.append(4)
print(ring_list.get())      # [3, 4, 18, 4]

ring_list.append(5)
print(ring_list.get())      # [4, 18, 4, 5]
print(ring_list.sum())      # 31
```

--------------------------------

### Enhanced Plotting with Matplotlib Wrapper

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/example-usage.md

Provides a simplified interface for creating plots using Matplotlib, including applying default styles for better aesthetics and managing figure and subplot creation. Requires optional 'plotting' dependencies.

```python
import tum_esm_utils

# apply some nice styles to axis/labels/etc.
tum_esm_utils.plotting.apply_better_defaults(font_family="Roboto")

with tum_esm_utils.plotting.create_figure(
    "some-path-to-figure.png",
    width=10,
    height=6,
) as fig:
    axis1 = tum_esm_utils.plotting.add_subplot(
        fig, (2, 1, 1), title="Test Plot", xlabel="X", ylabel="Y"
    )
    axis1.plot([1, 2, 3], [1, 2, 3])

    axis2 = tum_esm_utils.plotting.add_subplot(
        fig, (2, 1, 2), title="Test Plot 2", xlabel="X", ylabel="Y"
    )
    axis2.plot([1, 2, 3], [3, 2, 1])
```

```bash
pip install "tum-esm-utils[plotting]"
# or
pdm add "tum-esm-utils[plotting]"
```

--------------------------------

### OpusFile Class and Methods

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides an interface to interact with OPUS spectrum files. Includes methods for reading file data with various options for timestamp and interferogram handling.

```APIDOC
class OpusFile(pydantic.BaseModel)
    Interact with OPUS spectrum files.

    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)
```

--------------------------------

### React App Component

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/_app.mdx

The main App component for a React application. It renders the current page component and its props. It imports global styles.

```javascript
import '../style.css';

export default function App({ Component, pageProps }) {
    return (
        <>
            <Component {...pageProps} />
        </>
    );

}
```

--------------------------------

### Insert Text Replacements

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/example-usage.md

Shows how to use `tum_esm_utils.text.insert_replacements` to perform simple text substitutions within a template string. It takes a template string with placeholders and a dictionary of replacements to fill those placeholders.

```python
from tum_esm_utils.text import insert_replacements

template = """
Dear %YOU%,

thanks for reading this %TEXT_TYPE%!

Best,
%ME%
"""

replacements = {
    "ME": "person A",
    "YOU": "person B",
    "TEXT_TYPE": "letter",
}

# replace all items in here
filled_template = insert_replacements(template, replacements)
```

--------------------------------

### System Status Functions

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides functions to monitor system resource usage and status, including CPU, memory, disk space, battery level, last boot time, and UTC offset.

```python
def get_cpu_usage() -> list[float]:
    # Checks the CPU usage of the system.
    # Returns: The CPU usage in percent for each core.
    pass
```

```python
def get_memory_usage() -> float:
    # Checks the memory usage of the system.
    # Returns: The memory usage in percent.
    pass
```

```python
def get_physical_memory_usage() -> float:
    # Returns the memory usage (physical memory) of the current process in MB.
    pass
```

```python
def get_disk_space(path: str = "/") -> float:
    # Checks the disk space of a given path.
    # Arguments:
    # - path - The path to check the disk space for.
    # Returns:
    #   The available disk space in percent.
    pass
```

```python
def get_system_battery() -> Optional[int]:
    # Checks the system battery.
    # Returns:
    #   The battery state in percent if available, else None.
    pass
```

```python
import datetime
def get_last_boot_time() -> datetime.datetime:
    # Checks the last boot time of the system.
    pass
```

```python
def get_utc_offset() -> float:
    # Returns the UTC offset of the system.
    # Credits to https://stackoverflow.com/a/35058476/8255842
    # x = get_utc_offset()
    # local time == utc time + x
    # Returns:
    #   The UTC offset in hours.
    pass
```

--------------------------------

### OPUS Utility Functions

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides various static methods for interacting with the OPUS software, including macro management, experiment loading, parameter manipulation, and application control.

```python
import tum_esm_utils.opus

# Check if a macro is running
is_running = tum_esm_utils.opus.some_macro_is_running()

# Get the path to the currently loaded experiment
experiment_path = tum_esm_utils.opus.get_loaded_experiment()

# Load an experiment
tum_esm_utils.opus.load_experiment("path/to/experiment")

# Start a macro
macro_id = tum_esm_utils.opus.start_macro("path/to/macro.mac")

# Check if a specific macro is running
macro_is_running = tum_esm_utils.opus.macro_is_running(macro_id)

# Stop a macro by path or ID
tum_esm_utils.opus.stop_macro("path/to/macro.mac")

# Unload all files
tum_esm_utils.opus.unload_all_files()

# Close OPUS
tum_esm_utils.opus.close_opus()

# Set parameter mode
tum_esm_utils.opus.set_parameter_mode("file")

# Read a parameter
param_value = tum_esm_utils.opus.read_parameter("some_parameter")

# Write a parameter
tum_esm_utils.opus.write_parameter("some_parameter", "new_value")

# Get current language
language = tum_esm_utils.opus.get_language()

# Get current username
username = tum_esm_utils.opus.get_username()

# Get specific paths
opus_path = tum_esm_utils.opus.get_path("opus")

# Set processing mode
tum_esm_utils.opus.set_processing_mode("command")

# Execute a command line command
result = tum_esm_utils.opus.command_line("ls -l")
```

--------------------------------

### Version String Formatting

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides methods to format version strings, which follow the MAJOR.MINOR.PATCH[-(alpha|beta|rc).N] pattern, into different string representations suitable for tagging or as identifiers.

```python
class Version(pydantic.RootModel[str]):
    """A version string in the format of MAJOR.MINOR.PATCH[-(alpha|beta|rc).N]"""
    def as_tag(self) -> str:
        """Return the version string as a tag, i.e. vMAJOR.MINOR.PATCH..."""
        # ... implementation details ...

    def as_identifier(self) -> str:
        """Return the version string as a number, i.e. MAJOR.MINOR.PATCH..."""
        # ... implementation details ...
```

--------------------------------

### Download GitHub Release Asset

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Downloads a specific asset from the latest release of a GitHub repository. Allows specifying a destination directory, an optional final name, and supports forcing the download if the file already exists.

```python
def download_github_release_asset(repository: str,
                                  asset_name: str,
                                  dst_dir: str,
                                  final_name: Optional[str] = None,
                                  access_token: Optional[str] = None,
                                  force: bool = False) -> None:
    # Downloads a specific asset from the latest release of a GitHub repository.
    pass
```

--------------------------------

### File Operations

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides utility functions for file operations, including loading and dumping content in various formats (text, binary, JSON). It also includes functions for path manipulation, calculating directory and file checksums, and reading specific lines from a file.

```python
def load_file(path: str) -> str
```

```python
def dump_file(path: str, content: str) -> None
```

```python
def load_binary_file(path: str) -> bytes
```

```python
def dump_binary_file(path: str, content: bytes) -> None
```

```python
def load_json_file(path: str) -> Any
```

```python
def dump_json_file(path: str, content: Any, indent: Optional[int] = 4) -> None
```

```python
def get_parent_dir_path(script_path: str, current_depth: int = 1) -> str
```

```python
def get_dir_checksum(path: str) -> str
```

```python
def get_file_checksum(path: str) -> str
```

--------------------------------

### ColumnAveragingKernel Class and Methods

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

A class to store, load, and apply column averaging kernels. It is initialized with solar zenith angles, pressures, and optionally, the averaging kernels themselves.

```python
class ColumnAveragingKernel():
    def __init__(self, szas: np.ndarray[Any, Any],
                 pressures: np.ndarray[Any, Any],
                 aks: Optional[np.ndarray[Any, Any]] = None) -> None:
        # Initialize the ColumnAveragingKernel.
        # Arguments:
        # - szas: The solar zenith angles (SZAs) in degrees.
        # - pressures: The pressures in hPa.
        # - aks: The averaging kernels. If None, a zero array is created.
        pass
```

--------------------------------

### Load ColumnAveragingKernel from JSON

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Loads the ColumnAveragingKernel object from a JSON file.

```python
@staticmethod
def load(filepath: str) -> ColumnAveragingKernel:
    # ... implementation details ...
```

--------------------------------

### Render Directory Tree as String

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Renders a directory tree structure as a formatted string. It supports ignoring specific files/directories, limiting depth, and customizing prefixes for directories and files.

```python
def render_directory_tree(root: str,
                          ignore: list[str] = [],
                          max_depth: Optional[int] = None,
                          root_alias: Optional[str] = None,
                          directory_prefix: Optional[str] = "📁 ",
                          file_prefix: Optional[str] = "📄 ") -> Optional[str]:
    """Render a file tree as a string."""
    # Implementation details...
```

--------------------------------

### GitHub and GitLab File Request Functions

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides functions to request file content from GitHub and GitLab repositories. These functions handle authentication, branch selection, and timeouts, raising HTTPError for non-200 responses.

```python
def request_github_file(repository: str,
                        filepath: str,
                        access_token: Optional[str] = None,
                        branch_name: str = "main",
                        timeout: int = 10) -> str:
    # Sends a request and returns the content of the response, as a string.
    # Raises an HTTPError if the response status code is not 200.
    pass

def request_gitlab_file(repository: str,
                        filepath: str,
                        access_token: Optional[str] = None,
                        branch_name: str = "main",
                        hostname: str = "gitlab.com",
                        timeout: int = 10) -> str:
    # Sends a request and returns the content of the response, as a string.
    # Raises an HTTPError if the response status code is not 200.
    pass
```

--------------------------------

### Load Proffast2 Result

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Loads the output of Proffast 2 into a polars DataFrame. This function takes a file path as input and returns a DataFrame containing all columns from the Proffast 2 output file.

```python
def load_proffast2_result(path: str) -> pl.DataFrame
```

--------------------------------

### Strict File and Directory Path Validation with Pydantic

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/example-usage.md

Illustrates how to use `tum_esm_utils.validators.StrictFilePath` and `tum_esm_utils.validators.StrictDirectoryPath` with Pydantic models to enforce that string fields represent existing file or directory paths. It also shows how to disable this validation using context.

```python
from tum_esm_utils.validators import StrictFilePath, StrictDirectoryPath
import pydantic

class Config(pydantic.BaseModel):
    f: StrictFilePath
    d: StrictDirectoryPath

# it can be parsed just like a string
c = Config.model_validate({"f": "pyproject.toml", "d": "packages"})
alternative_c = Config(f="netlify.toml", d="packages")

# the value now has to be accessed by `<field>.root`
print(type(c.f))       # <class '__main__.StrictFilePath'>
print(type(c.f.root))  # <class 'str'>

# but the exported dicts do not show any sign that the
# respective fields are anything more than a regular string
print(c.model_dump_json())  # {"f": "netlify.toml", "d": "src"}

# you can turn off the file path validation at validation time if you want
c = Config.model_validate(
    {"f": "netlify.tom", "d": "package"},
    context={"ignore-path-existence": True},
)
```

--------------------------------

### List Directory Contents with Filtering

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Lists the contents of a directory with advanced filtering capabilities, similar to `os.listdir` but with regex matching and pattern ignoring. It can include/exclude directories, files, and symbolic links.

```python
def list_directory(path: str,
                   regex: Optional[str] = None,
                   ignore: Optional[list[str]] = None,
                   include_directories: bool = True,
                   include_files: bool = True,
                   include_links: bool = True) -> list[str]:
    """List the contents of a directory based on certain criteria."""
    # Implementation details...
```

--------------------------------

### RingList Datastructure

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

A list implementation with a maximum size, behaving like a ring buffer.

```python
class RingList():
    def __init__(self, max_size: int):
        # ... implementation details ...

    def clear() -> None:
        # ... implementation details ...

    def is_full() -> bool:
        # ... implementation details ...

    def append(x: float) -> None:
        # ... implementation details ...

    def get() -> list[float]:
        # ... implementation details ...

    def sum() -> float:
        # ... implementation details ...

    def set_max_size(new_max_size: int) -> None:
        # ... implementation details ...
```

--------------------------------

### Dump ColumnAveragingKernel to JSON

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Dumps the ColumnAveragingKernel object to a JSON file.

```python
def dump(filepath: str) -> None:
    # ... implementation details ...
```

--------------------------------

### tum_esm_utils Package Configuration

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Allows disabling automatic submodule imports by setting the TUM_ESM_UTILS_EXPLICIT_IMPORTS environment variable to 1. This can significantly reduce package import time.

```APIDOC
Environment Variable: TUM_ESM_UTILS_EXPLICIT_IMPORTS

Description:
  When set to '1', this environment variable disables automatic submodule imports within the tum_esm_utils package. This means that submodules like `tum_esm_utils.code` will not be accessible directly after a simple `import tum_esm_utils`.

  Instead, users must explicitly import each submodule, for example: `from tum_esm_utils import code`.

Benefit:
  Reduces the import time of the package by up to 60 times compared to the default behavior where all submodules are automatically imported.

Usage:
  Set the environment variable before importing the package:
  ```bash
  export TUM_ESM_UTILS_EXPLICIT_IMPORTS=1
  ```
  Then in Python:
  ```python
  import tum_esm_utils
  from tum_esm_utils import code # Required if TUM_ESM_UTILS_EXPLICIT_IMPORTS is set
  ```
```

--------------------------------

### RandomLabelGenerator Class

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Generates random labels following the Docker style naming convention (e.g., 'admiring-archimedes'). It supports tracking occupied labels to avoid duplicates and can also generate fully random labels.

```python
class RandomLabelGenerator():
    """A class to generate random labels that follow the Docker style naming of
    containers, e.g `admiring-archimedes` or `happy-tesla`.

    Usage with tracking duplicates:

    generator = RandomLabelGenerator()
    label = generator.generate()
    another_label = generator.generate()  # Will not be the same as `label`
    generator.free(label)  # Free the label to be used again

    Usage without tracking duplicates:

    label = RandomLabelGenerator.generate_fully_random()
    """
    pass
```

```python
def __init__(occupied_labels: set[str] | list[str] = set(),
             adjectives: set[str] | list[str] = CONTAINER_ADJECTIVES,
             names: set[str] | list[str] = CONTAINER_NAMES) -> None:
    """Initialize the label generator."""
    pass
```

```python
def generate() -> str:
    """Generate a random label that is not already occupied."""
    pass
```

```python
def free(label: str) -> None:
    """Free a label to be used again."""
    pass
```

```python
@staticmethod
def generate_fully_random(
        adjectives: set[str] | list[str] = CONTAINER_ADJECTIVES,
        names: set[str] | list[str] = CONTAINER_NAMES) -> str:
    """Get a random label without tracking duplicates.

    Use an instance of `RandomLabelGenerator` if you want to avoid
    duplicates by tracking occupied labels.
    """
    pass
```

--------------------------------

### Exponential Backoff for Retries

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/example-usage.md

Implements an exponential backoff strategy for handling retries after errors. The waiting time increases exponentially with each retry, with configurable bucket sizes for wait times. Useful for network requests or operations prone to transient failures.

```python
import tum_esm_utils

logger = ...

# both arguments are optional
exponential_backoff = tum_esm_utils.timing.ExponentialBackoff(
    log_info=logger.info, buckets= [60, 240, 900, 3600, 14400]
)

while True:
    try:
        # do something that might fail
        exponential_backoff.reset()
    except Exception as e:
        logger.exception(e)
        exponential_backoff.sleep()
```

--------------------------------

### StrictDirectoryPath Validation

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

A pydantic model for validating directory paths, ensuring that the specified path points to an existing directory. Validation can be bypassed using a context variable.

```python
class StrictDirectoryPath(pydantic.RootModel[str]):
    """A pydantic model that validates a directory path."""
    # ... implementation details ...
```

--------------------------------

### StrictIPv4Adress Validation

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

A Pydantic RootModel that validates input strings as IPv4 addresses. It can be used within other Pydantic models to ensure correct IP address formatting.

```python
class StrictIPv4Adress(pydantic.RootModel[str])

# Example usage:
class MyModel(pyndatic.BaseModel):
    ip: StrictIPv4Adress

m = MyModel(ip='192.186.2.1')
m = MyModel(ip='192.186.2.1:22')
```

--------------------------------

### Detect Corrupt OPUS Files

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/example-usage.md

Utilizes `tum_esm_utils.em27.detect_corrupt_opus_files` to identify interferogram files that cannot be processed by the Proffast 2 preprocessor. This function helps in pinpointing problematic files that could cause an entire day's measurement to fail.

```python
import tum_esm_utils

detection_results = tum_esm_utils.em27.detect_corrupt_opus_files(
    "/path/to/a/folder/with/interferograms"
)
assert detection_results == {
    'md20220409s0e00a.0199': [
        'Charfilter "DUR" is missing',
        'Charfilter "GBW" is missing',
        'Charfilter "GFW" is missing',
        'Charfilter "LWN" is missing',
        'Charfilter "TSC" is missing',
        'Differing sizes of dual channel IFGs!',
        'IFG size too small!',
        'Inconsistent dualifg!',
        'Inconsistent parameter kind in OPUS file!'
    ],
    'comb_invparms_ma_SN061_210329-210329.csv': [
        'File not even readible by the parser'
    ],
    'comb_invparms_mc_SN115_220602-220602.csv': [
        'File not even readible by the parser'
    ],
    'md20220409s0e00a.0200': [
        'File not even readible by the parser'
    ]
}
```

--------------------------------

### Matplotlib Plotting Utilities

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Provides enhanced matplotlib plotting functionalities, including applying better default styles and a context manager for creating and saving figures with customizable properties.

```python
import tum_esm_utils.plotting
import matplotlib.pyplot as plt

# Apply better defaults for matplotlib plots
tum_esm_utils.plotting.apply_better_defaults(font_family="Arial")

# Create and save a figure using a context manager
with tum_esm_utils.plotting.create_figure("my_plot.png", title="My Plot", width=8, height=6) as fig:
    ax = fig.add_subplot(111)
    ax.plot([1, 2, 3], [4, 5, 6])
    ax.set_title("Subplot Title")

print("Figure saved successfully.")
```

--------------------------------

### ExponentialBackoff Class

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Implements an exponential backoff strategy for handling retries, suitable for operations that might fail intermittently. It allows customization of sleep intervals through predefined buckets.

```python
class ExponentialBackoff():
    """Exponential backoff e.g. when errors occur."""
    def __init__(self, log_info: Optional[Callable[[str], None]] = None, buckets: list[int] = [60, 240, 900, 3600, 14400]) -> None:
        """Create a new exponential backoff object."""
        # ... implementation details ...

    def sleep(self, max_sleep_time: Optional[float] = None) -> float:
        """Wait and increase the wait time to the next bucket."""
        # ... implementation details ...

    def reset(self) -> None:
        """Reset the waiting period to the first bucket."""
        # ... implementation details ...

    @contextlib.contextmanager
    def timed_section(label: str) -> Generator[None, None, None]:
        """Time a section of code and print the duration."""
        # ... implementation details ...
```

--------------------------------

### StrictFilePath Validation

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

A pydantic model for validating file paths, ensuring that the specified path points to an existing file. Validation can be bypassed using a context variable.

```python
class StrictFilePath(pydantic.RootModel[str]):
    """A pydantic model that validates a file path."""
    # ... implementation details ...
```

--------------------------------

### Convert Relative to Absolute Path

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/api-reference.md

Converts a path relative to the caller's file into an absolute path. It takes a variable number of string arguments representing path components.

```python
def rel_to_abs_path(*path: str) -> str:
    """Convert a path relative to the caller's file to an absolute path."""
    # Implementation details...
```

--------------------------------

### Convert Relative Path to Absolute Path

Source: https://github.com/tum-esm/utils/blob/main/docs/pages/example-usage.md

Converts a relative file path to an absolute path based on the script's directory. This is useful to ensure file operations work correctly regardless of the current working directory. It supports multiple arguments for path components.

```python
from tum_esm_utils.files import rel_to_abs_path

with open(rel_to_abs_path("./somedir/some_file.txt"), "r") as f:
    print(f.read())

# or

with open(rel_to_abs_path("somedir/some_file.txt"), "r") as f:
    print(f.read())

# or

with open(rel_to_abs_path("somedir", "some_file.txt"), "r") as f:
    print(f.read())
```