Remote Operations

The remote operations module provides utilities for working with remote systems, SSH connections, and remote file operations.

Module Overview

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

siege_utilities.files.remote.download_file(url, local_filename, chunk_size=8192, timeout=30, verify_ssl=True, allow_insecure_fallback=False)

Download a file from a URL to a local file with progress bar.

SECURITY: Validates local file path to prevent path traversal attacks.

SSL behavior: when verify_ssl is True (the default), SSL certificate verification is enforced. If verification fails the original SSLError is re-raised and nothing is written – there is no silent retry with verification disabled. An insecure retry only happens when the caller explicitly sets allow_insecure_fallback=True, which downgrades to an unverified connection (vulnerable to man-in-the-middle) and is logged at ERROR. Leave it at the default False unless you fully accept that risk.

Parameters:

• url (str) – The URL to download from

• local_filename (str | Path) – The local path where the file should be saved

• chunk_size (int) – Size of chunks to download at once

• timeout (int) – Request timeout in seconds

• verify_ssl (bool) – Whether to verify SSL certificates

• allow_insecure_fallback (bool) – If True, an SSL failure triggers an explicit retry with verification disabled (insecure; logged at ERROR). Defaults to False, in which case SSL failures are raised.

Returns:

The local filename as a string

Raises:

• PathSecurityError – If local path fails security validation

• ConnectionError – If HTTP request fails (non-2xx status)

• requests.exceptions.SSLError – If SSL verification fails and allow_insecure_fallback is False

• requests.exceptions.Timeout – If request times out

• requests.exceptions.RequestException – If request fails

• OSError – If file write fails

Return type:

str

Example

>>> result = download_file("https://example.com/file.zip", "downloads/file.zip")
>>> print(f"Downloaded to {result}")

siege_utilities.files.remote.generate_local_path_from_url(url, directory_path, as_string=True)

Generate a local file path from a URL.

SECURITY: Validates directory path to prevent path traversal attacks.

Parameters:

• url (str) – URL to extract filename from

• directory_path (str | Path) – Directory where the file should be saved

• as_string (bool) – Whether to return the result as a string

Returns:

Path object or string

Raises:

• ValueError – If filename cannot be extracted from URL

• PathSecurityError – If directory path fails security validation

• OSError – If directory creation fails

Return type:

Path | str

Example

>>> path = generate_local_path_from_url("https://example.com/file.zip", "downloads")
>>> print(f"Local path: {path}")

siege_utilities.files.remote.download_file_with_retry(url, local_filename, max_retries=3, retry_delay=5, **kwargs)

Download a file with automatic retry on failure.

Parameters:

• url (str) – The URL to download from

• local_filename (str | Path) – The local path where the file should be saved

• max_retries (int) – Maximum number of retry attempts

• retry_delay (int) – Delay between retries in seconds

• **kwargs – Additional arguments passed to download_file. SSL behavior is inherited: verify_ssl defaults to True and SSL failures raise unless allow_insecure_fallback=True is passed through explicitly.

Returns:

The local filename as a string

Raises:

• requests.exceptions.SSLError – If SSL verification fails; raised immediately without retry unless download_file handles an explicitly allowed insecure fallback

• ConnectionError – If all retry attempts fail

• requests.exceptions.RequestException – If all retry attempts fail

Return type:

str

Example

>>> result = download_file_with_retry("https://example.com/file.zip", "file.zip")
>>> print(f"Downloaded to {result}")

siege_utilities.files.remote.get_file_info(url, timeout=10)

Get information about a remote file without downloading it.

Parameters:

• url (str) – URL to get information about

• timeout (int) – Request timeout in seconds

Returns:

Dictionary with file information

Raises:

• ConnectionError – If HTTP request fails (non-2xx status)

• requests.exceptions.RequestException – If request fails

• ImportError – If requests library is not available

Return type:

dict

Example

>>> info = get_file_info("https://example.com/file.zip")
>>> print(f"File size: {info['size']} bytes")

siege_utilities.files.remote.is_downloadable(url, timeout=10)

Check if a URL points to a downloadable file.

Parameters:

• url (str) – URL to check

• timeout (int) – Request timeout in seconds

Returns:

True if the URL points to a downloadable file, False otherwise

Return type:

bool

Example

>>> if is_downloadable("https://example.com/file.zip"):
...     print("URL is downloadable")

Functions

Usage Examples

Basic SSH connection:

Remote command execution:

File operations:

Batch operations:

Unit Tests

The remote operations module has comprehensive test coverage:

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