B2 Api client

class b2sdk.v1.B2Api[source]

Provide file-level access to B2 services.

While b2sdk.v1.B2RawApi 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.

BUCKET_FACTORY_CLASS

alias of b2sdk.bucket.BucketFactory

BUCKET_CLASS

alias of b2sdk.bucket.Bucket

__init__(account_info=None, cache=None, raw_api=None, max_upload_workers=10, max_copy_workers=10)[source]

Initialize the API using the given account info.

Parameters
property account_info
property cache
property raw_api

Warning

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

authorize_automatically()[source]

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

authorize_account(realm, application_key_id, application_key)[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: Optional[b2sdk.encryption.setting.EncryptionSetting] = 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 (dict) – bucket lifecycle rules to store with the bucket

  • default_server_side_encryption (b2sdk.v1.EncryptionSetting) – default server side encryption settings (None if unknown)

Returns

a Bucket object

Return type

b2sdk.v1.Bucket

download_file_by_id(file_id, download_dest, progress_listener=None, range_=None, encryption: Optional[b2sdk.encryption.setting.EncryptionSetting] = None)[source]

Download a file with the given ID.

Parameters
Returns

context manager that returns an object that supports iter_content()

get_bucket_by_id(bucket_id)[source]

Return a bucket object with a given ID. Unlike get_bucket_by_name, this method does not need to make any API calls.

Parameters

bucket_id (str) – a bucket ID

Returns

a Bucket object

Return type

b2sdk.v1.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

Returns

a Bucket object

Return type

b2sdk.v1.Bucket

Raises

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

delete_bucket(bucket)[source]

Delete a chosen bucket.

Parameters

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

Return type

None

list_buckets(bucket_name=None, bucket_id=None)[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 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

Return type

list[b2sdk.v1.Bucket]

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

Generator that yields a b2sdk.v1.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) – a file ID

Return type

None

delete_file_version(file_id, file_name)[source]

Permanently and irrevocably delete one version of a file.

Parameters
  • file_id (str) – a file ID

  • file_name (str) – a file name

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

Create a new application key.

Parameters
  • capabilities (list) – a list of capabilities

  • key_name (str) – a name of a key

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

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

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

delete_key(application_key_id)[source]

Delete application key.

Parameters

application_key_id (str) – an application key ID

list_keys(start_application_key_id=None)[source]

List application keys.

Parameters

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

get_file_info(file_id: str)Dict[str, Any][source]

Legacy interface which just returns whatever remote API returns.

Parameters

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

Returns

The parsed response

Return type

dict

check_bucket_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.v1.exception.RestrictedBucket error.

Parameters

bucket_name (str) – a bucket name

Raises

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