B2 Bucket

class b2sdk.v1.Bucket

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

DEFAULT_CONTENT_TYPE = 'b2/x-auto'

MAX_UPLOAD_ATTEMPTS = 5

MAX_LARGE_FILE_SIZE = 10000000000000

__init__(api, id_, name=None, type_=None, bucket_info=None, cors_rules=None, lifecycle_rules=None, revision=None, bucket_dict=None)

Parameters

• api (b2sdk.v1.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

get_id()

Return bucket ID.

Return type

str

set_info(new_bucket_info, if_revision_is=None)

Update bucket info.

Parameters

• new_bucket_info (dict) – new bucket info dictionary

• if_revision_is (int) – revision number, update the info only if revision equals to if_revision_is

set_type(bucket_type)

Update bucket type.

Parameters

bucket_type (str) – a bucket type (“allPublic” or “allPrivate”)

update(bucket_type=None, bucket_info=None, cors_rules=None, lifecycle_rules=None, if_revision_is=None)

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 only if revision equals to if_revision_is

cancel_large_file(file_id)

Cancel a large file transfer.

Parameters

file_id (str) – a file ID

download_file_by_id(file_id, download_dest, progress_listener=None, range_=None)

Download a file by ID.

Note

download_file_by_id actually belongs in b2sdk.v1.B2Api, not in b2sdk.v1.Bucket; we just provide a convenient redirect here

Parameters

• file_id (str) – a file ID

• download_dest (str) – a local file path

• None progress_listener (b2sdk.v1.AbstractProgressListener,) – a progress listener object to use, or None to not report progress

• int] range (tuple[int,) – two integer values, start and end offsets

download_file_by_name(file_name, download_dest, progress_listener=None, range_=None)

Download a file by name.

See also

Synchronizer, a high-performance utility that synchronizes a local folder with a Bucket.

Parameters

• file_id (str) – a file ID

• download_dest (str) – a local file path

• None progress_listener (b2sdk.v1.AbstractProgressListener,) – a progress listener object to use, or None to not track progress

• int] range (tuple[int,) – two integer values, start and end offsets

get_download_authorization(file_name_prefix, valid_duration_in_seconds)

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

list_parts(file_id, start_part_number=None, batch_size=None)

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

ls(folder_to_list='', show_versions=False, recursive=False, fetch_count=None)

Pretend 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,None) – how many entries to return or None to use the default. Acceptable values: 1 - 1000

Return type

generator[tuple[b2sdk.v1.FileVersionInfo, str]]

Returns

generator of (file_version_info, folder_name) tuples

Note

In case of recursive=True, folder_name is returned only for first file in the folder.

list_unfinished_large_files(start_file_id=None, batch_size=None)

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

Parameters

• start_file_id (str,None) – a file ID to start from or None to start from the beginning

• batch_size (int,None) – max file count

Return type

generator[b2sdk.v1.UnfinishedLargeFile]

start_large_file(file_name, content_type=None, file_info=None)

Start a large file transfer.

Parameters

• file_name (str) – a file name

• 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,None) – a file info to store with the file or None to not store anything

upload_bytes(data_bytes, file_name, content_type=None, file_infos=None, progress_listener=None)

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,None) – the MIME type, or None to accept the default based on file extension of the B2 file name

• file_infos (dict,None) – a file info to store with the file or None to not store anything

• progress_listener (b2sdk.v1.AbstractProgressListener,None) – a progress listener object to use, or None to not track progress

upload_local_file(local_file, file_name, content_type=None, file_infos=None, sha1_sum=None, min_part_size=None, progress_listener=None)

Upload a file on local disk to a B2 file.

See also

Synchronizer, a high-performance utility that synchronizes a local folder with a Bucket.

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,None) – the MIME type, or None to accept the default based on file extension of the B2 file name

• file_infos (dict,None) – a file info to store with the file or None to not store anything

• sha1_sum (str,None) – file SHA1 hash or None to compute it automatically

• min_part_size (int) – a minimum size of a part

• progress_listener (b2sdk.v1.AbstractProgressListener,None) – a progress listener object to use, or None to not report progress

upload(upload_source, file_name, content_type=None, file_info=None, min_part_size=None, progress_listener=None)

Upload 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.v1.UploadSource) – an 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,None) – a file info to store with the file or None to not store anything

• min_part_size (int,None) – the smallest part size to use or None to determine automatically

• progress_listener (b2sdk.v1.AbstractProgressListener,None) – a progress listener object to use, or None to not report progress

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.

get_download_url(filename)

Get file download URL.

Parameters

filename (str) – a file name

Return type

str

hide_file(file_name)

Hide a file.

Parameters

file_name (str) – a file name

Return type

b2sdk.v1.FileVersionInfo

copy_file(file_id, new_file_name, bytes_range=None, metadata_directive=None, content_type=None, file_info=None)

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 (inclusive!), 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)

Delete a file version.

Parameters

• file_id (str) – a file ID

• file_name (str) – a file name

as_dict()

Return bucket representation as a dictionary.

Return type

dict