Collections Module

The collections module provides advanced file system operations and enhanced data structures with comprehensive functionality for file management, recycling bin operations, and file system monitoring.

Key Components

• FileStats: Enhanced data class for file statistics

• File: Enhanced file class with additional capabilities

• Directory: Enhanced directory class with advanced operations

• RecycleBin: Advanced recycling bin implementation

• OSUtils: Comprehensive OS utility class

• DummyFile: Template-based dummy file creator

File Management

FileStats

class true.collections.FileStats(size, created, modified, accessed, permissions, is_hidden, mime_type, owner, group, is_symlink, symlink_target, md5_hash=None)

Enhanced data class to hold file statistics

size: int

created: datetime

modified: datetime

accessed: datetime

permissions: str

is_hidden: bool

mime_type: str

owner: str

group: str

is_symlink: bool

symlink_target: Optional[str]

md5_hash: Optional[str] = None

to_dict()

Convert stats to dictionary format

Return type:

dict

classmethod from_dict(data)

Create FileStats instance from dictionary

Return type:

FileStats

__init__(size, created, modified, accessed, permissions, is_hidden, mime_type, owner, group, is_symlink, symlink_target, md5_hash=None)

File

class true.collections.File(path, base_path=None)

Enhanced file class with additional capabilities

__init__(path, base_path=None)

property filename: str

property extension: str

property size: int

property md5: str

property mime_type: str

Get file MIME type

get_stats()

Get comprehensive file statistics

Return type:

FileStats

copy_to(destination, overwrite=False)

Copy file to destination with retry mechanism

Return type:

bool

create_backup(suffix='.bak')

Create a backup copy of the file

Return type:

File

is_text_file()

Check if file is a text file

Return type:

bool

read_text(encoding='utf-8')

Read text file content

Return type:

str

write_text(content, encoding='utf-8')

Write text to file

Return type:

int

Directory

class true.collections.Directory(path, base_path=None)

Enhanced directory class with additional capabilities

__init__(path, base_path=None)

property size: int

Get cached directory size with automatic refresh

_calculate_size()

Calculate total directory size

Return type:

int

glob(pattern)

Return type:

Generator[Path, None, None]

rglob(pattern)

Return type:

Generator[Path, None, None]

create(exist_ok=True)

Create directory if it doesn’t exist

Return type:

bool

zip_contents(output_path, compression=8)

Create a zip archive of directory contents

Return type:

bool

get_tree(max_depth=None)

Get directory structure as a nested dictionary

Return type:

Dict[str, Any]

property is_empty: bool

Check if directory is empty

delete()

Delete directory and its contents

Return type:

None

Recycling Bin

RecycleBin

class true.collections.RecycleBin(location, max_size=1073741824)

Advanced RecycleBin implementation with extensive features.

__init__(location, max_size=1073741824)

Initialize RecycleBin.

Parameters:

• location (str) – Base directory for the recycle bin

• max_size (int) – Maximum size in bytes (default 1GB)

_setup()

Initialize recycle bin directory structure.

Return type:

None

_load_metadata()

Load metadata from disk.

Return type:

None

_save_metadata()

Save metadata to disk.

Return type:

None

get_total_size()

Get total size of items in recycle bin.

Return type:

int

delete(path)

Move item to recycle bin.

Parameters:

path (str) – Path to item to be deleted

Returns:

Item ID in recycle bin

Return type:

str

Raises:

• StorageFullError – If recycle bin is full

• FileNotFoundError – If item doesn’t exist

async async_delete(path)

Asynchronous version of delete operation.

Return type:

str

restore(item_id)

Restore item from recycle bin.

Parameters:

item_id (str) – ID of item to restore

Raises:

• ItemNotFoundError – If item not found in recycle bin

• RestoreError – If restoration fails

Return type:

None

async async_restore(item_id)

Asynchronous version of restore operation.

Return type:

None

static _calculate_checksum(path)

Calculate file checksum.

Return type:

str

list_items(pattern=None)

List items in recycle bin with optional pattern matching.

