Merge pull request #240 from reef-technologies/ProviderToPublicApi

Encryption settings, types and providers are now part of the public API

Author: ppolewicz

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Make `B2Api.get_bucket_by_id` return populated bucket objects in v2
 * Add proper support of `recommended_part_size` and `absolute_minimum_part_size` in `AccountInfo`
 * Refactored `minimum_part_size` to `recommended_part_size` (tha value used stays the same)
+* Encryption settings, types and providers are now part of the public API
 
 ### Removed
 * Remove `Bucket.copy_file` and `Bucket.start_large_file` 

b2sdk/sync/encryption_provider.py

@@ -32,8 +32,6 @@ def get_setting_for_upload(
     ) -> Optional[EncryptionSetting]:
         """
         Return an EncryptionSetting for uploading an object or None if server should decide.
-
-        WARNING: the signature of this method is not final yet and not part of the public interface
         """
 
     @abstractmethod
@@ -44,8 +42,6 @@ def get_source_setting_for_copy(
     ) -> Optional[EncryptionSetting]:
         """
         Return an EncryptionSetting for a source of copying an object or None if not required
-
-        WARNING: the signature of this method is not final yet and not part of the public interface
         """
 
     @abstractmethod
@@ -58,8 +54,6 @@ def get_destination_setting_for_copy(
     ) -> Optional[EncryptionSetting]:
         """
         Return an EncryptionSetting for a destination for copying an object or None if server should decide
-
-        WARNING: the signature of this method is not final yet and not part of the public interface
         """
 
     @abstractmethod
@@ -70,8 +64,6 @@ def get_setting_for_download(
     ) -> Optional[EncryptionSetting]:
         """
         Return an EncryptionSetting for downloading an object from, or None if not required
-
-        WARNING: the signature of this method is not final yet and not part of the public interface
         """
 
 
@@ -101,8 +93,6 @@ class BasicSyncEncryptionSettingsProvider(AbstractSyncEncryptionSettingsProvider
     """
     Basic encryption setting provider that supports exactly one encryption setting per bucket for reading
     and one encryption setting per bucket for writing
-
-    WARNING: This class can be used by B2CLI for SSE-B2, but it's still in development
     """
 
     def __init__(

doc/source/api/encryption/setting.rst

@@ -0,0 +1,23 @@
+.. _encryption_setting:
+
+Encryption Settings
+===================
+
+.. autoclass:: b2sdk.v1.EncryptionKey()
+   :no-members:
+   :special-members: __init__
+
+
+.. autoclass:: b2sdk.v1.EncryptionSetting()
+   :no-members:
+   :special-members: __init__, as_dict
+
+
+.. autoattribute:: b2sdk.v1.SSE_NONE
+
+    Commonly used "no encryption" setting
+
+
+.. autoattribute:: b2sdk.v1.SSE_B2_AES
+
+    Commonly used SSE-B2 setting

doc/source/api/internal/encryption/types.rst renamed to doc/source/api/encryption/types.rst

@@ -1,6 +1,6 @@
 .. _encryption_types:
 
-:mod:`b2sdk.encryption.types`
-=============================
+Encryption Types
+================
 
 .. automodule:: b2sdk.encryption.types

doc/source/api/internal/encryption/setting.rst

@@ -189,9 +189,14 @@ also uploaded a new version of f2.txt to bucket using B2 web.
 
 
 Handling encryption
-===================
+-------------------
 The `Synchronizer` object may need `EncryptionSetting` instances to perform downloads and copies. For this reason, the
-`sync_folder` method accepts an `EncryptionSettingsProvider`, see :ref:`server_side_encryption` for details.
+`sync_folder` method accepts an `EncryptionSettingsProvider`, see :ref:`server_side_encryption` for further explanation
+and :ref:`encryption_provider` for public API.
+
+
+Public API classes
+==================
 
 .. autoclass:: b2sdk.v1.ScanPoliciesManager()
    :special-members: __init__
@@ -204,3 +209,22 @@ The `Synchronizer` object may need `EncryptionSetting` instances to perform down
 .. autoclass:: b2sdk.v1.SyncReport()
    :special-members: __init__
    :members:
+
+
+.. _encryption_provider:
+
+Sync Encryption Settings Providers
+==================================
+
+
+.. autoclass:: b2sdk.v1.AbstractSyncEncryptionSettingsProvider()
+   :members:
+
+
+.. autoclass:: b2sdk.v1.ServerDefaultSyncEncryptionSettingsProvider()
+   :no-members:
+
+
+.. autoclass:: b2sdk.v1.BasicSyncEncryptionSettingsProvider()
+   :special-members: __init__
+   :no-members:

doc/source/api/internal/sync/encryption_provider.rst

@@ -33,6 +33,8 @@ Public API
    api/transfer/emerge/write_intent
    api/transfer/outbound/outbound_source
    api/download_dest
+   api/encryption/setting
+   api/encryption/types
 
 .. _api_internal:
 
@@ -62,9 +64,6 @@ Internal API
    api/internal/sync/policy_manager
    api/internal/sync/scan_policies
    api/internal/sync/sync
-   api/internal/sync/encryption_provider
-   api/internal/encryption/setting
-   api/internal/encryption/types
    api/internal/transfer/inbound/downloader/abstract
    api/internal/transfer/inbound/downloader/parallel
    api/internal/transfer/inbound/downloader/range

doc/source/api/sync.rst

@@ -104,7 +104,10 @@
     extras_require={
         'doc':
             [
-                'sphinx', 'sphinx-autobuild', 'sphinx_rtd_theme', 'sphinxcontrib-plantuml',
+                'sphinx<4.0',  # sphinx>=4.0 doesn't support Python 3.5
+                'sphinx-autobuild',
+                'sphinx_rtd_theme',
+                'sphinxcontrib-plantuml',
                 'sadisplay'
             ],
     },