File Renamer

A Python utility script that renames files in a folder based on mappings defined in a CSV file. This tool is useful for batch renaming files while maintaining a clear record of the changes.

Features

• CSV-based rename mapping
• Dry-run mode to preview changes
• Validation checks to prevent naming conflicts
• Detailed error reporting
• UTF-8 support for international filenames

Requirements

• Python 3.6 or higher
• No additional dependencies required (uses only standard library)

Installation

1. Clone or download the script to your local machine
2. Ensure you have Python 3.6+ installed
3. No additional installation steps required

Usage

Prepare Your CSV File

Create a CSV file with two columns:

• original_name: The current filename
• new_name: The desired new filename

Example rename_mapping.csv:

original_name,new_name
old_document.pdf,new_document.pdf
report2023.txt,final_report.txt
image001.jpg,profile_photo.jpg

Basic Usage

Run the script with the CSV file and target folder as arguments:

python rename_files.py path/to/mapping.csv path/to/folder

Preview Changes

Use the --dry-run option to see what changes would be made without actually renaming files:

python rename_files.py path/to/mapping.csv path/to/folder --dry-run

Safety Features

The script includes several safety measures:

1. CSV Validation

   • Checks for required columns
   • Validates CSV format
   • Uses UTF-8 encoding for international character support

2. File Operation Validation

   • Verifies source files exist
   • Prevents duplicate destination names
   • Checks for existing destination files
   • Validates file paths

3. Error Handling

   • Detailed error messages for each failed operation
   • Continues processing even if individual renames fail
   • Reports warnings for potential issues

Error Messages

Common error messages and their meanings:

• "CSV must have 'original_name' and 'new_name' columns": The CSV file is missing required columns
• "Source file '{filename}' not found in folder": A file listed in the CSV doesn't exist
• "Multiple files would be renamed to '{filename}'": The CSV contains duplicate destination names
• "Destination '{filename}' already exists": A target filename already exists in the folder

Examples

Basic Rename Operation

python rename_files.py mapping.csv /path/to/files

Example output:

Renamed 'old_document.pdf' to 'new_document.pdf'
Renamed 'report2023.txt' to 'final_report.txt'
Warning: Source file 'missing_file.txt' not found in folder

Dry Run

python rename_files.py mapping.csv /path/to/files --dry-run

Example output:

Would rename 'old_document.pdf' to 'new_document.pdf'
Would rename 'report2023.txt' to 'final_report.txt'
Warning: Source file 'missing_file.txt' not found in folder

Contributing

Feel free to submit issues and enhancement requests!

License

This project is licensed under the MIT License - feel free to use it in your own projects.