B2 Api client

class b2sdk.v3.B2Api(account_info=None, cache=None, max_upload_workers=None, max_copy_workers=None, api_config=<b2sdk._internal.api_config.B2HttpApiConfig object>, max_download_workers=None, save_to_buffer_size=None, check_download_hash=True, max_download_streams_per_file=None)[source]

Provide file-level access to B2 services.

While b2sdk.v2.B2RawHTTPApi provides direct access to the B2 web APIs, this class handles several things that simplify the task of uploading and downloading files:

  • re-acquires authorization tokens when they expire

  • retrying uploads when an upload URL is busy

  • breaking large files into parts

  • emulating a directory structure (B2 buckets are flat)

Adds an object-oriented layer on top of the raw API, so that buckets and files returned are Python objects with accessor methods.

The class also keeps a cache of information needed to access the service, such as auth tokens and upload URLs.

Parameters:
BUCKET_FACTORY_CLASS

alias of BucketFactory

BUCKET_CLASS

alias of Bucket

SESSION_CLASS

alias of B2Session

FILE_VERSION_FACTORY_CLASS

alias of FileVersionFactory

DOWNLOAD_VERSION_FACTORY_CLASS

alias of DownloadVersionFactory

SERVICES_CLASS

alias of Services

APPLICATION_KEY_CLASS

alias of ApplicationKey

FULL_APPLICATION_KEY_CLASS

alias of FullApplicationKey

DEFAULT_LIST_KEY_COUNT = 1000
API_VERSION = 'v4'
__init__(account_info=None, cache=None, max_upload_workers=None, max_copy_workers=None, api_config=<b2sdk._internal.api_config.B2HttpApiConfig object>, max_download_workers=None, save_to_buffer_size=None, check_download_hash=True, max_download_streams_per_file=None)[source]

Initialize the API using the given account info.

Parameters:

  • account_info (Optional[AbstractAccountInfo]) – To learn more about Account Info objects, see here SqliteAccountInfo

  • cache (Optional[AbstractCache]) – It is used by B2Api to cache the mapping between bucket name and bucket ids. default is DummyCache

  • max_upload_workers (Optional[int]) – a number of upload threads

  • max_copy_workers (Optional[int]) – a number of copy threads

  • api_config (B2HttpApiConfig) –

  • max_download_workers (Optional[int]) – maximum number of download threads

  • save_to_buffer_size (Optional[int]) – buffer size to use when writing files using DownloadedFile.save_to

  • check_download_hash (bool) – 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 (Optional[int]) – number of streams for parallel download manager

property account_info
property cache
property raw_api

Warning

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

authorize_automatically()[source]

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

authorize_account(application_key_id, application_key, realm='production')[source]

Perform account authorization.

Parameters:
get_account_id()[source]

Return the account ID.

Return type:

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

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

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

FileRetentionSetting

Parameters:
Return type:

LegalHold

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

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

delete_bucket(bucket)[source]

Delete a chosen bucket.

Parameters:

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

Return type:

None

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_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

cancel_large_file(file_id)[source]

Cancel a large file upload.

Parameters:

file_id (str) –

Return type:

FileIdAndName

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

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_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

create_key(capabilities, key_name, valid_duration_seconds=None, bucket_ids=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 – 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

  • bucket_ids (Optional[list[str]]) –

Return type:

FullApplicationKey

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

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]

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]

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

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) –

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) –

class b2sdk.v3.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