AccountInfo

AccountInfo stores basic information about the account, such as Application Key ID and Application Key, in order to let b2sdk.v1.B2Api perform authenticated requests.

There are two usable implementations provided by b2sdk:

• b2sdk.v1.InMemoryAccountInfo - a basic implementation with no persistence

• b2sdk.v1.SqliteAccountInfo - for console and GUI applications

They both provide the full AccountInfo interface.

Note

Backup applications and many server-side applications should implement their own AccountInfo, backed by the metadata/configuration database of the application.

AccountInfo implementations

InMemoryAccountInfo

AccountInfo with no persistence.

class b2sdk.v1.InMemoryAccountInfo

Implements all methods of AccountInfo interface.

Hint

Usage of this class is appropriate for secure Web applications which do not wish to persist any user data.

Using this class for applications such as CLI, GUI or backup is discouraged, as InMemoryAccountInfo does not write down the authorization token persistently. That would be slow, as it would force the application to retrieve a new one on every command/click/backup start. Furthermore - an important property of AccountInfo is caching the bucket_name:bucket_id mapping; in case of InMemoryAccountInfo the cache will be flushed between executions of the program.

__init__()

The constructor takes no parameters.

SqliteAccountInfo

class b2sdk.v1.SqliteAccountInfo

Implements all methods of AccountInfo interface.

Uses a SQLite database for persistence and access synchronization between multiple processes. Not suitable for usage over NFS.

Underlying database has the following schema:

Hint

Usage of this class is appropriate for interactive applications installed on a user’s machine (i.e.: CLI and GUI applications).

Usage of this class might be appropriate for non-interactive applications installed on the user’s machine, such as backup applications. An alternative approach that should be considered is to store the AccountInfo data alongside the configuration of the rest of the application.

__init__(file_name=None, last_upgrade_to_run=None)

If file_name argument is empty or None, path from B2_ACCOUNT_INFO environment variable is used. If that is not available, a default of ~/.b2_account_info is used.

Parameters

• file_name (str) – The sqlite file to use; overrides the default.

• last_upgrade_to_run (int) – For testing only, override the auto-update on the db.

BUCKET_UPLOAD_POOL_CLASS

alias of b2sdk.account_info.upload_url_pool.UploadUrlPool

DEFAULT_ALLOWED = {'bucketId': None, 'bucketName': None, 'capabilities': ['listKeys', 'writeKeys', 'deleteKeys', 'listBuckets', 'writeBuckets', 'deleteBuckets', 'readBucketEncryption', 'writeBucketEncryption', 'readBucketRetentions', 'writeBucketRetentions', 'writeFileRetentions', 'writeFileLegalHolds', 'readFileRetentions', 'readFileLegalHolds', 'listFiles', 'readFiles', 'shareFiles', 'writeFiles', 'deleteFiles'], 'namePrefix': None}

LARGE_FILE_UPLOAD_POOL_CLASS

alias of b2sdk.account_info.upload_url_pool.UploadUrlPool

REALM_URLS = {'dev': 'http://api.backblazeb2.xyz:8180', 'production': 'https://api.backblazeb2.com', 'staging': 'https://api.backblaze.net'}

classmethod all_capabilities()

Return a list of all possible capabilities.

Return type

list

classmethod allowed_is_valid(allowed)

Make sure that all of the required fields are present, and that bucketId is set if bucketName is.

If the bucketId is for a bucket that no longer exists, or the capabilities do not allow for listBuckets, then we will not have a bucketName.

Parameters

allowed (dict) – the structure to use for old account info that was saved without ‘allowed’

Return type

bool

clear()

Remove all info about accounts and buckets.

clear_bucket_upload_data(bucket_id)

Remove all upload URLs for the given bucket.

Parameters

bucket_id (str) – a bucket ID

clear_large_file_upload_urls(file_id)

Clear the pool of URLs for a given file ID.

Parameters

file_id (str) – a file ID

get_absolute_minimum_part_size()

Return the absolute minimum number of bytes in a part of a large file.

Returns

number of bytes

Return type

int

get_account_auth_token()

Return account_auth_token or raises MissingAccountData exception.

Return type

str

get_account_id()

Return account ID or raises MissingAccountData exception.

Return type

str

get_allowed()

Return ‘allowed’ dictionary info. Example:

{
    "bucketId": null,
    "bucketName": null,
    "capabilities": [
        "listKeys",
        "writeKeys"
    ],
    "namePrefix": null
}

The ‘allowed’ column was not in the original schema, so it may be NULL.

Return type

dict

get_api_url()

Return api_url or raises MissingAccountData exception.

Return type

str

get_application_key()

Return application_key or raises MissingAccountData exception.

Return type

str

get_application_key_id()

Return an application key ID. The ‘account_id_or_app_key_id’ column was not in the original schema, so it may be NULL.

Nota bene - this is the only place where we are not renaming account_id_or_app_key_id to application_key_id because it requires a column change.

application_key_id == account_id_or_app_key_id

Return type

str

get_bucket_id_or_none_from_bucket_name(bucket_name)

Look up the bucket ID for the given bucket name.

Parameters

bucket_name (str) – a bucket name

Return bucket ID or None

Return type

str, None

get_bucket_name_or_none_from_bucket_id(bucket_id: str) → Optional[str]

Look up the bucket name for the given bucket id.

get_download_url()

Return download_url or raises MissingAccountData exception.

Return type

str

get_minimum_part_size()

get_realm()

Return realm or raises MissingAccountData exception.

Return type

str

get_recommended_part_size()

Return the recommended number of bytes in a part of a large file.

Returns

number of bytes

Return type

int

get_s3_api_url()

Return s3_api_url or raises MissingAccountData exception.

Return type

str

is_same_account(account_id: str, realm: str) → bool

Check whether cached account is the same as the one provided.

Parameters

• account_id (str) – account ID

• realm (str) – authorization realm

Return type

bool

is_same_key(application_key_id, realm)

Check whether cached application key is the same as the one provided.

Parameters

• application_key_id (str) – application key ID

• realm (str) – authorization realm

Return type

bool

put_bucket_upload_url(bucket_id, upload_url, upload_auth_token)

Add an (upload_url, upload_auth_token) pair to the pool available for the bucket.

Parameters

• bucket_id (str) – a bucket ID

• upload_url (str) – an upload URL

• upload_auth_token (str) – an upload authentication token

Return type

tuple

put_large_file_upload_url(file_id, upload_url, upload_auth_token)

Put a large file upload URL into a pool.

Parameters

• file_id (str) – a file ID

• upload_url (str) – an upload URL

• upload_auth_token (str) – an upload authentication token

refresh_entire_bucket_name_cache(name_id_iterable)

Remove all previous name-to-id mappings and stores new ones.

Parameters

name_id_iterable (iterable) – an iterable of tuples of the form (name, id)

remove_bucket_name(bucket_name)

Remove one entry from the bucket name cache.

Parameters

bucket_name (str) – a bucket name

save_bucket(bucket)

Remember the ID for the given bucket name.

Parameters

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

set_auth_data(account_id, auth_token, api_url, download_url, minimum_part_size, application_key, realm, allowed=None, application_key_id=None, s3_api_url=None)

Check permission correctness and stores the results of b2_authorize_account.

The allowed structure is the one returned by b2_authorize_account, e.g.

{
  "absoluteMinimumPartSize": 5000000,
  "accountId": "YOUR_ACCOUNT_ID",
  "allowed": {
    "bucketId": "BUCKET_ID",
    "bucketName": "BUCKET_NAME",
    "capabilities": [
      "listBuckets",
      "listFiles",
      "readFiles",
      "shareFiles",
      "writeFiles",
      "deleteFiles"
    ],
    "namePrefix": null
  },
  "apiUrl": "https://apiNNN.backblazeb2.com",
  "authorizationToken": "4_0022623512fc8f80000000001_0186e431_d18d02_acct_tH7VW03boebOXayIc43-sxptpfA=",
  "downloadUrl": "https://f002.backblazeb2.com",
  "recommendedPartSize": 100000000,
  "s3ApiUrl": "https://s3.us-west-NNN.backblazeb2.com"
}

For keys with bucket restrictions, the name of the bucket is looked up and stored as well. The console_tool does everything by bucket name, so it’s convenient to have the restricted bucket name handy.

Parameters

• account_id (str) – user account ID

• auth_token (str) – user authentication token

• api_url (str) – an API URL

• download_url (str) – path download URL

