IoT Storage Client Library for Python
Project description
iot-storage-client
This package is a wrapper around the azure-storage-blob SDK.
Table of Contents
Getting Started
This section provides basic examples with the iot-storage-client
.
Prerequisites
-
Python 3.7 or later is required to use this package.
-
You must have an Azure subscription and Azure storage account to use this package.
Basic Examples
-
Install via pip:
pip install iot-storage-client
-
Import and say hello:
from iot.storage.client import __version__ print(f"hello world from iot-storage-client version: {__version__}")
-
Basic usage:
import tempfile from iot.storage.client import CredentialType, LocationType, IoTStorageClient # instantiate client storage_client = IoTStorageClient( credential_type=CredentialType.ACCOUNT_KEY, location_type=LocationType.CLOUD_BASED, account_name="myAzBlobStorageAcctName", credential="myBlobPrimaryKey***" ) # print info w/ repr print(f"{storage_client.__repr__()}") # download blob to tempfile temp_file = tempfile.NamedTemporaryFile() download_result = storage_client.download_file( container_name="myAzBlobContainerName", source="path/to/blob.txt", dest=temp_file.name, ) if not download_result: print("unable to download file") temp_file.close() raise # upload tempfile to blob upload_result = storage_client.upload_file( container_name="myAzBlobContainerName", source=temp_file.name, dest="path/to/new/blob.txt", ) if not upload_result: print("unable to upload file") temp_file.close() raise # clean-up local memory temp_file.close()
-
Basic async usage:
import tempfile
from iot.storage.client import CredentialType, LocationType, IoTStorageClientAsync
# instantiate client
storage_client = IoTStorageClientAsync(
credential_type=CredentialType.ACCOUNT_KEY,
location_type=LocationType.CLOUD_BASED,
account_name="myAzBlobStorageAcctName",
credential="myBlobPrimaryKey***"
)
# print info w/ repr
print(f"{storage_client.__repr__()}")
# download blob to tempfile
temp_file = tempfile.NamedTemporaryFile()
download_result = await storage_client.download_file(
container_name="myAzBlobContainerName",
source="path/to/blob.txt",
dest=temp_file.name,
)
if not download_result:
print("unable to download file")
temp_file.close()
raise
# upload tempfile to blob
upload_result = await storage_client.upload_file(
container_name="myAzBlobContainerName",
source=temp_file.name,
dest="path/to/new/blob.txt",
)
if not upload_result:
print("unable to upload file")
temp_file.close()
raise
# clean-up local memory
temp_file.close()
API Documentation
IoTStorageClient Class
A wrapper client to interact with the Azure Blob Service at the account level.
This client provides operations to list, create and delete storage containers and blobs within the account. An asynchronous client is also available with the same functionality and methods.
IoTStorageClient(credential_type, location_type, account_name, credential, host=None, port=None)
IoTStorageClientAsync(credential_type, location_type, account_name, credential, host=None, port=None)
Parameters
-
credential_type
strThe type of credential that will be used for authentication. One of "ACCOUNT_KEY" or "CONNECTION_STRING".
-
location_type
strThe location of the Azure storage account. This allows for communicating with storage accounts that live on IoT Edge devices. One of "CLOUD_BASED" or "EDGE_BASED".
-
account_name
strThe name of the Azure storage account.
-
credential
strThe credential (account key or connection string), that is being used for authentication.
-
host
Optional[str]The DNS or IP address of the Azure storage account when it lives on an IoT Edge device.
-
port
Optional[str]The open port of the Azure storage account when it lives on an IoT Edge device.
Container Exists Method
Check if a container exists.
storage_client.container_exists(container_name)
Parameters
-
container_name
strThe name of the container within the Azure storage account to check for existence.
Returns
Returns a boolean - true if the container exists, false if it doesn't exist.
File Exists Method
Check if a file exists.
storage_client.file_exists(container_name, file_name)
Parameters
-
container_name
strThe name of the container within the Azure storage account that the file is in.
-
file_name
strThe name and path to the file within the Azure storage account to check for existence.
Returns
Returns a boolean - true if the file exists, false if it doesn't exist.
Download Method
Download a file or directory a path on the local filesystem.
storage_client.download(container_name, source, dest)
Parameters
-
container_name
strThe name of the container within the Azure storage account that the file or directory is in.
-
source
strThe name and path to the file or directory within the Azure storage account to download.
-
dest
strThe name and path to the file or directory on the local filesystem to download to.
Returns
Returns a boolean - true if the file or directory was downloaded, false if it was not.
Download File Method
Download a file to a path on the local filesystem.
storage_client.download_file(container_name, source, dest)
Parameters
-
container_name
strThe name of the container within the Azure storage account that the file is in.
-
source
strThe name and path to the file within the Azure storage account to download.
-
dest
strThe name and path to the file on the local filesystem to download to.
Returns
Returns a boolean - true if the file was downloaded, false if it was not.
Upload Method
Upload a file or directory to a path inside the container.
storage_client.upload(container_name, source, dest)
Parameters
-
container_name
strThe name of the container within the Azure storage account that the file or directory will be uploaded to.
-
source
strThe name and path to the directory or file on the local filesystem to use for uploading.
-
dest
strThe name and path to the directory or file within the Azure storage account to upload to/create.
Returns
Returns a boolean - true if the file or directory was uploaded, false if it was not.
Upload File Method
Upload a file to a path inside the container.
storage_client.upload_file(container_name, source, dest, content_type="application/octet-stream", overwrite=True)
Parameters
-
container_name
strThe name of the container within the Azure storage account that the file will be uploaded to.
-
source
strThe name and path to the file on the local filesystem to use for uploading.
-
dest
strThe name and path to the file within the Azure storage account to upload to/create.
-
content_type
Optional[str]The content-type for the uploaded blob. Default is "application/octet-stream".
-
overwrite
Optional[bool]Overwrite the blob if it already exists. Default is True.
Returns
Returns a boolean - true if the file was uploaded, false if it was not.
Delete Directory Method
Delete a directory and its contents recursively from a path inside the container.
storage_client.delete_dir(container_name, path)
Parameters
-
container_name
strThe name of the container within the Azure storage account that the directory is located in.
-
path
strThe name and path to the directory within the Azure storage account to delete.
Returns
Returns a boolean - true if the directory was deleted, false if it was not.
Delete File Method
Delete a file from a path inside the container.
storage_client.delete_file(container_name, path)
Parameters
-
container_name
strThe name of the container within the Azure storage account that the file is located in.
-
path
strThe name and path to the file within the Azure storage account to delete.
Returns
Returns a boolean - true if the file was deleted, false if it was not.
List Directories Method
List directories under a path inside the container, optionally recursive.
storage_client.list_dirs(container_name, path, recursive=False)
Parameters
-
container_name
strThe name of the container within the Azure storage account that the directories are located in.
-
path
strThe path to the directories within the Azure storage account to list.
-
recursive
Optional[bool]List all sub-directories of the listed directories. Default is False.
Returns
Returns a list of strings (directory paths) or None.
List Files Method
List files under a path inside the container, optionally recursive.
storage_client.list_files(container_name, path, recursive=False)
Parameters
-
container_name
strThe name of the container within the Azure storage account that the files are located in.
-
path
strThe path to the files within the Azure storage account to list.
-
recursive
Optional[bool]List all sub-directories and its files of the listed files root directory. Default is False.
Returns
Returns a list of strings (file paths) or None.
Contributing
Contributions and suggestions are welcomed. However, there is a level of responsibility placed on the contributor to follow best-practices, provide thorough testing, follow the branching strategy, use the pull request template, and maintain a positive and coachable attitude when receiving feedback or questions on your code.
Local Development
-
Clone the repository.
-
Install and enable pre-commit
-
Checkout to a
features/*
orbugs/*
branch. -
Create and activate venv.
-
Pip install dependencies found in
setup.py
. -
Develop.
-
Write, test and validate unit tests.
-
Submit PR and comply with PR template.
-
Feedback loop and review process.
-
Thanks for your help!
Test Commands
To run your tests with the default unittest
library:
python3 -m unittest discover tests -b
Versioning
This repository adheres to Semantic Versioning. It will be maintained through the CHANGELOG.md
- as is standard with PyPI packages It's important to note that you must maintain the version with your releases in iot/storage/client/_version.py
, otherwise a new package version will fail to get published.
Deployment Process
-
Linting, testing and building occurs when a pull request is made from a
features/*
orbugs/*
branch to themaster
branch. -
Deployments to PyPI occur when an approved user triggers the GitHub Action. If the version has not been updated, this deployment will fail.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for iot_storage_client-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e63b4d439f628fb694a9dab15574947944116f80d91815f87269fcd22d150aeb |
|
MD5 | 7d876f1ccf6e928b69a5472ad9169889 |
|
BLAKE2b-256 | 053a43e1109db53b9089604f2e08abb8721e9fa8f1f2aef8d422959b1dff7868 |