ddp_utils.net_utils¶

import ddp_utils.net_utils

Provide HTTP, FTP, FTPS, and SFTP networking utilities.

Examples

Send a request through a reusable session:

with HttpClient("https://api.example.com") as client:
    response = client.get("/health")

exception ddp_utils.net_utils.InsecureTransportWarning¶

Bases: UserWarning

Warn when plaintext FTP is used without an explicit policy.

Examples

Create or use the documented type:

warning = InsecureTransportWarning('plaintext transport selected')

ddp_utils.net_utils.get_current_ip_info(timeout: int = 10, retries: int = 2, use_cache: bool = True, cache_ttl: int = 300) → Dict[str, Any]¶

Resolve public IP, geolocation, and provider metadata.

Parameters

Name	Type	Description
timeout	int	Maximum wait in seconds for the network operation.
retries	int	Number of retry attempts after the initial failure.
use_cache	bool	Reuse a non-expired process-local result when true.
cache_ttl	int	Maximum cached-result age in seconds.

Returns

Type	Description
Dict[str, Any]	A normalized metadata mapping, or an empty mapping when every provider fails.

Examples

Use the operation in its owning client context:

info = get_current_ip_info(timeout=3.0, retries=1)
country = info.get("country")

ddp_utils.net_utils.clear_ip_info_cache() → None¶

Discard the process-local public-IP information cache.

Examples

Use the operation in its owning client context:

clear_ip_info_cache()

ddp_utils.net_utils.create_progress_callback(description: str, total: int, transient: bool = True)¶

Create a Rich-backed byte-transfer progress callback.

Parameters

Name	Type	Description
description	str	Human-readable progress label.
total	int	Expected total byte count; zero means unknown.
transient	bool	Remove the progress display after completion when true.

Returns

A callback accepting transferred and total byte counts.

Examples

Use the operation in its owning client context:

report = create_progress_callback("Downloading", total=4096)
report(1024, 4096)

class ddp_utils.net_utils.HttpClient(base_url: str = '', timeout: int = 30, retries: int = 3, backoff_factor: float = 0.5, status_forcelist: List[int] = None, allowed_methods: List[str] = None, headers: Dict[str, str] = None, proxies: Dict[str, str] = None, verify: bool | str = True, cert: str | Tuple[str, str] = None, stream: bool = False, hooks: Dict[str, Any] = None, auth: Any = None)¶

Bases: object

Provide a retrying HTTP session client.

Examples

Create or use the documented type:

with HttpClient("https://api.example.com") as client:
    response = client.get("/health")

Initialize the retrying HTTP session client.

Parameters

Name	Type	Description
base_url	str	Optional base URL joined to relative request paths.
timeout	int	Maximum wait in seconds for the network operation.
retries	int	Number of retry attempts after the initial failure.
backoff_factor	float	Exponential retry-delay multiplier.
status_forcelist	List[int]	HTTP status codes that trigger a retry.
allowed_methods	List[str]	HTTP methods eligible for retries.
headers	Dict[str, str]	Default HTTP request headers.
proxies	Dict[str, str]	Requests-compatible proxy mapping.
verify	bool \| str	TLS verification flag or CA bundle path.
cert	str \| Tuple[str, str]	Client certificate path or certificate/key pair.
stream	bool	Default requests streaming mode.
hooks	Dict[str, Any]	Requests event-hook mapping.
auth	Any	Requests-compatible authentication object.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
client = HttpClient("https://api.example.com")

request(method: str, url: str, **kwargs) → Response¶

Send an HTTP request through the configured retrying session.

Parameters

Name	Type	Description
method	str	HTTP method name.
url	str	Absolute URL or path relative to the configured base URL.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Response	The unvalidated `requests.Response` object.

Raises

Exception	Description
requests.RequestException	The HTTP request fails.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
response = client.request("GET", "/health")

get(url: str, **kwargs) → Response¶

Send an HTTP GET request.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Response	The `requests.Response` object.

Raises

Exception	Description
requests.RequestException	The HTTP request fails.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
response = client.get("/health")

post(url: str, data=None, json=None, **kwargs) → Response¶

Send an HTTP POST request.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
data		Request body data.
json		JSON-compatible request payload.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Response	The `requests.Response` object.

Raises

Exception	Description
requests.RequestException	The HTTP request fails.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
response = client.post("/items", json={"id": 7})

put(url: str, data=None, **kwargs) → Response¶

Send an HTTP PUT request.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
data		Request body data.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Response	The `requests.Response` object.

Raises

Exception	Description
requests.RequestException	The HTTP request fails.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
response = client.put("/items/7", data=b"value")

delete(url: str, **kwargs) → Response¶

Send an HTTP DELETE request.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Response	The `requests.Response` object.

Raises

