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.

Author: sinhasubham

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

@@ -50,8 +50,16 @@
 DEFAULT_RETRY_TIMEOUT_SECS = 30
 
 
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class _BatchBase(_SessionWrapper):
-    """Accumulate mutations for transmission during :meth:`commit`.
+    """{experimental_api}Accumulate mutations for transmission during :meth:`commit`.
 
     :type session: :class:`~google.cloud.spanner_v1.session.Session`
     :param session: the session used to perform the commit

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

@@ -167,8 +167,16 @@ def _initialize_metrics(project, credentials):
                     )
 
 
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\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",
+            "",
+        )
+    }
+)
 class Client(ClientWithProject):
-    """Client for interacting with Cloud Spanner API.
+    """{experimental_api}Client for interacting with Cloud Spanner API.
 
     .. note::
 

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

@@ -115,8 +115,16 @@
 DEFAULT_RETRY_BACKOFF = AsyncRetry(initial=0.02, maximum=32, multiplier=1.3)
 
 
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class Database(object):
-    """Representation of a Cloud Spanner Database.
+    """{experimental_api}Representation of a Cloud Spanner Database.
 
     We can use a :class:`Database` to:
 

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

@@ -80,9 +80,17 @@ def _type_string_to_type_pb(type_string):
     return _OPERATION_METADATA_TYPES.get(type_string, Empty)
 
 
-@CrossSync.convert_class(add_mapping_for_name="Instance")
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    },
+    add_mapping_for_name="Instance",
+)
 class Instance(object):
-    """Representation of a Cloud Spanner Instance.
+    """{experimental_api}Representation of a Cloud Spanner Instance.
 
     We can use a :class:`Instance` to:
 

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

@@ -72,9 +72,16 @@ async def __aexit__(self, exc_type, exc_value, traceback):
         await self._pool.put(self._session)
 
 
-@CrossSync.convert_class
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class AbstractSessionPool(object):
-    """Specifies required API for concrete session pool implementations.
+    """{experimental_api}Specifies required API for concrete session pool implementations.
 
     :type labels: dict (str -> str) or None
     :param labels: (Optional) user-assigned labels for sessions created
@@ -208,9 +215,16 @@ def session(self, **kwargs):
         return SessionCheckout(self, **kwargs)
 
 
-@CrossSync.convert_class
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class FixedSizePool(AbstractSessionPool):
-    """Concrete session pool implementation:
+    """{experimental_api}Concrete session pool implementation:
 
     - Pre-allocates / creates a fixed number of sessions.
 
@@ -474,9 +488,16 @@ async def clear(self):
                 await session.delete()
 
 
-@CrossSync.convert_class
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class BurstyPool(AbstractSessionPool):
-    """Concrete session pool implementation:
+    """{experimental_api}Concrete session pool implementation:
 
     - "Pings" existing sessions via :meth:`session.exists` before returning
       them.
@@ -585,9 +606,16 @@ async def clear(self):
                 await session.delete()
 
 
-@CrossSync.convert_class
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class PingingPool(FixedSizePool):
-    """Concrete session pool implementation:
+    """{experimental_api}Concrete session pool implementation:
 
     - Pre-allocates / creates a fixed number of sessions.
 
@@ -834,9 +862,16 @@ async def ping(self):
             await self.put(session)
 
 
-@CrossSync.convert_class
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class TransactionPingingPool(PingingPool):
-    """Concrete session pool implementation:
+    """{experimental_api}Concrete session pool implementation:
 
     Deprecated: TransactionPingingPool no longer begins a transaction for each of its sessions at startup.
     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

@@ -48,8 +48,16 @@
 
 
 @total_ordering
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class Session(object):
-    """Representation of a Cloud Spanner Session.
+    """{experimental_api}Representation of a Cloud Spanner Session.
 
     We can use a :class:`Session` to:
 

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

@@ -776,8 +776,16 @@ def _update_for_precommit_token_pb_unsafe(
             self._precommit_token = precommit_token_pb
 
 
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class Snapshot(_SnapshotBase):
-    """Allow a set of reads / SQL statements with shared staleness."""
+    """{experimental_api}Allow a set of reads / SQL statements with shared staleness."""
 
     def __init__(
         self,

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

@@ -23,8 +23,16 @@
 from google.cloud.spanner_v1.types.type import TypeCode
 
 
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class StreamedResultSet(object):
-    """Process a sequence of partial result sets into a single set of row data.
+    """{experimental_api}Process a sequence of partial result sets into a single set of row data.
 
     :type response_iterator:
     :param response_iterator:

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

@@ -54,8 +54,16 @@
 from google.cloud.spanner_v1.types.transaction import TransactionOptions
 
 
+@CrossSync.convert_class(
+    docstring_format_vars={
+        "experimental_api": (
+            "\n\n    .. warning::\n        The Spanner AsyncIO API is experimental and may be subject to breaking changes.\n",
+            "",
+        )
+    }
+)
 class Transaction(_SnapshotBase, _BatchBase):
-    """Implement read-write transaction semantics for a session.
+    """{experimental_api}Implement read-write transaction semantics for a session.
 
     :type session: :class:`~google.cloud.spanner_v1.session.Session`
     :param session: the session used to perform the commit