Merge pull request Backblaze#274 from reef-technologies/apiver-v2

Apiver v2

Author: mpnowacki-reef

CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+* apiver `v2` interface released. `from b2sdk.v2 import ...` is now the recommended import, 
+ but `from b2sdk.v1 import ...` works as before
+
 ## [1.10.0] - 2021-06-23
 
 ### Added

b2sdk/account_info/abstract.py

@@ -73,7 +73,7 @@ def save_bucket(self, bucket):
  """
  Remember the ID for the given bucket name.
 
- :param b2sdk.v1.Bucket bucket: a Bucket object
+ :param b2sdk.v2.Bucket bucket: a Bucket object
  """
 
  @abstractmethod
@@ -129,7 +129,7 @@ def is_same_account(self, account_id: str, realm: str) -> bool:
  @abstractmethod
  def get_account_id(self):
  """
- Return account ID or raises :class:`~b2sdk.v1.exception.MissingAccountData` exception.
+ Return account ID or raises :class:`~b2sdk.v2.exception.MissingAccountData` exception.
 
  :rtype: str
  """
@@ -145,39 +145,39 @@ def get_application_key_id(self):
  @abstractmethod
  def get_account_auth_token(self):
  """
- Return account_auth_token or raises :class:`~b2sdk.v1.exception.MissingAccountData` exception.
+ Return account_auth_token or raises :class:`~b2sdk.v2.exception.MissingAccountData` exception.
 
  :rtype: str
  """
 
  @abstractmethod
  def get_api_url(self):
  """
- Return api_url or raises :class:`~b2sdk.v1.exception.MissingAccountData` exception.
+ Return api_url or raises :class:`~b2sdk.v2.exception.MissingAccountData` exception.
 
  :rtype: str
  """
 
  @abstractmethod
  def get_application_key(self):
  """
- Return application_key or raises :class:`~b2sdk.v1.exception.MissingAccountData` exception.
+ Return application_key or raises :class:`~b2sdk.v2.exception.MissingAccountData` exception.
 
  :rtype: str
  """
 
  @abstractmethod
  def get_download_url(self):
  """
- Return download_url or raises :class:`~b2sdk.v1.exception.MissingAccountData` exception.
+ Return download_url or raises :class:`~b2sdk.v2.exception.MissingAccountData` exception.
 
  :rtype: str
  """
 
  @abstractmethod
  def get_realm(self):
  """
- Return realm or raises :class:`~b2sdk.v1.exception.MissingAccountData` exception.
+ Return realm or raises :class:`~b2sdk.v2.exception.MissingAccountData` exception.
 
  :rtype: str
  """
@@ -213,7 +213,7 @@ def get_allowed(self):
  @abstractmethod
  def get_s3_api_url(self):
  """
- Return s3_api_url or raises :class:`~b2sdk.v1.exception.MissingAccountData` exception.
+ Return s3_api_url or raises :class:`~b2sdk.v2.exception.MissingAccountData` exception.
 
  :rtype: str
  """

b2sdk/account_info/upload_url_pool.py

