API Reference

Date/time utility functions for high-precision local timestamps.

date_time_functions.date_time_functions.date_time_stamp() → str

Returns a high-precision local timestamp string including:

• Gregorian calendar date

• Local time with nanosecond precision

• IANA time zone

• ISO week format: YYYY-Www-ddd

• Ordinal day of the year

Format:

‘YYYY-MMM-DDD HHH.MMM.SSS.NNNNNNNNN TZ_NAME YYYY-Www-ddd YYYY-DDD’

Example

>>> date_time_stamp()
'2025-007-030 016.035.051.123456789 America/New_York 2025-W031-003 2025-211'

Returns:

Formatted timestamp string with nanosecond precision and multiple calendar representations.

Return type:

str

date_time_functions.date_time_functions.generate_pdb_name_from_timestamp() → str

Generates a dynamic PDB name in the format: pdb_<YYYY>_<MMM>_<DDD>_<HHH>_<MMM>_<SSS>

Example

pdb_2025_007_031_017_020_008

Returns:

Dynamically constructed PDB name based on the current local time.

Return type:

str

date_time_functions.date_time_functions.generate_prefixed_timestamp(prefix: str) → str

Generates a high-precision, time zone-aware timestamp string with a given prefix.

The format returned is:

<prefix>_YYYY_MMM_DDD_HHH_MMM_SSS_NNNNNNNNN_TimeZone_ISOYEAR_WWWW_WEEKDAY_YYYY_DOY

Example

big_data_test_2025_007_031_019_007_040_353635000_America_slash_New_York_2025_W031_004_2025_212

Parameters:

prefix (str) – A string prefix such as “big_data_test” or “everyday_calculations”.

Returns:

A formatted timestamp string with the given prefix.

Return type:

str

date_time_functions.date_time_functions.get_timestamp() → str

Returns a high-precision, time zone-aware timestamp string: YYYY_MMM_DDD_HHH_MMM_SSS_NNNNNNNNN_TimeZone_ISOYEAR_WWWW_WEEKDAY_YYYY_DOY_UnixSeconds_Nanoseconds

Example

2025_008_004_013_048_029_083107000_America_slash_New_York_2025_W032_001_2025_216_1754681668_083107000

Image functions/utilities.

image_functions.image_functions.compare_images(image1_path: str, image2_path: str) → None

Compare two images using multiple techniques:

• SHA-256 hash comparison (byte-level)

• Pixel-by-pixel comparison using Pillow (ImageChops)

• Structural Similarity Index (SSIM) using scikit-image

• ImageMagick ‘compare’ with Absolute Error (AE) metric

Outputs detailed results and stores an ImageMagick diff image in a unique temporary folder based on a UUID.

Parameters:

• image1_path (str) – Path to the first image.

• image2_path (str) – Path to the second image.

image_functions.image_functions.sha256_hash(filepath: str) → str

Compute the SHA-256 hash of a file.

System management utilities.

system_management_functions.system_management_functions.convert_blob_to_raw_github_url(blob_url: str) → str

Converts a GitHub “blob” URL to a “raw” content URL.

GitHub blob URL:

https://github.com/{user}/{repo}/blob/{branch}/{path}

Converted raw URL:

https://github.com/{user}/{repo}/raw/{branch}/{path}

Parameters:

blob_url (str) – The GitHub blob URL to convert.

Returns:

The converted raw GitHub URL.

Return type:

str

Raises:

ValueError – If the input URL does not contain “/blob/”.

system_management_functions.system_management_functions.get_file_size(path: str | Path) → int

Returns the size in bytes of a file or directory. Accepts either a string path or a Path object.

system_management_functions.system_management_functions.get_file_size_human_readable(path: str | Path) → str

Returns the size of the file or directory in a human-readable format. Supports units: bytes, KB, MB, GB, TB (3 decimal places). Accepts str or Path input.

system_management_functions.system_management_functions.valid_Windows_filename(name: str | Path) → bool

Checks whether a given filename is valid according to Windows naming rules.

This function is a simplified wrapper around validate_Windows_filename_with_reasons that returns only a boolean indicating validity.

Parameters:

name (str or Path) – The filename to check.

Returns:

True if the filename is valid, False otherwise.

Return type:

bool

system_management_functions.system_management_functions.validate_Windows_filename_with_reasons(name: str | Path) → dict

Validates a Windows filename against Microsoft’s file naming restrictions.

This function uses a JSON ruleset hosted on GitHub that defines: - Disallowed characters grouped by category - Reserved device names (e.g., CON, NUL, COM1) - Forbidden trailing characters (space or period)

The JSON rules are retrieved via HTTP with up to 100 retries using the requests library.

Parameters:

name (str or Path) – The filename to validate (e.g., “nul.txt”).

Returns:

A dictionary indicating whether the filename is valid.

If valid:

{

“valid”: True

}

If invalid:

{

“valid”: False, “problems”: [

{

“character”: “<offending character or name>”, “reason”: “<explanation of the problem>”

]

}

Return type:

dict

Raises:

• RuntimeError – If the rules file cannot be retrieved after 100 attempts.

• ValueError – If the GitHub blob URL is malformed.