• recommended_part_size (int) – recommended size of a file part

• absolute_minimum_part_size (int) – minimum size of a file part

• application_key (str) – application key

• realm (str) – a realm to authorize account in

• allowed (dict) – the structure to use for old account info that was saved without ‘allowed’

• application_key_id (str) – application key ID

• s3_api_url (str) – S3-compatible API URL

Changed in version 0.1.5: account_id_or_app_key_id renamed to application_key_id

set_auth_data_with_schema_0_for_test(account_id, auth_token, api_url, download_url, minimum_part_size, application_key, realm)

Set authentication data for tests.

Parameters

• account_id (str) – an account ID

• auth_token (str) – an authentication token

• api_url (str) – an API URL

• download_url (str) – a download URL

• minimum_part_size (int) – a minimum part size

• application_key (str) – an application key

• realm (str) – a realm to authorize account in

take_bucket_upload_url(bucket_id)

Return a pair (upload_url, upload_auth_token) that has been removed from the pool for this bucket, or (None, None) if there are no more left.

Parameters

bucket_id (str) – a bucket ID

Return type

tuple

take_large_file_upload_url(file_id)

Take the chosen large file upload URL from the pool.

Parameters

file_id (str) – a file ID

Implementing your own

When building a server-side application or a web service, you might want to implement your own AccountInfo class backed by a database. In such case, you should inherit from b2sdk.v1.UrlPoolAccountInfo, which has groundwork for url pool functionality). If you cannot use it, inherit directly from b2sdk.v1.AbstractAccountInfo.

>>> from b2sdk.v1 import UrlPoolAccountInfo
>>> class MyAccountInfo(UrlPoolAccountInfo):
        ...

b2sdk.v1.AbstractAccountInfo describes the interface, while b2sdk.v1.UrlPoolAccountInfo and b2sdk.v1.UploadUrlPool implement a part of the interface for in-memory upload token management.

AccountInfo interface

class b2sdk.v1.AbstractAccountInfo

get_s3_api_url()

Return s3_api_url or raises MissingAccountData exception.

Return type

str

get_bucket_name_or_none_from_bucket_id(bucket_id: str) → Optional[str]

Look up the bucket name for the given bucket id.

get_recommended_part_size()

Return the recommended number of bytes in a part of a large file.

Returns

number of bytes

Return type

int

get_absolute_minimum_part_size()

Return the absolute minimum number of bytes in a part of a large file.

Returns

number of bytes

Return type

int

abstract get_minimum_part_size()

Return the minimum number of bytes in a part of a large file.

Returns

number of bytes

Return type

int

abstract _set_auth_data(account_id, auth_token, api_url, download_url, minimum_part_size, application_key, realm, s3_api_url, allowed, application_key_id)

Actually store the auth data. Can assume that ‘allowed’ is present and valid.

All of the information returned by b2_authorize_account is saved, because all of it is needed at some point.

DEFAULT_ALLOWED = {'bucketId': None, 'bucketName': None, 'capabilities': ['listKeys', 'writeKeys', 'deleteKeys', 'listBuckets', 'writeBuckets', 'deleteBuckets', 'readBucketEncryption', 'writeBucketEncryption', 'readBucketRetentions', 'writeBucketRetentions', 'writeFileRetentions', 'writeFileLegalHolds', 'readFileRetentions', 'readFileLegalHolds', 'listFiles', 'readFiles', 'shareFiles', 'writeFiles', 'deleteFiles'], 'namePrefix': None}

REALM_URLS = {'dev': 'http://api.backblazeb2.xyz:8180', 'production': 'https://api.backblazeb2.com', 'staging': 'https://api.backblaze.net'}

_abc_impl = <_abc_data object>

classmethod all_capabilities()

Return a list of all possible capabilities.

Return type

list

classmethod allowed_is_valid(allowed)

Make sure that all of the required fields are present, and that bucketId is set if bucketName is.

If the bucketId is for a bucket that no longer exists, or the capabilities do not allow for listBuckets, then we will not have a bucketName.

Parameters

allowed (dict) – the structure to use for old account info that was saved without ‘allowed’

Return type

bool

abstract clear()

Remove all stored information.

abstract clear_bucket_upload_data(bucket_id)

Remove all upload URLs for the given bucket.