Exception	Description
requests.RequestException	The HTTP request fails.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
response = client.delete("/items/7")

patch(url: str, data=None, **kwargs) → Response¶

Send an HTTP PATCH request.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
data		Request body data.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Response	The `requests.Response` object.

Raises

Exception	Description
requests.RequestException	The HTTP request fails.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
response = client.patch("/items/7", data=b"value")

head(url: str, **kwargs) → Response¶

Send an HTTP HEAD request.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Response	The `requests.Response` object.

Raises

Exception	Description
requests.RequestException	The HTTP request fails.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
response = client.head("/items/7")

options(url: str, **kwargs) → Response¶

Send an HTTP OPTIONS request.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Response	The `requests.Response` object.

Raises

Exception	Description
requests.RequestException	The HTTP request fails.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
response = client.options("/items")

get_json(url: str, **kwargs) → Any¶

Fetch an HTTP resource and decode its successful JSON response.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Any	The decoded JSON-compatible response value.

Raises

Exception	Description
requests.RequestException	The HTTP request or status validation fails.
ValueError	The successful response body is not valid JSON.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
payload = client.get_json("/items/7")

post_json(url: str, json: Dict, **kwargs) → Any¶

Post JSON data and decode the successful JSON response.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
json	Dict	JSON-compatible request payload.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Any	The decoded JSON-compatible response value.

Raises

Exception	Description
requests.RequestException	The HTTP request or status validation fails.
ValueError	The successful response body is not valid JSON.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
payload = client.post_json("/items", {"id": 7})

download_file(url: str, local_path: str, chunk_size: int = 8192, progress: bool = False, callback=None, **kwargs) → None¶

Download a remote file to the local filesystem.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
local_path	str	Local filesystem path.
chunk_size	int	Streaming block size in bytes.
progress	bool	Create a built-in progress display when no callback is supplied.
callback		Optional transfer callback receiving progress values.
kwargs		Additional keyword arguments forwarded to the underlying client.

Raises

Exception	Description
requests.RequestException	The HTTP request or status validation fails.
OSError	The local transfer file cannot be read or written.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
client.download_file("/archive.zip", "archive.zip")

upload_file(url: str, file_path: str, field_name: str = 'file', progress: bool = False, callback=None, **kwargs) → Response¶

Upload a local file to the remote endpoint.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
file_path	str	Local file path.
field_name	str	Multipart form field used for the uploaded file.
progress	bool	Create a built-in progress display when no callback is supplied.
callback		Optional transfer callback receiving progress values.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Response	The upload response or operation success value supplied by the protocol implementation.

Raises

Exception	Description
requests.RequestException	The HTTP request or status validation fails.
OSError	The local transfer file cannot be read or written.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
response = client.upload_file("/upload", "archive.zip")

close() → None¶

Release the client’s network resources.

Examples

Use the operation in its owning client context:

client = HttpClient("https://api.example.com")
client.close()

class ddp_utils.net_utils.FtpClient(host: str, user: str = '', passwd: str = '', port: int = 21, timeout: int = 30, retries: int = 3, backoff_factor: float = 0.5, encoding: str = 'utf-8', passive: bool = True, raise_on_error: bool = False, *, allow_insecure_ftp: bool | None = None)¶

Bases: object

Provide a plaintext FTP client.

Examples

Create or use the documented type:

client = FtpClient(
    "ftp.example.com",
    "user",
    "secret",
    allow_insecure_ftp=True,
)

Initialize the plaintext FTP client.

Parameters

Name	Type	Description
host	str	Remote server hostname or address.
user	str	Remote account username.
passwd	str	Remote account password.
port	int	Remote service port.
timeout	int	Maximum wait in seconds for the network operation.
retries	int	Number of retry attempts after the initial failure.
backoff_factor	float	Exponential retry-delay multiplier.
encoding	str	Encoding used for remote filenames.
passive	bool	Enable passive FTP data connections when true.
raise_on_error	bool	Override the client’s error-propagation policy for this operation.
allow_insecure_ftp	bool \| None	Plaintext FTP policy: allow, reject, or warn when unset.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)

get_results(clear: bool = False) → List[Dict[str, Any]]¶

Return a snapshot of recorded operation outcomes.

Parameters

Name	Type	Description
clear	bool	Clear stored results after returning their snapshot when true.

Returns

Type	Description
List[Dict[str, Any]]	A copy of accumulated operation-result dictionaries.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
results = client.get_results(clear=True)

clear_results()¶

Remove every recorded operation outcome.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
client.clear_results()

set_raise_on_error(value: bool)¶

Set the default error-propagation policy.

Parameters

Name	Type	Description
value	bool	New boolean policy value.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
client.set_raise_on_error(True)

connect() → None¶

