b2sdk.api – API client

class b2sdk.api.B2Api(account_info=None, cache=None, raw_api=None, max_upload_workers=10)

Bases: object

Provides file-level access to B2 services.

While 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.

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

__init__(account_info=None, cache=None, raw_api=None, max_upload_workers=10)

Initializes the API using the given account info.

Parameters

• account_info – an instance of UrlPoolAccountInfo, or any custom class derived from AbstractAccountInfo

• cache – an instance of the one of the following classes: DummyCache, InMemoryCache, AuthInfoCache, or any custom class derived from AbstractCache

• raw_api – an instance of one of the following classes: B2RawApi, RawSimulator, or any custom class derived from AbstractRawApi

• max_upload_workers (int) – a number of upload threads, default is 10

authorize_account(realm, application_key_id, application_key)

Perform account authorization

Parameters

• realm (str) – a realm to authorize account in (usually just “production”)

• application_key_id (str) – application key ID

• application_key (str) – user’s application key

authorize_automatically()

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

cancel_large_file(file_id)

Cancel a large file upload

Parameters

file_id (str) – a file ID

check_bucket_restrictions(bucket_name)

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

If it does, does the bucket_name for a given api call match that. If not it raises a RestrictedBucket error.

Parameters

bucket_name (str) – a bucket name

create_bucket(name, bucket_type, bucket_info=None, cors_rules=None, lifecycle_rules=None)

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

Returns

a Bucket object

Return type

b2sdk.bucket.Bucket

create_key(capabilities, key_name, valid_duration_seconds=None, bucket_id=None, name_prefix=None)

Create a new application key

Parameters

• capabilities (list) – a list of capabilities

• key_name (str) – a name of a key

• valid_duration_seconds (int) – key duration in seconds

• bucket_id (str) – a bucket ID

• name_prefix (str) – a name prefix

delete_bucket(bucket)

Deletes the bucket remotely. For legacy reasons it returns whatever server sends in response, but API user should not rely on the response: if it doesn’t raise an exception, it means that the operation was a success

Parameters

bucket (b2sdk.bucket.Bucket) – a Bucket object

delete_file_version(file_id, file_name)

Permanently and irrevocably delete one version of a file

Parameters

• file_id – a file ID

• file_name (str) – a file name

Type

file_id: str

delete_key(application_key_id)

Delete application key with a given ID

Parameters

application_key_id – an application key ID

download_file_by_id(file_id, download_dest, progress_listener=None, range_=None)

Download a file with a given ID

Parameters

• file_id (str) – a file ID

• download_dest (str) – a local file path

• progress_listener – an instance of the one of the following classes: PartProgressReporter, TqdmProgressListener, SimpleProgressListener, DoNothingProgressListener, ProgressListenerForTest, SyncFileReporter, or any sub class of AbstractProgressListener

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

Returns

context manager that returns an object that supports iter_content()

get_account_id()

Return account ID

Returns

account ID

Return type

str

get_bucket_by_id(bucket_id)

Return bucket object with a given ID

Parameters

bucket_id (str) – a bucket ID

Returns

a Bucket object

Return type

b2sdk.bucket.Bucket

get_bucket_by_name(bucket_name)

Returns the Bucket for the given bucket_name.

Parameters

bucket_name (str) – The name of the bucket to return.

Returns

a Bucket object

Return type

b2sdk.bucket.Bucket

Raises

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

get_download_url_for_file_name(bucket_name, file_name)

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

Returns a URL to download the given file by ID.

Parameters

file_id (str) – a file ID

get_file_info(file_id)

legacy interface which just returns whatever remote API returns

get_thread_pool()

Returns the thread pool executor to use for uploads and downloads.

list_buckets(bucket_name=None)

Calls b2_list_buckets and returns a list of buckets.

When no bucket name is specified, returns all of the buckets in the account. When a bucket name 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.

Returns

A list of instances of b2sdk.bucket.Bucket.

Return type

list

list_keys(start_application_key_id=None)

List application keys

Parameters

start_application_key_id (str) – an application key ID to start from

list_parts(file_id, start_part_number=None, batch_size=None)

Generator that yields a 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

set_thread_pool_size(max_workers)

Sets the size of the thread pool to use for uploads and downloads.

Must be called before any work starts, or the thread pool will get the default size of 1.

Parameters

max_workers (int) – maximum allowed number of workers in a pool

b2sdk.api.url_for_api(info, api_name)

Return URL for an API endpoint

Parameters

• info – account info

• api_name (str) –

Return type

str