B2 Bucket
- class b2sdk.v2.Bucket[source]
- get_fresh_state() Bucket [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.
- 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: ~b2sdk.encryption.setting.EncryptionSetting = <EncryptionSetting(EncryptionMode.UNKNOWN, None, None)>, default_retention: ~b2sdk.file_lock.BucketRetentionSetting = BucketRetentionSetting('unknown', None), is_file_lock_enabled: ~typing.Optional[bool] = None, replication: ~typing.Optional[~b2sdk.replication.setting.ReplicationConfiguration] = 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 (list) – 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 (b2sdk.v2.EncryptionSetting) – default server side encryption settings
default_retention (b2sdk.v2.BucketRetentionSetting) – default retention setting
is_file_lock_enabled (bool) – whether file locking is enabled or not
replication (b2sdk.v2.ReplicationConfiguration) – replication rules for the bucket
- 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: Optional[EncryptionSetting] = None, file_retention: Optional[FileRetentionSetting] = None, legal_hold: Optional[LegalHold] = None, min_part_size=None, max_part_size=None, large_file_sha1=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 copyfile_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 copyprogress_listener (b2sdk.v2.AbstractProgressListener,None) – a progress listener object to use, or
None
to not report progressrecommended_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 sizecontinue_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 idencryption (b2sdk.v2.EncryptionSetting) – encryption settings (
None
if unknown)file_retention (b2sdk.v2.FileRetentionSetting) – file retention setting
legal_hold (bool) – legal hold setting
min_part_size (int) – lower limit of part size for the transfer planner, in bytes
max_part_size (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
- 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: Optional[EncryptionSetting] = None, file_retention: Optional[FileRetentionSetting] = None, legal_hold: Optional[LegalHold] = None, large_file_sha1: Optional[Sha1HexDigest] = 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 copyfile_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 copyprogress_listener (b2sdk.v2.AbstractProgressListener,None) – a progress listener object to use, or
None
to not report progressrecommended_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 sizecontinue_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 fileencryption (b2sdk.v2.EncryptionSetting) – encryption setting (
None
if unknown)file_retention (b2sdk.v2.FileRetentionSetting) – file retention setting
legal_hold (bool) – legal hold setting
large_file_sha1 (Sha1HexDigest,None) – SHA-1 hash of the result file or
None
if unknown
- copy(file_id, new_file_name, content_type=None, file_info=None, offset=0, length=None, progress_listener=None, destination_encryption: Optional[EncryptionSetting] = None, source_encryption: Optional[EncryptionSetting] = None, source_file_info: Optional[dict] = None, source_content_type: Optional[str] = None, file_retention: Optional[FileRetentionSetting] = None, legal_hold: Optional[LegalHold] = None, min_part_size=None, max_part_size=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
andb2_copy_file
will be used content_type will be copied from source file - otherwise content_type would be automatically determinedfile_info (dict,None) – file_info for the new file, if
None
will andb2_copy_file
will be used file_info will be copied from source file - otherwise it will be set to empty dictoffset (int) – offset of existing file that copy should start from
length (int,None) – number of bytes to copy, if
None
thenoffset
have to be0
and it will useb2_copy_file
withoutrange
parameter so it may fail if file is too large. For large files length have to be specified to useb2_copy_part
instead.progress_listener (b2sdk.v2.AbstractProgressListener,None) – a progress listener object to use for multipart copy, or
None
to not report progressdestination_encryption (b2sdk.v2.EncryptionSetting) – encryption settings for the destination (
None
if unknown)source_encryption (b2sdk.v2.EncryptionSetting) – encryption settings for the source (
None
if unknown)source_file_info (dict,None) – source file’s file_info dict, useful when copying files with SSE-C
source_content_type (str,None) – source file’s content type, useful when copying files with SSE-C
file_retention (b2sdk.v2.FileRetentionSetting) – file retention setting for the new file.
legal_hold (bool) – legal hold setting for the new file.
min_part_size (int) – lower limit of part size for the transfer planner, in bytes
max_part_size (int) – upper limit of part size for the transfer planner, in bytes
- 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: Optional[EncryptionSetting] = None, file_retention: Optional[FileRetentionSetting] = None, legal_hold: Optional[LegalHold] = None, min_part_size=None, max_part_size=None, large_file_sha1=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 copyfile_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 copyprogress_listener (b2sdk.v2.AbstractProgressListener,None) – a progress listener object to use, or
None
to not report progressrecommended_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 sizecontinue_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 idencryption (b2sdk.v2.EncryptionSetting) – encryption settings (
None
if unknown)file_retention (b2sdk.v2.FileRetentionSetting) – file retention setting
legal_hold (bool) – legal hold setting
min_part_size (int) – lower limit of part size for the transfer planner, in bytes
max_part_size (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
- 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: Optional[EncryptionSetting] = None, file_retention: Optional[FileRetentionSetting] = None, legal_hold: Optional[LegalHold] = None, min_part_size=None, max_part_size=None, large_file_sha1=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 copyfile_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 copyprogress_listener (b2sdk.v2.AbstractProgressListener,None) – a progress listener object to use, or
None
to not report progressrecommended_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 sizecontinue_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 fileencryption (b2sdk.v2.EncryptionSetting) – encryption settings (
None
if unknown)file_retention (b2sdk.v2.FileRetentionSetting) – file retention setting
legal_hold (bool) – legal hold setting
min_part_size (int) – lower limit of part size for the transfer planner, in bytes
max_part_size (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
- download_file_by_id(file_id: str, progress_listener: Optional[AbstractProgressListener] = None, range_: Optional[Tuple[int, int]] = None, encryption: Optional[EncryptionSetting] = None) DownloadedFile [source]
Download a file by ID.
Note
download_file_by_id actually belongs in
b2sdk.v2.B2Api
, not inb2sdk.v2.Bucket
; we just provide a convenient redirect here- Parameters:
file_id – a file ID
progress_listener – a progress listener object to use, or
None
to not track progressrange – two integer values, start and end offsets
encryption – encryption settings (
None
if unknown)
- download_file_by_name(file_name: str, progress_listener: Optional[AbstractProgressListener] = None, range_: Optional[Tuple[int, int]] = None, encryption: Optional[EncryptionSetting] = None) DownloadedFile [source]
Download a file by name.
See also
Synchronizer, a high-performance utility that synchronizes a local folder with a Bucket.
- Parameters:
file_name – a file name
progress_listener – a progress listener object to use, or
None
to not track progressrange – two integer values, start and end offsets
encryption – encryption settings (
None
if unknown)
- 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.
- get_file_info_by_id(file_id: str) FileVersion [source]
Gets a file version’s by ID.
- Parameters:
file_id (str) – the id of the file who’s info will be retrieved.
- Return type:
generator[b2sdk.v2.FileVersion]
- get_file_info_by_name(file_name: str) DownloadVersion [source]
Gets a file’s DownloadVersion by name.
- Parameters:
file_name (str) – the name of the file who’s info will be retrieved.
- list_file_versions(file_name, fetch_count=None)[source]
Lists all of the versions for a single file.
- Parameters:
- 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.
- 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:
- Return type:
generator[b2sdk.v2.UnfinishedLargeFile]
- ls(folder_to_list: str = '', latest_only: bool = True, recursive: bool = False, fetch_count: Optional[int] = 10000, with_wildcard: bool = False)[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 – the name of the folder to list; must not start with “/”. Empty string means top-level folder
latest_only – when
False
returns info about all versions of a file, whenTrue
, just returns info about the most recent versionsrecursive – if
True
, list folders recursivelyfetch_count – how many entries to return or
None
to use the default. Acceptable values: 1 - 10000with_wildcard – 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.
- 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.
- set_type(bucket_type) Bucket [source]
Update bucket type.
- Parameters:
bucket_type (str) – a bucket type (“allPublic” or “allPrivate”)
- update(bucket_type: Optional[str] = None, bucket_info: Optional[dict] = None, cors_rules: Optional[dict] = None, lifecycle_rules: Optional[list] = None, if_revision_is: Optional[int] = None, default_server_side_encryption: Optional[EncryptionSetting] = None, default_retention: Optional[BucketRetentionSetting] = None, replication: Optional[ReplicationConfiguration] = None, is_file_lock_enabled: Optional[bool] = None) Bucket [source]
Update various bucket parameters.
- Parameters:
bucket_type – a bucket type, e.g.
allPrivate
orallPublic
bucket_info – an info to store with a bucket
cors_rules – CORS rules to store with a bucket
lifecycle_rules – lifecycle rules to store with a bucket
if_revision_is – revision number, update the info only if revision equals to if_revision_is
default_server_side_encryption – default server side encryption settings (
None
if unknown)default_retention – bucket default retention setting
replication – replication rules for the bucket
is_file_lock_enabled (bool) – specifies whether bucket should get File Lock-enabled
- upload(upload_source, file_name, content_type=None, file_info=None, min_part_size=None, progress_listener=None, encryption: Optional[EncryptionSetting] = None, file_retention: Optional[FileRetentionSetting] = None, legal_hold: Optional[LegalHold] = None, large_file_sha1: Optional[Sha1HexDigest] = 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 namefile_info (dict,None) – a file info to store with the file or
None
to not store anythingmin_part_size (int,None) – the smallest part size to use or
None
to determine automaticallyprogress_listener (b2sdk.v2.AbstractProgressListener,None) – a progress listener object to use, or
None
to not report progressencryption (b2sdk.v2.EncryptionSetting) – encryption settings (
None
if unknown)file_retention (b2sdk.v2.FileRetentionSetting) – file retention setting
legal_hold (bool) – legal hold setting
large_file_sha1 (Sha1HexDigest,None) – SHA-1 hash of the result file or
None
if unknown
- Return type:
- upload_bytes(data_bytes, file_name, content_type=None, file_infos=None, progress_listener=None, encryption: Optional[EncryptionSetting] = None, file_retention: Optional[FileRetentionSetting] = None, legal_hold: Optional[LegalHold] = None, large_file_sha1: Optional[Sha1HexDigest] = 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,None) – the MIME type, or
None
to accept the default based on file extension of the B2 file namefile_infos (dict,None) – a file info to store with the file or
None
to not store anythingprogress_listener (b2sdk.v2.AbstractProgressListener,None) – a progress listener object to use, or
None
to not track progressencryption (b2sdk.v2.EncryptionSetting) – encryption settings (
None
if unknown)file_retention (b2sdk.v2.FileRetentionSetting) – file retention setting
legal_hold (bool) – legal hold setting
large_file_sha1 (Sha1HexDigest,None) – SHA-1 hash of the result file or
None
if unknown
- Return type:
generator[b2sdk.v2.FileVersion]
- upload_local_file(local_file, file_name, content_type=None, file_infos=None, sha1_sum=None, min_part_size=None, progress_listener=None, encryption: Optional[EncryptionSetting] = None, file_retention: Optional[FileRetentionSetting] = None, legal_hold: Optional[LegalHold] = None, upload_mode: UploadMode = UploadMode.FULL)[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 (str,None) – the MIME type, or
None
to accept the default based on file extension of the B2 file namefile_infos (dict,None) – a file info to store with the file or
None
to not store anythingsha1_sum (str,None) – file SHA1 hash or
None
to compute it automaticallymin_part_size (int) – a minimum size of a part
progress_listener (b2sdk.v2.AbstractProgressListener,None) – a progress listener object to use, or
None
to not report progressencryption (b2sdk.v2.EncryptionSetting) – encryption settings (
None
if unknown)file_retention (b2sdk.v2.FileRetentionSetting) – file retention setting
legal_hold (bool) – legal hold setting
upload_mode (b2sdk.v2.UploadMode) – desired upload mode
- Return type:
- upload_unbound_stream(read_only_object, file_name: str, content_type: str = None, file_info: Optional[Dict[str, str]] = None, progress_listener: Optional[AbstractProgressListener] = None, recommended_upload_part_size: Optional[int] = None, encryption: Optional[EncryptionSetting] = None, file_retention: Optional[FileRetentionSetting] = None, legal_hold: Optional[LegalHold] = None, min_part_size: Optional[int] = None, max_part_size: Optional[int] = None, large_file_sha1: Optional[Sha1HexDigest] = None, buffers_count: int = 2, buffer_size: Optional[int] = None, read_size: int = 8192, unused_buffer_timeout_seconds: float = 3600.0)[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
andmax_part_size
should all be greater thanaccount_info.get_absolute_minimum_part_size()
.buffers_count
describes a desired number of buffers that are to be used. Minimal amount is two, as we need 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, in turns, describe the amount of data that can be pulled fromread_only_object
while also uploading it. Providing multiple buffers also allows for higher parallelization. Default two buffers allow for the process to fill one buffer with data while the other one is being sent to the B2. 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 bybuffer_size
parameter. If left unset, it will default to a value ofrecommended_upload_part_size
, whatever it resolves to be. Note that in the current implementation buffers are (almost) directly sent to B2, thus whatever is picked as thebuffer_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, another buffer (above the aforementioned limit) will be allocated.- Parameters:
read_only_object – any object containing a
read
method accepting size of the readfile_name – 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 namefile_info – a file info to store with the file or
None
to not store anythingprogress_listener – a progress listener object to use, or
None
to not report progressencryption – encryption settings (
None
if unknown)file_retention – file retention setting
legal_hold – legal hold setting
min_part_size – a minimum size of a part
recommended_upload_part_size – the recommended part size to use for uploading local sources or
None
to determine automaticallymax_part_size – a maximum size of a part
large_file_sha1 – SHA-1 hash of the result file or
None
if unknownbuffers_count – desired number of buffers allocated, cannot be smaller than 2
buffer_size – size of a single buffer that we pull data to or upload data to B2. If
None
, value ofrecommended_upload_part_size
is used. If that also isNone
, it will be determined automatically as “recommended upload size”.read_size – size of a single read operation performed on the
read_only_object
unused_buffer_timeout_seconds – amount of time that a buffer can be idle before returning error
- Return type: