PYCO-61: Add API Documentation

acouchbase_analytics/cluster.py

@@ -34,32 +34,32 @@
 class AsyncCluster:
     """Create an AsyncCluster instance.
 
-    The cluster instance exposes the operations which are available to be performed against a Columnar cluster.
+    The cluster instance exposes the operations which are available to be performed against a Analytics cluster.
 
     .. important::
         Use the static :meth:`.AsyncCluster.create_instance` method to create an AsyncCluster.
 
     Args:
-        connstr:
-            The connection string to use for connecting to the cluster.
-            The format of the connection string is the *scheme* (``couchbases`` as TLS enabled connections are _required_), followed a hostname
+        endpoint:
+            The endpoint to use for sending HTTP requests to the Analytics server.
+            The format of the endpoint string is the **scheme** (``http`` or ``https`` is *required*, use ``https`` for TLS enabled connections), followed a hostname and optional port.
         credential: User credentials.
         options: Global options to set for the cluster.
             Some operations allow the global options to be overriden by passing in options to the operation.
         **kwargs: keyword arguments that can be used in place or to overrride provided :class:`~acouchbase_analytics.options.ClusterOptions`
 
     Raises:
-        ValueError: If incorrect connstr is provided.
+        ValueError: If incorrect endpoint is provided.
         ValueError: If incorrect options are provided.
 
     """  # noqa: E501
 
     def __init__(
-        self, connstr: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
+        self, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
     ) -> None:
         from acouchbase_analytics.protocol.cluster import AsyncCluster as _AsyncCluster
 
-        self._impl = _AsyncCluster(connstr, credential, options, **kwargs)
+        self._impl = _AsyncCluster(endpoint, credential, options, **kwargs)
 
     def database(self, name: str) -> AsyncDatabase:
         """Creates a database instance.
@@ -77,7 +77,7 @@ def database(self, name: str) -> AsyncDatabase:
         return AsyncDatabase(self._impl, name)
 
     def execute_query(self, statement: str, *args: object, **kwargs: object) -> Awaitable[AsyncQueryResult]:
-        """Executes a query against a Capella Columnar cluster.
+        """Executes a query against an Analytics cluster.
 
         .. note::
             A departure from the operational SDK, the query is *NOT* executed lazily.
@@ -142,7 +142,7 @@ def execute_query(self, statement: str, *args: object, **kwargs: object) -> Awai
         """  # noqa: E501
         return self._impl.execute_query(statement, *args, **kwargs)
 
-    def shutdown(self) -> None:
+    async def shutdown(self) -> None:
         """Shuts down this cluster instance. Cleaning up all resources associated with it.
 
         .. warning::
@@ -151,51 +151,58 @@ def shutdown(self) -> None:
             is necessary and in those types of applications, this method might be beneficial.
 
         """
