theca-procurator 0.1.0
Desktop File & Folder Utility
Requires Python: >=3.9

# Theca Procurator User Guide

## Overview

**Theca Procurator** is a powerful desktop file and folder utility designed to simplify common file management tasks. Whether you need to create multiple copies of a folder with sequential names, rename hundreds of files at once, or perform advanced pattern-based renaming, Theca Procurator provides an intuitive interface to get the job done quickly and safely.

### What Can Theca Procurator Do?

- **Duplicate Folders Sequentially**: Create multiple numbered copies of a folder (e.g., "Project_001", "Project_002", "Project_003")
- **Bulk Rename Files**: Rename multiple files at once using an import list
- **Advanced Regex Renaming**: Use powerful pattern matching and sequential numbering to rename files with precision
- **Safe Operations**: Preview all changes before applying them, with pause/resume capabilities for long operations

### Who Is This For?

- **Photographers** organizing photo shoots into numbered folders
- **Project Managers** creating standardized project folder structures
- **Data Organizers** batch renaming files according to naming conventions
- **Anyone** who regularly performs repetitive file and folder operations

---

## System Requirements

### Operating System
- **Windows** 10 or later (primary platform)
- **macOS** 10.14+ (compatible)
- **Linux** (compatible with modern distributions)

### Software Requirements
- **Python 3.9 or later** (if running from source)
- **No additional software required** if using the packaged executable

### Hardware Requirements
- **Processor**: Any modern CPU
- **RAM**: 512 MB minimum, 1 GB recommended
- **Disk Space**: 100 MB for installation
- **Display**: 1024x768 minimum resolution

---

## Installation

### Option 1: Using the Executable (Recommended for Most Users)

1. **Download** the latest release from your distribution source
2. **Extract** the ZIP file to a location on your computer (e.g., `C:\Program Files\Theca Procurator`)
3. **Run** `Theca Procurator.exe` (Windows) or the application file for your platform
4. **Optional**: Create a desktop shortcut for easy access

### Option 2: Running from Source (For Advanced Users)

