Utils

sereto.utils

assert_file_size_within_range(file, max_bytes, min_bytes=0, interactive=False)

Evaluates if the file size is within the specified range.

If interactive is True, the user is first prompted whether to continue if the file size is not within the range.

Parameters:

Name	Type	Description	Default
file	FilePath	The path to the file.	required
max_bytes	int	The maximum file size in bytes.	required
min_bytes	int	The minimum file size in bytes. Defaults to 0.	0
interactive	bool	If True, the user is prompted whether to continue if the file size is not within the range. Defaults to False.	False

Raises:

Type	Description
SeretoPathError	If the file does not exist.
SeretoValueError	If the file size is not within the specified range.

Source code in sereto/utils.py

@validate_call
def assert_file_size_within_range(
    file: FilePath, max_bytes: int, min_bytes: int = 0, interactive: bool = False
) -> None:
    """Evaluates if the file size is within the specified range.

    If `interactive` is True, the user is first prompted whether to continue if the file size is not within the range.

    Args:
        file: The path to the file.
        max_bytes: The maximum file size in bytes.
        min_bytes: The minimum file size in bytes. Defaults to 0.
        interactive: If True, the user is prompted whether to continue if the file size is not within the range.
            Defaults to False.

    Raises:
        SeretoPathError: If the file does not exist.
        SeretoValueError: If the file size is not within the specified range.
    """
    # Check the input values
    if not file.is_file():
        raise SeretoPathError(f"File '{file}' does not exist")

    if not 0 <= min_bytes <= max_bytes:
        raise SeretoValueError(f"Invalid size threshold range: {min_bytes} - {max_bytes}")

    # Get the file size in bytes
    size = file.stat().st_size

    # Check if the file size is within the specified range
    if min_bytes <= size <= max_bytes:
        return

    # File size is not within the range

    logger.warning(
        "File '{}' size is {}, which is outside the allowed range {} - {}",
        file,
        naturalsize(size, binary=True),
        naturalsize(min_bytes, binary=True),
        naturalsize(max_bytes, binary=True),
    )

    # In interactive mode, user can choose to continue
    if interactive and click.confirm("Do you want to continue?", default=False):
        return

    # Otherwise, raise an error
    raise SeretoValueError(f"File '{file}' size is not within the range {min_bytes} - {max_bytes} B")

copy_skel(templates, dst, overwrite=False)

Copy the content of a templates skel directory to a destination directory.

A skel directory is a directory that contains a set of files and directories that can be used as a template for creating new projects. This function copies the contents of the skel directory located at the path specified by templates to the destination directory specified by dst.

Parameters:

Name	Type	Description	Default
templates	DirectoryPath	The path to the directory containing the skel directory.	required
dst	DirectoryPath	The destination directory to copy the skel directory contents to.	required
overwrite	bool	Whether to allow overwriting of existing files in the destination directory. If True, existing files will be overwritten. If False (default), a SeretoPathError will be raised if the destination already exists.	False

Raises:

Type	Description
SeretoPathError	If the destination directory already exists and overwrite is False.

Source code in sereto/utils.py

@validate_call
def copy_skel(templates: DirectoryPath, dst: DirectoryPath, overwrite: bool = False) -> None:
    """Copy the content of a templates `skel` directory to a destination directory.

    A `skel` directory is a directory that contains a set of files and directories that can be used as a template
    for creating new projects. This function copies the contents of the `skel` directory located at
    the path specified by `templates` to the destination directory specified by `dst`.

    Args:
        templates: The path to the directory containing the `skel` directory.
        dst: The destination directory to copy the `skel` directory contents to.
        overwrite: Whether to allow overwriting of existing files in the destination directory.
            If `True`, existing files will be overwritten. If `False` (default), a `SeretoPathError` will be raised
            if the destination already exists.

    Raises:
        SeretoPathError: If the destination directory already exists and `overwrite` is `False`.
    """
    skel_path: Path = templates / "skel"

    logger.info("Copying 'skel' directory: '{}' -> '{}'", skel_path, dst)

    for item in skel_path.iterdir():
        dst_item: Path = dst / (item.relative_to(skel_path))
        if not overwrite and dst_item.exists():
            raise SeretoPathError("Destination already exists")
        if item.is_file():
            logger.info("[green]+[/green] copy file: '{}'", escape(str(item.relative_to(skel_path))), markup=True)
            copy2(item, dst_item, follow_symlinks=False)
        if item.is_dir():
            logger.info("[green]+[/green] copy dir: '{}'", escape(str(item.relative_to(skel_path))), markup=True)
            copytree(item, dst_item, dirs_exist_ok=overwrite)

lower_alphanum(text)

Converts the input text to lowercase alphanumerical delimited by underscores.

Also all spaces are replaced with underscores.

Parameters:

Name	Type	Description	Default
text	str	The input text.	required

Returns:

Type	Description
str	The input text with the modifications applied.

Source code in sereto/utils.py

