`b2sdk.bucket` – Bucket¶

class b2sdk.bucket.Bucket(api, id_, name=None, type_=None, bucket_info=None, cors_rules=None, lifecycle_rules=None, revision=None, bucket_dict=None)[source]¶

Bases: object

Provides access to a bucket in B2: listing files, uploading and downloading.

DEFAULT_CONTENT_TYPE = 'b2/x-auto'¶

MAX_LARGE_FILE_SIZE = 10000000000000¶

MAX_UPLOAD_ATTEMPTS = 5¶

__init__(api, id_, name=None, type_=None, bucket_info=None, cors_rules=None, lifecycle_rules=None, revision=None, bucket_dict=None)[source]¶

Parameters

api (b2sdk.api.B2Api) – an API object
id (str) – a bucket id
name (str) – a bucket name
type (str) – a bucket type
bucket_info (dict) – an info to store with a bucket
cors_rules (dict) – CORS rules to store with a bucket
lifecycle_rules (dict) – lifecycle rules to store with a bucket
revision (int) – a bucket revision number
bucket_dict (dict) – a dictionary which contains bucket parameters

as_dict()[source]¶

Return bucket representation as a dictionary

Return type: dict

cancel_large_file(file_id)[source]¶

Cancel large file transfer

Parameters: file_id (str) – a file ID

copy_file(file_id, new_file_name, bytes_range=None, metadata_directive=None, content_type=None, file_info=None, destination_bucket_id=None)[source]¶

Creates a new file in this bucket by (server-side) copying from an existing file.

Parameters

file_id (str) – file ID of existing file
new_file_name (str) – file name of the new file
bytes_range (tuple[int,int],None) – start and end offsets, default is the entire file
metadata_directive (b2sdk.v1.MetadataDirectiveMode,None) – default is b2sdk.v1.MetadataDirectiveMode.COPY
content_type (str,None) – content_type for the new file if metadata_directive is set to b2sdk.v1.MetadataDirectiveMode.REPLACE, default will copy the content_type of old file
file_info (dict,None) – file_info for the new file if metadata_directive is set to b2sdk.v1.MetadataDirectiveMode.REPLACE, default will copy the file_info of old file

delete_file_version(file_id, file_name)[source]¶

Delete file version

Parameters

file_id (str) – a file ID
file_name (str) – a file name

download_file_by_id(file_id, download_dest, progress_listener=None, range_=None)[source]¶

Download a file by ID, download_file_by_id actually belongs in B2Api, not in Bucket, we just provide a convenient redirect here

Parameters

file_id (str) – a file ID
download_dest (str) – a local file path
progress_listener (b2sdk.progress.AbstractProgressListener) – a progress listener object
range (list) – a list of two integer values, start and end offsets

download_file_by_name(file_name, download_dest, progress_listener=None, range_=None)[source]¶

Download a file by name

Parameters

file_id (str) – a file ID
download_dest (str) – a local file path
progress_listener (b2sdk.progress.AbstractProgressListener) – a progress listener object
range (list) – a list of two integer values, start and end offsets

get_download_authorization(file_name_prefix, valid_duration_in_seconds)[source]¶

Return an authorization token that is valid only for downloading files from the given bucket

Parameters

file_name_prefix (str) – a file name prefix, only files that match it could be downloaded
valid_duration_in_seconds (int) – a token is valid only during this amount of seconds

get_download_url(filename)[source]¶

Get file download URL

Parameters: filename (str) – a file name
Returns: file download URL
Return type: str

get_id()[source]¶

Return bucket ID

Type: str

hide_file(file_name)[source]¶

Hide a file

Parameters: file_name (str) – a file name
Returns: file version info
Return type: b2sdk.file_version.FileVersionInfoFactory

list_file_names(start_filename=None, max_entries=None, prefix=None)[source]¶: legacy interface which just returns whatever remote API returns

list_file_versions(start_filename=None, start_file_id=None, max_entries=None, prefix=None)[source]¶: legacy interface which just returns whatever remote API returns

list_parts(file_id, start_part_number=None, batch_size=None)[source]¶

Get a list of all parts that have been uploaded for a given file

Parameters

file_id (str) – a file ID
start_part_number (int) – the first part number to return. defaults to the first part.
batch_size (int) – the number of parts to fetch at a time from the server

list_unfinished_large_files(start_file_id=None, batch_size=None)[source]¶

A generator that yields an UnfinishedLargeFile for each unfinished large file in the bucket, starting at the given file.

Parameters

start_file_id (str) – a file ID to start with
batch_size (int) – max file count

Return type

generator

ls(folder_to_list='', show_versions=False, recursive=False, fetch_count=None)[source]¶

Pretends that folders exist, and yields the information about the files in a folder.

B2 has a flat namespace for the files in a bucket, but there is a convention of using “/” as if there were folders. This method searches through the flat namespace to find the files and “folders” that live within a given folder.

When the recursive flag is set, lists all of the files in the given folder, and all of its sub-folders.

Parameters

folder_to_list (str) – the name of the folder to list. Must not start with “/”. Empty string means top-level folder.
show_versions (bool) – when true returns info about all versions of a file, when false, just returns info about the most recent versions.
recursive (bool) – if True, list folders recursively
fetch_count (int) – how many entries to return. 1 - 1000

Return type

generator

set_info(new_bucket_info, if_revision_is=None)[source]¶

Update bucket info

Parameters

