API Reference#

The following content outlines the API of aiob2.

Clients#

Client#

class aiob2.Client(application_key_id, application_key, *, session=None, log_handler=..., log_formatter=..., log_level=..., root_logger=False)#

Represents an aiob2 Client that makes requests to Backblaze’s B2 API.

Parameters:

  • application_key_id (str) – The application key id to use for authentication.

  • application_key (str) – The application key to use for authentication.

  • session (Optional[aiohttp.ClientSession]) – An optional session to pass, otherwise one will be lazily created.

  • logging_handler (Optional[logging.LogHandler]) –

    The log handler to use for the library’s logger. If this is None then the library will not set up anything logging related. Logging will still work if None is passed, though it is your responsibility to set it up.

    The default log handler if not provided is logging.StreamHandler.

  • log_formatter (logging.Formatter) – The formatter to use with the given log handler. If not provided then it defaults to a colour based logging formatter (if available).

  • log_level (int) – The default log level for the library’s logger. This is only applied if the log_handler parameter is not None. Defaults to logging.INFO.

  • root_logger (bool) –

    Whether to set up the root logger rather than the library logger. By default, only the library logger ('aiob2') is set up. If this is set to True then the root logger is set up as well.

    Defaults to False.

await upload_file(*, file_name, content_bytes, bucket_id, content_type=None, content_disposition=None, content_language=None, expires=None, content_encoding=None, comments=None, upload_timestamp=None, server_side_encryption=None)#

Uploads a file to a bucket.