1. **Install Python 3.9 or later** from [python.org](https://www.python.org)

2. **Download or clone** the Theca Procurator source code

3. **Open a terminal/command prompt** and navigate to the installation directory:
   ```bash
   cd "path/to/Theca Procurator/Code/Python/Main"
   ```

4. **Install required packages**:
   ```bash
   pip install ttkbootstrap yapsy toml
   ```

5. **Run the application**:
   ```bash
   python run/run_theca_procurator.py
   ```
   
   Or on Windows, simply double-click `run\RUN.bat`

### First Launch

When you first launch Theca Procurator, you'll see a splash screen followed by the main application window. The application is ready to use immediately with no additional configuration required.

---

## Getting Started

### Launching the Program

- **Windows**: Double-click the `Theca Procurator.exe` icon
- **macOS/Linux**: Run the application from your Applications folder or terminal
- **From Source**: Run `RUN.bat` (Windows) or execute `python run/run_theca_procurator.py`

### Understanding the Main Window

When Theca Procurator opens, you'll see:

1. **Menu Bar** (at the top):
   - **File**: Exit the application
   - **Edit**: Undo/Redo operations (coming soon)
   - **Help**: About information and version details

2. **Tab Bar**: Three main tabs for different operations:
   - **Duplicate Folders**: Create multiple sequential folder copies
   - **Bulk Rename**: Rename files from an import list
   - **Regex Rename**: Advanced pattern-based file renaming

3. **Status Bar** (at the bottom): Shows current operation status and messages

4. **Scrollable Content Area**: Each tab contains its own set of controls and preview areas

### Choosing Your Operation

Click on any tab to access that feature. Each tab is self-contained with all the controls you need for that specific operation.

---

## Main Features

### Feature 1: Duplicate Folders

The Duplicate Folders feature creates multiple copies of a source folder with sequential numbering. Perfect for creating project templates, organizing photo shoots, or setting up standardized folder structures.

#### How to Use Duplicate Folders

1. **Select Source Folder**:
   - Click the **Browse** button next to "Source Folder"
   - Navigate to and select the folder you want to duplicate
   - The folder path will appear in the text field

2. **Select Destination Folder**:
   - Click the **Browse** button next to "Destination Folder"
   - Choose where you want the duplicated folders to be created
   - This can be the same location as the source or a different location

3. **Configure Naming**:
   - **Base Name**: Enter the base name for your folders (e.g., "Project", "PhotoShoot")
   - **Number of Copies**: Specify how many copies to create (e.g., 5)
   - **Start Number**: Choose the starting number for the sequence (default: 1)
   - **Padding**: Set how many digits to use for numbering (e.g., 3 = "001", "002", "003")

4. **Preview Your Folders**:
   - Click **Generate Preview**
   - Review the list of folder names that will be created
   - Example output: `Project_001`, `Project_002`, `Project_003`, etc.

5. **Start Duplication**:
   - Click **Start** to begin the operation
   - A progress bar shows the current status
   - You can **Pause** or **Cancel** at any time during the operation

6. **Monitor Progress**:
   - Watch the progress bar fill as folders are created
   - The status label shows which folder is currently being processed
   - When complete, a confirmation message appears

#### Tips for Duplicate Folders

- **Test First**: Start with a small number of copies to verify the naming pattern
- **Padding**: Use padding of 2 for up to 99 folders, 3 for up to 999 folders
- **Pause Feature**: Use Pause if you need to temporarily stop a long operation
- **Existing Folders**: If a destination folder already exists, it will be skipped

#### Example Use Cases

- **Photography**: Create "Shoot_001" through "Shoot_050" for a year's worth of photo sessions
- **Projects**: Set up "Client_Project_001" through "Client_Project_020" for new clients
- **Archiving**: Create "Backup_2026_01" through "Backup_2026_12" for monthly backups

---

### Feature 2: Bulk Rename from List

The Bulk Rename feature allows you to rename multiple files based on a text file containing old and new names. Ideal for batch renaming files according to a predefined list.

#### How to Use Bulk Rename

1. **Prepare Your Import File**:
   - Create a text file (`.txt` or `.csv`) with two columns
   - **First column**: Current filename (without path)
   - **Second column**: New filename
   - Separate columns with a delimiter (tab, comma, or custom character)
   
   Example file content (tab-delimited):
   ```
   IMG_001.jpg    Vacation_Beach_01.jpg
   IMG_002.jpg    Vacation_Beach_02.jpg
   IMG_003.jpg    Vacation_Beach_03.jpg
   ```

2. **Select Import File**:
   - Click **Browse** next to "Import File"
   - Select your prepared text file
   - The file path will appear in the text field

3. **Specify Delimiter**:
   - Enter the delimiter used in your file
   - Common delimiters: `\t` (tab), `,` (comma), `|` (pipe)
   - For multi-character delimiters, type them directly (e.g., `::`)

4. **Select Target Folder**:
   - Click **Browse** next to "Target Folder"
   - Choose the folder containing the files to be renamed
   - The application will search this folder and all subfolders

5. **Search and Preview**:
   - Click **Search & Preview**
   - The preview table shows:
     - **Current Path**: Where the file is located (hover for full path)
     - **Old Name**: Current filename
     - **New Name**: Proposed new filename
   - Review carefully to ensure the mapping is correct

6. **Execute Rename**:
   - Click **Execute Rename** to perform the renaming
   - A confirmation dialog appears showing how many files will be renamed
   - Click **Yes** to proceed
   - A success message shows how many files were renamed

#### Tips for Bulk Rename

- **Backup First**: Always keep a backup of your files before bulk renaming
- **Check Preview**: Carefully review the preview table before executing
- **File Extensions**: Include file extensions in both old and new names
- **Path Tooltips**: Hover over truncated paths in the preview to see the full path
- **Case Sensitive**: File matching is case-sensitive on some operating systems

#### Example Use Cases

- **Media Libraries**: Rename downloaded files to match your naming convention
- **Document Management**: Standardize document names across a project
- **Photo Organization**: Rename camera files to descriptive names

---

### Feature 3: Regex Rename (Advanced)

The Regex Rename feature provides powerful pattern-based renaming with support for:
- Regular expression find and replace
- Sequential prefix/suffix numbering
- Literal prefix/suffix text
- Custom separators

This is the most flexible renaming tool, perfect for complex renaming scenarios.

#### How to Use Regex Rename

1. **Select Target Folder**:
   - Click **Browse** next to "Target Folder"
   - Choose the folder containing files to rename
   - All files in the folder and subfolders will be included

2. **Configure Prefix** (Optional):
   - Choose **None**, **Literal**, or **Sequential**
   
   **Literal Prefix**:
   - Enter fixed text to add at the beginning (e.g., "Photo_")
   
   **Sequential Prefix**:
   - **Start Number**: First number in sequence (e.g., 1)
   - **Increment**: How much to increase each time (e.g., 1)
   - **Padding**: Number of digits (e.g., 3 = "001")

3. **Configure Suffix** (Optional):
   - Choose **None**, **Literal**, or **Sequential**
   - Works the same as prefix but adds to the end of the filename

4. **Set Separator**:
   - Enter a character to separate prefix/suffix from the filename
   - Common separators: `_` (underscore), `-` (dash), ` ` (space)
   - Leave blank for no separator

5. **Configure Regex Find/Replace** (Optional):
   - **Find Pattern**: Enter a regular expression pattern to find
   - **Replace With**: Enter the replacement text
   - This operates on the filename (without extension) after prefix/suffix
   
   Example patterns:
   - Find: `IMG` → Replace: `Photo` (replaces "IMG" with "Photo")
   - Find: `\d+` → Replace: `` (removes all numbers)
   - Find: `[_-]` → Replace: ` ` (replaces underscores/dashes with spaces)

6. **Generate Preview**:
   - Click **Generate Preview**
   - The preview table shows:
     - **Current Path**: File location (hover for full path)
     - **Old Name**: Current filename
     - **New Name**: Proposed new filename
   - **Select Rows**: Click rows to select/deselect them (Ctrl+Click for multiple)
   - **Selected rows** appear in light blue text
   - Only selected rows will be renamed

7. **Execute Rename**:
   - Click **Execute Rename**
   - Only files with selected rows will be renamed
   - A confirmation dialog shows the count
   - Progress bar displays during the operation

#### Tips for Regex Rename

- **Start Simple**: Test with a few files first before processing large batches
- **Row Selection**: Use row selection to rename only specific files
- **Preview Carefully**: The preview shows exactly what will happen
- **Regex Help**: If unfamiliar with regex, start with simple literal text replacements
- **Settings Saved**: Your last-used settings are automatically saved for next time
- **File Extensions**: Extensions are always preserved

#### Example Use Cases

**Example 1: Add Sequential Numbers**
- Prefix: Sequential (Start: 1, Increment: 1, Padding: 3)
- Separator: `_`
- Result: `001_filename.jpg`, `002_filename.jpg`, etc.

**Example 2: Clean Up Camera Files**
- Find: `DSC` → Replace: `Photo`
- Suffix: Sequential (Start: 1, Increment: 1, Padding: 2)
- Separator: `_`
- Result: `Photo_01.jpg`, `Photo_02.jpg`, etc.

**Example 3: Remove Dates**
- Find: `\d{4}-\d{2}-\d{2}` → Replace: `` (empty)
- Result: Removes date patterns like "2026-01-03"

**Example 4: Standardize Naming**
- Find: `[_-]` → Replace: ` ` (space)
- Prefix: Literal "Project"
- Separator: `_`
- Result: Converts "old_file-name.txt" to "Project_old file name.txt"

#### Understanding Row Selection

- **Click a row** to select it (text turns light blue)
- **Click again** to deselect it (text returns to white)
- **Ctrl+Click** to select multiple rows
- **Only selected rows** will be renamed when you click Execute Rename
- **Light gray borders** separate rows for easy reading

---

## Settings and Configuration

### Accessing Settings

Currently, most settings are configured through the `config.toml` file located in the application directory. Future versions will include a Settings dialog accessible from the menu.

### Available Settings

#### UI Theme
- **Current Theme**: Darkly (dark mode)
- **Location**: `config.toml` → `[ui]` → `theme`
- **Options**: darkly, flatly, cosmo, litera, minty, pulse, sandstone, united, yeti, and more
- **How to Change**: Edit the config file and restart the application

#### Window Size
- **Default Size**: 1000x700 pixels
- **Minimum Size**: 800x600 pixels
- **Location**: `config.toml` → `[ui]` section

#### Operation Defaults
- **Folder Duplication**:
  - Default padding: 3 digits
  - Default start number: 1
  - Default count: 5 folders

- **Bulk Rename**:
  - Default padding: 2 digits
  - Default start number: 1
  - Default increment: 1

#### Persistence Settings
- **Remember Last Source**: Yes (enabled by default)
- **Remember Last Destination**: Yes (enabled by default)
- **Remember Last Parameters**: Yes (enabled by default)

These settings ensure your last-used folders and parameters are remembered between sessions.

### Undo/Redo Settings
- **Maximum Undo Steps**: 10 (configurable in `config.toml`)
- **Note**: Full undo/redo functionality is planned for a future release

---

## Troubleshooting

### Common Issues and Solutions

#### Issue: Application Won't Start

**Symptoms**: Double-clicking the executable does nothing, or an error appears immediately.

**Solutions**:
1. **Check Python Version** (if running from source):
   - Open a terminal and type: `python --version`
   - Ensure it's Python 3.9 or later
   
2. **Check Dependencies** (if running from source):
   - Run: `pip install ttkbootstrap yapsy toml`
   
3. **Check Logs**:
   - Look for `debug.log` in the application directory
   - Open it with a text editor to see error messages
   
4. **Run from Terminal**:
   - Open a terminal/command prompt
   - Navigate to the application directory
   - Run: `python run/run_theca_procurator.py`
   - This will show any error messages

#### Issue: "Permission Denied" Errors

**Symptoms**: Operations fail with permission errors, especially when renaming or copying files.

**Solutions**:
1. **Check File Permissions**:
   - Ensure you have write access to the target folders
   - On Windows, right-click the folder → Properties → Security
   
2. **Close Other Programs**:
   - Make sure no other program has the files open
   - Close Excel, Word, image viewers, etc.
   
3. **Run as Administrator** (Windows):
   - Right-click the executable → "Run as administrator"
   
4. **Check Antivirus**:
   - Some antivirus software may block file operations
   - Temporarily disable or add an exception

#### Issue: Files Not Found During Bulk Rename

**Symptoms**: The preview table shows "0 files found" or fewer files than expected.

**Solutions**:
1. **Check File Names**:
   - Ensure the old names in your import file match exactly
   - File names are case-sensitive on some systems
   
2. **Check Delimiter**:
   - Verify you're using the correct delimiter
   - Common mistake: using comma when file uses tab
   
3. **Check Target Folder**:
   - Ensure you selected the correct folder
   - The search includes all subfolders
   
4. **Check Import File Format**:
   - Open your import file in a text editor
   - Verify it has two columns separated by your delimiter

#### Issue: Preview Table Shows Truncated Paths

**Symptoms**: File paths in the preview table are cut off with "..."

**Solutions**:
- This is normal for long paths
- **Hover your mouse** over the truncated path to see the full path in a tooltip
- The full path is always used for operations, even if truncated in display

#### Issue: Regex Pattern Not Working

**Symptoms**: The regex find/replace doesn't change filenames as expected.

**Solutions**:
1. **Test Your Pattern**:
   - Use an online regex tester (e.g., regex101.com)
   - Test with sample filenames first
   
2. **Escape Special Characters**:
   - Characters like `.`, `*`, `+`, `?`, `[`, `]` have special meaning
   - Escape them with a backslash: `\.` for a literal period
   
3. **Start Simple**:
   - Begin with literal text replacement
   - Add complexity gradually
   
4. **Check the Preview**:
   - The preview shows exactly what will happen
   - If it's not right, adjust your pattern

#### Issue: Operation Stuck or Frozen

**Symptoms**: Progress bar stops moving, application becomes unresponsive.

**Solutions**:
1. **Wait a Moment**:
   - Large operations may take time
   - Check if the hard drive light is still active
   
2. **Use Pause**:
   - Click the **Pause** button
   - Wait a few seconds, then click **Resume**
   
3. **Cancel Operation**:
   - Click the **Cancel** button
   - Wait for the operation to stop gracefully
   
4. **Force Close** (last resort):
   - Close the application using Task Manager (Windows) or Activity Monitor (macOS)
   - Restart the application

#### Issue: Settings Not Saved

**Symptoms**: Your last-used folders or parameters aren't remembered.

**Solutions**:
1. **Check Persistence Settings**:
   - Open `config.toml`
   - Verify `remember_last_source = true` under `[persistence]`
   
2. **Check File Permissions**:
   - Ensure the application can write to its directory
   - Settings files may be blocked by permissions
   
3. **Check for Settings Files**:
   - Look for `regex_rename_settings.toml` in the application directory
   - If missing, the application will create it on next use

### Viewing Log Files

If you encounter persistent issues, the log files can help diagnose problems.

**Location**: `debug.log` in the application directory (usually `Code/Python/Main/`)

**How to View**:
1. Navigate to the application directory
2. Open `debug.log` with any text editor (Notepad, TextEdit, etc.)
3. Look for lines marked `ERROR` or `WARNING`
4. The most recent entries are at the bottom of the file

**What to Look For**:
- Error messages with stack traces
- Permission denied messages
- File not found errors
- Plugin loading errors

---

## FAQ

### 1. Is Theca Procurator free to use?

Yes, Theca Procurator is free software. Check the license file in the installation directory for specific terms.

### 2. Can I undo a rename or duplication operation?

Currently, operations cannot be undone automatically. Always preview your changes carefully and consider backing up important files before performing bulk operations. Full undo/redo functionality is planned for a future release.

### 3. How many files can I rename at once?

There's no hard limit, but performance depends on your system. The application has been tested with thousands of files. For very large operations (10,000+ files), consider breaking them into smaller batches.

### 4. Does Theca Procurator work with network drives?

Yes, you can select folders on network drives. However, network operations may be slower, and you need appropriate permissions on the network share.

### 5. Can I rename files across multiple folders?

Yes! Both Bulk Rename and Regex Rename search the target folder and all its subfolders. The preview table shows the full path for each file.

### 6. What file types are supported?

All file types are supported. Theca Procurator works with the filename and doesn't need to open or read the file contents.

### 7. Is my data safe?

Theca Procurator performs operations directly on your files. Always:
- Preview changes before executing
- Keep backups of important files
- Test with a few files first
- Use the Pause feature for long operations

The application does not send any data over the internet and operates entirely on your local system.

### 8. Can I use Theca Procurator for commercial purposes?

Check the license file included with your installation for specific terms regarding commercial use.

### 9. What's the difference between Bulk Rename and Regex Rename?

- **Bulk Rename**: Uses a predefined list from a text file. Best when you know exactly what each file should be named.
- **Regex Rename**: Uses patterns and rules to generate new names. Best for applying consistent naming patterns to many files.

### 10. How do I report a bug or request a feature?

Contact the development team at the email or website listed in the About dialog (Help → About). Include:
- Your operating system and version
- Steps to reproduce the issue
- Contents of the `debug.log` file if applicable
- Screenshots if relevant

---

## Keyboard Shortcuts

### Global Shortcuts
- **Ctrl+Q** (Windows/Linux) or **Cmd+Q** (macOS): Quit application
- **F1**: Show About dialog (planned)

### In Preview Tables
- **Click**: Select/deselect a row (Regex Rename only)
- **Ctrl+Click**: Select multiple rows (Regex Rename only)
- **Mouse Wheel**: Scroll through table
- **Hover**: Show full path tooltip for truncated paths

---

## About

### Version Information
- **Version**: 0.1.0
- **Release Date**: January 2026

### Credits
- **Author**: RH Labs/The SurveyOS Project
- **Built With**:
  - Python 3.9+
  - ttkbootstrap (modern UI framework)
  - Yapsy (plugin system)
  - Extensio Pulchra Skinny (application framework)
  - Tabula Mutabilis (table widget)
  - Vultus Serpentis (event bus and command manager)

### License

Please refer to the LICENSE file included with your installation for complete license terms.

### Contact

For support, bug reports, or feature requests, please contact:
- **Project**: The SurveyOS Project
- **Developer**: RH Labs

### Acknowledgments

Thank you to all the open-source projects that made Theca Procurator possible, and to the users who provide valuable feedback and suggestions.

---

*Last Updated: January 3, 2026*
*User Guide Version: 1.0*