replace_pattern

replace_pattern

Functions

Name	Description
replace_pattern	Replace specific patterns in filenames within a directory.

replace_pattern

replace_pattern.replace_pattern(pattern, replacement, dir=None)

Replace specific patterns in filenames within a directory.

This function iterates over all files in the specified directory and renames them by substituting a target string or character with a new one. This is useful for targeted batch updates, such as swapping delimiters or correcting specific naming errors.

The following transformations are applied: 1. All occurrences of the input pattern within the filename root are replaced by the replacement string. 2. File extensions are preserved and excluded from the replacement logic. 3. Directory structure remains unchanged; only the filenames are modified.

Parameters

Name	Type	Description	Default
pattern	str	The substring or character pattern to search for in filenames.	required
replacement	str	The string or character to insert in place of the found pattern.	required
dir	str	Path to the directory containing files to be modified. If None, defaults to the current working directory.	None

Returns

Name	Type	Description
	bool	True if any files were renamed, False otherwise.

Raises

Name	Type	Description
	FileNotFoundError	If the specified directory path does not exist.
	NotADirectoryError	If the path points to a file instead of a directory.
	PermissionError	If insufficient permissions to rename files in the directory.

Examples

>>> replace_pattern("_", " & ", "docs/")
Renames files like:
"file_janitors.txt" -> "file & janitors.txt"
"report_v1_final.pdf" -> "report & v1 & final.pdf"

>>> replace_pattern("_", " ")  # Uses current directory
Renames files in current working directory.

Notes

• Only the filename root is modified; file extensions are always preserved
• All occurrences of the pattern within each filename are replaced
• Directory structure remains unchanged
• Files without the pattern in their name are left unchanged
• Hidden files (starting with .) are processed unless explicitly excluded