Skip to content

docs(async): mark new AsyncIO APIs as experimental #1533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sinhasubham merged 1 commit into from
Mar 27, 2026
+118 −19
Merged

docs(async): mark new AsyncIO APIs as experimental #1533

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion google/cloud/spanner_v1/_async/batch.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 9 additions & 1 deletion google/cloud/spanner_v1/_async/client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Copy link
Contributor

@olavloite olavloite Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the most important class to mark clearly, as this is the main entry point for the async API. Can we add a bit more context to the docstring of this class? So something like this:

.. note::
The Async API is currently experimental and subject to breaking changes. This comment will be removed once the API has stabilized.

Copy link
Contributor Author

@sinhasubham sinhasubham Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure will add

"""Client for interacting with Cloud Spanner API.
"""{experimental_api}Client for interacting with Cloud Spanner API.

.. note::

Expand Down
10 changes: 9 additions & 1 deletion google/cloud/spanner_v1/_async/database.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
12 changes: 10 additions & 2 deletions google/cloud/spanner_v1/_async/instance.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
55 changes: 45 additions & 10 deletions google/cloud/spanner_v1/_async/pool.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
10 changes: 9 additions & 1 deletion google/cloud/spanner_v1/_async/session.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
10 changes: 9 additions & 1 deletion google/cloud/spanner_v1/_async/snapshot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
10 changes: 9 additions & 1 deletion google/cloud/spanner_v1/_async/streamed.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
10 changes: 9 additions & 1 deletion google/cloud/spanner_v1/_async/transaction.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading