docs(async): mark new AsyncIO APIs as experimental#1533
docs(async): mark new AsyncIO APIs as experimental#1533sinhasubham wants to merge 1 commit intomainfrom
Conversation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request aims to clearly communicate the experimental nature of the new AsyncIO APIs within the Google Cloud Spanner Python client. By adding explicit warnings, users are informed that these APIs are currently in a beta phase and may undergo modifications, ensuring transparency regarding their stability and readiness for production use. Additionally, minor code style improvements were made in synchronous client files. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
There was a problem hiding this comment.
Code Review
This pull request introduces comments to mark several asynchronous API classes as experimental across various modules (e.g., _async/batch.py, _async/client.py, _async/database.py, _async/pool.py, _async/session.py, _async/snapshot.py, _async/streamed.py, _async/transaction.py). Additionally, it updates numerous instances of tuple unpacking and dictionary comprehensions to use explicit parentheses (e.g., a, b = c to (a, b) = c) for improved clarity and consistency across the google/cloud/spanner_v1 directory. No feedback to provide.
| DEFAULT_RETRY_TIMEOUT_SECS = 30 | ||
|
|
||
|
|
||
| # Experimental API - Please note that this API is currently experimental and can change in the future. |
There was a problem hiding this comment.
Normally, this should be part of the docstring so it shows up in IDEs. Now a customer must read the source code to see that this is an experimental API. So it should be something like this:
class Batch(_BatchBase):
"""Accumulate mutations for transmission during :meth:`commit`.
.. note::
This API is experimental and subject to breaking changes.
"""
There was a problem hiding this comment.
So the problem with adding this directly to docString is that it will get copied to sync files as well. CrossSync ignores the "#"comments so it easily works this way.
Other way i can think of is by adding a method at the end of async classes to check if this is a async file using "crossSync.is_async" then append the experimental warning to the doc string. Something like:
if CrossSync.is_async:
if Client.__doc__ is not None:
Client.__doc__ += "\n\nExperimental API - Please note that this API is currently experimental and can change in the future.\n"
| request_options=request_options, | ||
| ) | ||
| call_metadata, error_augmenter = database.with_error_augmentation( | ||
| (call_metadata, error_augmenter) = database.with_error_augmentation( |
There was a problem hiding this comment.
Can we move these other changes to a separate PR?
|
|
||
|
|
||
| # Experimental API - Please note that this API is currently experimental and can change in the future. | ||
| class Client(ClientWithProject): |
There was a problem hiding this comment.
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.
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.