Establish the configured remote connection.

Raises

Exception	Description
PermissionError	Plaintext FTP is explicitly disabled.
Exception	All connection attempts fail.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
client.connect()

property is_connected: bool¶

Report whether the client currently holds a connection handle.

Returns

True when a connection handle exists; otherwise False.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
connected = client.is_connected

ensure_connected() → None¶

Create a connection when no connection handle exists.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
client.ensure_connected()

disconnect() → None¶

Close the active remote connection and clear its handle.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
client.disconnect()

list(path: str = '.') → List[str]¶

List names in a remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
List[str]	Remote entry names.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
entries = client.list("/incoming")

listdir(path: str = '.') → List[str]¶

List names in a remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
List[str]	Remote entry names.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
entries = client.listdir("/incoming")

chdir(path: str) → None¶

Change the remote working directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
client.chdir("/incoming")

cwd(path: str) → None¶

Change the remote working directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
client.cwd("/incoming")

getcwd() → str¶

Return the remote working directory.

Returns

Type	Description
str	The current remote directory, or the implementation’s empty-state value.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
path = client.getcwd()

pwd() → str¶

Return the remote working directory.

Returns

Type	Description
str	The current remote directory, or the implementation’s empty-state value.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
path = client.pwd()

mkdir(path: str, raise_on_error: bool | None = None) → bool¶

Create a remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
result = client.mkdir("/incoming/item")

rmdir(path: str, raise_on_error: bool | None = None) → bool¶

Remove an empty remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
result = client.rmdir("/incoming/item")

download_file(remote_path: str, local_path: str, progress: bool = False, callback=None, raise_on_error: bool | None = None) → bool¶

Download a remote file to the local filesystem.

Parameters

Name	Type	Description
remote_path	str	Remote server path.
local_path	str	Local filesystem path.
progress	bool	Create a built-in progress display when no callback is supplied.
callback		Optional transfer callback receiving progress values.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
result = client.download_file("/remote/a.zip", "a.zip")

upload_file(local_path: str, remote_path: str, progress: bool = False, callback=None, raise_on_error: bool | None = None) → bool¶

Upload a local file to the remote endpoint.

Parameters

Name	Type	Description
local_path	str	Local filesystem path.
remote_path	str	Remote server path.
progress	bool	Create a built-in progress display when no callback is supplied.
callback		Optional transfer callback receiving progress values.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	The upload response or operation success value supplied by the protocol implementation.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
result = client.upload_file("a.zip", "/remote/a.zip")

delete_file(remote_path: str, raise_on_error: bool | None = None) → bool¶

Delete a remote file.

Parameters

Name	Type	Description
remote_path	str	Remote server path.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
result = client.delete_file("/incoming/item")

remove(remote_path: str, raise_on_error: bool | None = None) → bool¶

Delete a remote file.

Parameters

Name	Type	Description
remote_path	str	Remote server path.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
result = client.remove("/incoming/item")

rename(from_path: str, to_path: str, raise_on_error: bool | None = None) → bool¶

Rename or move a remote path.

Parameters

Name	Type	Description
from_path	str	Existing remote path.
to_path	str	Destination remote path.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
result = client.rename("/incoming/a", "/archive/a")

close() → None¶

Release the client’s network resources.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
client.close()

walk(top: str, topdown: bool = True, onerror=None, followlinks: bool = False)¶

Traverse a remote directory tree with os.walk-style results.

Parameters

Name	Type	Description
top	str	Remote directory at which traversal starts.
topdown	bool	Yield a directory before its descendants when true.
onerror		Optional callback invoked with traversal errors.
followlinks	bool	Whether traversal may descend through directory links.

Returns

An iterator of (directory, directories, files) tuples.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
for directory, dirs, files in client.walk("/"):
    print(directory)

listdir_attr(path: str = '.') → List[Dict[str, Any]]¶

List remote directory entries with available metadata.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
List[Dict[str, Any]]	Protocol-native remote entry metadata.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
entries = client.listdir_attr("/incoming")

is_dir(path: str) → bool¶

Determine whether a remote path is a directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
bool	`True` only when the remote path resolves to a directory.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
result = client.is_dir("/incoming/item")

is_file(path: str) → bool¶

Determine whether a remote path is a regular file.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
bool	`True` only when the remote path resolves to a regular file.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
result = client.is_file("/incoming/item")

get_root() → str¶

Return the remote filesystem root path.

Returns

Type	Description
str	The normalized remote root path.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
path = client.get_root()

parent_dir(levels: int = 1) → str¶

Move upward in the remote directory tree and return the result.

Parameters

Name	Type	Description
levels	int	Number of parent-directory levels to traverse.

Returns

Type	Description
str	The resulting remote working directory.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
parent = client.parent_dir(levels=2)