Parameters:

  • file_name (str) – The name of the file.

  • content_bytes (bytes) – The raw bytes of the file to be uploaded.

  • bucket_id (str) – The ID of the bucket to upload to.

  • content_type (Optional[str]) –

    The content type of the content_bytes, e.g. video/mp4. This should be the original media/content, and not the result of the encodings applied. This is specified in the content_encoding.

    B2’s list of content types/extensions can be found [here](https://www.backblaze.com/b2/docs/content-types.html)

    If not provided, it will be automatically detected by Backblaze, and upon it not being discoverable, it’ll default to application/octet-stream.

  • content_disposition (Optional[str]) –

    Indicates whether the content is displayed inline in the browser, or as an attachment, which is locally downloaded.

    More info: [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)

  • content_language (Optional[List[str]]) –

    The intended language(s) for the audience. By default, when this is not specified, it indicates that the content is for all language audiences.

    For example, ['en'] (English) or ['en', 'da'] (English and Danish).

  • expires (Optional[datetime.datetime]) – Indicates the date/time after which the content is considered expired. This does NOT automatically delete the file.

  • content_encoding (Optional[List[Literal[gzip, compress, deflate, identity]]]) – Lists any encodings that have been applied to the content, and in what order.

  • comments (Optional[Dict[str, str]]) – A key-value pair of strings denoting any extra information to store as metadata with the file. The key will be quote_plus encoded.

  • upload_timestamp (Optional[datetime.datetime]) –

    The upload timestamp to use, instead of now.

    Note

    Your account must be authorized to use this by Backblaze support.

  • server_side_encryption (Optional[Literal[AES256]]) – Specifying this will encrypt the data before storing it using [Server-Side Encryption with Backblaze-Managed Keys](https://backblaze.com/b2/docs/server_side_encryption.html) with the specified algorithm, currently only AES256.

Returns:

The uploaded file.

Return type:

File

await upload_large_file(bucket_id, file_name, content_type=None, upload_timestamp=None, comments=None)#

Creates a large file to upload parts/chunks to incrementally.

Parameters:

  • bucket_id (str) – The ID of the bucket to upload to.

  • file_name (str) – The name of the file.

  • content_type (str) –

    The content type of the file once every part is combined together.

    If not provided, it will be automatically detected by Backblaze, and upon it not being discoverable, it’ll default to application/octet-stream.

  • upload_timestamp (Optional[datetime.datetime]) –

    The upload timestamp to use, instead of now.

    Note

    Your account must be authorized to use this by Backblaze support.

  • comments (Optional[Dict[Any, Any]]) –

    Key-value pairs denoting any extra information to store as metadata with the file.

    Unlike upload_file, multiple k-v pairs may be provided of any JSON-compatible data type.

await delete_file(file_name, file_id)#

Deletes a file from a bucket.

Parameters:

  • file_name (str) – The name of the file to delete.

  • file_id (str) – The id of the file to delete.

Returns:

The deleted file.

Return type:

DeletedFile

await download_file_by_id(file_id, *, content_disposition=None, content_language=None, expires=None, cache_control=None, content_encoding=None, content_type=None, server_side_encryption=None)#

Downloads a file.

Parameters:

  • file_id (str) – The file id of the file to be downloaded.

  • content_disposition (Optional[str]) – Overrides the current ‘b2-content-disposition’ specified when the file was uploaded.

  • content_language (Optional[str]) – Overrides the current ‘b2-content-language’ specified when the file was uploaded.

  • expires (Optional[str]) – Overrides the current ‘b2-expires’ specified when the file was uploaded.

  • cache_control (Optional[str]) – Overrides the current ‘b2-cache-control’ specified when the file was uploaded.

  • content_encoding (Optional[str]) – Overrides the current ‘b2-content-encoding’ specified when the file was uploaded.

  • content_type (Optional[str]) – Overrides the current ‘Content-Type’ specified when the file was uploaded.

  • server_side_encryption (Optional[str]) – This is requires if the file was uploaded and stored using Server-Side Encryption with Customer-Managed Keyts (SSE-C)

Returns:

The file requested.

Return type:

DownloadedFile

await download_file_by_name(file_name, bucket_name, *, content_disposition=None, content_language=None, expires=None, cache_control=None, content_encoding=None, content_type=None, server_side_encryption=None)#

Downloads a file.

Parameters:

  • file_name (str) – The file name of the file to be downloaded.

  • bucket_name (str) – The bucket name of the file to be downloaded. This should only be specified if you have specified file_name and not file_id.

  • content_disposition (Optional[str]) – Overrides the current ‘b2-content-disposition’ specified when the file was uploaded.

  • content_language (Optional[str]) – Overrides the current ‘b2-content-language’ specified when the file was uploaded.

  • expires (Optional[str]) – Overrides the current ‘b2-expires’ specified when the file was uploaded.

  • cache_control (Optional[str]) – Overrides the current ‘b2-cache-control’ specified when the file was uploaded.

  • content_encoding (Optional[str]) – Overrides the current ‘b2-content-encoding’ specified when the file was uploaded.

  • content_type (Optional[str]) – Overrides the current ‘Content-Type’ specified when the file was uploaded.

  • server_side_encryption (Optional[str]) – This is requires if the file was uploaded and stored using Server-Side Encryption with Customer-Managed Keyts (SSE-C)

Returns:

The file requested.

Return type:

DownloadedFile

aiob2 Models#

Models are classes that are received from Backblaze, and are not intended to be created by users of the library.

Danger

The classes listed below are not intended to be created by users and are also read-only.

For example, this means that you should not make your own File instances nor should you modify the File instance yourself.

If you want to get one of these model classes instances, they’d have to be through the API or a property of another object that had been fetched already.

Files#

class aiob2.File#

Represents a file uploaded to Backblaze.

account_id#

The account’s ID that owns the file.

Type:

str

action#

This will always be upload.

Type:

Literal['upload']

bucket_id#

The file’s bucket ID.

Type:

str

content_length#

The file’s size represented in number of bytes.

Type:

int

content_sha1#

The file’s SHA-1.

Type:

str

content_md5#

The MD5 of the file’s bytes as a 40-digit hex string.

Type:

Optional[str]

content_type#

The file’s content type, e.g. image/jpeg.

Type:

str

id#

The file’s ID.

Type:

str

info#

Any custom info regarding the file submitted at upload.

Type:

dict

name#

The file’s name.

Type:

str

retention#

The file’s object lock retention settings.

Type:

Optional[dict]

legal_hold#

The file’s object lock legal hold status.

Type:

Optional[dict]

replication_status#

The file’s replication status.

Type:

Optional[Literal['PENDING', 'COMPLETED', 'FAILED', 'REPLICA']

server_side_encryption#

The file’s encryption mode, and algorithm.

Type:

Optional[dict]

created#

The time at which the file was uploaded.

Type:

datetime.datetime

class aiob2.DeletedFile#

Represents a deleted file from Backblaze.

name#

The file’s name.

Type:

str

id#

The file’s ID.

Type:

str

class aiob2.DownloadedFile#

Represents a file downloaded from Backblaze.

name#

The file’s name.

Type:

str

id#

The file’s ID.

Type:

str

content_type#

The file’s content type, e.g. image/jpeg.

Type:

str

content_length#

The file’s size represented in number of bytes.

Type:

int

content_sha1#

The file’s SHA-1.

Type:

str

created#

The time at which the file was uploaded.

Type:

datetime.datetime

downloaded_at#

The date at which the download was requested.

Type:

str

content_disposition#

Whether or not the content is intended to be played inline, or downloaded locally and optionally the filename.

Type:

Optional[str]

content_language#

The content’s intended language audience.

Type:

Optional[str]

expires#

The intended expiration date of the content.

Type:

Optional[datetime.datetime]

content_encoding#

The content’s encoding in the order they were performed in.

Type:

Optional[str]

server_side_encryption#

The server side encryption performed on the content including the algorithm.

Type:

Optional[Literal[AES256]]

comments#

The comments uploaded with the file.

Type:

Optional[Dict[str, str]]

content#

The raw bytes of the downloaded file.

Type:

bytes