API Reference 📖¶
AsyncClient¶
The MictlanX Client is an intuitive interface designed to facilitate seamless interactions between users and the MictlanX decentralized storage system. This client provides essential functionalities that enable users to securely store (put) and retrieve (get) data with ease.
__init__(uri, client_id, debug=True, max_workers=12, log_output_path=os.environ.get('MICTLANX_LOG_PATH', '/mictlanx/client'), log_when='m', log_interval=30, eviction_policy='LRU', capacity_storage='1GB', verify=False)
¶
Initializes the Client with the following parameters:
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client_id
|
str
|
The unique identifier for the client. |
required |
debug
|
bool
|
Enables or disables debug mode. Defaults to True. |
True
|
max_workers
|
int
|
The maximum number of workers. Defaults to 12. |
12
|
log_output_path
|
str
|
The path for log output. Defaults to "/mictlanx/client". |
get('MICTLANX_LOG_PATH', '/mictlanx/client')
|
log_when
|
str
|
The log rotation interval. Defaults to "m" (minutes). |
'm'
|
log_interval
|
int
|
The log rotation interval value. Defaults to 30. |
30
|
await_bulk(bulk_id, remove_on_completion=False)
async
¶
Waits for all registered tasks in a specific bulk job to complete and returns the results.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bulk_id
|
str
|
The ID of the bulk job to wait for. |
required |
remove_on_completion
|
bool
|
If True (default), the job and its results will be removed from memory after being returned. Set to False if you might need to inspect the results again. |
False
|
Returns:
| Type | Description |
|---|---|
Result[BulkPutResponse, MictlanXError]
|
Result[BulkPutResponse, EX.MictlanXError]: A Result object containing the final BulkPutResponse, or an error if the job is not found or waiting fails. |
delete_bucket(bucket_id, headers={}, timeout=120, force=True)
async
¶
Asynchronously deletes the specified bucket by fetching metadata from each router, then concurrently deleting each object (ball) found.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bucket_id
|
str
|
The ID of the bucket to delete. |
required |
headers
|
Dict[str, str]
|
Optional HTTP headers. |
{}
|
timeout
|
int
|
Request timeout in seconds. |
120
|
Returns:
| Type | Description |
|---|---|
Result[DeleteBucketResponse, Exception]
|
Result[InterfaceX.DeleteBucketResponse, Exception]: An Ok-wrapped response on success, |
Result[DeleteBucketResponse, Exception]
|
or an Err with an Exception on failure. |
delete_by_key(key, bucket_id='', timeout=120, force=True, headers={})
async
¶
Asynchronously deletes the data associated with the given key from the specified bucket.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
The key for the data to be deleted. |
required |
bucket_id
|
str
|
The ID of the bucket from which the data will be deleted. Defaults to an empty string. |
''
|
timeout
|
int
|
The timeout for the operation in seconds. Defaults to 120 seconds. |
120
|
headers
|
Dict[str, str]
|
Additional headers for the request. Defaults to an empty dictionary. |
{}
|
Returns:
| Type | Description |
|---|---|
Result[DeletedByKeyResponse, MictlanXError]
|
Result[InterfaceX.DeleteByKeyResponse, Exception]: The result of the delete operation. |
get_chunks_by_bucket_id(bucket_id, timeout=120, headers={})
async
¶
Asynchronously fetches the metadata for the specified bucket from the given router.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bucket_id
|
str
|
The ID of the bucket. |
required |
router
|
Router
|
The router to use for the request. |
required |
timeout
|
int
|
The timeout for the request (in seconds). |
120
|
headers
|
Dict[str, str]
|
Optional HTTP headers to include in the request. |
{}
|
Returns:
| Type | Description |
|---|---|
Result[GetRouterBucketMetadataResponse, MictlanXError]
|
Result[InterfaceX.GetRouterBucketMetadataResponse, Exception]: On success, returns an Ok-wrapped response; otherwise, returns an Err with the exception. |
put(bucket_id, key, value, chunk_size='256kb', rf=1, timeout=120, max_tries=5, max_concurrency=10, max_backoff=5, tags={})
async
¶
Uploads chunks and retries failed ones up to MAX_TRIES.
put_bulk(bulk_id, balls, max_concurrency=10, stop_on_failure=False)
async
¶
Puts multiple items (from bytes or file paths) in bulk.
It manages the concurrency of the top-level 'put' and 'put_file' operations, while each individual operation handles its own chunking and retries.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
items
|
List[BulkPutItem]
|
A list of dictionaries, each defining an item to upload. See BulkPutItem TypedDict. |
required |
max_concurrency
|
int
|
The maximum number of files to upload concurrently. Defaults to 10. |
10
|
stop_on_failure
|
bool
|
If True, the bulk operation will stop after the first failed upload. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
Result[bool, MictlanXError]
|
Result[BulkPutResponse, EX.MictlanXError]: A Result object containing a BulkPutResponse with 'successes' and 'failures' lists, or an MictlanXError if a setup error occurs. |
put_single_chunk(bucket_id, ball_id, chunk, chunk_size='256kb', rf=1, timeout=120, max_tries=5, max_concurrency=10, max_backoff=5, tags={})
async
¶
Uploads chunks and retries failed ones up to MAX_TRIES.
Peer¶
Router¶
get_by_checksum_to_file(checksum, chunk_size='1MB', sink_folder_path='/mictlanx/data', timeout=300, filename='', headers={}, extension='', verify=False)
async
¶
Downloads a file identified by a checksum and saves it to disk.
Parameters: checksum: The checksum used to identify the file. chunk_size: The size of each chunk to read (e.g., "1MB"). sink_folder_path: Folder path where the file will be saved. timeout: Timeout for the HTTP request. filename: Optional custom filename. If not provided, the checksum is used. headers: HTTP headers to include in the request. extension: File extension to append.
Returns: A Result containing the full file path on success or an Exception on error.
get_metadata(bucket_id, key, timeout=300, headers={}, verify=False)
async
¶
Asynchronously fetches metadata for a given bucket and key.
Constructs the URL from the base URL, API version, bucket_id, and key, and then sends a GET request. On success, it returns an Ok containing an instance of ResponseModels.GetMetadataResponse created from the JSON response. On failure, it returns an Err with the exception.