B2 Bucket

class b2sdk.v2.Bucket(api, id_, name=None, type_=None, bucket_info=None, cors_rules=None, lifecycle_rules=None, revision=None, bucket_dict=None, options_set=None, default_server_side_encryption=<EncryptionSetting(EncryptionMode.UNKNOWN, None, None)>, default_retention=BucketRetentionSetting('unknown', None), is_file_lock_enabled=None, replication=None)[source]
Parameters:
FILE_VERSION_FACTORY_CLASS

alias of FileVersionFactory

get_fresh_state()[source]

Fetch all the information about this bucket and return a new bucket object. This method does NOT change the object it is called on.

Return type:

Bucket

upload_bytes(data_bytes, file_name, content_type=None, file_info=None, progress_listener=None, encryption=None, file_retention=None, legal_hold=None, large_file_sha1=None, custom_upload_timestamp=None, cache_control=None, *args, **kwargs)[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,None) – the MIME type, or None to accept the default based on file extension of the B2 file name

  • file_info (Optional[dict]) – a file info to store with the file or None to not store anything

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

  • encryption (Optional[EncryptionSetting]) – encryption settings (None if unknown)

  • file_retention (Optional[FileRetentionSetting]) – file retention setting

  • legal_hold (Optional[LegalHold]) – legal hold setting

  • large_file_sha1 (Optional[NewType(Sha1HexDigest, str)]) – SHA-1 hash of the result file or None if unknown

  • custom_upload_timestamp (Optional[int]) – override object creation date, expressed as a number of milliseconds since epoch

  • cache_control (Optional[str]) – an optional cache control setting. Syntax based on the section 14.9 of RFC 2616. Example string value: ‘public, max-age=86400, s-maxage=3600, no-transform’.

  • expires (str,datetime.datetime,None) – an optional cache expiration setting. If this argument is a string, its syntax must be based on the section 14.21 of RFC 2616. Example string value: ‘Thu, 01 Dec 2050 16:00:00 GMT’. If this argument is a datetime, it will be converted to a string in the same format.

  • content_disposition (str,None) – an optional content disposition setting. Syntax based on the section 19.5.1 of RFC 2616. Example string value: ‘attachment; filename=”fname.ext”’.

  • content_encoding (str,None) – an optional content encoding setting.Syntax based on the section 14.11 of RFC 2616. Example string value: ‘gzip’.

  • content_language (str,None) – an optional content language setting. Syntax based on the section 14.12 of RFC 2616. Example string value: ‘mi, en_US’.

  • file_info –

  • encryption –

  • file_retention –

  • legal_hold –

  • large_file_sha1 –

  • custom_upload_timestamp –

  • cache_control –

Return type:

b2sdk.v2.FileVersion

upload_local_file(local_file, file_name, content_type=None, file_info=None, sha1_sum=None, min_part_size=None, progress_listener=None, encryption=None, file_retention=None, legal_hold=None, upload_mode=UploadMode.FULL, custom_upload_timestamp=None, cache_control=None, *args, **kwargs)[source]

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

  • file_info (Optional[dict]) – a file info to store with the file or None to not store anything

  • sha1_sum – file SHA1 hash or None to compute it automatically

  • min_part_size – lower limit of part size for the transfer planner, in bytes

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

  • encryption (Optional[EncryptionSetting]) – encryption settings (None if unknown)

  • file_retention (Optional[FileRetentionSetting]) – file retention setting

  • legal_hold (Optional[LegalHold]) – legal hold setting

  • upload_mode (UploadMode) – desired upload mode

  • custom_upload_timestamp (Optional[int]) – override object creation date, expressed as a number of milliseconds since epoch

  • cache_control (Optional[str]) – an optional cache control setting. Syntax based on the section 14.9 of RFC 2616. Example string value: ‘public, max-age=86400, s-maxage=3600, no-transform’.

  • expires (str,datetime.datetime,None) – an optional cache expiration setting. If this argument is a string, its syntax must be based on the section 14.21 of RFC 2616. Example string value: ‘Thu, 01 Dec 2050 16:00:00 GMT’. If this argument is a datetime, it will be converted to a string in the same format.

  • content_disposition (str,None) – an optional content disposition setting. Syntax based on the section 19.5.1 of RFC 2616. Example string value: ‘attachment; filename=”fname.ext”’.

  • content_encoding (str,None) – an optional content encoding setting.Syntax based on the section 14.11 of RFC 2616. Example string value: ‘gzip’.

  • content_language (str,None) – an optional content language setting. Syntax based on the section 14.12 of RFC 2616. Example string value: ‘mi, en_US’.

  • encryption –

  • file_retention –

  • legal_hold –

  • upload_mode –

  • custom_upload_timestamp –

  • cache_control –