-        return self._impl.shutdown()
+        return await self._impl.shutdown()
 
     @classmethod
     def create_instance(
-        cls, connstr: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
+        cls, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
     ) -> AsyncCluster:
         """Create an AsyncCluster instance
 
+        .. important::
+            The appropriate port needs to be specified. The SDK's default ports are 80 (http) and 443 (https).
+            If attempting to connect to Capella, the correct ports are most likely to be 8095 (http) and 18095 (https).
+
+            Capella example: https://cb.2xg3vwszqgqcrsix.cloud.couchbase.com:18095
+
         Args:
-            connstr:
-                The connection string to use for connecting to the cluster.
-                The format of the connection string is the *scheme* (``couchbases`` as TLS enabled connections are _required_), followed a hostname
+            endpoint:
+                The endpoint to use for sending HTTP requests to the Analytics server.
+                The format of the endpoint string is the **scheme** (``http`` or ``https`` is *required*, use ``https`` for TLS enabled connections), followed a hostname and optional port.
             credential: User credentials.
             options: Global options to set for the cluster.
                 Some operations allow the global options to be overriden by passing in options to the operation.
             **kwargs: Keyword arguments that can be used in place or to overrride provided :class:`~acouchbase_analytics.options.ClusterOptions`
 
 
         Returns:
-            A Capella Columnar Cluster instance.
+            An Analytics Cluster instance.
 
         Raises:
-            ValueError: If incorrect connstr is provided.
+            ValueError: If incorrect endpoint is provided.
             ValueError: If incorrect options are provided.
 
 
         Examples:
             Initialize cluster using default options::
 
-                from acouchbase_analytics import get_event_loop
+                import asyncio
+
                 from acouchbase_analytics.cluster import AsyncCluster
                 from acouchbase_analytics.credential import Credential
 
                 async def main() -> None:
                     cred = Credential.from_username_and_password('username', 'password')
-                    cluster = AsyncCluster.create_instance('couchbases://hostname', cred)
+                    cluster = AsyncCluster.create_instance('https://hostname', cred)
                     # ... other async code ...
 
                 if __name__ == '__main__':
-                    loop = get_event_loop()
-                    loop.run_until_complete(main())
+                    asyncio.run(main())
 
 
             Initialize cluster using with global timeout options::
 
+                import asyncio
                 from datetime import timedelta
 
                 from acouchbase_analytics import get_event_loop
@@ -206,15 +213,14 @@ async def main() -> None:
                 async def main() -> None:
                     cred = Credential.from_username_and_password('username', 'password')
                     opts = ClusterOptions(timeout_options=ClusterTimeoutOptions(query_timeout=timedelta(seconds=120)))
-                    cluster = AsyncCluster.create_instance('couchbases://hostname', cred, opts)
+                    cluster = AsyncCluster.create_instance('https://hostname', cred, opts)
                     # ... other async code ...
 
                 if __name__ == '__main__':
-                    loop = get_event_loop()
-                    loop.run_until_complete(main())
+                    asyncio.run(main())
 
         """  # noqa: E501
-        return cls(connstr, credential, options, **kwargs)
+        return cls(endpoint, credential, options, **kwargs)
 
 
 Cluster: TypeAlias = AsyncCluster

acouchbase_analytics/cluster.pyi

@@ -28,15 +28,15 @@ from couchbase_analytics.result import AsyncQueryResult
 
 class AsyncCluster:
     @overload
-    def __init__(self, http_endpoint: str, credential: Credential) -> None: ...
+    def __init__(self, endpoint: str, credential: Credential) -> None: ...
     @overload
