File Operations

The file operations module provides utilities for file manipulation, copying, moving, and general file system operations.

Module Overview

Modern file operations for siege_utilities. Provides clean, type-safe file manipulation utilities.

Functions

siege_utilities.files.operations.copy_file(source, destination, overwrite=False)

Copy a file from source to destination.

SECURITY: Validates both source and destination paths.

Parameters:

• source – Source file path

• destination – Destination file path

• overwrite – Whether to overwrite existing files

Returns:

True if successful, False otherwise

Raises:

PathSecurityError – If paths fail security validation

Example

>>> copy_file("source.txt", "backup/source.txt")
>>> copy_file(Path("config.yaml"), Path("config.yaml.bak"))

siege_utilities.files.operations.move_file(source, destination, overwrite=False)

Move a file from source to destination.

SECURITY: Validates both source and destination paths.

Parameters:

• source – Source file path

• destination – Destination file path

• overwrite – Whether to overwrite existing files

Returns:

True if successful, False otherwise

Raises:

PathSecurityError – If paths fail security validation

Example

>>> move_file("temp.txt", "archive/temp.txt")
>>> move_file(Path("old.log"), Path("logs/old.log"))

Usage Examples

Basic file operations:

import siege_utilities

# Copy a file
siege_utilities.copy_file('source.txt', 'destination.txt')

# Move a file
siege_utilities.move_file('old_name.txt', 'new_name.txt')

# Delete a file
siege_utilities.delete_file('unwanted_file.txt')

# Create directory
siege_utilities.create_directory('new_folder')

# List files in directory
files = siege_utilities.list_files('data_folder')
print(f"Found {len(files)} files")

Batch file processing:

import os

# Process multiple files
source_dir = 'input_files'
output_dir = 'processed_files'

# Create output directory
siege_utilities.create_directory(output_dir)

# Process all files
for filename in siege_utilities.list_files(source_dir):
    if filename.endswith('.txt'):
        source_path = os.path.join(source_dir, filename)
        dest_path = os.path.join(output_dir, f"processed_{filename}")
        siege_utilities.copy_file(source_path, dest_path)

Unit Tests

The file operations module has comprehensive test coverage:

✅ test_file_operations.py - All file operation tests pass

Test Coverage:
- File copying with various scenarios
- File moving and renaming
- File deletion with safety checks
- Directory creation and management
- File listing and discovery
- Error handling for missing files
- Permission handling

Test Results: All file operation tests pass successfully with comprehensive coverage.