Skip to content

Commit 3909c04

Browse files
sinhasubhamsinhasubham
authored
docs(async): mark new AsyncIO APIs as experimental (#1533)
Add experimental warning comments to all async Spanner Python components to inform users that the API is in the beta phase and subject to change.
1 parent 8f68116 commit 3909c04

File tree

9 files changed

+118
-19
lines changed

9 files changed

+118
-19
lines changed

‎packages/google-cloud-spanner/google/cloud/spanner_v1/_async/batch.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,16 @@
5050
DEFAULT_RETRY_TIMEOUT_SECS = 30
5151

5252

53+
@CrossSync.convert_class(
54+
docstring_format_vars={
55+
"experimental_api": (
56+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
57+
"",
58+
)
59+
}
60+
)
5361
class _BatchBase(_SessionWrapper):
54-
"""Accumulate mutations for transmission during :meth:`commit`.
62+
"""{experimental_api}Accumulate mutations for transmission during :meth:`commit`.
5563
5664
:type session: :class:`~google.cloud.spanner_v1.session.Session`
5765
:param session: the session used to perform the commit

‎packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -167,8 +167,16 @@ def _initialize_metrics(project, credentials):
167167
)
168168

169169

170+
@CrossSync.convert_class(
171+
docstring_format_vars={
172+
"experimental_api": (
173+
"\n\n .. warning::\n The Async API is currently experimental and subject to breaking changes. This comment will be removed once the API has stabilized.\n",
174+
"",
175+
)
176+
}
177+
)
170178
class Client(ClientWithProject):
171-
"""Client for interacting with Cloud Spanner API.
179+
"""{experimental_api}Client for interacting with Cloud Spanner API.
172180
173181
.. note::
174182

‎packages/google-cloud-spanner/google/cloud/spanner_v1/_async/database.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,8 +115,16 @@
115115
DEFAULT_RETRY_BACKOFF = AsyncRetry(initial=0.02, maximum=32, multiplier=1.3)
116116

117117

118+
@CrossSync.convert_class(
119+
docstring_format_vars={
120+
"experimental_api": (
121+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
122+
"",
123+
)
124+
}
125+
)
118126
class Database(object):
119-
"""Representation of a Cloud Spanner Database.
127+
"""{experimental_api}Representation of a Cloud Spanner Database.
120128
121129
We can use a :class:`Database` to:
122130

‎packages/google-cloud-spanner/google/cloud/spanner_v1/_async/instance.py‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -80,9 +80,17 @@ def _type_string_to_type_pb(type_string):
8080
return _OPERATION_METADATA_TYPES.get(type_string, Empty)
8181

8282

83-
@CrossSync.convert_class(add_mapping_for_name="Instance")
83+
@CrossSync.convert_class(
84+
docstring_format_vars={
85+
"experimental_api": (
86+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
87+
"",
88+
)
89+
},
90+
add_mapping_for_name="Instance",
91+
)
8492
class Instance(object):
85-
"""Representation of a Cloud Spanner Instance.
93+
"""{experimental_api}Representation of a Cloud Spanner Instance.
8694
8795
We can use a :class:`Instance` to:
8896

‎packages/google-cloud-spanner/google/cloud/spanner_v1/_async/pool.py‎

Lines changed: 45 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,16 @@ async def __aexit__(self, exc_type, exc_value, traceback):
7272
await self._pool.put(self._session)
7373

7474

75-
@CrossSync.convert_class
75+
@CrossSync.convert_class(
76+
docstring_format_vars={
77+
"experimental_api": (
78+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
79+
"",
80+
)
81+
}
82+
)
7683
class AbstractSessionPool(object):
77-
"""Specifies required API for concrete session pool implementations.
84+
"""{experimental_api}Specifies required API for concrete session pool implementations.
7885
7986
:type labels: dict (str -> str) or None
8087
:param labels: (Optional) user-assigned labels for sessions created
@@ -208,9 +215,16 @@ def session(self, **kwargs):
208215
return SessionCheckout(self, **kwargs)
209216

210217

211-
@CrossSync.convert_class
218+
@CrossSync.convert_class(
219+
docstring_format_vars={
220+
"experimental_api": (
221+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
222+
"",
223+
)
224+
}
225+
)
212226
class FixedSizePool(AbstractSessionPool):
213-
"""Concrete session pool implementation:
227+
"""{experimental_api}Concrete session pool implementation:
214228
215229
- Pre-allocates / creates a fixed number of sessions.
216230
@@ -474,9 +488,16 @@ async def clear(self):
474488
await session.delete()
475489

