chore(docs): add preview docstrings to v3 client (#926)

googleapis · Feb 7, 2024 · 3393f8c · 3393f8c
1 parent 74b93f2
commit 3393f8c
Show file tree

Hide file tree

Showing 3 changed files with 90 additions and 36 deletions.
diff --git a/README.rst b/README.rst
@@ -20,6 +20,24 @@ Analytics, Maps, and Gmail.
 .. _Client Library Documentation: https://googleapis.dev/python/bigtable/latest
 .. _Product Documentation:  https://cloud.google.com/bigtable/docs
 
+
+Preview Async Data Client
+-------------------------
+
+:code:`v2.23.0` includes a preview release of the new :code:`BigtableDataClientAsync` client, accessible at the import path
+:code:`google.cloud.bigtable.data`.
+
+The new client brings a simplified API and increased performance using asyncio, with a corresponding synchronous surface
+coming soon. The new client is focused on the data API (i.e. reading and writing Bigtable data), with admin operations
+remaining in the existing client.
+
+:code:`BigtableDataClientAsync` is currently in preview, and is not recommended for production use.
+
+Feedback and bug reports are welcome at [email protected],
+or through the Github `issue tracker`_.
+
+.. _issue tracker: https://github.com/googleapis/python-bigtable/issues
+
 Quick Start
 -----------
 
@@ -94,14 +112,3 @@ Next Steps
    to see other available methods on the client.
 -  Read the `Product documentation`_ to learn
    more about the product and see How-to Guides.
-
-``google-cloud-happybase``
---------------------------
-
-In addition to the core ``google-cloud-bigtable``, we provide a
-`google-cloud-happybase
-<http://google-cloud-python-happybase.readthedocs.io/en/latest/>`__ library
-with the same interface as the popular `HappyBase
-<https://happybase.readthedocs.io/en/latest/>`__ library. Unlike HappyBase,
-``google-cloud-happybase`` uses ``google-cloud-bigtable`` under the covers,
-rather than Apache HBase.
diff --git a/google/cloud/bigtable/data/README.rst b/google/cloud/bigtable/data/README.rst
@@ -0,0 +1,11 @@
+Async Data Client Preview
+=========================
+
+This new client is currently in preview, and is not recommended for production use.
+
+Synchronous API surface and usage examples coming soon
+
+Feedback and bug reports are welcome at [email protected],
+or through the Github `issue tracker`_.
+
+.. _issue tracker: https://github.com/googleapis/python-bigtable/issues
diff --git a/google/cloud/bigtable/data/_async/client.py b/google/cloud/bigtable/data/_async/client.py
@@ -101,6 +101,9 @@ def __init__(
 
         Client should be created within an async context (running event loop)
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             project: the project which the client acts on behalf of.
                 If not passed, falls back to the default inferred
@@ -563,6 +566,9 @@ async def read_rows_stream(
         Failed requests within operation_timeout will be retried based on the
         retryable_errors list until operation_timeout is reached.
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             - query: contains details about which rows to return
             - operation_timeout: the time budget for the entire operation, in seconds.
@@ -614,6 +620,9 @@ async def read_rows(
         Failed requests within operation_timeout will be retried based on the
         retryable_errors list until operation_timeout is reached.
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             - query: contains details about which rows to return
             - operation_timeout: the time budget for the entire operation, in seconds.
@@ -660,6 +669,9 @@ async def read_row(
         Failed requests within operation_timeout will be retried based on the
         retryable_errors list until operation_timeout is reached.
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             - query: contains details about which rows to return
             - operation_timeout: the time budget for the entire operation, in seconds.
@@ -715,6 +727,9 @@ async def read_rows_sharded(
         results = await table.read_rows_sharded(shard_queries)
         ```
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             - sharded_query: a sharded query to execute
             - operation_timeout: the time budget for the entire operation, in seconds.
@@ -795,6 +810,9 @@ async def row_exists(
         Return a boolean indicating whether the specified row exists in the table.
         uses the filters: chain(limit cells per row = 1, strip value)
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             - row_key: the key of the row to check
             - operation_timeout: the time budget for the entire operation, in seconds.
@@ -849,6 +867,9 @@ async def sample_row_keys(
         RowKeySamples is simply a type alias for list[tuple[bytes, int]]; a list of
             row_keys, along with offset positions in the table
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             - operation_timeout: the time budget for the entire operation, in seconds.
                 Failed requests will be retried within the budget.i
@@ -921,6 +942,9 @@ def mutations_batcher(
         Can be used to iteratively add mutations that are flushed as a group,
         to avoid excess network calls
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
           - flush_interval: Automatically flush every flush_interval seconds. If None,
               a table default will be used
@@ -962,35 +986,38 @@ async def mutate_row(
         | TABLE_DEFAULT = TABLE_DEFAULT.DEFAULT,
     ):
         """
-         Mutates a row atomically.
+        Mutates a row atomically.
 
-         Cells already present in the row are left unchanged unless explicitly changed
-         by ``mutation``.
+        Cells already present in the row are left unchanged unless explicitly changed
+        by ``mutation``.
 
-         Idempotent operations (i.e, all mutations have an explicit timestamp) will be
-         retried on server failure. Non-idempotent operations will not.
+        Idempotent operations (i.e, all mutations have an explicit timestamp) will be
+        retried on server failure. Non-idempotent operations will not.
 
-         Args:
-            - row_key: the row to apply mutations to
-            - mutations: the set of mutations to apply to the row
-            - operation_timeout: the time budget for the entire operation, in seconds.
-                Failed requests will be retried within the budget.
-                Defaults to the Table's default_operation_timeout
-            - attempt_timeout: the time budget for an individual network request, in seconds.
-                If it takes longer than this time to complete, the request will be cancelled with
-                a DeadlineExceeded exception, and a retry will be attempted.
-                Defaults to the Table's default_attempt_timeout.
-                If None, defaults to operation_timeout.
-            - retryable_errors: a list of errors that will be retried if encountered.
-                Only idempotent mutations will be retried. Defaults to the Table's
-                default_retryable_errors.
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
+        Args:
+          - row_key: the row to apply mutations to
+          - mutations: the set of mutations to apply to the row
+          - operation_timeout: the time budget for the entire operation, in seconds.
+              Failed requests will be retried within the budget.
+              Defaults to the Table's default_operation_timeout
+          - attempt_timeout: the time budget for an individual network request, in seconds.
+              If it takes longer than this time to complete, the request will be cancelled with
+              a DeadlineExceeded exception, and a retry will be attempted.
+              Defaults to the Table's default_attempt_timeout.
+              If None, defaults to operation_timeout.
+          - retryable_errors: a list of errors that will be retried if encountered.
+              Only idempotent mutations will be retried. Defaults to the Table's
+              default_retryable_errors.
         Raises:
-             - DeadlineExceeded: raised after operation timeout
-                 will be chained with a RetryExceptionGroup containing all
-                 GoogleAPIError exceptions from any retries that failed
-             - GoogleAPIError: raised on non-idempotent operations that cannot be
-                 safely retried.
-            - ValueError if invalid arguments are provided
+           - DeadlineExceeded: raised after operation timeout
+               will be chained with a RetryExceptionGroup containing all
+               GoogleAPIError exceptions from any retries that failed
+           - GoogleAPIError: raised on non-idempotent operations that cannot be
+               safely retried.
+          - ValueError if invalid arguments are provided
         """
         operation_timeout, attempt_timeout = _get_timeouts(
             operation_timeout, attempt_timeout, self
@@ -1050,6 +1077,9 @@ async def bulk_mutate_rows(
         will be retried on failure. Non-idempotent will not, and will reported in a
         raised exception group
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             - mutation_entries: the batches of mutations to apply
                 Each entry will be applied atomically, but entries will be applied
@@ -1098,6 +1128,9 @@ async def check_and_mutate_row(
 
         Non-idempotent operation: will not be retried
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             - row_key: the key of the row to mutate
             - predicate: the filter to be applied to the contents of the specified row.
@@ -1166,6 +1199,9 @@ async def read_modify_write_row(
 
         Non-idempotent operation: will not be retried
 
+        Warning: BigtableDataClientAsync is currently in preview, and is not
+        yet recommended for production use.
+
         Args:
             - row_key: the key of the row to apply read/modify/write rules to
             - rules: A rule or set of rules to apply to the row.