theca-procurator 0.1.0

Desktop File & Folder Utility

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

2. Download or clone the Theca Procurator source code

3. Open a terminal/command prompt and navigate to the installation directory:

   cd "path/to/Theca Procurator/Code/Python/Main"
   

4. Install required packages:

   pip install ttkbootstrap yapsy toml
   

5. Run the application:

   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