476490

477-
@CrossSync.convert_class
491+
@CrossSync.convert_class(
492+
docstring_format_vars={
493+
"experimental_api": (
494+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
495+
"",
496+
)
497+
}
498+
)
478499
class BurstyPool(AbstractSessionPool):
479-
"""Concrete session pool implementation:
500+
"""{experimental_api}Concrete session pool implementation:
480501
481502
- "Pings" existing sessions via :meth:`session.exists` before returning
482503
them.
@@ -585,9 +606,16 @@ async def clear(self):
585606
await session.delete()
586607

587608

588-
@CrossSync.convert_class
609+
@CrossSync.convert_class(
610+
docstring_format_vars={
611+
"experimental_api": (
612+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
613+
"",
614+
)
615+
}
616+
)
589617
class PingingPool(FixedSizePool):
590-
"""Concrete session pool implementation:
618+
"""{experimental_api}Concrete session pool implementation:
591619
592620
- Pre-allocates / creates a fixed number of sessions.
593621
@@ -834,9 +862,16 @@ async def ping(self):
834862
await self.put(session)
835863

836864

837-
@CrossSync.convert_class
865+
@CrossSync.convert_class(
866+
docstring_format_vars={
867+
"experimental_api": (
868+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
869+
"",
870+
)
871+
}
872+
)
838873
class TransactionPingingPool(PingingPool):
839-
"""Concrete session pool implementation:
874+
"""{experimental_api}Concrete session pool implementation:
840875
841876
Deprecated: TransactionPingingPool no longer begins a transaction for each of its sessions at startup.
842877
Hence the TransactionPingingPool is same as :class:`PingingPool` and maybe removed in the future.

‎packages/google-cloud-spanner/google/cloud/spanner_v1/_async/session.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,16 @@
4848

4949

5050
@total_ordering
51+
@CrossSync.convert_class(
52+
docstring_format_vars={
53+
"experimental_api": (
54+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
55+
"",
56+
)
57+
}
58+
)
5159
class Session(object):
52-
"""Representation of a Cloud Spanner Session.
60+
"""{experimental_api}Representation of a Cloud Spanner Session.
5361
5462
We can use a :class:`Session` to:
5563

‎packages/google-cloud-spanner/google/cloud/spanner_v1/_async/snapshot.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -776,8 +776,16 @@ def _update_for_precommit_token_pb_unsafe(
776776
self._precommit_token = precommit_token_pb
777777

778778

779+
@CrossSync.convert_class(
780+
docstring_format_vars={
781+
"experimental_api": (
782+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
783+
"",
784+
)
785+
}
786+
)
779787
class Snapshot(_SnapshotBase):
780-
"""Allow a set of reads / SQL statements with shared staleness."""
788+
"""{experimental_api}Allow a set of reads / SQL statements with shared staleness."""
781789

782790
def __init__(
783791
self,

‎packages/google-cloud-spanner/google/cloud/spanner_v1/_async/streamed.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,16 @@
2323
from google.cloud.spanner_v1.types.type import TypeCode
2424

2525

26+
@CrossSync.convert_class(
27+
docstring_format_vars={
28+
"experimental_api": (
29+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
30+
"",
31+
)
32+
}
33+
)
2634
class StreamedResultSet(object):
27-
"""Process a sequence of partial result sets into a single set of row data.
35+
"""{experimental_api}Process a sequence of partial result sets into a single set of row data.
2836
2937
:type response_iterator:
3038
:param response_iterator:

‎packages/google-cloud-spanner/google/cloud/spanner_v1/_async/transaction.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,16 @@
5454
from google.cloud.spanner_v1.types.transaction import TransactionOptions
5555

5656

57+
@CrossSync.convert_class(
58+
docstring_format_vars={
59+
"experimental_api": (
60+
"\n\n .. warning::\n The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
61+
"",
62+
)
63+
}
64+
)
5765
class Transaction(_SnapshotBase, _BatchBase):
58-
"""Implement read-write transaction semantics for a session.
66+
"""{experimental_api}Implement read-write transaction semantics for a session.
5967
6068
:type session: :class:`~google.cloud.spanner_v1.session.Session`
6169
:param session: the session used to perform the commit

0 commit comments

Comments
 (0)