PYCBC-1734: Migrate Collection management away from Wrapper decorators

Changes
-------
* Add collection mgmt types, request builder
* Add collection mgmt impl for all 3 APIs
* Update APIs collection manager classes to use impl and remove wrapper
  decorators
* Remove pytest.skip() from collection mgmt tests
* Remove use of OverloadManager and instead use static type hints

Change-Id: If4c16707124f205e8f561bc3555e53481f19e53d
Reviewed-on: https://review.couchbase.org/c/couchbase-python-client/+/239334
Reviewed-by: Dimitris Christodoulou <dimitris.christodoulou@couchbase.com>
Tested-by: Build Bot <build@couchbase.com>

Author: thejcfactor

acouchbase/management/collections.py

@@ -0,0 +1,87 @@
+#  Copyright 2016-2023. Couchbase, Inc.
+#  All Rights Reserved.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License")
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from __future__ import annotations
+
+from asyncio import AbstractEventLoop
+from datetime import timedelta
+from typing import TYPE_CHECKING, List
+
+from couchbase.management.logic.collection_mgmt_req_builder import CollectionMgmtRequestBuilder
+from couchbase.management.logic.collection_mgmt_req_types import (CollectionSpec,
+                                                                  CreateCollectionRequest,
+                                                                  CreateScopeRequest,
+                                                                  DropCollectionRequest,
+                                                                  DropScopeRequest,
+                                                                  GetAllScopesRequest,
+                                                                  ScopeSpec,
+                                                                  UpdateCollectionRequest)
+
+if TYPE_CHECKING:
+    from acouchbase.logic.client_adapter import AsyncClientAdapter
+
+
+class AsyncCollectionMgmtImpl:
+    def __init__(self, client_adapter: AsyncClientAdapter) -> None:
+        self._client_adapter = client_adapter
+        self._request_builder = CollectionMgmtRequestBuilder()
+
+    @property
+    def loop(self) -> AbstractEventLoop:
+        """**INTERNAL**"""
+        return self._client_adapter.loop
+
+    @property
+    def request_builder(self) -> CollectionMgmtRequestBuilder:
+        """**INTERNAL**"""
+        return self._request_builder
+
+    async def create_collection(self, req: CreateCollectionRequest) -> None:
+        """**INTERNAL**"""
+        await self._client_adapter.execute_mgmt_request(req)
+
+    async def create_scope(self, req: CreateScopeRequest) -> None:
+        """**INTERNAL**"""
+        await self._client_adapter.execute_mgmt_request(req)
+
+    async def drop_collection(self, req: DropCollectionRequest) -> None:
+        """**INTERNAL**"""
+        await self._client_adapter.execute_mgmt_request(req)
+
+    async def drop_scope(self, req: DropScopeRequest) -> None:
+        """**INTERNAL**"""
+        await self._client_adapter.execute_mgmt_request(req)
+
+    async def get_all_scopes(self, req: GetAllScopesRequest) -> List[ScopeSpec]:
+        """**INTERNAL**"""
+        res = await self._client_adapter.execute_mgmt_request(req)
+        scopes = []
+        raw_scopes = res.raw_result.get('scopes', None)
+        if raw_scopes:
+            for s in raw_scopes:
+                scope = ScopeSpec(s['name'], list())
+                for c in s['collections']:
+                    scope.collections.append(
+                        CollectionSpec(c['name'],
+                                       c['scope_name'],
+                                       timedelta(seconds=c['max_expiry']),
+                                       history=c.get('history')))
+                scopes.append(scope)
+
+        return scopes
+
+    async def update_collection(self, req: UpdateCollectionRequest) -> None:
+        """**INTERNAL**"""
+        await self._client_adapter.execute_mgmt_request(req)

acouchbase/management/logic/collection_mgmt_impl.py

@@ -36,7 +36,6 @@
 from ._test_utils import TestEnvironment
 
 
-@pytest.mark.skip(reason='Skip until PYCBC-1734')
 class CollectionManagementTests:
 
     TEST_BUCKET = "test-bucket"

acouchbase/tests/collectionmgmt_t.py

@@ -15,21 +15,23 @@
 
 from __future__ import annotations
 
-from inspect import Parameter, Signature
+import sys
 from typing import (TYPE_CHECKING,
                     Any,
-                    Dict,
                     Iterable,
-                    Optional)
+                    Optional,
+                    overload)
 