Parameters

bucket_id (str) – a bucket ID

abstract clear_large_file_upload_urls(file_id)

Clear the pool of URLs for a given file ID.

Parameters

file_id (str) – a file ID

abstract get_account_auth_token()

Return account_auth_token or raises MissingAccountData exception.

Return type

str

abstract get_account_id()

Return account ID or raises MissingAccountData exception.

Return type

str

abstract get_allowed()

An ‘allowed’ dict, as returned by b2_authorize_account. Never None; for account info that was saved before ‘allowed’ existed, returns DEFAULT_ALLOWED.

Return type

dict

abstract get_api_url()

Return api_url or raises MissingAccountData exception.

Return type

str

abstract get_application_key()

Return application_key or raises MissingAccountData exception.

Return type

str

abstract get_application_key_id()

Return the application key ID used to authenticate.

Return type

str

abstract get_bucket_id_or_none_from_bucket_name(bucket_name)

Look up the bucket ID for the given bucket name.

Parameters

bucket_name (str) – a bucket name

Return bucket ID or None

Return type

str, None

abstract get_download_url()

Return download_url or raises MissingAccountData exception.

Return type

str

abstract get_realm()

Return realm or raises MissingAccountData exception.

Return type

str

is_same_account(account_id: str, realm: str) → bool

Check whether cached account is the same as the one provided.

Parameters

• account_id (str) – account ID

• realm (str) – authorization realm

Return type

bool

is_same_key(application_key_id, realm)

Check whether cached application key is the same as the one provided.

Parameters

• application_key_id (str) – application key ID

• realm (str) – authorization realm

Return type

bool

abstract put_bucket_upload_url(bucket_id, upload_url, upload_auth_token)

Add an (upload_url, upload_auth_token) pair to the pool available for the bucket.

Parameters

• bucket_id (str) – a bucket ID

• upload_url (str) – an upload URL

• upload_auth_token (str) – an upload authentication token

Return type

tuple

abstract put_large_file_upload_url(file_id, upload_url, upload_auth_token)

Put a large file upload URL into a pool.

Parameters

• file_id (str) – a file ID

• upload_url (str) – an upload URL

• upload_auth_token (str) – an upload authentication token

abstract refresh_entire_bucket_name_cache(name_id_iterable)

Remove all previous name-to-id mappings and stores new ones.

Parameters

name_id_iterable (iterable) – an iterable of tuples of the form (name, id)

abstract remove_bucket_name(bucket_name)

Remove one entry from the bucket name cache.

Parameters

bucket_name (str) – a bucket name

abstract save_bucket(bucket)

Remember the ID for the given bucket name.

Parameters

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

set_auth_data(account_id, auth_token, api_url, download_url, minimum_part_size, application_key, realm, allowed=None, application_key_id=None, s3_api_url=None)

Check permission correctness and stores the results of b2_authorize_account.

The allowed structure is the one returned by b2_authorize_account, e.g.

{
  "absoluteMinimumPartSize": 5000000,
  "accountId": "YOUR_ACCOUNT_ID",
  "allowed": {
    "bucketId": "BUCKET_ID",
    "bucketName": "BUCKET_NAME",
    "capabilities": [
      "listBuckets",
      "listFiles",
      "readFiles",
      "shareFiles",
      "writeFiles",
      "deleteFiles"
    ],
    "namePrefix": null
  },
  "apiUrl": "https://apiNNN.backblazeb2.com",
  "authorizationToken": "4_0022623512fc8f80000000001_0186e431_d18d02_acct_tH7VW03boebOXayIc43-sxptpfA=",
  "downloadUrl": "https://f002.backblazeb2.com",
  "recommendedPartSize": 100000000,
  "s3ApiUrl": "https://s3.us-west-NNN.backblazeb2.com"
}

For keys with bucket restrictions, the name of the bucket is looked up and stored as well. The console_tool does everything by bucket name, so it’s convenient to have the restricted bucket name handy.

Parameters

• account_id (str) – user account ID

• auth_token (str) – user authentication token

• api_url (str) – an API URL

• download_url (str) – path download URL

• recommended_part_size (int) – recommended size of a file part

• absolute_minimum_part_size (int) – minimum size of a file part

• application_key (str) – application key

• realm (str) – a realm to authorize account in