get_parent_path(levels: int = 1) → str¶

Compute a parent path without changing remote working directory.

Parameters

Name	Type	Description
levels	int	Number of parent-directory levels to traverse.

Returns

Type	Description
str	The normalized parent path.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpClient("ftp.example.com", allow_insecure_ftp=True)
parent = client.get_parent_path(levels=2)

class ddp_utils.net_utils.FtpsClient(host: str, user: str = '', passwd: str = '', port: int = 21, timeout: int = 30, retries: int = 3, backoff_factor: float = 0.5, encoding: str = 'utf-8', passive: bool = True, raise_on_error: bool = False, tls_verify: bool | str = True, tls_ca_file: str | None = None, tls_check_hostname: bool | None = None, tls_certfile: str | None = None, tls_keyfile: str | None = None, tls_data_channel: bool = True, implicit_tls: bool = False, *, allow_insecure_tls: bool = False)¶

Bases: FtpClient

Provide a TLS-protected FTP client.

Examples

Create or use the documented type:

client = FtpsClient("ftps.example.com", "user", "secret")

Initialize the TLS-protected FTP client.

Parameters

Name	Type	Description
host	str	Remote server hostname or address.
user	str	Remote account username.
passwd	str	Remote account password.
port	int	Remote service port.
timeout	int	Maximum wait in seconds for the network operation.
retries	int	Number of retry attempts after the initial failure.
backoff_factor	float	Exponential retry-delay multiplier.
encoding	str	Encoding used for remote filenames.
passive	bool	Enable passive FTP data connections when true.
raise_on_error	bool	Override the client’s error-propagation policy for this operation.
tls_verify	bool \| str	Verify the FTPS server certificate when true.
tls_ca_file	str \| None	Optional CA bundle used for FTPS verification.
tls_check_hostname	bool \| None	Verify that the FTPS certificate matches the host.
tls_certfile	str \| None	Optional client-certificate path.
tls_keyfile	str \| None	Optional client private-key path.
tls_data_channel	bool	Protect FTPS data transfers when true.
implicit_tls	bool	Use implicit TLS immediately after TCP connection.
allow_insecure_tls	bool	Allow explicitly disabled TLS verification when true.

Raises

Exception	Description
ValueError	TLS verification is disabled without explicit insecure-TLS consent.

Examples

Use the operation in its owning client context:

client = FtpsClient("ftps.example.com")

connect() → None¶

Establish the configured remote connection.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpsClient("ftps.example.com")
client.connect()

property is_connected: bool¶

Report whether the client currently holds a connection handle.

Returns

True when a connection handle exists; otherwise False.

Examples

Use the operation in its owning client context:

client = FtpsClient("ftps.example.com")
connected = client.is_connected

ensure_connected() → None¶

Create a connection when no connection handle exists.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FtpsClient("ftps.example.com")
client.ensure_connected()

disconnect() → None¶

Close the active remote connection and clear its handle.

Examples

Use the operation in its owning client context:

client = FtpsClient("ftps.example.com")
client.disconnect()

close() → None¶

Release the client’s network resources.

Examples

Use the operation in its owning client context:

client = FtpsClient("ftps.example.com")
client.close()

class ddp_utils.net_utils.SftpClient(host: str, port: int = 22, username: str | None = None, password: str | None = None, private_key_path: str | None = None, passphrase: str | None = None, timeout: int = 30, retries: int = 3, backoff_factor: float = 0.5, compress: bool = True, raise_on_error: bool = False)¶

Bases: object

Provide a SSH File Transfer Protocol client.

Examples

Create or use the documented type:

client = SftpClient("sftp.example.com", "user", "secret")

Initialize the SSH File Transfer Protocol client.

Parameters

Name	Type	Description
host	str	Remote server hostname or address.
port	int	Remote service port.
username	str \| None	Remote account username.
password	str \| None	Remote account password.
private_key_path	str \| None	Optional SSH private-key path.
passphrase	str \| None	Optional private-key passphrase.
timeout	int	Maximum wait in seconds for the network operation.
retries	int	Number of retry attempts after the initial failure.
backoff_factor	float	Exponential retry-delay multiplier.
compress	bool	Enable SSH transport compression when true.
raise_on_error	bool	Override the client’s error-propagation policy for this operation.

Raises

Exception	Description
ImportError	Paramiko is unavailable.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")

get_results(clear: bool = False) → List[Dict[str, Any]]¶

Return a snapshot of recorded operation outcomes.

Parameters

Name	Type	Description
clear	bool	Clear stored results after returning their snapshot when true.

Returns

Type	Description
List[Dict[str, Any]]	A copy of accumulated operation-result dictionaries.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
results = client.get_results(clear=True)

clear_results()¶