-from couchbase._utils import OverloadType
-from couchbase.logic.supportability import Supportability
-from couchbase.management.logic.collections_logic import (CollectionManagerLogic,
-                                                          CollectionSpec,
-                                                          CreateCollectionSettings,
-                                                          ScopeSpec,
-                                                          UpdateCollectionSettings)
-from couchbase.management.logic.wrappers import BlockingMgmtWrapper, ManagementType
+if sys.version_info >= (3, 13):
+    from warnings import deprecated
+else:
+    from typing_extensions import deprecated
+
+from couchbase.management.logic.collection_mgmt_impl import CollectionMgmtImpl
+from couchbase.management.logic.collection_mgmt_req_types import (CollectionSpec,
+                                                                  CreateCollectionSettings,
+                                                                  ScopeSpec,
+                                                                  UpdateCollectionSettings)
 
 # @TODO:  lets deprecate import of options from couchbase.management.collections
 from couchbase.management.options import (CreateCollectionOptions,
@@ -43,16 +45,16 @@
     from couchbase.logic.client_adapter import ClientAdapter
 
 
-class CollectionManager(CollectionManagerLogic):
+class CollectionManager:
 
     def __init__(self, client_adapter: ClientAdapter, bucket_name: str) -> None:
-        super().__init__(client_adapter.connection, bucket_name)
+        self._bucket_name = bucket_name
+        self._impl = CollectionMgmtImpl(client_adapter)
 
-    @BlockingMgmtWrapper.block(None, ManagementType.CollectionMgmt, CollectionManagerLogic._ERROR_MAPPING)
     def create_scope(self,
                      scope_name: str,
                      *options: CreateScopeOptions,
-                     **kwargs: Dict[str, Any]
+                     **kwargs: Any
                      ) -> None:
         """Creates a new scope.
 
@@ -64,13 +66,16 @@ def create_scope(self,
         Raises:
             :class:`~couchbase.exceptions.ScopeAlreadyExistsException`: If the scope already exists.
         """  # noqa: E501
-        return super().create_scope(scope_name, *options, **kwargs)
+        req = self._impl.request_builder.build_create_scope_request(self._bucket_name,
+                                                                    scope_name,
+                                                                    *options,
+                                                                    **kwargs)
+        self._impl.create_scope(req)
 
-    @BlockingMgmtWrapper.block(None, ManagementType.CollectionMgmt, CollectionManagerLogic._ERROR_MAPPING)
     def drop_scope(self,
                    scope_name: str,
                    *options: DropScopeOptions,
-                   **kwargs: Dict[str, Any]
+                   **kwargs: Any
                    ) -> None:
         """Drops an existing scope.
 
@@ -82,13 +87,15 @@ def drop_scope(self,
         Raises:
             :class:`~couchbase.exceptions.ScopeNotFoundException`: If the scope does not exist.
         """  # noqa: E501
-        return super().drop_scope(scope_name, *options, **kwargs)
+        req = self._impl.request_builder.build_drop_scope_request(self._bucket_name,
+                                                                  scope_name,
+                                                                  *options,
+                                                                  **kwargs)
+        self._impl.drop_scope(req)
 
-    @BlockingMgmtWrapper.block((ScopeSpec, CollectionSpec), ManagementType.CollectionMgmt,
-                               CollectionManagerLogic._ERROR_MAPPING)
     def get_all_scopes(self,
                        *options: GetAllScopesOptions,
-                       **kwargs: Dict[str, Any]
+                       **kwargs: Any
                        ) -> Iterable[ScopeSpec]:
         """Returns all configured scopes along with their collections.
 
@@ -100,73 +107,37 @@ def get_all_scopes(self,
         Returns:
             Iterable[:class:`.ScopeSpec`]: A list of all configured scopes.
         """  # noqa: E501
-        return super().get_all_scopes(*options, **kwargs)
+        req = self._impl.request_builder.build_get_all_scopes_request(self._bucket_name,
+                                                                      *options,
+                                                                      **kwargs)
+        return self._impl.get_all_scopes(req)
 
-    @BlockingMgmtWrapper.block(None,
-                               ManagementType.CollectionMgmt,
-                               CollectionManagerLogic._ERROR_MAPPING,
-                               OverloadType.SECONDARY)
+    @overload
+    @deprecated("Use ``create_collection(scope_name, collection_name, settings=None, *options, **kwargs)`` instead.")
     def create_collection(self,
                           collection: CollectionSpec,
                           *options: CreateCollectionOptions,
-                          **kwargs: Dict[str, Any]
+                          **kwargs: Any
                           ) -> None:
-        """
-        .. deprecated:: 4.1.9
-            Use ``create_collection(scope_name, collection_name, settings=None, *options, **kwargs)`` instead.
-
-        Creates a new collection in a specified scope.
-
-        Args:
-            collection (:class:`.CollectionSpec`): The collection details.
-            options (:class:`~couchbase.management.options.CreateCollectionOptions`): Optional parameters for this operation.
-            **kwargs (Dict[str, Any]): keyword arguments that can be used as optional parameters for this operation.
+        ...
 
-        Raises:
-            :class:`~couchbase.exceptions.CollectionAlreadyExistsException`: If the collection already exists.
-            :class:`~couchbase.exceptions.ScopeNotFoundException`: If the scope does not exist.
-        """  # noqa: E501
-        Supportability.method_signature_deprecated(
-            'create_collection',
-            Signature(
-                parameters=[
-                    Parameter('collection', Parameter.POSITIONAL_OR_KEYWORD, annotation=CollectionSpec),
-                    Parameter('options', Parameter.VAR_POSITIONAL, annotation=CreateCollectionOptions),
-                    Parameter('kwargs', Parameter.VAR_KEYWORD, annotation=Dict[str, Any]),
-                ],
-                return_annotation=None
-            ),
-            Signature(
-                parameters=[
-                    Parameter('scope_name', Parameter.POSITIONAL_OR_KEYWORD, annotation=str),
-                    Parameter('collection_name', Parameter.POSITIONAL_OR_KEYWORD, annotation=str),
-                    Parameter('settings', Parameter.POSITIONAL_OR_KEYWORD,
-                              annotation=Optional[CreateCollectionSettings]),
-                    Parameter('options', Parameter.VAR_POSITIONAL, annotation=CreateCollectionOptions),
-                    Parameter('kwargs', Parameter.VAR_KEYWORD, annotation=Dict[str, Any]),
-                ],
-                return_annotation=None
-            )
-        )
-        settings = None
-        if collection.max_expiry is not None:
-            settings = CreateCollectionSettings(max_expiry=collection.max_expiry)
-
-        return super().create_collection(collection.scope_name, collection.name, settings, *options, **kwargs)
-
-    @BlockingMgmtWrapper.block(None,
-                               ManagementType.CollectionMgmt,
-                               CollectionManagerLogic._ERROR_MAPPING,
-                               OverloadType.DEFAULT)
-    def create_collection(self,  # noqa: F811
+    @overload
+    def create_collection(self,
                           scope_name: str,
                           collection_name: str,
                           settings: Optional[CreateCollectionSettings] = None,
                           *options: CreateCollectionOptions,
-                          **kwargs: Dict[str, Any]
+                          **kwargs: Any
                           ) -> None:
+        ...
+
+    def create_collection(self, *args: object, **kwargs: object) -> None:
         """Creates a new collection in a specified scope.
 
+        .. note::
+            The overloaded create_collection method that takes a CollectionSpec is deprecated as of v4.1.9
+            and will be removed in a future version.
+
         Args:
             scope_name (str): The name of the scope the collection will be created in.
             collection_name (str): The name of the collection to be created
@@ -178,64 +149,33 @@ def create_collection(self,  # noqa: F811
             :class:`~couchbase.exceptions.CollectionAlreadyExistsException`: If the collection already exists.
             :class:`~couchbase.exceptions.ScopeNotFoundException`: If the scope does not exist.
         """  # noqa: E501
-        return super().create_collection(scope_name, collection_name, settings, *options, **kwargs)
+        req = self._impl.request_builder.build_create_collection_request(self._bucket_name, *args, **kwargs)
+        self._impl.create_collection(req)
 
-    @BlockingMgmtWrapper.block(None,
-                               ManagementType.CollectionMgmt,
-                               CollectionManagerLogic._ERROR_MAPPING,
-                               OverloadType.SECONDARY)
+    @overload
+    @deprecated("Use ``drop_collection(scope_name, collection_name, *options, **kwargs)`` instead.")
     def drop_collection(self,
                         collection: CollectionSpec,
                         *options: DropCollectionOptions,
-                        **kwargs: Dict[str, Any]
+                        **kwargs: Any
                         ) -> None:
-        """
-        .. deprecated:: 4.1.9
-            Use ``drop_collection(scope_name, collection_name, *options, **kwargs)`` instead.
-
-        Drops a collection from the specified scope.
-
-        Args:
-            collection (:class:`.CollectionSpec`): The collection details.
-            options (:class:`~couchbase.management.options.DropCollectionOptions`): Optional parameters for this operation.
-            **kwargs (Dict[str, Any]): keyword arguments that can be used as optional parameters for this operation.
+        ...
 
-        Raises:
-            :class:`~couchbase.exceptions.CollectionNotFoundException`: If the collection does not exist.
-        """  # noqa: E501
-        Supportability.method_signature_deprecated(
-            'drop_collection',
-            Signature(
-                parameters=[
-                    Parameter('collection', Parameter.POSITIONAL_OR_KEYWORD, annotation=CollectionSpec),
-                    Parameter('options', Parameter.VAR_POSITIONAL, annotation=DropCollectionOptions),
-                    Parameter('kwargs', Parameter.VAR_KEYWORD, annotation=Dict[str, Any]),
-                ],
-                return_annotation=None,
-            ),
-            Signature(
-                parameters=[
-                    Parameter('scope_name', Parameter.POSITIONAL_OR_KEYWORD, annotation=str),
-                    Parameter('collection_name', Parameter.POSITIONAL_OR_KEYWORD, annotation=str),
-                    Parameter('options', Parameter.VAR_POSITIONAL, annotation=DropCollectionOptions),
-                    Parameter('kwargs', Parameter.VAR_KEYWORD, annotation=Dict[str, Any]),
-                ],
-                return_annotation=None
-            )
-        )
-        return super().drop_collection(collection.scope_name, collection.name, *options, **kwargs)
-
-    @BlockingMgmtWrapper.block(None,
-                               ManagementType.CollectionMgmt,
-                               CollectionManagerLogic._ERROR_MAPPING,
-                               OverloadType.DEFAULT)
-    def drop_collection(self,  # noqa: F811
+    @overload
+    def drop_collection(self,
                         scope_name: str,
                         collection_name: str,
                         *options: DropCollectionOptions,
-                        **kwargs: Dict[str, Any]) -> None:
+                        **kwargs: Any) -> None:
+        ...
+
+    def drop_collection(self, *args: object, **kwargs: object) -> None:
         """Drops a collection from the specified scope.
 
+        .. note::
+            The overloaded drop_collection method that takes a CollectionSpec is deprecated as of v4.1.9
+            and will be removed in a future version.
+
         Args:
             scope_name (str): The name of the scope the collection is in.
             collection_name (str): The name of the collection to be dropped
@@ -245,15 +185,15 @@ def drop_collection(self,  # noqa: F811
         Raises:
             :class:`~couchbase.exceptions.CollectionNotFoundException`: If the collection does not exist.
         """  # noqa: E501
-        return super().drop_collection(scope_name, collection_name, *options, **kwargs)
+        req = self._impl.request_builder.build_drop_collection_request(self._bucket_name, *args, **kwargs)
+        self._impl.drop_collection(req)
 
-    @BlockingMgmtWrapper.block(None, ManagementType.CollectionMgmt, CollectionManagerLogic._ERROR_MAPPING)
     def update_collection(self,
                           scope_name: str,
                           collection_name: str,
                           settings: UpdateCollectionSettings,
                           *options: UpdateCollectionOptions,
-                          **kwargs: Dict[str, Any]
+                          **kwargs: Any
                           ) -> None:
         """Updates a collection in a specified scope.
 
@@ -268,4 +208,10 @@ def update_collection(self,
             :class:`~couchbase.exceptions.CollectionNotFoundException`: If the collection does not exist.
             :class:`~couchbase.exceptions.ScopeNotFoundException`: If the scope does not exist.
         """  # noqa: E501
-        return super().update_collection(scope_name, collection_name, settings, *options, **kwargs)
+        req = self._impl.request_builder.build_update_collection_request(self._bucket_name,
+                                                                         scope_name,
+                                                                         collection_name,
+                                                                         settings,
+                                                                         *options,
+                                                                         **kwargs)
+        self._impl.update_collection(req)