B2 Api client

class b2sdk.v2.B2Api[source]
SESSION_CLASS

alias of B2Session

BUCKET_CLASS

alias of Bucket

BUCKET_FACTORY_CLASS

alias of BucketFactory

SERVICES_CLASS

alias of Services

FILE_VERSION_FACTORY_CLASS

alias of FileVersionFactory

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

Initialize the API using the given account info.

Parameters:

  • account_info – To learn more about Account Info objects, see here SqliteAccountInfo

  • cache – It is used by B2Api to cache the mapping between bucket name and bucket ids. default is DummyCache

  • max_upload_workers – a number of upload threads

  • max_copy_workers – a number of copy threads

  • api_config –

  • max_download_workers – maximum number of download threads

  • save_to_buffer_size – buffer size to use when writing files using DownloadedFile.save_to

  • check_download_hash – whether to check hash of downloaded files. Can be disabled for files with internal checksums, for example, or to forcefully retrieve objects with corrupted payload or hash value

  • max_download_streams_per_file – number of streams for parallel download manager

get_bucket_by_id(bucket_id)[source]

Return the Bucket matching the given bucket_id. :raises b2sdk.v2.exception.BucketIdNotFound: if the bucket does not exist in the account

Parameters:

bucket_id (str) –

Return type:

Bucket

authorize_account(realm, application_key_id, application_key)[source]

Perform account authorization.

Parameters:
DEFAULT_LIST_KEY_COUNT = 1000
DOWNLOAD_VERSION_FACTORY_CLASS

alias of DownloadVersionFactory

property account_info
authorize_automatically()[source]

Perform automatic account authorization, retrieving all account data from account info object passed during initialization.

property cache
cancel_large_file(file_id)[source]

Cancel a large file upload.

Parameters:

file_id (str) –

Return type:

FileIdAndName

check_bucket_id_restrictions(bucket_id)[source]

Check to see if the allowed field from authorize-account has a bucket restriction.

If it does, checks if the bucket_id for a given api call matches that. If not, it raises a b2sdk.v2.exception.RestrictedBucket error.

Raises:

b2sdk.v2.exception.RestrictedBucket – if the account is not allowed to use this bucket

Parameters:

bucket_id (str) –

check_bucket_name_restrictions(bucket_name)[source]

Check to see if the allowed field from authorize-account has a bucket restriction.

If it does, checks if the bucket_name for a given api call matches that. If not, it raises a b2sdk.v2.exception.RestrictedBucket error.

Raises:

b2sdk.v2.exception.RestrictedBucket – if the account is not allowed to use this bucket

Parameters:

bucket_name (str) –

create_bucket(name, bucket_type, bucket_info=None, cors_rules=None, lifecycle_rules=None, default_server_side_encryption=None, is_file_lock_enabled=None, replication=None)[source]

Create a bucket.

Parameters:

  • name (str) – bucket name

  • bucket_type (str) – a bucket type, could be one of the following values: "allPublic", "allPrivate"

  • bucket_info (dict) – additional bucket info to store with the bucket

  • cors_rules (dict) – bucket CORS rules to store with the bucket

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

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

  • is_file_lock_enabled (Optional[bool]) – boolean value specifies whether bucket is File Lock-enabled

  • replication (Optional[ReplicationConfiguration]) – bucket replication rules or None

  • default_server_side_encryption –

  • is_file_lock_enabled –

  • replication –

Returns:

a Bucket object

Return type:

b2sdk.v2.Bucket

create_key(capabilities, key_name, valid_duration_seconds=None, bucket_id=None, name_prefix=None)[source]

Create a new application key.

Parameters:

  • capabilities (list[str]) – a list of capabilities

  • key_name (str) – a name of a key

  • valid_duration_seconds (Optional[int]) – key auto-expire time after it is created, in seconds, or None to not expire

  • bucket_id (Optional[str]) – a bucket ID to restrict the key to, or None to not restrict

  • name_prefix (Optional[str]) – a remote filename prefix to restrict the key to or None to not restrict

Return type:

FullApplicationKey

delete_bucket(bucket)[source]

Delete a chosen bucket.

Parameters:

bucket (b2sdk.v2.Bucket) – a bucket to delete

Return type:

None

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

Permanently and irrevocably delete one version of a file. bypass_governance must be set to true if deleting a file version protected by Object Lock governance mode retention settings (unless its retention period expired)

Parameters:

  • file_id (str) –

  • file_name (str) –

  • bypass_governance (bool) –

Return type:

FileIdAndName