• allowed (dict) – the structure to use for old account info that was saved without ‘allowed’

• application_key_id (str) – application key ID

• s3_api_url (str) – S3-compatible API URL

Changed in version 0.1.5: account_id_or_app_key_id renamed to application_key_id

abstract take_bucket_upload_url(bucket_id)

Return a pair (upload_url, upload_auth_token) that has been removed from the pool for this bucket, or (None, None) if there are no more left.

Parameters

bucket_id (str) – a bucket ID

Return type

tuple

abstract take_large_file_upload_url(file_id)

Take the chosen large file upload URL from the pool.

Parameters

file_id (str) – a file ID

AccountInfo helper classes

class b2sdk.v1.UrlPoolAccountInfo

Caution

This class is not part of the public interface. To find out how to safely use it, read this.

BUCKET_UPLOAD_POOL_CLASS

A url pool class to use for small files.

alias of b2sdk.account_info.upload_url_pool.UploadUrlPool

DEFAULT_ALLOWED = {'bucketId': None, 'bucketName': None, 'capabilities': ['listKeys', 'writeKeys', 'deleteKeys', 'listBuckets', 'writeBuckets', 'deleteBuckets', 'readBucketEncryption', 'writeBucketEncryption', 'readBucketRetentions', 'writeBucketRetentions', 'writeFileRetentions', 'writeFileLegalHolds', 'readFileRetentions', 'readFileLegalHolds', 'listFiles', 'readFiles', 'shareFiles', 'writeFiles', 'deleteFiles'], 'namePrefix': None}

LARGE_FILE_UPLOAD_POOL_CLASS

A url pool class to use for large files.

alias of b2sdk.account_info.upload_url_pool.UploadUrlPool

REALM_URLS = {'dev': 'http://api.backblazeb2.xyz:8180', 'production': 'https://api.backblazeb2.com', 'staging': 'https://api.backblaze.net'}

classmethod all_capabilities()

Return a list of all possible capabilities.

Return type

list

classmethod allowed_is_valid(allowed)

Make sure that all of the required fields are present, and that bucketId is set if bucketName is.

If the bucketId is for a bucket that no longer exists, or the capabilities do not allow for listBuckets, then we will not have a bucketName.

Parameters

allowed (dict) – the structure to use for old account info that was saved without ‘allowed’

Return type

bool

abstract clear()

Remove all stored information.

clear_bucket_upload_data(bucket_id)

Remove all upload URLs for the given bucket.

Parameters

bucket_id (str) – a bucket ID

clear_large_file_upload_urls(file_id)

Clear the pool of URLs for a given file ID.

Parameters

file_id (str) – a file ID

abstract get_absolute_minimum_part_size()

Return the absolute minimum number of bytes in a part of a large file.

Returns

number of bytes

Return type

int

abstract get_account_auth_token()

Return account_auth_token or raises MissingAccountData exception.

Return type

str

abstract get_account_id()

Return account ID or raises MissingAccountData exception.

Return type

str

abstract get_allowed()

An ‘allowed’ dict, as returned by b2_authorize_account. Never None; for account info that was saved before ‘allowed’ existed, returns DEFAULT_ALLOWED.

Return type

dict

abstract get_api_url()

Return api_url or raises MissingAccountData exception.

Return type

str

abstract get_application_key()

Return application_key or raises MissingAccountData exception.

Return type

str

abstract get_application_key_id()

Return the application key ID used to authenticate.

Return type

str

abstract get_bucket_id_or_none_from_bucket_name(bucket_name)

Look up the bucket ID for the given bucket name.

Parameters

bucket_name (str) – a bucket name

Return bucket ID or None

Return type

str, None

abstract get_bucket_name_or_none_from_bucket_id(bucket_id: str) → Optional[str]

Look up the bucket name for the given bucket id.

abstract get_download_url()

Return download_url or raises MissingAccountData exception.

Return type

str

abstract get_realm()

Return realm or raises MissingAccountData exception.

Return type

str

abstract get_recommended_part_size()

Return the recommended number of bytes in a part of a large file.

Returns

number of bytes

Return type

int

abstract get_s3_api_url()

Return s3_api_url or raises MissingAccountData exception.

Return type

str

is_same_account(account_id: str, realm: str) → bool