@@ -68,7 +68,7 @@ def clear_for_key(self, key):
 class UrlPoolAccountInfo(AbstractAccountInfo):
  """
  Implement part of :py:class:`AbstractAccountInfo` for upload URL pool management
- with a simple, key-value storage, such as :py:class:`b2sdk.v1.UploadUrlPool`.
+ with a simple, key-value storage, such as :py:class:`b2sdk.v2.UploadUrlPool`.
  """
  # staticmethod is necessary here to avoid the first argument binding to the first argument (like ``partial(fun, arg)``)
  BUCKET_UPLOAD_POOL_CLASS = staticmethod(

b2sdk/api.py

@@ -55,7 +55,7 @@ def __init__(self, api, max_upload_workers=10, max_copy_workers=10):
  """
  Initialize Services object using given session.
 
- :param b2sdk.v1.B2Api api:
+ :param b2sdk.v2.B2Api api:
  :param int max_upload_workers: a number of upload threads
  :param int max_copy_workers: a number of copy threads
  """
@@ -72,7 +72,7 @@ class B2Api(metaclass=B2TraceMeta):
  """
  Provide file-level access to B2 services.
 
- While :class:`b2sdk.v1.B2RawHTTPApi` provides direct access to the B2 web APIs, this
+ While :class:`b2sdk.v2.B2RawHTTPApi` provides direct access to the B2 web APIs, this
  class handles several things that simplify the task of uploading
  and downloading files:
 
@@ -107,7 +107,7 @@ def __init__(
  Initialize the API using the given account info.
 
  :param account_info: To learn more about Account Info objects, see here
- :class:`~b2sdk.v1.SqliteAccountInfo`
+ :class:`~b2sdk.v2.SqliteAccountInfo`
 
  :param cache: It is used by B2Api to cache the mapping between bucket name and bucket ids.
  default is :class:`~b2sdk.cache.DummyCache`
@@ -189,10 +189,10 @@ def create_bucket(
  :param dict bucket_info: additional bucket info to store with the bucket
  :param dict cors_rules: bucket CORS rules to store with the bucket
  :param dict lifecycle_rules: bucket lifecycle rules to store with the bucket
- :param b2sdk.v1.EncryptionSetting default_server_side_encryption: default server side encryption settings (``None`` if unknown)
+ :param b2sdk.v2.EncryptionSetting default_server_side_encryption: default server side encryption settings (``None`` if unknown)
  :param bool is_file_lock_enabled: boolean value specifies whether bucket is File Lock-enabled
  :return: a Bucket object
- :rtype: b2sdk.v1.Bucket
+ :rtype: b2sdk.v2.Bucket
  """
  account_id = self.account_info.get_account_id()
 
@@ -269,7 +269,7 @@ def update_file_legal_hold(
  def get_bucket_by_id(self, bucket_id: str) -> Bucket:
  """
  Return the Bucket matching the given bucket_id.
- :raises b2sdk.v1.exception.NonExistentBucket: if the bucket does not exist in the account
+ :raises b2sdk.v2.exception.BucketIdNotFound: if the bucket does not exist in the account
  """
  # Give a useful warning if the current application key does not
  # allow access to bucket.
@@ -294,8 +294,8 @@ def get_bucket_by_name(self, bucket_name):
 
  :param str bucket_name: the name of the bucket to return
  :return: a Bucket object
- :rtype: b2sdk.v1.Bucket
- :raises b2sdk.v1.exception.NonExistentBucket: if the bucket does not exist in the account
+ :rtype: b2sdk.v2.Bucket
+ :raises b2sdk.v2.exception.NonExistentBucket: if the bucket does not exist in the account
  """
  # Give a useful warning if the current application key does not
  # allow access to the named bucket.
@@ -318,7 +318,7 @@ def delete_bucket(self, bucket):
  """
  Delete a chosen bucket.
 
- :param b2sdk.v1.Bucket bucket: a :term:`bucket` to delete
+ :param b2sdk.v2.Bucket bucket: a :term:`bucket` to delete
  :rtype: None
  """
  account_id = self.account_info.get_account_id()
@@ -336,7 +336,7 @@ def list_buckets(self, bucket_name=None, bucket_id=None):
 
  :param str bucket_name: the name of the one bucket to return
  :param str bucket_id: the ID of the one bucket to return
- :rtype: list[b2sdk.v1.Bucket]
+ :rtype: list[b2sdk.v2.Bucket]
  """
  # Give a useful warning if the current application key does not
  # allow access to the named bucket.
@@ -367,7 +367,7 @@ def list_buckets(self, bucket_name=None, bucket_id=None):
 
  def list_parts(self, file_id, start_part_number=None, batch_size=None):
  """
- Generator that yields a :py:class:`b2sdk.v1.Part` for each of the parts that have been uploaded.
+ Generator that yields a :py:class:`b2sdk.v2.Part` for each of the parts that have been uploaded.
 
  :param str file_id: the ID of the large file that is not finished
  :param int start_part_number: the first part number to return; defaults to the first part
@@ -507,9 +507,9 @@ def check_bucket_name_restrictions(self, bucket_name: str):
  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 :py:exc:`b2sdk.v1.exception.RestrictedBucket` error.
+ If not, it raises a :py:exc:`b2sdk.v2.exception.RestrictedBucket` error.
 
- :raises b2sdk.v1.exception.RestrictedBucket: if the account is not allowed to use this bucket
+ :raises b2sdk.v2.exception.RestrictedBucket: if the account is not allowed to use this bucket
  """
  self._check_bucket_restrictions('bucketName', bucket_name)
 
@@ -518,9 +518,9 @@ def check_bucket_id_restrictions(self, bucket_id: str):
  Check to see if the allowed field from authorize-account has a bucket restriction.
 
  If it does, checks if the bucket_id for a given api call matches that.
- If not, it raises a :py:exc:`b2sdk.v1.exception.RestrictedBucket` error.
+ If not, it raises a :py:exc:`b2sdk.v2.exception.RestrictedBucket` error.
 
- :raises b2sdk.v1.exception.RestrictedBucket: if the account is not allowed to use this bucket
+ :raises b2sdk.v2.exception.RestrictedBucket: if the account is not allowed to use this bucket
  """
  self._check_bucket_restrictions('bucketId', bucket_id)