Note

This README was created with the help of NotebookLM

Important

This script is not perfect so I recommend caution using it

Normalize Filename Paths Script

This script is a Python utility designed to recursively normalize the names of files and directories within a specified execution path.

It prioritises safety, logging all operations, warnings, and errors.

Requirements

• Python: Requires Python version 3.14 or greater.
• uv: Requires uv to run
• Dependencies: The script requires the loguru library.
  • (Note: The script header suggests using uv run --script for execution, which manages these requirements).

Run

uv run normalize-files-dirs-names.py

Functionality and Normalization Process

The script operates on the base_path, which defaults to the current working directory (Path.cwd()). It iterates through all files and directories recursively using base_path.rglob("*").

The normalization process (normaliza_path_name) includes the following steps:

1. Unicode Normalization: The path name is normalized using the NFKD Unicode form (unicodedata.normalize("NFKD", path_name)).
2. ASCII Conversion: The name is encoded to ASCII, ignoring any non-ASCII characters, and then decoded back to UTF-8.
3. Character Replacement: Spaces (" ") and underscores ("_") are replaced with hyphens ("-").

If the resulting new_name is different from the original name, the script attempts to rename the path. The renaming operation is logged using an informational message.

Safety Features and Conflict Handling

Critical Directory Warning

The script includes a critical safety check to prevent accidental execution in sensitive system directories. The script will not execute if the base_path is detected as:

• The home directory (Path.home())
• The configuration directory (CONFIG_PATH)
• The root path (ROOT_PATH)

If executed in one of these locations, an error is logged.

Existing Path Conflict

Before renaming, the script checks if the new_path already exists.

• If the target path exists, the script logs a warning and skips the renaming of the original file/directory to prevent overwriting or data loss.

Logging

The script uses loguru to handle all output.

All operations, warnings, and errors are written to a dedicated log file named normalize-files-dirs-names.log. The log file includes backtrace, diagnosis, and serialisation features enabled.