Remove every recorded operation outcome.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
client.clear_results()

set_raise_on_error(value: bool)¶

Set the default error-propagation policy.

Parameters

Name	Type	Description
value	bool	New boolean policy value.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
client.set_raise_on_error(True)

connect() → None¶

Establish the configured remote connection.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
client.connect()

property is_connected: bool¶

Report whether the client currently holds a connection handle.

Returns

True when a connection handle exists; otherwise False.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
connected = client.is_connected

ensure_connected() → None¶

Create a connection when no connection handle exists.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
client.ensure_connected()

disconnect() → None¶

Close the active remote connection and clear its handle.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
client.disconnect()

close() → None¶

Release the client’s network resources.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
client.close()

listdir(path: str = '.') → List[str]¶

List names in a remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
List[str]	Remote entry names.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
entries = client.listdir("/incoming")

listdir_attr(path: str = '.')¶

List remote directory entries with available metadata.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Protocol-native remote entry metadata.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
entries = client.listdir_attr("/incoming")

chdir(path: str) → None¶

Change the remote working directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
client.chdir("/incoming")

cwd(path: str) → None¶

Change the remote working directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
client.cwd("/incoming")

getcwd() → str¶

Return the remote working directory.

Returns

Type	Description
str	The current remote directory, or the implementation’s empty-state value.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
path = client.getcwd()

pwd() → str¶

Return the remote working directory.

Returns

Type	Description
str	The current remote directory, or the implementation’s empty-state value.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
path = client.pwd()

mkdir(path: str, mode: int = 493, raise_on_error: bool | None = None) → bool¶

Create a remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.
mode	int	Remote permission bits for the new directory.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.mkdir("/incoming/item")

rmdir(path: str, raise_on_error: bool | None = None) → bool¶

Remove an empty remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.rmdir("/incoming/item")

remove(path: str, raise_on_error: bool | None = None) → bool¶

Delete a remote file.

Parameters

Name	Type	Description
path	str	Remote path operated on.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.remove("/incoming/item")

rename(old_path: str, new_path: str, raise_on_error: bool | None = None) → bool¶

Rename or move a remote path.

Parameters

Name	Type	Description
old_path	str	Existing remote path.
new_path	str	Destination remote path.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.rename("/incoming/a", "/archive/a")

stat(path: str)¶

Return protocol-native attributes for a remote path.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Protocol-native attributes for the requested path.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.stat("/incoming/item")

download_file(remote_path: str, local_path: str, progress: bool = False, callback=None, raise_on_error: bool | None = None) → bool¶

Download a remote file to the local filesystem.

Parameters

Name	Type	Description
remote_path	str	Remote server path.
local_path	str	Local filesystem path.
progress	bool	Create a built-in progress display when no callback is supplied.
callback		Optional transfer callback receiving progress values.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.download_file("/remote/a.zip", "a.zip")

upload_file(local_path: str, remote_path: str, progress: bool = False, callback=None, confirm=True, raise_on_error: bool | None = None) → bool¶

Upload a local file to the remote endpoint.

Parameters

Name	Type	Description
local_path	str	Local filesystem path.
remote_path	str	Remote server path.
progress	bool	Create a built-in progress display when no callback is supplied.
callback		Optional transfer callback receiving progress values.
confirm		Request post-upload size confirmation when supported.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	The upload response or operation success value supplied by the protocol implementation.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.upload_file("a.zip", "/remote/a.zip")

get(remote_path: str, local_path: str, callback=None, raise_on_error: bool | None = None) → bool¶

Send an HTTP GET request.

Parameters

Name	Type	Description
remote_path	str	Remote server path.
local_path	str	Local filesystem path.
callback		Optional transfer callback receiving progress values.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	The `requests.Response` object.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.get("/remote/a.zip", "a.zip")

put(local_path: str, remote_path: str, progress=False, callback=None, confirm=True, raise_on_error: bool | None = None) → bool¶

Send an HTTP PUT request.

Parameters

Name	Type	Description
local_path	str	Local filesystem path.
remote_path	str	Remote server path.
progress		Create a built-in progress display when no callback is supplied.
callback		Optional transfer callback receiving progress values.
confirm		Request post-upload size confirmation when supported.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	The `requests.Response` object.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.put("a.zip", "/remote/a.zip")

walk(top: str, topdown: bool = True, onerror=None, followlinks: bool = False)¶

Traverse a remote directory tree with os.walk-style results.

Parameters

Name	Type	Description
top	str	Remote directory at which traversal starts.
topdown	bool	Yield a directory before its descendants when true.
onerror		Optional callback invoked with traversal errors.
followlinks	bool	Whether traversal may descend through directory links.

Returns

An iterator of (directory, directories, files) tuples.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
for directory, dirs, files in client.walk("/"):
    print(directory)

