Validators

psengine.helpers.helpers.Validators

Common validators for pydantic models.

check_uhash_prefix staticmethod

check_uhash_prefix(value: str | list) -> str | list

Validate that all fields start with 'uhash:' and add it if missing.

PARAMETER	DESCRIPTION
value	String or list of strings to check for uhash prefix. TYPE: str | list

RETURNS	DESCRIPTION
str | list	String or list with 'uhash:' prefix ensured.

Source code in psengine/helpers/helpers.py

@staticmethod
def check_uhash_prefix(
    value: Annotated[str | list, Doc('String or list of strings to check for uhash prefix.')],
) -> Annotated[str | list, Doc("String or list with 'uhash:' prefix ensured.")]:
    """Validate that all fields start with 'uhash:' and add it if missing."""
    uhash = 'uhash:'
    if isinstance(value, str):
        return f'{uhash}{value}' if not value.startswith(uhash) else value

    if isinstance(value, list):
        new_values = []
        for h in value:
            if h:
                complete_value = f'{uhash}{h}' if not h.startswith(uhash) else h
                new_values.append(complete_value)
        return new_values

    return value

convert_relative_time staticmethod

convert_relative_time(input_time: str) -> str

Convert relative time to datetime string if possible.

PARAMETER	DESCRIPTION
input_time	Relative time string, e.g., '7d', '3h'. TYPE: str

RETURNS	DESCRIPTION
str	Datetime string in ISO 8601 format if conversion is possible.

Source code in psengine/helpers/helpers.py

@staticmethod
def convert_relative_time(
    input_time: Annotated[str, Doc("Relative time string, e.g., '7d', '3h'.")],
) -> Annotated[str, Doc('Datetime string in ISO 8601 format if conversion is possible.')]:
    """Convert relative time to datetime string if possible."""
    return (
        TimeHelpers.rel_time_to_date(input_time)
        if TimeHelpers.is_rel_time_valid(input_time)
        else input_time
    )

convert_str_to_list staticmethod

convert_str_to_list(
    value: str | list | None,
) -> list | None

Convert value from str to list, strip strings, drop None/empty strings.

Non-string items in a list are passed through unchanged so enum-typed fields (e.g. list[DomainTypes]) keep their values.

PARAMETER	DESCRIPTION
value	String or list to convert. TYPE: str | list | None

RETURNS	DESCRIPTION
list | None	Converted list, stripped and cleaned.

Source code in psengine/helpers/helpers.py

@staticmethod
def convert_str_to_list(
    value: Annotated[str | list | None, Doc('String or list to convert.')],
) -> Annotated[list | None, Doc('Converted list, stripped and cleaned.')]:
    """Convert value from str to list, strip strings, drop None/empty strings.

    Non-string items in a list are passed through unchanged so enum-typed
    fields (e.g. `list[DomainTypes]`) keep their values.
    """
    if value is None:
        return None
    if isinstance(value, str):
        value = value.strip()
        return [value] if value else []
    if isinstance(value, list):
        result = []
        for v in value:
            if v is None:
                continue
            if isinstance(v, str):
                stripped = v.strip()
                if not stripped:
                    continue
                result.append(stripped)
            else:
                result.append(v)
        return result
    return value

empty_str_to_none staticmethod

empty_str_to_none(value: str | None) -> str | None

Normalise an empty string ('') to None; pass everything else through.

PARAMETER	DESCRIPTION
value	A value that may be an empty string. TYPE: str | None

RETURNS	DESCRIPTION
str | None	None if the value is an empty string, else the value.

Source code in psengine/helpers/helpers.py

@staticmethod
def empty_str_to_none(
    value: Annotated[str | None, Doc('A value that may be an empty string.')],
) -> Annotated[str | None, Doc('None if the value is an empty string, else the value.')]:
    """Normalise an empty string (`''`) to None; pass everything else through."""
    return None if value == '' else value

is_rel_time_valid staticmethod

is_rel_time_valid(input_time: str | None)

Check that a relative time like -3d is valid.

PARAMETER	DESCRIPTION
input_time	Relative time string, e.g., '7d', '3h'. TYPE: str | None

Source code in psengine/helpers/helpers.py

@staticmethod
def is_rel_time_valid(
    input_time: Annotated[str | None, Doc("Relative time string, e.g., '7d', '3h'.")],
):
    """Check that a relative time like `-3d` is valid."""
    if input_time is not None and not TimeHelpers.is_rel_time_valid(input_time):
        raise ValueError(f'Invalid relative time: {input_time}')
    return input_time

none_to_empty_list staticmethod

none_to_empty_list(value: list | None) -> list

Coerce a null/empty API value to a list so the field is always iterable.

PARAMETER	DESCRIPTION
value	A list or null/empty value from the API. TYPE: list | None

RETURNS	DESCRIPTION
list	The value, or [] when it is None/empty.

Source code in psengine/helpers/helpers.py

@staticmethod
def none_to_empty_list(
    value: Annotated[list | None, Doc('A list or `null`/empty value from the API.')],
) -> Annotated[list, Doc('The value, or [] when it is None/empty.')]:
    """Coerce a `null`/empty API value to a list so the field is always iterable."""
    return value or []