Skip to content

Commit 45a646c

Browse files
thejcfactorthejcfactor
authored
PYCO-61: Add API Documentation (#5)
Changes ------- * Clean up doc-strings (remove Columnar references, update examples, etc.) * Add and verify API documentation
1 parent 563dd7f commit 45a646c

47 files changed

Lines changed: 1436 additions & 108 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CONTRIBUTING.md‎

Whitespace-only changes.

‎acouchbase_analytics/cluster.py‎

Lines changed: 30 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -34,32 +34,32 @@
3434
class AsyncCluster:
3535
"""Create an AsyncCluster instance.
3636
37-
The cluster instance exposes the operations which are available to be performed against a Columnar cluster.
37+
The cluster instance exposes the operations which are available to be performed against a Analytics cluster.
3838
3939
.. important::
4040
Use the static :meth:`.AsyncCluster.create_instance` method to create an AsyncCluster.
4141
4242
Args:
43-
connstr:
44-
The connection string to use for connecting to the cluster.
45-
The format of the connection string is the *scheme* (``couchbases`` as TLS enabled connections are _required_), followed a hostname
43+
endpoint:
44+
The endpoint to use for sending HTTP requests to the Analytics server.
45+
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.
4646
credential: User credentials.
4747
options: Global options to set for the cluster.
4848
Some operations allow the global options to be overriden by passing in options to the operation.
4949
**kwargs: keyword arguments that can be used in place or to overrride provided :class:`~acouchbase_analytics.options.ClusterOptions`
5050
5151
Raises:
52-
ValueError: If incorrect connstr is provided.
52+
ValueError: If incorrect endpoint is provided.
5353
ValueError: If incorrect options are provided.
5454
5555
""" # noqa: E501
5656

5757
def __init__(
58-
self, connstr: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
58+
self, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
5959
) -> None:
6060
from acouchbase_analytics.protocol.cluster import AsyncCluster as _AsyncCluster
6161

62-
self._impl = _AsyncCluster(connstr, credential, options, **kwargs)
62+
self._impl = _AsyncCluster(endpoint, credential, options, **kwargs)
6363

6464
def database(self, name: str) -> AsyncDatabase:
6565
"""Creates a database instance.
@@ -77,7 +77,7 @@ def database(self, name: str) -> AsyncDatabase:
7777
return AsyncDatabase(self._impl, name)
7878

7979
def execute_query(self, statement: str, *args: object, **kwargs: object) -> Awaitable[AsyncQueryResult]:
80-
"""Executes a query against a Capella Columnar cluster.
80+
"""Executes a query against an Analytics cluster.
8181
8282
.. note::
8383
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
142142
""" # noqa: E501
143143
return self._impl.execute_query(statement, *args, **kwargs)
144144

145-
def shutdown(self) -> None:
145+
async def shutdown(self) -> None:
146146
"""Shuts down this cluster instance. Cleaning up all resources associated with it.
147147
148148
.. warning::
@@ -151,51 +151,58 @@ def shutdown(self) -> None:
151151
is necessary and in those types of applications, this method might be beneficial.
152152
153153
"""
154-
return self._impl.shutdown()
154+
return await self._impl.shutdown()
155155

156156
@classmethod
157157
def create_instance(
158-
cls, connstr: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
158+
cls, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
159159
) -> AsyncCluster:
160160
"""Create an AsyncCluster instance
161161
162+
.. important::
163+
The appropriate port needs to be specified. The SDK's default ports are 80 (http) and 443 (https).
164+
If attempting to connect to Capella, the correct ports are most likely to be 8095 (http) and 18095 (https).
165+
166+
Capella example: https://cb.2xg3vwszqgqcrsix.cloud.couchbase.com:18095
167+
162168
Args:
163-
connstr:
164-
The connection string to use for connecting to the cluster.
165-
The format of the connection string is the *scheme* (``couchbases`` as TLS enabled connections are _required_), followed a hostname
169+
endpoint:
170+
The endpoint to use for sending HTTP requests to the Analytics server.
171+
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.
166172
credential: User credentials.
167173
options: Global options to set for the cluster.
168174
Some operations allow the global options to be overriden by passing in options to the operation.
169175
**kwargs: Keyword arguments that can be used in place or to overrride provided :class:`~acouchbase_analytics.options.ClusterOptions`
170176
171177
172178
Returns:
173-
A Capella Columnar Cluster instance.
179+
An Analytics Cluster instance.
174180
175181
Raises:
176-
ValueError: If incorrect connstr is provided.
182+
ValueError: If incorrect endpoint is provided.
177183
ValueError: If incorrect options are provided.
178184
179185
180186
Examples:
181187
Initialize cluster using default options::
182188
183-
from acouchbase_analytics import get_event_loop
189+
import asyncio
190+
184191
from acouchbase_analytics.cluster import AsyncCluster
185192
from acouchbase_analytics.credential import Credential
186193
187194
async def main() -> None:
188195
cred = Credential.from_username_and_password('username', 'password')
189-
cluster = AsyncCluster.create_instance('couchbases://hostname', cred)
196+
cluster = AsyncCluster.create_instance('https://hostname', cred)
190197
# ... other async code ...
191198
192199
if __name__ == '__main__':
193-
loop = get_event_loop()
194-
loop.run_until_complete(main())
200+
asyncio.run(main())
195201
196202
197203
Initialize cluster using with global timeout options::
198204
205+
import asyncio
199206
from datetime import timedelta
200207
201208
from acouchbase_analytics import get_event_loop
@@ -206,15 +213,14 @@ async def main() -> None:
206213
async def main() -> None:
207214
cred = Credential.from_username_and_password('username', 'password')
208215
opts = ClusterOptions(timeout_options=ClusterTimeoutOptions(query_timeout=timedelta(seconds=120)))
209-
cluster = AsyncCluster.create_instance('couchbases://hostname', cred, opts)
216+
cluster = AsyncCluster.create_instance('https://hostname', cred, opts)
210217
# ... other async code ...
211218
212219
if __name__ == '__main__':
213-
loop = get_event_loop()
214-
loop.run_until_complete(main())
220+
asyncio.run(main())
215221
216222
""" # noqa: E501
217-
return cls(connstr, credential, options, **kwargs)
223+
return cls(endpoint, credential, options, **kwargs)
218224

219225

220226
Cluster: TypeAlias = AsyncCluster

‎acouchbase_analytics/cluster.pyi‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,15 @@ from couchbase_analytics.result import AsyncQueryResult
2828

2929
class AsyncCluster:
3030
@overload
31-
def __init__(self, http_endpoint: str, credential: Credential) -> None: ...
31+
def __init__(self, endpoint: str, credential: Credential) -> None: ...
3232
@overload
33-
def __init__(self, http_endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
33+
def __init__(self, endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
3434
@overload
35-
def __init__(self, http_endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
35+
def __init__(self, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
3636
@overload
3737
def __init__(
3838
self,
39-
http_endpoint: str,
39+
endpoint: str,
4040
credential: Credential,
4141
options: ClusterOptions,
4242
**kwargs: Unpack[ClusterOptionsKwargs],
@@ -62,20 +62,20 @@ class AsyncCluster:
6262
) -> Awaitable[AsyncQueryResult]: ...
6363
@overload
6464
def execute_query(self, statement: str, *args: str, **kwargs: str) -> Awaitable[AsyncQueryResult]: ...
65-
def shutdown(self) -> None: ...
65+
def shutdown(self) -> Awaitable[None]: ...
6666
@overload
6767
@classmethod
68-
def create_instance(cls, http_endpoint: str, credential: Credential) -> AsyncCluster: ...
68+
def create_instance(cls, endpoint: str, credential: Credential) -> AsyncCluster: ...
6969
@overload
7070
@classmethod
71-
def create_instance(cls, http_endpoint: str, credential: Credential, options: ClusterOptions) -> AsyncCluster: ...
71+
def create_instance(cls, endpoint: str, credential: Credential, options: ClusterOptions) -> AsyncCluster: ...
7272
@overload
7373
@classmethod
7474
def create_instance(
75-
cls, http_endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
75+
cls, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
7676
) -> AsyncCluster: ...
7777
@overload
7878
@classmethod
7979
def create_instance(
80-
cls, http_endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
80+
cls, endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
8181
) -> AsyncCluster: ...

‎acouchbase_analytics/protocol/cluster.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,11 +39,11 @@
3939

4040
class AsyncCluster:
4141
def __init__(
42-
self, connstr: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
42+
self, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
4343
) -> None:
4444
self._cluster_id = str(uuid4())
4545
kwargs['cluster_id'] = self._cluster_id
46-
self._client_adapter = _AsyncClientAdapter(connstr, credential, options, **kwargs)
46+
self._client_adapter = _AsyncClientAdapter(endpoint, credential, options, **kwargs)
4747
self._request_builder = _RequestBuilder(self._client_adapter)
4848
self._backend = current_async_library()
4949

@@ -117,9 +117,9 @@ def execute_query(self, statement: str, *args: object, **kwargs: object) -> Awai
117117

118118
@classmethod
119119
def create_instance(
120-
cls, connstr: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
120+
cls, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
121121
) -> AsyncCluster:
122-
return cls(connstr, credential, options, **kwargs)
122+
return cls(endpoint, credential, options, **kwargs)
123123

124124

125125
Cluster: TypeAlias = AsyncCluster

‎acouchbase_analytics/protocol/cluster.pyi‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -29,20 +29,20 @@ from couchbase_analytics.options import ClusterOptions, ClusterOptionsKwargs, Qu
2929

3030
class AsyncCluster:
3131
@overload
32-
def __init__(self, connstr: str, credential: Credential) -> None: ...
32+
def __init__(self, endpoint: str, credential: Credential) -> None: ...
3333
@overload
34-
def __init__(self, connstr: str, credential: Credential, options: ClusterOptions) -> None: ...
34+
def __init__(self, endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
3535
@overload
36-
def __init__(self, connstr: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
36+
def __init__(self, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
3737
@overload
3838
def __init__(
39-
self, connstr: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
39+
self, endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
4040
) -> None: ...
4141
@property
4242
def client_adapter(self) -> _AsyncClientAdapter: ...
4343
@property
4444
def connected(self) -> bool: ...
45-
def shutdown(self) -> None: ...
45+
def shutdown(self) -> Awaitable[None]: ...
4646
def database(self, name: str) -> AsyncDatabase: ...
4747
@overload
4848
def execute_query(self, statement: str) -> Awaitable[AsyncQueryResult]: ...
@@ -66,17 +66,17 @@ class AsyncCluster:
6666
def execute_query(self, statement: str, *args: str, **kwargs: str) -> Awaitable[AsyncQueryResult]: ...
6767
@overload
6868
@classmethod
69-
def create_instance(cls, connstr: str, credential: Credential) -> AsyncCluster: ...
69+
def create_instance(cls, endpoint: str, credential: Credential) -> AsyncCluster: ...
7070
@overload
7171
@classmethod
72-
def create_instance(cls, connstr: str, credential: Credential, options: ClusterOptions) -> AsyncCluster: ...
72+
def create_instance(cls, endpoint: str, credential: Credential, options: ClusterOptions) -> AsyncCluster: ...
7373
@overload
7474
@classmethod
7575
def create_instance(
76-
cls, connstr: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
76+
cls, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
7777
) -> AsyncCluster: ...
7878
@overload
7979
@classmethod
8080
def create_instance(
81-
cls, connstr: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
81+
cls, endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
8282
) -> AsyncCluster: ...

‎acouchbase_analytics/scope.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ def name(self) -> str:
4444
return self._impl.name
4545

4646
def execute_query(self, statement: str, *args: object, **kwargs: object) -> Future[AsyncQueryResult]:
47-
"""Executes a query against a Capella Columnar scope.
47+
"""Executes a query against an Analytics scope.
4848
4949
.. note::
5050
A departure from the operational SDK, the query is *NOT* executed lazily.

‎couchbase_analytics/_version.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# This file automatically generated by
2-
# /Users/jaredcasey/GIT/couchbase/clients/python/analytics-python-client/couchbase_analytics_version.py
2+
# /Users/jaredcasey/GIT/couchbase/clients/python/analytics-python-client/./couchbase_analytics_version.py
33
# at
4-
# 2025-07-24 17:08:38.315069
4+
# 2025-08-01 15:43:36.591881
55
__version__ = '0.0.1'

‎couchbase_analytics/cluster.py‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -35,26 +35,26 @@ class Cluster:
3535
Use the static :meth:`.Cluster.create_instance` method to create a Cluster.
3636
3737
Args:
38-
http_endpoint:
39-
The HTTP endpoint to use for sending requests to the Analytics server.
40-
The format of the endpoint string is the *scheme* (``http`` or ``https`` is _required_), followed a hostname
38+
endpoint:
39+
The endpoint to use for sending HTTP requests to the Analytics server.
40+
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.
4141
credential: User credentials.
4242
options: Global options to set for the cluster.
4343
Some operations allow the global options to be overriden by passing in options to the operation.
4444
**kwargs: keyword arguments that can be used in place or to overrride provided :class:`~couchbase_analytics.options.ClusterOptions`
4545
4646
Raises:
47-
ValueError: If incorrect connstr is provided.
47+
ValueError: If incorrect endpoint is provided.
4848
ValueError: If incorrect options are provided.
4949
5050
""" # noqa: E501
5151

5252
def __init__(
53-
self, http_endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
53+
self, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
5454
) -> None:
5555
from couchbase_analytics.protocol.cluster import Cluster as _Cluster
5656

57-
self._impl = _Cluster(http_endpoint, credential, options, **kwargs)
57+
self._impl = _Cluster(endpoint, credential, options, **kwargs)
5858

5959
def database(self, name: str) -> Database:
6060
"""Creates a database instance.
@@ -151,14 +151,20 @@ def shutdown(self) -> None:
151151

152152
@classmethod
153153
def create_instance(
154-
cls, http_endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
154+
cls, endpoint: str, credential: Credential, options: Optional[ClusterOptions] = None, **kwargs: object
155155
) -> Cluster:
156156
"""Create a Cluster instance
157157
158+
.. important::
159+
The appropriate port needs to be specified. The SDK's default ports are 80 (http) and 443 (https).
160+
If attempting to connect to Capella, the correct ports are most likely to be 8095 (http) and 18095 (https).
161+
162+
Capella example: https://cb.2xg3vwszqgqcrsix.cloud.couchbase.com:18095
163+
158164
Args:
159-
http_endpoint:
160-
The HTTP endpoint to use for sending requests to the Analytics server.
161-
The format of the endpoint string is the *scheme* (``http`` or ``https`` is _required_), followed a hostname
165+
endpoint:
166+
The endpoint to use for sending HTTP requests to the Analytics server.
167+
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.
162168
credential: User credentials.
163169
options: Global options to set for the cluster.
164170
Some operations allow the global options to be overriden by passing in options to the operation.
@@ -169,7 +175,7 @@ def create_instance(
169175
An Analytics Cluster instance.
170176
171177
Raises:
172-
ValueError: If incorrect connstr is provided.
178+
ValueError: If incorrect endpoint is provided.
173179
ValueError: If incorrect options are provided.
174180
175181
@@ -196,4 +202,4 @@ def create_instance(
196202
cluster = Cluster.create_instance('https://hostname', cred, opts)
197203
198204
""" # noqa: E501
199-
return cls(http_endpoint, credential, options, **kwargs)
205+
return cls(endpoint, credential, options, **kwargs)

‎couchbase_analytics/cluster.pyi‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,15 +30,15 @@ from couchbase_analytics.result import BlockingQueryResult
3030

3131
class Cluster:
3232
@overload
33-
def __init__(self, http_endpoint: str, credential: Credential) -> None: ...
33+
def __init__(self, endpoint: str, credential: Credential) -> None: ...
3434
@overload
35-
def __init__(self, http_endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
35+
def __init__(self, endpoint: str, credential: Credential, options: ClusterOptions) -> None: ...
3636
@overload
37-
def __init__(self, http_endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
37+
def __init__(self, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]) -> None: ...
3838
@overload
3939
def __init__(
4040
self,
41-
http_endpoint: str,
41+
endpoint: str,
4242
credential: Credential,
4343
options: ClusterOptions,
4444
**kwargs: Unpack[ClusterOptionsKwargs],
@@ -117,17 +117,17 @@ class Cluster:
117117
def shutdown(self) -> None: ...
118118
@overload
119119
@classmethod
120-
def create_instance(cls, http_endpoint: str, credential: Credential) -> Cluster: ...
120+
def create_instance(cls, endpoint: str, credential: Credential) -> Cluster: ...
121121
@overload
122122
@classmethod
123-
def create_instance(cls, http_endpoint: str, credential: Credential, options: ClusterOptions) -> Cluster: ...
123+
def create_instance(cls, endpoint: str, credential: Credential, options: ClusterOptions) -> Cluster: ...
124124
@overload
125125
@classmethod
126126
def create_instance(
127-
cls, http_endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
127+
cls, endpoint: str, credential: Credential, **kwargs: Unpack[ClusterOptionsKwargs]
128128
) -> Cluster: ...
129129
@overload
130130
@classmethod
131131
def create_instance(
132-
cls, http_endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
132+
cls, endpoint: str, credential: Credential, options: ClusterOptions, **kwargs: Unpack[ClusterOptionsKwargs]
133133
) -> Cluster: ...

0 commit comments

Comments
 (0)