fitzzftw.patch.utils

General Utilities and Configuration Handling

This module provides helper functions for filesystem operations, string normalization, and hierarchical configuration merging.

Core Functions:

  • get_string_of_type:

    A robust helper to extract human-readable names from type objects or strings. It ensures consistent naming even when dealing with complex Protocols or edge cases where a simple __name__ access might fail.

  • get_backup_extension:

    Normalizes backup extensions and handles dynamic keywords like ‘timestamp’ to generate ISO-compliant suffixes.

  • get_merged_config:

    Implements the configuration layering logic, merging project-specific TOML files with global user preferences.

Key Features:

  • Configuration Priority:

    Ensures that pyproject.toml settings always override user-level defaults to maintain project standards.

  • Platform Awareness:

    Uses platformdirs.user_config_path() to correctly resolve user configuration paths across different operating systems.

Functions

get_backup_extension(ext[, now])

Normalize the backup extension and handle dynamic keywords.

get_merged_config([app_name, manual_user_cfg])

Merge configuration from hierarchical sources into a single dictionary.

get_string_of_type(protocol_type)

Extracts a human-readable string representation of a type.

replace_keywords_to_isodatetime(path_str, now)

Replace predefined placeholders in a path string with an ISO timestamp.
get_backup_extension(ext, now=datetime.datetime(2026, 4, 2, 10, 1, 18, 305967))[source]

Normalize the backup extension and handle dynamic keywords.

This function cleans the input by removing outer whitespace and dots. If a keyword from DATETIME_KEYWORDS is detected, it is replaced by an ISO 8601 compliant timestamp.

Parameters:

  • ext (str) – The extension string or a valid datetime keyword.

  • now (datetime) – The datetime.datetime object used for timestamp generation.

Returns:

A normalized extension string starting with a dot and including the timestamp if a keyword was used.

Return type:

str

get_merged_config(app_name='ftw', manual_user_cfg='')[source]

Merge configuration from hierarchical sources into a single dictionary.

This function implements the configuration layering logic before the Pimple-object (args) is fully initialized. It resolves the ‘chicken-and-egg’ problem of locating the user configuration file via CLI before parsing the remaining arguments.

The priority order for settings (highest to lowest):

  1. Project Configuration: Defined in ‘pyproject.toml’ under [tool.fitzzftw.patch]. This level ensures project-specific standards (e.g., .gitignore compliance) always override global user preferences.

  2. Manual User Configuration: A TOML file specified via the ‘–userconfig’ flag.

  3. Platform User Configuration: The default OS-specific path (e.g., ~/.config/ftw/patch.toml on Linux).

Parameters:

  • app_name (str) – The application namespace used for platformdirs resolution.

  • manual_user_cfg (str) – Optional filesystem path to a custom TOML config.

Raises:

  • tomllib.TOMLDecodeError – If any encountered TOML file is syntactically invalid.

  • OSError – If there are permission issues accessing the configuration files.

Returns:

A dictionary containing the effective configuration defaults.

Return type:

dict

get_string_of_type(protocol_type)[source]

Extracts a human-readable string representation of a type.

This helper is used during protocol introspection to handle both actual class objects and pre-defined type strings. If the input has a ‘__name__’ attribute (e.g., a class), it returns that name; otherwise, it returns the input as is.

Parameters:

protocol_type – The type object or string to convert.

Returns:

A string representation of the type.

Return type:

str

replace_keywords_to_isodatetime(path_str, now)[source]

Replace predefined placeholders in a path string with an ISO timestamp.

This function searches the string for tokens defined in DATETIME_KEYWORDS enclosed by ‘@’ characters. It replaces them with a timestamp generated from ‘now’ using the format YYYYMMDDTHHMMSS.

Parameters:

  • path_str (str) – The path or filename string to process.

  • now (datetime) – The datetime.datetime object used as the source for the timestamp.

Returns:

The string containing the resolved timestamps.

Return type:

str