Return type:

Generator[FileMetadata, None, None]

add_tag(item_id, tag)

Add tag to item.

Return type:

None

remove_tag(item_id, tag)

Remove tag from item.

Return type:

None

cleanup(days=30)

Remove items older than specified days.

Return type:

None

_permanent_delete(item_id)

Permanently delete item from recycle bin.

Return type:

None

_start_job_handler()

Start background job handler thread.

Return type:

None

batch_operation()

Context manager for batch operations.

async_batch_operation()

Async context manager for batch operations.

__str__()

String representation.

Return type:

str

__repr__()

Detailed string representation.

Return type:

str

__enter__()

Context manager entry.

__exit__(exc_type, exc_val, exc_tb)

Context manager exit.

async __aenter__()

Async context manager entry.

async __aexit__(exc_type, exc_val, exc_tb)

Async context manager exit.

RecycleBinManager

class true.collections.RecycleBinManager

Singleton manager for recyclebin instances.

__init__()

OS Utilities

OSUtils

class true.collections.OSUtils(base_path=None, max_workers=4)

Enhanced OS utility class with comprehensive file system operations

__init__(base_path=None, max_workers=4)

_setup_logging()

Configure logging with rotation

get_file(path)

Return type:

File

get_directory(path)

Return type:

Directory

safe_move(src, dst, overwrite=False)

Safely move a file or directory with retry mechanism

Return type:

bool

batch_process(file_list, operation, parallel=True)

Process multiple files in parallel or sequentially

Return type:

Dict[str, bool]

watch_directory(directory, callback)

Watch a directory for changes and call callback on file events.

Parameters:

• directory (str) – Directory path to watch

• callback (callable) – Function to call when changes occur

Return type:

None

stop_watching(directory=None)

Stop watching a specific directory or all directories

Return type:

None

safe_delete(path, secure=False)

Safely delete a file or directory with optional secure deletion.

Parameters:

• path (str) – Path to delete

• secure (bool) – If True, overwrite file contents before deletion

Return type:

bool

force_delete(path)

Forcefully delete a file or directory, using extreme measures for both Unix and Windows.

Parameters:

path (str) – Path to delete

Returns:

True if deletion was successful, False otherwise

Return type:

bool

static _secure_delete_file(path, passes=3)

Securely delete a file by overwriting its contents

Return type:

None

find_files_by_date(directory, start_date=None, end_date=None, modified=True)

Find files within a date range.

Parameters:

• directory (str) – Directory to search

• start_date (datetime) – Start date for search

• end_date (datetime) – End date for search

• modified (bool) – If True, use modification date, else creation date

Return type:

List[str]

get_directory_stats(directory)

Get comprehensive directory statistics

Return type:

Dict[str, Any]

_log_operation(operation_type, details)

Log operation with timestamp

Return type:

None

export_operation_history(output_file)

Export operation history to JSON file

Return type:

bool

__enter__()

Context manager entry

__exit__(exc_type, exc_val, exc_tb)

Context manager exit with cleanup

__del__()

Cleanup on deletion

File Creation

DummyFile

class true.collections.DummyFile(default_size=1024, default_content=None)

A class to manage the creation out for various types of dummy files using the Template Pattern.

__init__(default_size=1024, default_content=None)

create_file(extension, filename=None, size=None, content=None)

Generic method to create a dummy file based on the extension.

Parameters:

• extension – File extension (e.g., ‘.pdf’).

• filename – Name of the file to create.

• size – Size of the file in bytes.

• content – Content to fill the file.

custom_file(filename, extension, header=None, size=None, content=None)

Create a custom dummy file.

Parameters:

• filename – Name of the file.

• extension – File extension (e.g., ‘.custom’).

• header – Custom header bytes.

• size – Size of the file in bytes.

• content – Custom content to fill the file.

reset()

Reset the list of created files.

static create_image(output_path)

create_video(output_path, sequence_dir=None, codec='libx264', fps=10)

static create_static_video(image_path, output_path, codec='libx264', duration=5, fps=24)

