cmeta.utils.net module
Network functions
cMeta author and developer: (C) 2025-2026 Grigori Fursin
See the cMeta COPYRIGHT and LICENSE files in the project root for details.
Functions
- cmeta.utils.net.access_api(url: str, params: dict, headers: dict = {}, timeout: int = 30)[source]
Send POST request to FastAPI endpoint with JSON params and return response.
- Parameters:
url (str) – The API endpoint URL.
params (dict) – Dictionary of parameters to send as JSON in the POST request body.
headers (dict) – Optional dictionary of HTTP headers to include in the request.
timeout (int) – Request timeout in seconds. Default is 30 seconds.
- Returns:
- Dictionary with ‘return’: 0 and ‘response’ containing parsed JSON response,
or ‘return’: 1 and ‘error’ message on failure.
- Return type:
dict
- Raises:
Exception – Propagated runtime errors, if any.
- cmeta.utils.net.download(url: str, filename: str = None, path: str = None, chunk_size: int = 65536, show_progress: bool = False, fail_on_error: bool = False, text: str = 'Downloading ', headers: dict = None, api_key: str = None, skip_ssl_certificate: bool = False, space: str = '', resume: bool = False)[source]
Download a file from URL to local filesystem.
Auto-detects filename from URL if not provided. Supports progress display with tqdm if show_progress is enabled.
The transfer is checked against the size the server announced (Content-Length): a connection that ends before it is an error (‘incomplete’: True, with ‘size’ = the bytes on disk and ‘total_size’), never a short file reported as downloaded. The bytes received stay in the file.
With resume=True a file left by an earlier interrupted call is continued instead of started over: the bytes on disk are kept and the rest is asked for with an HTTP range request, on the condition (If-Range) that the file on the server is still the one the first bytes came from - its ETag or Last-Modified date, recorded next to the partial file in “<file>.resume”. The download starts over whenever that cannot be guaranteed: no record, another URL, a server that names no such validator or does not serve ranges, a file that changed. A partial file is replaced only when the answer to replace it with has arrived. The record is removed when the file is complete.
- Parameters:
url (str) – URL of the file to download.
filename (str | None) – Name for the downloaded file. If None, extracts from URL.
path (str | None) – Directory to save the file. If None, uses current working directory.
chunk_size (int) – Size of chunks to download in bytes.
show_progress (bool) – If True, displays download progress using tqdm.
fail_on_error (bool) – If True, raises exception on error instead of returning error dict.
text (str) – Prefix text for progress bar description.
headers (dict | None) – Optional HTTP headers.
api_key (str | None) – API key added as X-API-Key header.
skip_ssl_certificate (bool) – If True, disables SSL certificate verification.
space (str) – Optional indentation prefix for console output formatting.
resume (bool) – If True, continues a partly downloaded file left by an earlier call.
- Returns:
- Dictionary with ‘return’: 0, ‘filename’, ‘path’, ‘size’ (of the file) and
’resumed_from’ (the bytes kept from an earlier call, 0 for a full download) on success, or ‘return’: 1 and ‘error’ on failure.
- Return type:
dict
- Raises:
Exception – Propagated runtime errors, if any.
Constants
- cmeta.utils.net.RESUME_RECORD_SUFFIX = '.resume'
str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.