is_dir(path: str) → bool¶

Determine whether a remote path is a directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
bool	`True` only when the remote path resolves to a directory.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.is_dir("/incoming/item")

is_file(path: str) → bool¶

Determine whether a remote path is a regular file.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
bool	`True` only when the remote path resolves to a regular file.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
result = client.is_file("/incoming/item")

get_root() → str¶

Return the remote filesystem root path.

Returns

Type	Description
str	The normalized remote root path.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
path = client.get_root()

parent_dir(levels: int = 1) → str¶

Move upward in the remote directory tree and return the result.

Parameters

Name	Type	Description
levels	int	Number of parent-directory levels to traverse.

Returns

Type	Description
str	The resulting remote working directory.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
parent = client.parent_dir(levels=2)

get_parent_path(levels: int = 1) → str¶

Compute a parent path without changing remote working directory.

Parameters

Name	Type	Description
levels	int	Number of parent-directory levels to traverse.

Returns

Type	Description
str	The normalized parent path.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
parent = client.get_parent_path(levels=2)

listdir_attr_dict(path: str = '.') → List[Dict[str, Any]]¶

Return remote directory metadata as plain dictionaries.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
List[Dict[str, Any]]	Remote entry metadata converted to dictionaries.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = SftpClient("sftp.example.com")
entries = client.listdir_attr_dict("/incoming")

class ddp_utils.net_utils.FTPClient(host: str, port: int | None = None, username: str = '', password: str = '', ssl: bool = False, tls: bool = False, tls_verify: bool | str = True, tls_ca_file: str | None = None, tls_check_hostname: bool | None = None, tls_certfile: str | None = None, tls_keyfile: str | None = None, tls_data_channel: bool = True, implicit_tls: bool = False, private_key_path: str | None = None, passphrase: str | None = None, timeout: int = 30, retries: int = 3, backoff_factor: float = 0.5, passive: bool = True, encoding: str = 'utf-8', compress: bool = True, raise_on_error: bool = False, *, allow_insecure_ftp: bool | None = None, allow_insecure_tls: bool = False, **kwargs)¶

Bases: object

Provide a unified FTP, FTPS, or SFTP facade.

Examples

Create or use the documented type:

client = FTPClient(
    "sftp.example.com",
    ssl=True,
    username="user",
    password="secret",
)

Initialize the unified FTP, FTPS, or SFTP facade.

Parameters

Name	Type	Description
host	str	Remote server hostname or address.
port	int \| None	Remote service port.
username	str	Remote account username.
password	str	Remote account password.
ssl	bool	Select SFTP when true; otherwise use FTP or FTPS according to `tls`.
tls	bool	Select FTPS when true and `ssl` is false.
tls_verify	bool \| str	Verify the FTPS server certificate when true.
tls_ca_file	str \| None	Optional CA bundle used for FTPS verification.
tls_check_hostname	bool \| None	Verify that the FTPS certificate matches the host.
tls_certfile	str \| None	Optional client-certificate path.
tls_keyfile	str \| None	Optional client private-key path.
tls_data_channel	bool	Protect FTPS data transfers when true.
implicit_tls	bool	Use implicit TLS immediately after TCP connection.
private_key_path	str \| None	Optional SSH private-key path.
passphrase	str \| None	Optional private-key passphrase.
timeout	int	Maximum wait in seconds for the network operation.
retries	int	Number of retry attempts after the initial failure.
backoff_factor	float	Exponential retry-delay multiplier.
passive	bool	Enable passive FTP data connections when true.
encoding	str	Encoding used for remote filenames.
compress	bool	Enable SSH transport compression when true.
raise_on_error	bool	Override the client’s error-propagation policy for this operation.
allow_insecure_ftp	bool \| None	Plaintext FTP policy: allow, reject, or warn when unset.
allow_insecure_tls	bool	Allow explicitly disabled TLS verification when true.
kwargs		Additional keyword arguments forwarded to the underlying client.

Raises

Exception	Description
ValueError	SFTP and FTPS are selected simultaneously.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)

property raise_on_error: bool¶

Execute the raise_on_error network utility operation.

Returns

True on success; otherwise False when failure is handled locally.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.raise_on_error = True

property is_connected: bool¶

Report whether the client currently holds a connection handle.

Returns

True when a connection handle exists; otherwise False.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
connected = client.is_connected

get_results(clear: bool = False) → List[Dict[str, Any]]¶

Return a snapshot of recorded operation outcomes.

Parameters

Name	Type	Description
clear	bool	Clear stored results after returning their snapshot when true.

Returns

Type	Description
List[Dict[str, Any]]	A copy of accumulated operation-result dictionaries.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
results = client.get_results(clear=True)

