chore(docs): improve async docstrings (#978)

daniel-sanche · web-flow · commit c67f275b5a11 · 2024-06-10T11:03:11.000-07:00
diff --git a/google/cloud/bigtable/data/_async/client.py b/google/cloud/bigtable/data/_async/client.py
@@ -112,12 +112,12 @@ def __init__(
                 client. If not passed (and if no ``_http`` object is
                 passed), falls back to the default inferred from the
                 environment.
-            client_options (Optional[Union[dict, google.api_core.client_options.ClientOptions]]):
+            client_options:
                 Client options used to set user options
                 on the client. API Endpoint should be set through client_options.
         Raises:
-          RuntimeError: if called outside of an async context (no running event loop)
-          ValueError: if pool_size is less than 1
+            RuntimeError: if called outside of an async context (no running event loop)
+            ValueError: if pool_size is less than 1
         """
         # set up transport in registry
         transport_str = f"pooled_grpc_asyncio_{pool_size}"
@@ -711,14 +711,13 @@ async def read_rows_sharded(
         Runs a sharded query in parallel, then return the results in a single list.
         Results will be returned in the order of the input queries.
 
-        This function is intended to be run on the results on a query.shard() call:
+        This function is intended to be run on the results on a query.shard() call.
+        For example::
 
-        ```
-        table_shard_keys = await table.sample_row_keys()
-        query = ReadRowsQuery(...)
-        shard_queries = query.shard(table_shard_keys)
-        results = await table.read_rows_sharded(shard_queries)
-        ```
+            table_shard_keys = await table.sample_row_keys()
+            query = ReadRowsQuery(...)
+            shard_queries = query.shard(table_shard_keys)
+            results = await table.read_rows_sharded(shard_queries)
 
         Args:
             sharded_query: a sharded query to execute
diff --git a/google/cloud/bigtable/data/mutations.py b/google/cloud/bigtable/data/mutations.py
@@ -94,11 +94,9 @@ def _from_dict(cls, input_dict: dict[str, Any]) -> Mutation:
         Create a `Mutation` instance from a dictionary representation.
 
         Args:
-            input_dict (dict[str, Any]): A dictionary representation of the mutation.
-
+            input_dict: A dictionary representation of the mutation.
         Returns:
             Mutation: A Mutation instance created from the dictionary.
-
         Raises:
             ValueError: If the input dictionary is invalid or does not represent a valid mutation type.
         """
@@ -139,10 +137,10 @@ class SetCell(Mutation):
     Mutation to set the value of a cell.
 
     Args:
-        family (str): The name of the column family to which the new cell belongs.
-        qualifier (bytes | str): The column qualifier of the new cell.
-        new_value (bytes | str | int): The value of the new cell.
-        timestamp_micros (int | None): The timestamp of the new cell. If `None`,
+        family: The name of the column family to which the new cell belongs.
+        qualifier: The column qualifier of the new cell.
+        new_value: The value of the new cell.
+        timestamp_micros: The timestamp of the new cell. If `None`,
             the current timestamp will be used. Timestamps will be sent with
             millisecond precision. Extra precision will be truncated. If -1, the
             server will assign a timestamp. Note that `SetCell` mutations with
@@ -207,13 +205,12 @@ class DeleteRangeFromColumn(Mutation):
     Mutation to delete a range of cells from a column.
 
     Args:
-        family (str): The name of the column family.
-         qualifier (bytes): The column qualifier.
-        start_timestamp_micros (int | None): The start timestamp of the range to
+        family: The name of the column family.
+         qualifier: The column qualifier.
+        start_timestamp_micros: The start timestamp of the range to
             delete. `None` represents 0. Defaults to `None`.
-        end_timestamp_micros (int | None): The end timestamp of the range to
+        end_timestamp_micros: The end timestamp of the range to
             delete. `None` represents infinity. Defaults to `None`.
-
     Raises:
         ValueError: If `start_timestamp_micros` is greater than `end_timestamp_micros`.
     """
@@ -254,7 +251,7 @@ class DeleteAllFromFamily(Mutation):
     Mutation to delete all cells from a column family.
 
     Args:
-        family_to_delete (str): The name of the column family to delete.
+        family_to_delete: The name of the column family to delete.
     """
 
     family_to_delete: str
@@ -287,8 +284,8 @@ class RowMutationEntry:
     Bigtable table.
 
     Args:
-        row_key (bytes | str): The key of the row to mutate.
-        mutations (Mutation | list[Mutation]): The mutation or list of mutations to apply
+        row_key: The key of the row to mutate.
+        mutations: The mutation or list of mutations to apply
             to the row.
 
     Raises:
@@ -358,7 +355,7 @@ def _from_dict(cls, input_dict: dict[str, Any]) -> RowMutationEntry:
         Create a `RowMutationEntry` instance from a dictionary representation.
 
         Args:
-            input_dict (dict[str, Any]): A dictionary representation of the mutation entry.
+            input_dict: A dictionary representation of the mutation entry.
 
         Returns:
             RowMutationEntry: A RowMutationEntry instance created from the dictionary.
diff --git a/google/cloud/bigtable/data/read_modify_write_rules.py b/google/cloud/bigtable/data/read_modify_write_rules.py
@@ -47,11 +47,11 @@ class IncrementRule(ReadModifyWriteRule):
     Rule to increment a cell's value.
 
     Args:
-        family (str):
+        family:
             The family name of the cell to increment.
-        qualifier (bytes | str):
+        qualifier:
             The qualifier of the cell to increment.
-        increment_amount (int):
+        increment_amount:
             The amount to increment the cell's value. Must be between -2**63 and 2**63 (64-bit signed int).
     Raises:
         TypeError:
@@ -83,11 +83,11 @@ class AppendValueRule(ReadModifyWriteRule):
     Rule to append a value to a cell's value.
 
     Args:
-        family (str):
+        family:
             The family name of the cell to append to.
-        qualifier (bytes | str):
+        qualifier:
             The qualifier of the cell to append to.
-        append_value (bytes | str):
+        append_value:
             The value to append to the cell's value.
     Raises:
         TypeError: If append_value is not bytes or str.
diff --git a/google/cloud/bigtable/data/read_rows_query.py b/google/cloud/bigtable/data/read_rows_query.py
@@ -31,6 +31,17 @@
 class RowRange:
     """
     Represents a range of keys in a ReadRowsQuery
+
+    Args:
+        start_key: The start key of the range. If empty, the range is unbounded on the left.
+        end_key: The end key of the range. If empty, the range is unbounded on the right.
+        start_is_inclusive: Whether the start key is inclusive. If None, the start key is
+            inclusive.
+        end_is_inclusive: Whether the end key is inclusive. If None, the end key is not inclusive.
+    Raises:
+        ValueError: if start_key is greater than end_key, or start_is_inclusive
+        ValueError: if end_is_inclusive is set when the corresponding key is None
+        ValueError: if start_key or end_key is not a string or bytes.
     """
 
     __slots__ = ("_pb",)
@@ -42,18 +53,6 @@ def __init__(
         start_is_inclusive: bool | None = None,
         end_is_inclusive: bool | None = None,
     ):
-        """
-        Args:
-            start_key: The start key of the range. If empty, the range is unbounded on the left.
-            end_key: The end key of the range. If empty, the range is unbounded on the right.
-            start_is_inclusive: Whether the start key is inclusive. If None, the start key is
-                inclusive.
-            end_is_inclusive: Whether the end key is inclusive. If None, the end key is not inclusive.
-        Raises:
-            ValueError: if start_key is greater than end_key, or start_is_inclusive
-            ValueError: if end_is_inclusive is set when the corresponding key is None
-            ValueError: if start_key or end_key is not a string or bytes.
-        """
         # convert empty key inputs to None for consistency
         start_key = None if not start_key else start_key
         end_key = None if not end_key else end_key
@@ -221,6 +220,14 @@ def __repr__(self) -> str:
 class ReadRowsQuery:
     """
     Class to encapsulate details of a read row request
+
+    Args:
+        row_keys: row keys to include in the query
+            a query can contain multiple keys, but ranges should be preferred
+        row_ranges: ranges of rows to include in the query
+        limit: the maximum number of rows to return. None or 0 means no limit
+            default: None (no limit)
+        row_filter: a RowFilter to apply to the query
     """
 
     slots = ("_limit", "_filter", "_row_set")
@@ -232,17 +239,6 @@ def __init__(
         limit: int | None = None,
         row_filter: RowFilter | None = None,
     ):
-        """
-        Create a new ReadRowsQuery
-
-        Args:
-            row_keys: row keys to include in the query
-                a query can contain multiple keys, but ranges should be preferred
-            row_ranges: ranges of rows to include in the query
-            limit: the maximum number of rows to return. None or 0 means no limit
-                default: None (no limit)
-            row_filter: a RowFilter to apply to the query
-        """
         if row_keys is None:
             row_keys = []
         if row_ranges is None:
diff --git a/google/cloud/bigtable/data/row.py b/google/cloud/bigtable/data/row.py
@@ -33,8 +33,13 @@ class Row:
     query.
     Expected to be read-only to users, and written by backend
 
-    Can be indexed:
-    cells = row["family", "qualifier"]
+    Can be indexed by family and qualifier to get cells in the row::
+
+        cells = row["family", "qualifier"]
+
+    Args:
+        key: Row key
+        cells: List of cells in the row
     """
 
     __slots__ = ("row_key", "cells", "_index_data")
@@ -45,14 +50,8 @@ def __init__(
         cells: list[Cell],
     ):
         """
-        Initializes a Row object
-
         Row objects are not intended to be created by users.
         They are returned by the Bigtable backend.
-
-        Args:
-            key (bytes): Row key
-            cells (list[Cell]): List of cells in the row
         """
         self.row_key = key
         self.cells: list[Cell] = cells
@@ -121,9 +120,9 @@ def get_cells(
 
         If family or qualifier not passed, will include all
 
-        Can also be accessed through indexing:
-          cells = row["family", "qualifier"]
-          cells = row["family"]
+        Can also be accessed through indexing::
+            cells = row["family", "qualifier"]
+            cells = row["family"]
 
         Args:
             family: family to filter cells by
@@ -172,9 +171,7 @@ def _get_all_from_family(self, family: str) -> Generator[Cell, None, None]:
 
     def __str__(self) -> str:
         """
-        Human-readable string representation
-
-        .. code-block:: python
+        Human-readable string representation::
 
             {
               (family='fam', qualifier=b'col'): [b'value', (+1 more),],
diff --git a/samples/quickstart/main_async_test.py b/samples/quickstart/main_async_test.py
@@ -16,7 +16,8 @@
 from typing import AsyncGenerator
 
 from google.cloud.bigtable.data import BigtableDataClientAsync, SetCell
-import pytest, pytest_asyncio
+import pytest
+import pytest_asyncio
 
 from main_async import main
 
diff --git a/samples/quickstart/requirements-test.txt b/samples/quickstart/requirements-test.txt
@@ -1 +1,2 @@
 pytest==7.4.4
+pytest-asyncio
diff --git a/samples/quickstart/requirements.txt b/samples/quickstart/requirements.txt
@@ -1 +1 @@
-google-cloud-bigtable==2.22.0
+google-cloud-bigtable==2.23.0
diff --git a/samples/snippets/deletes/deletes_async_test.py b/samples/snippets/deletes/deletes_async_test.py
@@ -18,7 +18,8 @@
 from typing import AsyncGenerator
 
 from google.cloud._helpers import _microseconds_from_datetime
-import pytest, pytest_asyncio
+import pytest
+import pytest_asyncio
 
 import deletes_snippets_async
 
@@ -72,7 +73,7 @@ async def _populate_table(table_id):
     timestamp = datetime.datetime(2019, 5, 1)
     timestamp_minus_hr = timestamp - datetime.timedelta(hours=1)
 
-    async with (BigtableDataClientAsync(project=PROJECT) as client):
+    async with BigtableDataClientAsync(project=PROJECT) as client:
         async with client.get_table(BIGTABLE_INSTANCE, table_id) as table:
             async with table.mutations_batcher() as batcher:
                 await batcher.append(
diff --git a/samples/snippets/deletes/requirements-test.txt b/samples/snippets/deletes/requirements-test.txt
@@ -1 +1,2 @@
 pytest==7.4.4
+pytest-asyncio
diff --git a/samples/snippets/deletes/requirements.txt b/samples/snippets/deletes/requirements.txt
@@ -1 +1 @@
-google-cloud-bigtable==2.22.0
+google-cloud-bigtable==2.23.0

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-google-cloud-bigtable==2.22.0`
	`1`	`+google-cloud-bigtable==2.23.0`