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
account_info – an instance of
UrlPoolAccountInfo
, or any custom class derived fromAbstractAccountInfo
To learn more about Account Info objects, see hereSqliteAccountInfo
cache – an instance of the one of the following classes:
DummyCache
,InMemoryCache
,AuthInfoCache
, or any custom class derived fromAbstractCache
It is used by B2Api to cache the mapping between bucket name and bucket ids. default isDummyCache
raw_api – an instance of one of the following classes:
B2RawApi
,RawSimulator
, or any custom class derived fromAbstractRawApi
It makes network-less unit testing simple by usingRawSimulator
, in tests andB2RawApi
in production. default isB2RawApi
max_upload_workers (int) – a number of upload threads, default is 10
max_copy_workers (int) – a number of copy threads, default is 10
-
property
account_info
¶
-
property
cache
¶
-
property
raw_api
¶
Perform automatic account authorization, retrieving all account data from account info object passed during initialization.
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
-
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
-
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
file_id (str) – a file ID
download_dest – an instance of the one of the following classes:
DownloadDestLocalFile
,DownloadDestBytes
,DownloadDestProgressWrapper
,PreSeekedDownloadDest
, or any sub class ofAbstractDownloadDestination
progress_listener – an instance of the one of the following classes:
PartProgressReporter
,TqdmProgressListener
,SimpleProgressListener
,DoNothingProgressListener
,ProgressListenerForTest
,SyncFileReporter
, or any sub class ofAbstractProgressListener
range (list) – a list of two integers, the first one is a start position, and the second one is the end position in the file
encryption (b2sdk.v1.EncryptionSetting) – encryption settings (
None
if unknown)
- 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
-
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
- 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
-
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
- Return type
-
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.
-
delete_file_version
(file_id, file_name)[source]¶ Permanently and irrevocably delete one version of a file.
- Parameters
- Return type
-
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.
-
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 expirebucket_id (str,None) – a bucket ID to restrict the key to, or
None
to not restrictname_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.
-
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