clear_results()¶

Remove every recorded operation outcome.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.clear_results()

set_raise_on_error(value: bool)¶

Set the default error-propagation policy.

Parameters

Name	Type	Description
value	bool	New boolean policy value.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.set_raise_on_error(True)

connect(*, raise_on_error: bool = True) → bool¶

Establish the configured remote connection.

Parameters

Name	Type	Description
raise_on_error	bool	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.connect()

ensure_connected(*, raise_on_error: bool = True) → bool¶

Create a connection when no connection handle exists.

Parameters

Name	Type	Description
raise_on_error	bool	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.ensure_connected()

disconnect(*, raise_on_error: bool = False) → bool¶

Close the active remote connection and clear its handle.

Parameters

Name	Type	Description
raise_on_error	bool	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
RuntimeError	The delegated disconnect fails and propagation is enabled.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.disconnect()

close(*, raise_on_error: bool = False) → bool¶

Release the client’s network resources.

Parameters

Name	Type	Description
raise_on_error	bool	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.close()

listdir(path: str = '.') → List[str]¶

List names in a remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
List[str]	Remote entry names.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
entries = client.listdir("/incoming")

ls(path: str = '.') → List[str]¶

List names in a remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
List[str]	Remote entry names.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
entries = client.ls("/incoming")

chdir(path: str) → None¶

Change the remote working directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.chdir("/incoming")

cwd(path: str) → None¶

Change the remote working directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.cwd("/incoming")

getcwd() → str¶

Return the remote working directory.

Returns

Type	Description
str	The current remote directory, or the implementation’s empty-state value.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
path = client.getcwd()

pwd() → str¶

Return the remote working directory.

Returns

Type	Description
str	The current remote directory, or the implementation’s empty-state value.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
path = client.pwd()

mkdir(path: str, mode: int = 493, raise_on_error: bool | None = None) → bool¶

Create a remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.
mode	int	Remote permission bits for the new directory.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.mkdir("/incoming/item")

rmdir(path: str, raise_on_error: bool | None = None) → bool¶

Remove an empty remote directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.rmdir("/incoming/item")

remove(path: str, raise_on_error: bool | None = None) → bool¶

Delete a remote file.

Parameters

Name	Type	Description
path	str	Remote path operated on.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.remove("/incoming/item")

rename(old_path: str, new_path: str, raise_on_error: bool | None = None) → bool¶

Rename or move a remote path.

Parameters

Name	Type	Description
old_path	str	Existing remote path.
new_path	str	Destination remote path.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.rename("/incoming/a", "/archive/a")

download_file(remote_path: str, local_path: str, progress: bool = False, callback=None, raise_on_error: bool | None = None) → bool¶

Download a remote file to the local filesystem.

Parameters

Name	Type	Description
remote_path	str	Remote server path.
local_path	str	Local filesystem path.
progress	bool	Create a built-in progress display when no callback is supplied.
callback		Optional transfer callback receiving progress values.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on success; otherwise `False` when failure is handled locally.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.download_file("/remote/a.zip", "a.zip")

upload_file(local_path: str, remote_path: str, progress: bool = False, callback=None, raise_on_error: bool | None = None) → bool¶

Upload a local file to the remote endpoint.

Parameters

Name	Type	Description
local_path	str	Local filesystem path.
remote_path	str	Remote server path.
progress	bool	Create a built-in progress display when no callback is supplied.
callback		Optional transfer callback receiving progress values.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	The upload response or operation success value supplied by the protocol implementation.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.upload_file("a.zip", "/remote/a.zip")

get(remote_path: str, local_path: str, callback=None, raise_on_error: bool | None = None) → bool¶

Send an HTTP GET request.

Parameters

Name	Type	Description
remote_path	str	Remote server path.
local_path	str	Local filesystem path.
callback		Optional transfer callback receiving progress values.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	The `requests.Response` object.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.get("/remote/a.zip", "a.zip")

put(local_path: str, remote_path: str, callback=None, raise_on_error: bool | None = None) → bool¶

Send an HTTP PUT request.

Parameters

Name	Type	Description
local_path	str	Local filesystem path.
remote_path	str	Remote server path.
callback		Optional transfer callback receiving progress values.
raise_on_error	bool \| None	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	The `requests.Response` object.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.put("a.zip", "/remote/a.zip")

walk(top: str, topdown: bool = True, onerror=None, followlinks: bool = False)¶

Traverse a remote directory tree with os.walk-style results.

Parameters

Name	Type	Description
top	str	Remote directory at which traversal starts.
topdown	bool	Yield a directory before its descendants when true.
onerror		Optional callback invoked with traversal errors.
followlinks	bool	Whether traversal may descend through directory links.

Returns