delete_key(application_key)[source]

Delete application key.

Parameters:

application_key (BaseApplicationKey) – an application key

delete_key_by_id(application_key_id)[source]

Delete application key.

Parameters:

application_key_id (str) – an application key ID

Return type:

ApplicationKey

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

Download a file with the given ID.

Parameters:

  • file_id (str) – a file ID

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

  • range – a list of two integers, the first one is a start position, and the second one is the end position in the file

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

  • file_id –

  • range_ (Optional[tuple[int, int]]) –

Return type:

DownloadedFile

get_account_id()[source]

Return the account ID.

Return type:

str

get_bucket_by_name(bucket_name)[source]

Return the Bucket matching the given bucket_name.

Parameters:

  • bucket_name (str) – the name of the bucket to return

  • bucket_name –

Returns:

a Bucket object

Return type:

b2sdk.v2.Bucket

Raises:

b2sdk.v2.exception.NonExistentBucket – if the bucket does not exist in the account

get_download_url_for_file_name(bucket_name, file_name)[source]

Return a URL to download the given file by name.

Parameters:

  • bucket_name (str) – a bucket name

  • file_name (str) – a file name

get_download_url_for_fileid(file_id)[source]

Return a URL to download the given file by ID.

Parameters:

file_id (str) – a file ID

get_file_info(file_id)[source]

Gets info about file version.

Parameters:

  • file_id (str) – the id of the file whose info will be retrieved.

  • file_id –

Return type:

FileVersion

get_file_info_by_name(bucket_name, file_name)[source]

Gets info about a file version. Similar to get_file_info but takes the bucket name and file name instead of file id.

Parameters:

  • bucket_name (str) – The name of the bucket where the file resides.

  • file_name (str) – The name of the file whose info will be retrieved.

  • bucket_name –

  • file_name –

Return type:

DownloadVersion

get_key(key_id)[source]

Gets information about a single key: it’s capabilities, prefix, name etc

Returns None if the key does not exist.

Raises an exception if profile is not permitted to list keys.

Parameters:

key_id (str) –

Return type:

Optional[ApplicationKey]

list_buckets(bucket_name=None, bucket_id=None, *, use_cache=False)[source]

Call b2_list_buckets and return a list of buckets.

When no bucket name nor ID is specified, returns all of the buckets in the account. When a bucket name or ID is given, returns just that bucket. When authorized with an application key restricted to one bucket, you must specify the bucket name or bucket id, or the request will be unauthorized.

Parameters:

  • bucket_name (str) – the name of the one bucket to return

  • bucket_id (str) – the ID of the one bucket to return

  • use_cache (bool) – if True use cached bucket list if available and not empty

  • use_cache –

Return type:

list[b2sdk.v2.Bucket]

list_keys(start_application_key_id=None)[source]

List application keys. Lazily perform requests to B2 cloud and return all keys.

Parameters:

start_application_key_id (Optional[str]) – an application key ID to start from or None to start from the beginning

Return type:

Generator[ApplicationKey, None, None]

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

Generator that yields a b2sdk.v2.Part for each of the parts that have been uploaded.

Parameters:

  • file_id (str) – the ID of the large file that is not finished

  • 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

Return type:

generator

property raw_api

Warning

B2RawHTTPApi attribute is deprecated. B2Session expose all B2RawHTTPApi methods now.

Parameters:
Return type:

LegalHold

update_file_retention(file_id, file_name, file_retention, bypass_governance=False)[source]
Parameters:
Return type:

FileRetentionSetting

class b2sdk.v2.B2HttpApiConfig(http_session_factory=<class 'requests.sessions.Session'>, install_clock_skew_hook=True, user_agent_append=None, _raw_api_class=None, decode_content=False)[source]
Parameters:
DEFAULT_RAW_API_CLASS

alias of B2RawHTTPApi

__init__(http_session_factory=<class 'requests.sessions.Session'>, install_clock_skew_hook=True, user_agent_append=None, _raw_api_class=None, decode_content=False)[source]

A structure with params to be passed to low level API.

Parameters:

  • http_session_factory (Callable[[], Session]) – a callable that returns a requests.Session object (or a compatible one)

  • install_clock_skew_hook (bool) – if True, install a clock skew hook

  • user_agent_append (Optional[str]) – if provided, the string will be appended to the User-Agent

  • _raw_api_class (Optional[type[AbstractRawApi]]) – AbstractRawApi-compliant class

  • decode_content (bool) – If true, the underlying http backend will try to decode encoded files when downloading, based on the response headers