Return type:

b2sdk.v2.FileVersion

ls(folder_to_list='', latest_only=True, recursive=False, fetch_count=10000, with_wildcard=False, filters=(), folder_to_list_can_be_a_file=False, **kwargs)[source]

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

  • latest_only (bool) – when False returns info about all versions of a file, when True, just returns info about the most recent versions

  • recursive (bool) – if True, list folders recursively

  • fetch_count (Optional[int]) – how many entries to list per API call or None to use the default. Acceptable values: 1 - 10000

  • with_wildcard (bool) – Accepts “*”, “?”, “[]” and “[!]” in folder_to_list, similarly to what shell does. As of 1.19.0 it can only be enabled when recursive is also enabled. Also, in this mode, folder_to_list is considered to be a filename or a pattern.

  • filters (Sequence[Filter]) – list of filters to apply to the files returned by the server.

  • folder_to_list_can_be_a_file (bool) – if True, folder_to_list can be a file, not just a folder This enabled default behavior of b2sdk.v3.Bucket.ls, in which for all paths that do not end with ‘/’, first we try to check if file with this exact name exists, and only if it does not then we try to list files with this prefix.

Return type:

generator[tuple[b2sdk.v2.FileVersion, str]]

Returns:

generator of (file_version, folder_name) tuples

Note

In case of recursive=True, folder_name is not returned.