@validate_call
def lower_alphanum(text: str) -> str:
    """Converts the input text to lowercase alphanumerical delimited by underscores.

    Also all spaces are replaced with underscores.

    Args:
        text: The input text.

    Returns:
        The input text with the modifications applied.
    """
    normalized = unicodedata.normalize("NFKD", text)
    ascii_text = normalized.encode("ascii", "ignore").decode("ascii").lower()
    ascii_text = re.sub(r"[^a-z0-9_\s]", "", ascii_text)
    return re.sub(r"\s+", "_", ascii_text)

replace_strings(text, replacements)

replace_strings(text: str, replacements: dict[str, str]) -> str

replace_strings(text: list[str], replacements: dict[str, str]) -> list[str]

One-pass string replacement with values from dictionary.

Parameters:

Name	Type	Description	Default
text	str | list[str]	The input text.	required
replacements	dict[str, str]	Dictionary with replacements. Key-value in dictionary refers to pattern string and replacement string, respectively.	required

Returns:

Type	Description
str | list[str]	String (or list of strings, depending on the input value) obtained by applying the replacements from the replacements dictionary.

Source code in sereto/utils.py

@validate_call
def replace_strings(text: str | list[str], replacements: dict[str, str]) -> str | list[str]:
    """One-pass string replacement with values from dictionary.

    Args:
        text: The input text.
        replacements: Dictionary with replacements. Key-value in dictionary refers to pattern string and replacement
            string, respectively.

    Returns:
        String (or list of strings, depending on the input value) obtained by applying the replacements from the
            `replacements` dictionary.
    """

    @validate_call
    def _clip(value: str, max_chars: Annotated[int, Field(ge=3)] = 120) -> str:
        return value if len(value) <= max_chars else f"{value[: max_chars - 3]}..."

    @validate_call
    def _preview_text(
        value: str | list[str],
        max_chars: Annotated[int, Field(ge=1)] = 120,
        max_items: Annotated[int, Field(ge=1)] = 5,
    ) -> str:
        if isinstance(value, str):
            return _clip(value, max_chars=max_chars)
        items: list[str] = []
        for idx, item in enumerate(value):
            if idx >= max_items:
                items.append(f"... (+{len(value) - max_items} more)")
                break
            items.append(_clip(item, max_chars=max_chars))
        return f"[{', '.join(items)}]"

    @validate_call
    def _preview_replacements(
        max_items: Annotated[int, Field(ge=1)] = 5, max_chars: Annotated[int, Field(ge=3)] = 80
    ) -> str:
        pairs: list[str] = []
        for idx, (pattern_key, pattern_value) in enumerate(replacements.items()):
            if idx >= max_items:
                pairs.append(f"... (+{len(replacements) - max_items} more)")
                break
            pairs.append(f"{_clip(pattern_key, max_chars=max_chars)}->{_clip(pattern_value, max_chars=max_chars)}")
        return ", ".join(pairs)

    text_len = len(text)
    replacements_count = len(replacements)

    logger.trace(
        "replace_strings called (text_type={}, text_len={}, replacements_count={}, text_preview='{}', "
        "replacements_preview={})",
        type(text).__name__,
        text_len,
        replacements_count,
        _preview_text(text),
        _preview_replacements(),
    )

    if text_len == 0 or replacements_count == 0:
        logger.debug(
            "replace_strings returning input unchanged (text_len={}, replacements={})",
            text_len,
            replacements_count,
        )
        return text

    pattern_source = "|".join([re.escape(rep) for rep in replacements])
    pattern = re.compile(pattern_source)

    if isinstance(text, str):
        result = pattern.sub(lambda match: replacements[match.group(0)], text)
        logger.trace(
            "replace_strings applied to string (before_len={}, after_len={}, replacements={}, before_preview='{}', "
            "after_preview='{}')",
            len(text),
            len(result),
            replacements_count,
            _preview_text(text),
            _preview_text(result),
        )
        return result

    result_list = [pattern.sub(lambda match: replacements[match.group(0)], item) for item in text]
    changed = sum(1 for original, updated in zip(text, result_list, strict=True) if original != updated)
    logger.debug(
        "replace_strings applied to list[str] (items={}, changed={}, replacements={}, before_preview={}, "
        "after_preview={})",
        len(result_list),
        changed,
        replacements_count,
        _preview_text(text),
        _preview_text(result_list),
    )
    return result_list

write_if_different(file, content)

Writes content to file only if the content is different from the existing file content.

Parameters:

Name	Type	Description	Default
file	Path	The path to the file.	required
content	str	The content to write to the file.	required

Returns:

Type	Description
bool	True if new content was written to the file, False otherwise.

Source code in sereto/utils.py

@validate_call
def write_if_different(file: Path, content: str) -> bool:
    """Writes content to file only if the content is different from the existing file content.

    Args:
        file: The path to the file.
        content: The content to write to the file.

    Returns:
        True if new content was written to the file, False otherwise.
    """
    # Check if the file exists and has the same size
    if file.is_file() and file.stat().st_size == len(content):
        assert_file_size_within_range(file=file, max_bytes=104_857_600)  # 100 MiB
        # Check if the content is the same
        if file.read_text(encoding="utf-8") == content:
            return False

    # Changes detected, write the content to the file
    file.write_text(content, encoding="utf-8")
    return True