AccountInfo
AccountInfo stores basic information about the account, such as Application Key ID and Application Key,
in order to let b2sdk.v2.B2Api
perform authenticated requests.
There are two usable implementations provided by b2sdk:
b2sdk.v2.InMemoryAccountInfo
- a basic implementation with no persistence
b2sdk.v2.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.v2.InMemoryAccountInfo[source]
AccountInfo which keeps all data in memory.
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 thebucket_name:bucket_id
mapping; in case ofInMemoryAccountInfo
the cache will be flushed between executions of the program.
SqliteAccountInfo
- class b2sdk.v2.SqliteAccountInfo[source]
Store account information in an sqlite3 database which is used to manage concurrent access to the data.
The
update_done
table tracks the schema updates that have been completed.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, profile: Optional[str] = None)[source]
Initialize SqliteAccountInfo.
The exact algorithm used to determine the location of the database file is not API in any sense. If the location of the database file is required (for cleanup, etc), do not assume a specific resolution: instead, use
self.filename
to get the actual resolved location.SqliteAccountInfo currently checks locations in the following order:
If
profile
arg is provided: *XDG_CONFIG_HOME/b2/db-<profile>.sqlite
, ifXDG_CONFIG_HOME
env var is set *~/.b2db-{profile}.sqlite
Otherwise: *
file_name
, if truthy *B2_ACCOUNT_INFO
env var’s value, if set *~/.b2_account_info
, if it exists *XDG_CONFIG_HOME/b2/account_info
, ifXDG_CONFIG_HOME
env var is set *~/.b2_account_info
, as defaultIf the directory
XDG_CONFIG_HOME/b2
does not exist (and is needed), it is created.
- set_auth_data_with_schema_0_for_test(account_id, auth_token, api_url, download_url, minimum_part_size, application_key, realm)[source]
Set authentication data for tests.
- get_application_key()[source]
Return application_key or raises
MissingAccountData
exception.- Return type
- get_application_key_id()[source]
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
- get_account_auth_token()[source]
Return account_auth_token or raises
MissingAccountData
exception.- Return type
- get_recommended_part_size()[source]
Return the recommended number of bytes in a part of a large file.
- Returns
number of bytes
- Return type
- get_absolute_minimum_part_size()[source]
Return the absolute minimum number of bytes in a part of a large file.
- Returns
number of bytes
- Return type
- get_allowed()[source]
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
- refresh_entire_bucket_name_cache(name_id_iterable)[source]
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)
- save_bucket(bucket)[source]
Remember the ID for the given bucket name.
- Parameters
bucket (b2sdk.v2.Bucket) – a Bucket object
- remove_bucket_name(bucket_name)[source]
Remove one entry from the bucket name cache.
- Parameters
bucket_name (str) – a bucket name
- get_bucket_id_or_none_from_bucket_name(bucket_name)[source]
Look up the bucket ID for the given bucket name.
- get_bucket_name_or_none_from_bucket_id(bucket_id: str) Optional[str] [source]
Look up the bucket name for the given bucket id.
- BUCKET_UPLOAD_POOL_CLASS
- DEFAULT_ALLOWED = {'bucketId': None, 'bucketName': None, 'capabilities': ['listKeys', 'writeKeys', 'deleteKeys', 'listBuckets', 'listAllBucketNames', 'readBuckets', 'writeBuckets', 'deleteBuckets', 'readBucketEncryption', 'writeBucketEncryption', 'readBucketRetentions', 'writeBucketRetentions', 'readFileRetentions', 'writeFileRetentions', 'readFileLegalHolds', 'writeFileLegalHolds', 'bypassGovernance', 'listFiles', 'readFiles', 'shareFiles', 'writeFiles', 'deleteFiles'], 'namePrefix': None}
- LARGE_FILE_UPLOAD_POOL_CLASS
- 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.
- 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
- is_same_account(account_id: str, realm: str) bool
Check whether cached account is the same as the one provided.
- is_same_key(application_key_id, realm)
Check whether cached application key is the same as the one provided.
- 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.
- put_large_file_upload_url(file_id, upload_url, upload_auth_token)
Put a large file upload URL into a pool.
- set_auth_data(account_id, auth_token, api_url, download_url, recommended_part_size, absolute_minimum_part_size, application_key, realm, s3_api_url, allowed, application_key_id)
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.
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.v2.UrlPoolAccountInfo
, which has groundwork for url pool functionality). If you cannot use it, inherit directly from b2sdk.v2.AbstractAccountInfo
.
>>> from b2sdk.v2 import UrlPoolAccountInfo
>>> class MyAccountInfo(UrlPoolAccountInfo):
...
b2sdk.v2.AbstractAccountInfo
describes the interface, while b2sdk.v2.UrlPoolAccountInfo
and b2sdk.v2.UploadUrlPool
implement a part of the interface for in-memory upload token management.
AccountInfo interface
- class b2sdk.v2.AbstractAccountInfo[source]
Abstract class for a holder for all account-related information that needs to be kept between API calls and between invocations of the program.
This includes: account ID, application key ID, application key, auth tokens, API URL, download URL, and uploads URLs.
This class must be THREAD SAFE because it may be used by multiple threads running in the same Python process. It also needs to be safe against multiple processes running at the same time.
- DEFAULT_ALLOWED = {'bucketId': None, 'bucketName': None, 'capabilities': ['listKeys', 'writeKeys', 'deleteKeys', 'listBuckets', 'listAllBucketNames', 'readBuckets', 'writeBuckets', 'deleteBuckets', 'readBucketEncryption', 'writeBucketEncryption', 'readBucketRetentions', 'writeBucketRetentions', 'readFileRetentions', 'writeFileRetentions', 'readFileLegalHolds', 'writeFileLegalHolds', 'bypassGovernance', 'listFiles', 'readFiles', 'shareFiles', 'writeFiles', 'deleteFiles'], 'namePrefix': None}
- abstract refresh_entire_bucket_name_cache(name_id_iterable)[source]
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)[source]
Remove one entry from the bucket name cache.
- Parameters
bucket_name (str) – a bucket name
- abstract save_bucket(bucket)[source]
Remember the ID for the given bucket name.
- Parameters
bucket (b2sdk.v2.Bucket) – a Bucket object
- abstract get_bucket_id_or_none_from_bucket_name(bucket_name)[source]
Look up the bucket ID for the given bucket name.
- abstract get_bucket_name_or_none_from_bucket_id(bucket_id: str) Optional[str] [source]
Look up the bucket name for the given bucket id.
- abstract clear_bucket_upload_data(bucket_id)[source]
Remove all upload URLs for the given bucket.
- Parameters
bucket_id (str) – a bucket ID
- is_same_key(application_key_id, realm)[source]
Check whether cached application key is the same as the one provided.
- is_same_account(account_id: str, realm: str) bool [source]
Check whether cached account is the same as the one provided.
- abstract get_account_id()[source]
Return account ID or raises
MissingAccountData
exception.- Return type
- abstract get_application_key_id()[source]
Return the application key ID used to authenticate.
- Return type
- abstract get_account_auth_token()[source]
Return account_auth_token or raises
MissingAccountData
exception.- Return type
- abstract get_application_key()[source]
Return application_key or raises
MissingAccountData
exception.- Return type
- abstract get_download_url()[source]
Return download_url or raises
MissingAccountData
exception.- Return type
- abstract get_recommended_part_size()[source]
Return the recommended number of bytes in a part of a large file.
- Returns
number of bytes
- Return type
- abstract get_absolute_minimum_part_size()[source]
Return the absolute minimum number of bytes in a part of a large file.
- Returns
number of bytes
- Return type
- abstract get_allowed()[source]
An ‘allowed’ dict, as returned by
b2_authorize_account
. NeverNone
; for account info that was saved before ‘allowed’ existed, returnsDEFAULT_ALLOWED
.- Return type
- abstract get_s3_api_url()[source]
Return s3_api_url or raises
MissingAccountData
exception.- Return type
- set_auth_data(account_id, auth_token, api_url, download_url, recommended_part_size, absolute_minimum_part_size, application_key, realm, s3_api_url, allowed, application_key_id)[source]
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
- classmethod allowed_is_valid(allowed)[source]
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.
- abstract _set_auth_data(account_id, auth_token, api_url, download_url, recommended_part_size, absolute_minimum_part_size, application_key, realm, s3_api_url, allowed, application_key_id)[source]
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.
- abstract take_bucket_upload_url(bucket_id)[source]
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.
- abstract put_bucket_upload_url(bucket_id, upload_url, upload_auth_token)[source]
Add an (upload_url, upload_auth_token) pair to the pool available for the bucket.
- abstract put_large_file_upload_url(file_id, upload_url, upload_auth_token)[source]
Put a large file upload URL into a pool.
- abstract take_large_file_upload_url(file_id)[source]
Take the chosen large file upload URL from the pool.
- Parameters
file_id (str) – a file ID
- abstract clear_large_file_upload_urls(file_id)[source]
Clear the pool of URLs for a given file ID.
- Parameters
file_id (str) – a file ID
- _abc_impl = <_abc_data object>
AccountInfo helper classes
- class b2sdk.v2.UrlPoolAccountInfo[source]
Implement part of
AbstractAccountInfo
for upload URL pool management with a simple, key-value storage, such asb2sdk.v2.UploadUrlPool
.Caution
This class is not part of the public interface. To find out how to safely use it, read this.
- BUCKET_UPLOAD_POOL_CLASS
- LARGE_FILE_UPLOAD_POOL_CLASS
- put_bucket_upload_url(bucket_id, upload_url, upload_auth_token)[source]
Add an (upload_url, upload_auth_token) pair to the pool available for the bucket.
- clear_bucket_upload_data(bucket_id)[source]
Remove all upload URLs for the given bucket.
- Parameters
bucket_id (str) – a bucket ID
- take_bucket_upload_url(bucket_id)[source]
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.
- put_large_file_upload_url(file_id, upload_url, upload_auth_token)[source]
Put a large file upload URL into a pool.
- take_large_file_upload_url(file_id)[source]
Take the chosen large file upload URL from the pool.
- Parameters
file_id (str) – a file ID
- clear_large_file_upload_urls(file_id)[source]
Clear the pool of URLs for a given file ID.
- Parameters
file_id (str) – a file ID
- DEFAULT_ALLOWED = {'bucketId': None, 'bucketName': None, 'capabilities': ['listKeys', 'writeKeys', 'deleteKeys', 'listBuckets', 'listAllBucketNames', 'readBuckets', 'writeBuckets', 'deleteBuckets', 'readBucketEncryption', 'writeBucketEncryption', 'readBucketRetentions', 'writeBucketRetentions', 'readFileRetentions', 'writeFileRetentions', 'readFileLegalHolds', 'writeFileLegalHolds', 'bypassGovernance', 'listFiles', 'readFiles', 'shareFiles', 'writeFiles', 'deleteFiles'], 'namePrefix': None}
- 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.
- 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
- abstract get_account_auth_token()
Return account_auth_token or raises
MissingAccountData
exception.- Return type
- abstract get_account_id()
Return account ID or raises
MissingAccountData
exception.- Return type
- abstract get_allowed()
An ‘allowed’ dict, as returned by
b2_authorize_account
. NeverNone
; for account info that was saved before ‘allowed’ existed, returnsDEFAULT_ALLOWED
.- Return type
- abstract get_application_key()
Return application_key or raises
MissingAccountData
exception.- Return type
- abstract get_application_key_id()
Return the application key ID used to authenticate.
- Return type
- abstract get_bucket_id_or_none_from_bucket_name(bucket_name)
Look up the bucket ID for the given bucket name.
- 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
- abstract get_recommended_part_size()
Return the recommended number of bytes in a part of a large file.
- Returns
number of bytes
- Return type
- abstract get_s3_api_url()
Return s3_api_url or raises
MissingAccountData
exception.- Return type
- is_same_account(account_id: str, realm: str) bool
Check whether cached account is the same as the one provided.
- is_same_key(application_key_id, realm)
Check whether cached application key is the same as the one provided.
- 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.v2.Bucket) – a Bucket object
- set_auth_data(account_id, auth_token, api_url, download_url, recommended_part_size, absolute_minimum_part_size, application_key, realm, s3_api_url, allowed, application_key_id)
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
- class b2sdk.account_info.upload_url_pool.UploadUrlPool[source]
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.