static create_audio(filename, duration=3000, frequency=440)

FileCreator

class true.collections.FileCreator(extension, default_size=1024, default_content=None)

Abstract base class that defines the template for creating a dummy file.

FILE_HEADERS = {'.7z': b"7z\xbc\xaf'\x1c", '.avi': b'RIFF', '.bmp': b'BM', '.docx': b'PK\x03\x04', '.epub': b'PK\x03\x04', '.gif': b'GIF89a', '.jpg': b'\xff\xd8\xff', '.mkv': b'\x1aE\xdf\xa3', '.mp3': b'ID3', '.mp4': b'ftyp', '.pdf': b'%PDF-1.4\n%', '.png': b'\x89PNG\r\n\x1a\n', '.rar': b'Rar!', '.svg': b'<?xml version="1.0"?>', '.tar': b'ustar', '.tiff': b'II*\x00', '.txt': b'', '.wav': b'RIFF', '.xlsx': b'PK\x03\x04', '.zip': b'PK\x03\x04'}

__init__(extension, default_size=1024, default_content=None)

Initialize the FileCreator instance.

Parameters:

• extension – File extension including dot (e.g., ‘.pdf’)

• default_size – Default size of the dummy file in bytes.

• default_content – Default content to fill the dummy file.

create_file(filename=None, size=None, content=None)

Template method to create a dummy file.

Parameters:

• filename – Name of the file to create.

• size – Size of the file in bytes.

• content – Content to fill the file.

property header

Get the header bytes for the file type.

property default_filename

Get the default filename for the file type.

list_created_files()

List all created dummy files.

Returns:

List of filenames.

reset()

Reset the list of created files.

Examples

File Operations

from true.collections import File, Directory, OSUtils

# Enhanced file operations
file = File("example.txt")
print(file.size)  # Get file size
print(file.md5)   # Get MD5 hash
print(file.mime_type)  # Get MIME type

# Copy with retry mechanism
file.copy_to("backup/example.txt")

# Create backup
file.create_backup()  # Creates example.txt.bak

# Directory operations
directory = Directory("my_folder")
directory.create()  # Create if not exists

# Get directory tree
tree = directory.get_tree(max_depth=2)

# Create zip archive
directory.zip_contents("archive.zip")

Recycling Bin Usage

from true.collections import RecycleBin

# Initialize recycle bin
recycle_bin = RecycleBin("./trash", max_size=1024*1024*1024)  # 1GB max

# Delete with move to recycle bin
item_id = recycle_bin.delete("old_file.txt")

# Restore from recycle bin
recycle_bin.restore(item_id)

# List items with pattern
items = recycle_bin.list_items("*.txt")

# Cleanup old items
recycle_bin.cleanup(days=30)

# Use as context manager for batch operations
with recycle_bin:
    recycle_bin.delete("file1.txt")
    recycle_bin.delete("file2.txt")

OS Utilities Usage

from true.collections import OSUtils
from datetime import datetime, timedelta

os_utils = OSUtils()

# Watch directory for changes
def on_change(event):
    print(f"Change detected: {event.src_path}")

os_utils.watch_directory("watched_dir", on_change)

# Find files by date
yesterday = datetime.now() - timedelta(days=1)
files = os_utils.find_files_by_date(
    "search_dir",
    start_date=yesterday,
    modified=True
)

# Safe delete with secure overwrite
os_utils.safe_delete("sensitive.txt", secure=True)

# Batch process files
def process_file(file_path):
    # Process file
    pass

os_utils.batch_process(
    ["file1.txt", "file2.txt"],
    process_file,
    parallel=True
)

Dummy File Creation

from true.collections import DummyFile

# Create dummy files of various types
dummy = DummyFile()

# Create PDF dummy file
dummy.create_file(".pdf", "test.pdf", size=1024*1024)  # 1MB file

# Create image file
dummy.create_image("test.png")

# Create video file
dummy.create_video("output.mp4", fps=30)

# Create audio file
dummy.create_audio("test.wav", duration=5000)