Check whether cached account is the same as the one provided.

Parameters

• account_id (str) – account ID

• realm (str) – authorization realm

Return type

bool

is_same_key(application_key_id, realm)

Check whether cached application key is the same as the one provided.

Parameters

• application_key_id (str) – application key ID

• realm (str) – authorization realm

Return type

bool

put_bucket_upload_url(bucket_id, upload_url, upload_auth_token)

Add an (upload_url, upload_auth_token) pair to the pool available for the bucket.

Parameters

• bucket_id (str) – a bucket ID

• upload_url (str) – an upload URL

• upload_auth_token (str) – an upload authentication token

Return type

tuple

put_large_file_upload_url(file_id, upload_url, upload_auth_token)

Put a large file upload URL into a pool.

Parameters

• file_id (str) – a file ID

• upload_url (str) – an upload URL

• upload_auth_token (str) – an upload authentication token

abstract refresh_entire_bucket_name_cache(name_id_iterable)

Remove all previous name-to-id mappings and stores new ones.

Parameters

name_id_iterable (iterable) – an iterable of tuples of the form (name, id)

abstract remove_bucket_name(bucket_name)

Remove one entry from the bucket name cache.

Parameters

bucket_name (str) – a bucket name

abstract save_bucket(bucket)

Remember the ID for the given bucket name.

Parameters

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

set_auth_data(account_id, auth_token, api_url, download_url, minimum_part_size, application_key, realm, allowed=None, application_key_id=None, s3_api_url=None)

Check permission correctness and stores the results of b2_authorize_account.

The allowed structure is the one returned by b2_authorize_account, e.g.

{
  "absoluteMinimumPartSize": 5000000,
  "accountId": "YOUR_ACCOUNT_ID",
  "allowed": {
    "bucketId": "BUCKET_ID",
    "bucketName": "BUCKET_NAME",
    "capabilities": [
      "listBuckets",
      "listFiles",
      "readFiles",
      "shareFiles",
      "writeFiles",
      "deleteFiles"
    ],
    "namePrefix": null
  },
  "apiUrl": "https://apiNNN.backblazeb2.com",
  "authorizationToken": "4_0022623512fc8f80000000001_0186e431_d18d02_acct_tH7VW03boebOXayIc43-sxptpfA=",
  "downloadUrl": "https://f002.backblazeb2.com",
  "recommendedPartSize": 100000000,
  "s3ApiUrl": "https://s3.us-west-NNN.backblazeb2.com"
}

For keys with bucket restrictions, the name of the bucket is looked up and stored as well. The console_tool does everything by bucket name, so it’s convenient to have the restricted bucket name handy.

Parameters

• account_id (str) – user account ID

• auth_token (str) – user authentication token

• api_url (str) – an API URL

• download_url (str) – path download URL

• recommended_part_size (int) – recommended size of a file part

• absolute_minimum_part_size (int) – minimum size of a file part

• application_key (str) – application key

• realm (str) – a realm to authorize account in

• allowed (dict) – the structure to use for old account info that was saved without ‘allowed’

• application_key_id (str) – application key ID

• s3_api_url (str) – S3-compatible API URL

Changed in version 0.1.5: account_id_or_app_key_id renamed to application_key_id

take_bucket_upload_url(bucket_id)

Return a pair (upload_url, upload_auth_token) that has been removed from the pool for this bucket, or (None, None) if there are no more left.

Parameters

bucket_id (str) – a bucket ID

Return type

tuple

take_large_file_upload_url(file_id)

Take the chosen large file upload URL from the pool.

Parameters

file_id (str) – a file ID

class b2sdk.account_info.upload_url_pool.UploadUrlPool

For each key (either a bucket id or large file id), hold a pool of (url, auth_token) pairs.

Caution

This class is not part of the public interface. To find out how to safely use it, read this.

put(key, url, auth_token)

Add the url and auth token to the pool for the given key.

Parameters

• key (str) – bucket ID or large file ID

• url (str) – bucket or file URL

• auth_token (str) – authentication token

take(key)

Return a (url, auth_token) if one is available, or (None, None) if not.

Parameters

key (str) – bucket ID or large file ID

Return type

tuple

clear_for_key(key)

Remove an item from the pool by key.

Parameters

key (str) – bucket ID or large file ID