new_bucket_info (dict) – new bucket info dictionary
if_revision_is (int) – revision number, update the info if revision equals to if_revision_is’ value

set_type(bucket_type)[source]¶

Update bucket type

Parameters: bucket_type (str) – a bucket type

start_large_file(file_name, content_type=None, file_info=None)[source]¶

Start large file transfer

Parameters

file_name (str) – a file name
content_type (str) – request content type
file_info (dict) – a file info to store with the file

update(bucket_type=None, bucket_info=None, cors_rules=None, lifecycle_rules=None, if_revision_is=None)[source]¶

Update various bucket parameters

Parameters

bucket_type (str) – a bucket type
bucket_info (dict) – an info to store with a bucket
cors_rules (dict) – CORS rules to store with a bucket
lifecycle_rules (dict) – lifecycle rules to store with a bucket
if_revision_is (int) – revision number, update the info if revision equals to if_revision_is’ value

upload(upload_source, file_name, content_type=None, file_info=None, min_part_size=None, progress_listener=None)[source]¶

Uploads a file to B2, retrying as needed.

The source of the upload is an UploadSource object that can be used to open (and re-open) the file. The result of opening should be a binary file whose read() method returns bytes.

Parameters

upload_source (b2sdk.upload_source.UploadSource) – an UploadSource object that opens the source of the upload
file_name (str) – the file name of the new B2 file
content_type (str, None) – the MIME type, or None to accept the default based on file extension of the B2 file name
file_infos (dict) – custom file info to be stored with the file
min_part_size (int) – the smallest part size to use
progress_listener (b2sdk.progress.AbstractProgressListener) – object to notify as data is transferred

The function opener should return a file-like object, and it must be possible to call it more than once in case the upload is retried.

upload_bytes(data_bytes, file_name, content_type=None, file_infos=None, progress_listener=None)[source]¶

Upload bytes in memory to a B2 file

Parameters

data_bytes (bytes) – a byte array to upload
file_name (str) – a file name to upload bytes to
content_type (str) – request content type
file_infos (dict) – a file info to store with the file
progress_listener (b2sdk.progress.AbstractProgressListener) – a progress listener object

upload_local_file(local_file, file_name, content_type=None, file_infos=None, sha1_sum=None, min_part_size=None, progress_listener=None)[source]¶

Uploads a file on local disk to a B2 file.

Parameters

local_file (str) – a path to a file on local disk
file_name (str) – a file name of the new B2 file
content_type (str) – request content type
file_infos (dict) – a file info to store with the file
sha1_sum (str) – file SHA1 hash
min_part_size (int) – a minimum size of a part
progress_listener (b2sdk.progress.AbstractProgressListener) – a progress listener object

class b2sdk.bucket.BucketFactory[source]¶

Bases: object

This is a factory for creating bucket objects from another kind of objects

classmethod from_api_bucket_dict(api, bucket_dict)[source]¶

Turns a dictionary, like this:

{
    "bucketType": "allPrivate",
    "bucketId": "a4ba6a39d8b6b5fd561f0010",
    "bucketName": "zsdfrtsazsdfafr",
    "accountId": "4aa9865d6f00",
    "bucketInfo": {},
    "revision": 1
}

into a Bucket object

Parameters

api (b2sdk.api.B2Api) – API object
bucket_dict (dict) – a dictionary with bucket properties

Returns

a Bucket object

Return type

b2sdk.bucket.Bucket

classmethod from_api_response(api, response)[source]¶

Create a Bucket object from API response

Parameters

api (b2sdk.api.B2Api) – API object
response (object) – response object

Returns

a Bucket object

Return type

b2sdk.bucket.Bucket

class b2sdk.bucket.LargeFileUploadState(file_progress_listener)[source]¶

Bases: object

Tracks the status of uploading a large file, accepting updates from the tasks that upload each of the parts.

The aggregated progress is passed on to a ProgressListener that reports the progress for the file as a whole.

This class is THREAD SAFE.

__init__(file_progress_listener)[source]¶

Parameters: file_progress_listener (b2sdk.progress.AbstractProgressListener) – a progress listener object

get_error_message()[source]¶

Get an error message

Returns: an error message
Return type: str

has_error()[source]¶

Check whether an error occured

Return type: bool

set_error(message)[source]¶

Set error message

Parameters: message (str) – an error message

update_part_bytes(bytes_delta)[source]¶

Update listener progress info

Parameters: bytes_delta (int) – number of bytes to increase a progress for

class b2sdk.bucket.PartProgressReporter(large_file_upload_state, *args, **kwargs)[source]¶

Bases: b2sdk.progress.AbstractProgressListener

An adapter that listens to the progress of upload a part and gives the information to a LargeFileUploadState.

Accepts absolute bytes_completed from the uploader, and reports deltas to the LargeFileUploadState. The bytes_completed for the part will drop back to 0 on a retry, which will result in a negative delta.

__init__(large_file_upload_state, *args, **kwargs)[source]¶

Parameters: large_file_upload_state (b2sdk.bucket.LargeFileUploadState) – LargeFileUploadState object

bytes_completed(byte_count)[source]¶

Update bytes completed value

Parameters: bytes_count (int) – a value to increase progress to

close()[source]¶: Perform cleanup operations

set_total_bytes(total_byte_count)[source]¶

Set total bytes value

Parameters: total_bytes_count (int) –

b2sdk.bucket – Bucket¶

`b2sdk.bucket` – Bucket¶