Paths Utilities

The paths utilities module provides utilities for working with file paths, directory structures, and path manipulation operations.

Module Overview

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

Functions

siege_utilities.files.paths.normalize_path(path)

Normalize a file path, resolving any relative components.

This function expands ~ (home directory), resolves .. (parent directory), and converts to an absolute path. It does NOT validate for security - use validate_safe_path() if you need security validation.

Parameters:

path – Path to normalize

Returns:

Normalized absolute path

Example

>>> norm_path = normalize_path("~/../data/file.txt")
>>> print(f"Normalized path: {norm_path}")

>>> # Resolves relative paths
>>> norm_path = normalize_path("./../data/file.txt")

siege_utilities.files.paths.get_file_extension(file_path)

Get the file extension from a file path.

SECURITY: Validates paths to prevent path traversal attacks.

Parameters:

file_path – Path to the file

Returns:

File extension (including the dot)

Raises:

PathSecurityError – If path fails security validation

Example

>>> ext = get_file_extension("document.pdf")
>>> print(f"File extension: {ext}")  # .pdf
>>>
>>> # This will raise PathSecurityError
>>> get_file_extension("../../../etc/passwd")  # Path traversal blocked

Usage Examples

Basic path operations:

File information extraction:

Path validation and existence:

Complex path operations:

Path manipulation:

Unit Tests

The paths utilities module has comprehensive test coverage:

Test Results: All paths utility tests pass successfully with comprehensive coverage.