DEFAULT_CONTENT_TYPE = 'b2/x-auto'
__init__(api, id_, name=None, type_=None, bucket_info=None, cors_rules=None, lifecycle_rules=None, revision=None, bucket_dict=None, options_set=None, default_server_side_encryption=<EncryptionSetting(EncryptionMode.UNKNOWN, None, None)>, default_retention=BucketRetentionSetting('unknown', None), is_file_lock_enabled=None, replication=None)[source]
Parameters:

  • api (b2sdk.v2.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 (Optional[list[LifecycleRule]]) – lifecycle rules of the bucket

  • revision (int) – a bucket revision number

  • bucket_dict (dict) – a dictionary which contains bucket parameters

  • options_set (set) – set of bucket options strings

  • default_server_side_encryption (EncryptionSetting) – default server side encryption settings

  • default_retention (BucketRetentionSetting) – default retention setting

  • is_file_lock_enabled (Optional[bool]) – whether file locking is enabled or not

  • replication (Optional[ReplicationConfiguration]) – replication rules for the bucket

  • default_server_side_encryption –

  • default_retention –

  • is_file_lock_enabled –

  • replication –

as_dict()[source]

Return bucket representation as a dictionary.

Return type:

dict

cancel_large_file(file_id)[source]

Cancel a large file transfer.

Parameters:

file_id (str) – a file ID

concatenate(outbound_sources, file_name, content_type=None, file_info=None, progress_listener=None, recommended_upload_part_size=None, continue_large_file_id=None, encryption=None, file_retention=None, legal_hold=None, min_part_size=None, max_part_size=None, large_file_sha1=None, custom_upload_timestamp=None, cache_control=None, expires=None, content_disposition=None, content_encoding=None, content_language=None)[source]

Creates a new file in this bucket by concatenating multiple remote or local sources.

Parameters:

  • outbound_sources (list[b2sdk.v2.OutboundTransferSource]) – list of outbound sources (remote or local)

  • file_name (str) – file name of the new file

  • content_type (str,None) – content_type for the new file, if None content_type would be automatically determined from file name or it may be copied if it resolves as single part remote source copy

  • file_info (dict,None) – file_info for the new file, if None it will be set to empty dict or it may be copied if it resolves as single part remote source copy

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

  • recommended_upload_part_size (int,None) – the recommended part size to use for uploading local sources or None to determine automatically, but remote sources would be copied with maximum possible part size

  • continue_large_file_id (str,None) – large file id that should be selected to resume file creation for multipart upload/copy, None for automatic search for this id

  • encryption (Optional[EncryptionSetting]) – encryption settings (None if unknown)

  • file_retention (Optional[FileRetentionSetting]) – file retention setting

  • legal_hold (Optional[LegalHold]) – legal hold setting

  • min_part_size (Optional[int]) – lower limit of part size for the transfer planner, in bytes

  • max_part_size (Optional[int]) – upper limit of part size for the transfer planner, in bytes

  • large_file_sha1 (Sha1HexDigest,None) – SHA-1 hash of the result file or None if unknown

  • custom_upload_timestamp (Optional[int]) – override object creation date, expressed as a number of milliseconds since epoch

  • cache_control (Optional[str]) – an optional cache control setting. Syntax based on the section 14.9 of RFC 2616. Example string value: ‘public, max-age=86400, s-maxage=3600, no-transform’.

  • expires (UnionType[str, datetime, None]) – an optional cache expiration setting. If this argument is a string, its syntax must be based on the section 14.21 of RFC 2616. Example string value: ‘Thu, 01 Dec 2050 16:00:00 GMT’. If this argument is a datetime, it will be converted to a string in the same format.

  • content_disposition (Optional[str]) – an optional content disposition setting. Syntax based on the section 19.5.1 of RFC 2616. Example string value: ‘attachment; filename=”fname.ext”’.

  • content_encoding (Optional[str]) – an optional content encoding setting.Syntax based on the section 14.11 of RFC 2616. Example string value: ‘gzip’.

  • content_language (Optional[str]) – an optional content language setting. Syntax based on the section 14.12 of RFC 2616. Example string value: ‘mi, en_US’.

  • encryption –

  • file_retention –

  • legal_hold –

  • custom_upload_timestamp –

  • cache_control –

  • expires –

  • content_disposition –

  • content_encoding –

  • content_language –

concatenate_stream(outbound_sources_iterator, file_name, content_type=None, file_info=None, progress_listener=None, recommended_upload_part_size=None, continue_large_file_id=None, encryption=None, file_retention=None, legal_hold=None, large_file_sha1=None, custom_upload_timestamp=None, cache_control=None, expires=None, content_disposition=None, content_encoding=None, content_language=None)[source]

Creates a new file in this bucket by concatenating stream of multiple remote or local sources.

Parameters:

  • outbound_sources_iterator (iterator[b2sdk.v2.OutboundTransferSource]) – iterator of outbound sources

  • file_name (str) – file name of the new file

  • content_type (str,None) – content_type for the new file, if None content_type would be automatically determined or it may be copied if it resolves as single part remote source copy

  • file_info (dict,None) – file_info for the new file, if None it will be set to empty dict or it may be copied if it resolves as single part remote source copy

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

  • recommended_upload_part_size (int,None) – the recommended part size to use for uploading local sources or None to determine automatically, but remote sources would be copied with maximum possible part size

  • continue_large_file_id (str,None) – large file id that should be selected to resume file creation for multipart upload/copy, if None in multipart case it would always start a new large file

  • encryption (Optional[EncryptionSetting]) – encryption setting (None if unknown)

  • file_retention (Optional[FileRetentionSetting]) – file retention setting

  • legal_hold (Optional[LegalHold]) – legal hold setting

  • large_file_sha1 (Optional[NewType(Sha1HexDigest, str)]) – SHA-1 hash of the result file or None if unknown

  • custom_upload_timestamp (Optional[int]) – override object creation date, expressed as a number of milliseconds since epoch

  • cache_control (Optional[str]) – an optional cache control setting. Syntax based on the section 14.9 of RFC 2616. Example string value: ‘public, max-age=86400, s-maxage=3600, no-transform’.

  • expires (UnionType[str, datetime, None]) – an optional cache expiration setting. If this argument is a string, its syntax must be based on the section 14.21 of RFC 2616. Example string value: ‘Thu, 01 Dec 2050 16:00:00 GMT’. If this argument is a datetime, it will be converted to a string in the same format.

  • content_disposition (Optional[str]) – an optional content disposition setting. Syntax based on the section 19.5.1 of RFC 2616. Example string value: ‘attachment; filename=”fname.ext”’.

  • content_encoding (Optional[str]) – an optional content encoding setting.Syntax based on the section 14.11 of RFC 2616. Example string value: ‘gzip’.

  • content_language (Optional[str]) – an optional content language setting. Syntax based on the section 14.12 of RFC 2616. Example string value: ‘mi, en_US’.

  • encryption –

  • file_retention –

  • legal_hold –

  • large_file_sha1 –

  • custom_upload_timestamp –

  • cache_control –

  • expires –

  • content_disposition –

  • content_encoding –

  • content_language –

copy(file_id, new_file_name, content_type=None, file_info=None, offset=0, length=None, progress_listener=None, destination_encryption=None, source_encryption=None, source_file_info=None, source_content_type=None, file_retention=None, legal_hold=None, cache_control=None, min_part_size=None, max_part_size=None, expires=None, content_disposition=None, content_encoding=None, content_language=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 to copy from

  • new_file_name (str) – file name of the new file

  • content_type (str,None) – content_type for the new file, if None and b2_copy_file will be used content_type will be copied from source file - otherwise content_type would be automatically determined

  • file_info (dict,None) – file_info for the new file, if None will and b2_copy_file will be used file_info will be copied from source file - otherwise it will be set to empty dict

  • offset (int) – offset of existing file that copy should start from

  • length (int,None) – number of bytes to copy, if None then offset have to be 0 and it will use b2_copy_file without range parameter so it may fail if file is too large. For large files length have to be specified to use b2_copy_part instead.

  • progress_listener (b2sdk.v2.AbstractProgressListener,None) – a progress listener object to use for multipart copy, or None to not report progress

  • destination_encryption (Optional[EncryptionSetting]) – encryption settings for the destination (None if unknown)

  • source_encryption (Optional[EncryptionSetting]) – encryption settings for the source (None if unknown)

  • source_file_info (Optional[dict]) – source file’s file_info dict, useful when copying files with SSE-C

  • source_content_type (Optional[str]) – source file’s content type, useful when copying files with SSE-C

  • file_retention (Optional[FileRetentionSetting]) – file retention setting for the new file.

  • legal_hold (Optional[LegalHold]) – legal hold setting for the new file.

  • cache_control (Optional[str]) – an optional cache control setting. Syntax based on the section 14.9 of RFC 2616. Example string value: ‘public, max-age=86400, s-maxage=3600, no-transform’.

  • min_part_size (Optional[int]) – lower limit of part size for the transfer planner, in bytes

  • max_part_size (Optional[int]) – upper limit of part size for the transfer planner, in bytes

  • expires (UnionType[str, datetime, None]) – an optional cache expiration setting. If this argument is a string, its syntax must be based on the section 14.21 of RFC 2616. Example string value: ‘Thu, 01 Dec 2050 16:00:00 GMT’. If this argument is a datetime, it will be converted to a string in the same format.

  • content_disposition (Optional[str]) – an optional content disposition setting. Syntax based on the section 19.5.1 of RFC 2616. Example string value: ‘attachment; filename=”fname.ext”’.

  • content_encoding (Optional[str]) – an optional content encoding setting.Syntax based on the section 14.11 of RFC 2616. Example string value: ‘gzip’.

  • content_language (Optional[str]) – an optional content language setting. Syntax based on the section 14.12 of RFC 2616. Example string value: ‘mi, en_US’.

  • destination_encryption –

  • source_encryption –

  • source_file_info –

  • source_content_type –

  • file_retention –

  • legal_hold –

  • cache_control –

  • expires –

  • content_disposition –

  • content_encoding –

  • content_language –

Return type:

FileVersion

create_file(write_intents, file_name, content_type=None, file_info=None, progress_listener=None, recommended_upload_part_size=None, continue_large_file_id=None, encryption=None, file_retention=None, legal_hold=None, min_part_size=None, max_part_size=None, large_file_sha1=None, custom_upload_timestamp=None, cache_control=None, expires=None, content_disposition=None, content_encoding=None, content_language=None)[source]

Creates a new file in this bucket using an iterable (list, tuple etc) of remote or local sources.

Source ranges can overlap and remote sources will be prioritized over local sources (when possible). For more information and usage examples please see Advanced usage patterns.

Parameters:

  • write_intents (list[b2sdk.v2.WriteIntent]) – list of write intents (remote or local sources)

  • file_name (str) – file name of the new file

  • content_type (str,None) – content_type for the new file, if None content_type would be automatically determined or it may be copied if it resolves as single part remote source copy

  • file_info (dict,None) – file_info for the new file, if None it will be set to empty dict or it may be copied if it resolves as single part remote source copy

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

  • recommended_upload_part_size (int,None) – the recommended part size to use for uploading local sources or None to determine automatically, but remote sources would be copied with maximum possible part size

  • continue_large_file_id (str,None) – large file id that should be selected to resume file creation for multipart upload/copy, None for automatic search for this id

  • encryption (Optional[EncryptionSetting]) – encryption settings (None if unknown)

  • file_retention (Optional[FileRetentionSetting]) – file retention setting

  • legal_hold (Optional[LegalHold]) – legal hold setting

  • min_part_size (Optional[int]) – lower limit of part size for the transfer planner, in bytes

  • max_part_size (Optional[int]) – upper limit of part size for the transfer planner, in bytes

  • large_file_sha1 (Sha1HexDigest,None) – SHA-1 hash of the result file or None if unknown

  • custom_upload_timestamp (Optional[int]) – override object creation date, expressed as a number of milliseconds since epoch

  • cache_control (Optional[str]) – an optional cache control setting. Syntax based on the section 14.9 of RFC 2616. Example string value: ‘public, max-age=86400, s-maxage=3600, no-transform’.

  • expires (UnionType[str, datetime, None]) – an optional cache expiration setting. If this argument is a string, its syntax must be based on the section 14.21 of RFC 2616. Example string value: ‘Thu, 01 Dec 2050 16:00:00 GMT’. If this argument is a datetime, it will be converted to a string in the same format.

  • content_disposition (Optional[str]) – an optional content disposition setting. Syntax based on the section 19.5.1 of RFC 2616. Example string value: ‘attachment; filename=”fname.ext”’.

  • content_encoding (Optional[str]) – an optional content encoding setting.Syntax based on the section 14.11 of RFC 2616. Example string value: ‘gzip’.

  • content_language (Optional[str]) – an optional content language setting. Syntax based on the section 14.12 of RFC 2616. Example string value: ‘mi, en_US’.

  • encryption –

  • file_retention –

  • legal_hold –

  • custom_upload_timestamp –

  • cache_control –

  • expires –

  • content_disposition –

  • content_encoding –

  • content_language –

create_file_stream(write_intents_iterator, file_name, content_type=None, file_info=None, progress_listener=None, recommended_upload_part_size=None, continue_large_file_id=None, encryption=None, file_retention=None, legal_hold=None, min_part_size=None, max_part_size=None, large_file_sha1=None, custom_upload_timestamp=None, cache_control=None, expires=None, content_disposition=None, content_encoding=None, content_language=None)[source]

Creates a new file in this bucket using a stream of multiple remote or local sources.

Source ranges can overlap and remote sources will be prioritized over local sources (when possible). For more information and usage examples please see Advanced usage patterns.

Parameters:

  • write_intents_iterator (iterator[b2sdk.v2.WriteIntent]) – iterator of write intents which are sorted ascending by destination_offset

  • file_name (str) – file name of the new file

  • content_type (str,None) – content_type for the new file, if None content_type would be automatically determined or it may be copied if it resolves as single part remote source copy

  • file_info (dict,None) – file_info for the new file, if None it will be set to empty dict or it may be copied if it resolves as single part remote source copy

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

  • recommended_upload_part_size (int,None) – the recommended part size to use for uploading local sources or None to determine automatically, but remote sources would be copied with maximum possible part size

  • continue_large_file_id (str,None) – large file id that should be selected to resume file creation for multipart upload/copy, if None in multipart case it would always start a new large file

  • encryption (Optional[EncryptionSetting]) – encryption settings (None if unknown)

  • file_retention (Optional[FileRetentionSetting]) – file retention setting

  • legal_hold (Optional[LegalHold]) – legal hold setting

  • min_part_size (Optional[int]) – lower limit of part size for the transfer planner, in bytes

  • max_part_size (Optional[int]) – upper limit of part size for the transfer planner, in bytes

  • large_file_sha1 (Sha1HexDigest,None) – SHA-1 hash of the result file or None if unknown

  • custom_upload_timestamp (Optional[int]) – override object creation date, expressed as a number of milliseconds since epoch

  • cache_control (Optional[str]) – an optional cache control setting. Syntax based on the section 14.9 of RFC 2616. Example string value: ‘public, max-age=86400, s-maxage=3600, no-transform’.

  • expires (UnionType[str, datetime, None]) – an optional cache expiration setting. If this argument is a string, its syntax must be based on the section 14.21 of RFC 2616. Example string value: ‘Thu, 01 Dec 2050 16:00:00 GMT’. If this argument is a datetime, it will be converted to a string in the same format.

  • content_disposition (Optional[str]) – an optional content disposition setting. Syntax based on the section 19.5.1 of RFC 2616. Example string value: ‘attachment; filename=”fname.ext”’.

  • content_encoding (Optional[str]) – an optional content encoding setting.Syntax based on the section 14.11 of RFC 2616. Example string value: ‘gzip’.

  • content_language (Optional[str]) – an optional content language setting. Syntax based on the section 14.12 of RFC 2616. Example string value: ‘mi, en_US’.

  • encryption –

  • file_retention –

  • legal_hold –

  • custom_upload_timestamp –

  • cache_control –

  • expires –

  • content_disposition –

  • content_encoding –

  • content_language –

delete_file_version(file_id, file_name, bypass_governance=False)[source]

Delete a file version.

Parameters:

  • file_id (str) – a file ID

  • file_name (str) – a file name

  • bypass_governance (bool) – Must be set to true if deleting a file version protected by Object Lock governance mode retention settings (unless its retention period expired)

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

Download a file by ID.

Note

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

Parameters:
Return type:

DownloadedFile

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

Download a file by name.

See also

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

Parameters:
Return type:

DownloadedFile

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

Return type:

str

get_file_info_by_id(file_id)[source]

Gets a file version’s by ID.

Parameters:

  • file_id (str) – the id of the file who’s info will be retrieved.

  • file_id –

Return type:

generator[b2sdk.v2.FileVersion]

get_file_info_by_name(file_name)[source]

Gets a file’s DownloadVersion by name.

Parameters:

  • file_name (str) – the name of the file who’s info will be retrieved.

  • file_name –

Return type:

DownloadVersion

get_id()[source]

Return bucket ID.

Return type:

str

get_notification_rules()[source]

Get all notification rules for this bucket.

Return type:

list[NotificationRuleResponse]

hide_file(file_name)[source]

Hide a file.

Parameters:

file_name (str) – a file name

Return type:

b2sdk.v2.FileVersion

list_file_versions(file_name, fetch_count=10000)[source]

Lists all of the versions for a single file.

Parameters:

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

  • fetch_count (Optional[int]) – how many entries to list per API call or None to use the default. Acceptable values: 1 - 10000

Return type:

generator[b2sdk.v2.FileVersion]

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, prefix=None)[source]

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

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

  • prefix (str,None) – file name prefix filter

Return type:

generator[b2sdk.v2.UnfinishedLargeFile]

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

Return type:

Bucket

set_notification_rules(rules)[source]

Set notification rules for this bucket.

Parameters:

rules (Iterable[NotificationRule]) –

Return type:

list[NotificationRuleResponse]

set_type(bucket_type)[source]

Update bucket type.

Parameters:

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

Return type:

Bucket

update(bucket_type=None, bucket_info=None, cors_rules=None, lifecycle_rules=None, if_revision_is=None, default_server_side_encryption=None, default_retention=None, replication=None, is_file_lock_enabled=None)[source]

Update various bucket parameters.

Parameters:

  • bucket_type (Optional[str]) – a bucket type, e.g. allPrivate or allPublic

  • bucket_info (Optional[dict]) – an info to store with a bucket

  • cors_rules (Optional[dict]) – CORS rules to store with a bucket

  • lifecycle_rules (Optional[list[LifecycleRule]]) – lifecycle rules to store with a bucket

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

  • default_server_side_encryption (Optional[EncryptionSetting]) – default server side encryption settings (None if unknown)

  • default_retention (Optional[BucketRetentionSetting]) – bucket default retention setting

  • replication (Optional[ReplicationConfiguration]) – replication rules for the bucket

  • is_file_lock_enabled (Optional[bool]) – specifies whether bucket should get File Lock-enabled

  • is_file_lock_enabled –

Return type:

Bucket

upload(upload_source, file_name, content_type=None, file_info=None, min_part_size=None, progress_listener=None, encryption=None, file_retention=None, legal_hold=None, large_file_sha1=None, custom_upload_timestamp=None, cache_control=None, expires=None, content_disposition=None, content_encoding=None, content_language=None)[source]

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.

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.

Parameters:

  • upload_source (b2sdk.v2.AbstractUploadSource) – 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_info (dict,None) – a file info to store with the file or None to not store anything

  • min_part_size (Optional[int]) – lower limit of part size for the transfer planner, in bytes

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

  • encryption (Optional[EncryptionSetting]) – encryption settings (None if unknown)

  • file_retention (Optional[FileRetentionSetting]) – file retention setting

  • legal_hold (Optional[LegalHold]) – legal hold setting

  • large_file_sha1 (Optional[NewType(Sha1HexDigest, str)]) – SHA-1 hash of the result file or None if unknown

  • custom_upload_timestamp (Optional[int]) – override object creation date, expressed as a number of milliseconds since epoch

  • cache_control (Optional[str]) – an optional cache control setting. Syntax based on the section 14.9 of RFC 2616. Example string value: ‘public, max-age=86400, s-maxage=3600, no-transform’.

  • expires (UnionType[str, datetime, None]) – an optional cache expiration setting. If this argument is a string, its syntax must be based on the section 14.21 of RFC 2616. Example string value: ‘Thu, 01 Dec 2050 16:00:00 GMT’. If this argument is a datetime, it will be converted to a string in the same format.

  • content_disposition (Optional[str]) – an optional content disposition setting. Syntax based on the section 19.5.1 of RFC 2616. Example string value: ‘attachment; filename=”fname.ext”’.

  • content_encoding (Optional[str]) – an optional content encoding setting.Syntax based on the section 14.11 of RFC 2616. Example string value: ‘gzip’.

  • content_language (Optional[str]) – an optional content language setting. Syntax based on the section 14.12 of RFC 2616. Example string value: ‘mi, en_US’.

  • encryption –

  • file_retention –

  • legal_hold –

  • large_file_sha1 –

  • custom_upload_timestamp –

  • cache_control –

  • expires –

  • content_disposition –

  • content_encoding –

  • content_language –

Return type:

b2sdk.v2.FileVersion

upload_unbound_stream(read_only_object, file_name, content_type=None, file_info=None, progress_listener=None, recommended_upload_part_size=None, encryption=None, file_retention=None, legal_hold=None, min_part_size=None, max_part_size=None, large_file_sha1=None, buffers_count=2, buffer_size=None, read_size=8192, unused_buffer_timeout_seconds=3600.0, custom_upload_timestamp=None, cache_control=None, expires=None, content_disposition=None, content_encoding=None, content_language=None)[source]

Upload an unbound file-like read-only object to a B2 file.

It is assumed that this object is streamed like stdin or socket, and the size is not known up front. It is up to caller to ensure that this object is open and available through the whole streaming process.

If stdin is to be passed, consider opening it in binary mode, if possible on the platform:

with open(sys.stdin.fileno(), mode='rb', buffering=min_part_size, closefd=False) as source:
    bucket.upload_unbound_stream(source, 'target-file')

For platforms without file descriptors, one can use the following:

bucket.upload_unbound_stream(sys.stdin.buffer, 'target-file')

but note that buffering in this case depends on the interpreter mode.

min_part_size, recommended_upload_part_size and max_part_size should all be greater than account_info.get_absolute_minimum_part_size().

buffers_count describes a desired number of buffers that are to be used. Minimal amount is 2. to determine the method of uploading this stream (if there’s only a single buffer we send it as a normal file, if there are at least two – as a large file). Number of buffers determines the amount of memory used by the streaming process and the amount of data that can be pulled from read_only_object while also uploading it. Providing more buffers allows for higher upload parallelization. While only one buffer can be filled with data at once, all others are used to send the data in parallel (limited only by the number of parallel threads).

Buffer size can be controlled by buffer_size parameter. If left unset, it will default to a value of recommended_upload_part_size. Note that in the current implementation buffers are (almost) directly sent to B2, thus whatever is picked as the buffer_size will also become the size of the part when uploading a large file in this manner. In rare cases, namely when the whole buffer was sent, but there was an error during sending of last bytes and a retry was issued, additional buffer (above the aforementioned limit) will be temporarily allocated.

Parameters:

  • read_only_object – any object containing a read method accepting size of the read

  • file_name (str) – a file name of the new B2 file

  • content_type (str) – the MIME type, or None to accept the default based on file extension of the B2 file name

  • file_info (Optional[dict[str, str]]) – a file info to store with the file or None to not store anything

  • progress_listener (Optional[AbstractProgressListener]) – a progress listener object to use, or None to not report progress

  • encryption (Optional[EncryptionSetting]) – encryption settings (None if unknown)

  • file_retention (Optional[FileRetentionSetting]) – file retention setting

  • legal_hold (Optional[LegalHold]) – legal hold setting

  • recommended_upload_part_size (Optional[int]) – the recommended part size to use for uploading local sources or None to determine automatically

  • min_part_size (Optional[int]) – lower limit of part size for the transfer planner, in bytes

  • max_part_size (Optional[int]) – upper limit of part size for the transfer planner, in bytes

  • large_file_sha1 (Optional[NewType(Sha1HexDigest, str)]) – SHA-1 hash of the result file or None if unknown

  • buffers_count (int) – desired number of buffers allocated, cannot be smaller than 2

  • buffer_size (Optional[int]) – size of a single buffer that we pull data to or upload data to B2. If None, value of recommended_upload_part_size is used. If that also is None, it will be determined automatically as “recommended upload size”.

  • read_size (int) – size of a single read operation performed on the read_only_object

  • unused_buffer_timeout_seconds (float) – amount of time that a buffer can be idle before returning error

  • custom_upload_timestamp (Optional[int]) – override object creation date, expressed as a number of milliseconds since epoch

  • cache_control (Optional[str]) – an optional cache control setting. Syntax based on the section 14.9 of RFC 2616. Example string value: ‘public, max-age=86400, s-maxage=3600, no-transform’.

  • expires (UnionType[str, datetime, None]) – an optional cache expiration setting. If this argument is a string, its syntax must be based on the section 14.21 of RFC 2616. Example string value: ‘Thu, 01 Dec 2050 16:00:00 GMT’. If this argument is a datetime, it will be converted to a string in the same format.

  • content_disposition (Optional[str]) – an optional content disposition setting. Syntax based on the section 19.5.1 of RFC 2616. Example string value: ‘attachment; filename=”fname.ext”’.

  • content_encoding (Optional[str]) – an optional content encoding setting.Syntax based on the section 14.11 of RFC 2616. Example string value: ‘gzip’.

  • content_language (Optional[str]) – an optional content language setting. Syntax based on the section 14.12 of RFC 2616. Example string value: ‘mi, en_US’.

  • custom_upload_timestamp –

  • cache_control –

  • expires –

  • content_disposition –

  • content_encoding –

  • content_language –

Return type:

b2sdk.v2.FileVersion