An iterator of (directory, directories, files) tuples.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
for directory, dirs, files in client.walk("/"):
    print(directory)

listdir_attr(path: str = '.') → List[Dict[str, Any]]¶

List remote directory entries with available metadata.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
List[Dict[str, Any]]	Protocol-native remote entry metadata.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
entries = client.listdir_attr("/incoming")

is_dir(path: str) → bool¶

Determine whether a remote path is a directory.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
bool	`True` only when the remote path resolves to a directory.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.is_dir("/incoming/item")

is_file(path: str) → bool¶

Determine whether a remote path is a regular file.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
bool	`True` only when the remote path resolves to a regular file.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
result = client.is_file("/incoming/item")

find(pattern: str = '*', path: str = '.', recursive: bool = False, file_type: str | None = None) → List[str]¶

Find remote files or directories by glob-style name pattern.

Parameters

Name	Type	Description
pattern	str	Glob-style filename pattern.
path	str	Remote path operated on.
recursive	bool	Search descendant directories when true.
file_type	str \| None	Optional `file` or `dir` result filter.

Returns

Type	Description
List[str]	Matching remote paths relative to the requested search root.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
matches = client.find("*.csv", "/incoming", recursive=True)

verify_connection(directory: str | None = None, *, keep_connected: bool = False, raise_on_error: bool = True) → bool¶

Validate connectivity and an optional remote directory.

Parameters

Name	Type	Description
directory	str \| None	Optional remote directory to validate after connection.
keep_connected	bool	Leave a successful validation connection open when true.
raise_on_error	bool	Override the client’s error-propagation policy for this operation.

Returns

Type	Description
bool	`True` on successful validation; otherwise `False` unless configured to raise.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
ready = client.verify_connection("/incoming")

open_dir(path: str) → None¶

Change to a remote directory through the unified facade.

Parameters

Name	Type	Description
path	str	Remote path operated on.

Returns

Type	Description
None	The resulting remote working directory or delegated operation value.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
client.open_dir("/incoming")

get_current_dir() → str¶

Return the remote working directory through the facade.

Returns

Type	Description
str	The current remote working directory.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
path = client.get_current_dir()

get_root() → str¶

Return the remote filesystem root path.

Returns

Type	Description
str	The normalized remote root path.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
path = client.get_root()

parent_dir(levels: int = 1) → str¶

Move upward in the remote directory tree and return the result.

Parameters

Name	Type	Description
levels	int	Number of parent-directory levels to traverse.

Returns

Type	Description
str	The resulting remote working directory.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
parent = client.parent_dir(levels=2)

get_parent_path(levels: int = 1) → str¶

Compute a parent path without changing remote working directory.

Parameters

Name	Type	Description
levels	int	Number of parent-directory levels to traverse.

Returns

Type	Description
str	The normalized parent path.

Raises

Exception	Description
Exception	The protocol operation fails and the effective raise-on-error policy requires propagation.

Examples

Use the operation in its owning client context:

client = FTPClient("sftp.example.com", ssl=True)
parent = client.get_parent_path(levels=2)

ddp_utils.net_utils.create_client(url: str, **kwargs) → HttpClient | FtpClient | SftpClient | FTPClient¶

Create an HTTP or file-transfer client from a URL scheme.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
HttpClient \| FtpClient \| SftpClient \| FTPClient	A configured `HttpClient` or `FTPClient` instance.

Raises

Exception	Description
ValueError	The URL scheme is unsupported or required connection data is missing.

Examples

Use the operation in its owning client context:

client = create_client("https://api.example.com")

ddp_utils.net_utils.request(method: str, url: str, **kwargs) → Tuple[int, Any]¶

Send an HTTP request through the configured retrying session.

Parameters

Name	Type	Description
method	str	HTTP method name.
url	str	Absolute URL or path relative to the configured base URL.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Tuple[int, Any]	The unvalidated `requests.Response` object.

Examples

Use the operation in its owning client context:

response = request("GET", "https://example.com")

ddp_utils.net_utils.get(url: str, **kwargs) → Tuple[int, str]¶

Send an HTTP GET request.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Tuple[int, str]	A `(status_code, response_text)` tuple.

Examples

Use the operation in its owning client context:

status, text = get("https://example.com")

ddp_utils.net_utils.post(url: str, data=None, json=None, **kwargs) → Tuple[int, str]¶

Send an HTTP POST request.

Parameters

Name	Type	Description
url	str	Absolute URL or path relative to the configured base URL.
data		Request body data.
json		JSON-compatible request payload.
kwargs		Additional keyword arguments forwarded to the underlying client.

Returns

Type	Description
Tuple[int, str]	A `(status_code, response_text)` tuple.

Examples

Use the operation in its owning client context:

status, text = post("https://example.com", json={"ready": True})