-    def __init__(self, http_endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
+    def __init__(self, endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
     @overload
-    def __init__(self, http_endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
+    def __init__(self, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
     @overload
     def __init__(
         self,
-        http_endpoint: str,
+        endpoint: str,
         credential: Credential,
         options: ClusterOptions,
         **kwargs: Unpack[ClusterOptionsKwargs],
@@ -62,20 +62,20 @@ class AsyncCluster:
     ) -> Awaitable[AsyncQueryResult]: ...
     @overload
     def execute_query(self, statement: str, *args: str, **kwargs: str) -> Awaitable[AsyncQueryResult]: ...
-    def shutdown(self) -> None: ...
+    def shutdown(self) -> Awaitable[None]: ...
     @overload
     @classmethod
-    def create_instance(cls, http_endpoint: str, credential: Credential) -> AsyncCluster: ...
+    def create_instance(cls, endpoint: str, credential: Credential) -> AsyncCluster: ...
     @overload
     @classmethod
-    def create_instance(cls, http_endpoint: str, credential: Credential, options: ClusterOptions) -> AsyncCluster: ...
+    def create_instance(cls, endpoint: str, credential: Credential, options: ClusterOptions) -> AsyncCluster: ...
     @overload
     @classmethod
     def create_instance(
-        cls, http_endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
+        cls, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
     ) -> AsyncCluster: ...
     @overload
     @classmethod
     def create_instance(
-        cls, http_endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
+        cls, endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
     ) -> AsyncCluster: ...

acouchbase_analytics/protocol/cluster.py

@@ -38,11 +38,11 @@
 
 class AsyncCluster:
     def __init__(
-        self, connstr: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
+        self, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
     ) -> None:
         self._cluster_id = str(uuid4())
         kwargs['cluster_id'] = self._cluster_id
-        self._client_adapter = _AsyncClientAdapter(connstr, credential, options, **kwargs)
+        self._client_adapter = _AsyncClientAdapter(endpoint, credential, options, **kwargs)
         self._request_builder = _RequestBuilder(self._client_adapter)
         self._backend = current_async_library()
 
@@ -115,9 +115,9 @@ def execute_query(self, statement: str, *args: object, **kwargs: object) -> Awai
 
     @classmethod
     def create_instance(
-        cls, connstr: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
+        cls, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
     ) -> AsyncCluster:
-        return cls(connstr, credential, options, **kwargs)
+        return cls(endpoint, credential, options, **kwargs)
 
 
 Cluster: TypeAlias = AsyncCluster

acouchbase_analytics/protocol/cluster.pyi

@@ -29,20 +29,20 @@ from couchbase_analytics.options import ClusterOptions, ClusterOptionsKwargs, Qu
 
 class AsyncCluster:
     @overload
-    def __init__(self, connstr: str, credential: Credential) -> None: ...
+    def __init__(self, endpoint: str, credential: Credential) -> None: ...
     @overload
-    def __init__(self, connstr: str, credential: Credential, options: ClusterOptions) -> None: ...
+    def __init__(self, endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
     @overload
-    def __init__(self, connstr: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
+    def __init__(self, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
     @overload
     def __init__(
-        self, connstr: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
+        self, endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
     ) -> None: ...
     @property
     def client_adapter(self) -> _AsyncClientAdapter: ...
     @property
     def connected(self) -> bool: ...
-    def shutdown(self) -> None: ...
+    def shutdown(self) -> Awaitable[None]: ...
     def database(self, name: str) -> AsyncDatabase: ...
     @overload
     def execute_query(self, statement: str) -> Awaitable[AsyncQueryResult]: ...
@@ -66,17 +66,17 @@ class AsyncCluster:
     def execute_query(self, statement: str, *args: str, **kwargs: str) -> Awaitable[AsyncQueryResult]: ...
     @overload
     @classmethod
-    def create_instance(cls, connstr: str, credential: Credential) -> AsyncCluster: ...
+    def create_instance(cls, endpoint: str, credential: Credential) -> AsyncCluster: ...
     @overload
     @classmethod
-    def create_instance(cls, connstr: str, credential: Credential, options: ClusterOptions) -> AsyncCluster: ...
+    def create_instance(cls, endpoint: str, credential: Credential, options: ClusterOptions) -> AsyncCluster: ...
     @overload
     @classmethod
     def create_instance(
-        cls, connstr: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
+        cls, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
     ) -> AsyncCluster: ...
     @overload
     @classmethod
     def create_instance(
-        cls, connstr: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
+        cls, endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
     ) -> AsyncCluster: ...

acouchbase_analytics/scope.py

@@ -44,7 +44,7 @@ def name(self) -> str:
         return self._impl.name
 
     def execute_query(self, statement: str, *args: object, **kwargs: object) -> Future[AsyncQueryResult]:
-        """Executes a query against a Capella Columnar scope.
+        """Executes a query against an Analytics scope.
 
         .. note::
             A departure from the operational SDK, the query is *NOT* executed lazily.

couchbase_analytics/_version.py

@@ -1,5 +1,5 @@
 # This file automatically generated by
-#    /Users/jaredcasey/GIT/couchbase/clients/python/analytics-python-client/couchbase_analytics_version.py
+#    /Users/jaredcasey/GIT/couchbase/clients/python/analytics-python-client/./couchbase_analytics_version.py
 # at
-#    2025-07-24 17:08:38.315069
+#    2025-08-01 15:43:36.591881
 __version__ = '0.0.1'

couchbase_analytics/cluster.py

@@ -35,26 +35,26 @@ class Cluster:
         Use the static :meth:`.Cluster.create_instance` method to create a Cluster.
 
     Args:
-        http_endpoint:
-            The HTTP endpoint to use for sending requests to the Analytics server.
-            The format of the endpoint string is the *scheme* (``http`` or ``https`` is _required_), followed a hostname
+        endpoint:
+            The endpoint to use for sending HTTP requests to the Analytics server.
+            The format of the endpoint string is the **scheme** (``http`` or ``https`` is *required*, use ``https`` for TLS enabled connections), followed a hostname and optional port.
         credential: User credentials.
         options: Global options to set for the cluster.
             Some operations allow the global options to be overriden by passing in options to the operation.
         **kwargs: keyword arguments that can be used in place or to overrride provided :class:`~couchbase_analytics.options.ClusterOptions`
 
     Raises:
-        ValueError: If incorrect connstr is provided.
+        ValueError: If incorrect endpoint is provided.
         ValueError: If incorrect options are provided.
 
     """  # noqa: E501
 
     def __init__(
-        self, http_endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
+        self, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
     ) -> None:
         from couchbase_analytics.protocol.cluster import Cluster as _Cluster
 
-        self._impl = _Cluster(http_endpoint, credential, options, **kwargs)
+        self._impl = _Cluster(endpoint, credential, options, **kwargs)
 
     def database(self, name: str) -> Database:
         """Creates a database instance.
@@ -151,14 +151,20 @@ def shutdown(self) -> None:
 
     @classmethod
     def create_instance(
-        cls, http_endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
+        cls, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
     ) -> Cluster:
         """Create a Cluster instance
 
+        .. important::
+            The appropriate port needs to be specified. The SDK's default ports are 80 (http) and 443 (https).
+            If attempting to connect to Capella, the correct ports are most likely to be 8095 (http) and 18095 (https).
+
+            Capella example: https://cb.2xg3vwszqgqcrsix.cloud.couchbase.com:18095
+
         Args:
-            http_endpoint:
-                The HTTP endpoint to use for sending requests to the Analytics server.
-                The format of the endpoint string is the *scheme* (``http`` or ``https`` is _required_), followed a hostname
+            endpoint:
+                The endpoint to use for sending HTTP requests to the Analytics server.
+                The format of the endpoint string is the **scheme** (``http`` or ``https`` is *required*, use ``https`` for TLS enabled connections), followed a hostname and optional port.
             credential: User credentials.
             options: Global options to set for the cluster.
                 Some operations allow the global options to be overriden by passing in options to the operation.
@@ -169,7 +175,7 @@ def create_instance(
             An Analytics Cluster instance.
 
         Raises:
-            ValueError: If incorrect connstr is provided.
+            ValueError: If incorrect endpoint is provided.
             ValueError: If incorrect options are provided.
 
 
@@ -196,4 +202,4 @@ def create_instance(
                 cluster = Cluster.create_instance('https://hostname', cred, opts)
 
         """  # noqa: E501
-        return cls(http_endpoint, credential, options, **kwargs)
+        return cls(endpoint, credential, options, **kwargs)

couchbase_analytics/cluster.pyi

@@ -30,15 +30,15 @@ from couchbase_analytics.result import BlockingQueryResult
 
 class Cluster:
     @overload
-    def __init__(self, http_endpoint: str, credential: Credential) -> None: ...
+    def __init__(self, endpoint: str, credential: Credential) -> None: ...
     @overload
-    def __init__(self, http_endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
+    def __init__(self, endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
     @overload
-    def __init__(self, http_endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
+    def __init__(self, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
     @overload
     def __init__(
         self,
-        http_endpoint: str,
+        endpoint: str,
         credential: Credential,
         options: ClusterOptions,
         **kwargs: Unpack[ClusterOptionsKwargs],
@@ -117,17 +117,17 @@ class Cluster:
     def shutdown(self) -> None: ...
     @overload
     @classmethod
-    def create_instance(cls, http_endpoint: str, credential: Credential) -> Cluster: ...
+    def create_instance(cls, endpoint: str, credential: Credential) -> Cluster: ...
     @overload
     @classmethod
-    def create_instance(cls, http_endpoint: str, credential: Credential, options: ClusterOptions) -> Cluster: ...
+    def create_instance(cls, endpoint: str, credential: Credential, options: ClusterOptions) -> Cluster: ...
     @overload
     @classmethod
     def create_instance(
-        cls, http_endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
+        cls, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
     ) -> Cluster: ...
     @overload
     @classmethod
     def create_instance(
-        cls, http_endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
+        cls, endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
     ) -> Cluster: ...