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)[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
- Returns
a Bucket object
- Return type
-
download_file_by_id
(file_id, download_dest, progress_listener=None, range_=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
- 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)[source]¶ Call
b2_list_buckets
and return 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
- 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
-
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