add type hints & docstrings to TableClient

Author: vgvoleg

ydb/aio/table.py

@@ -3,6 +3,14 @@
 import time
 import typing
 
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+)
+
 import ydb
 
 from ydb import issues, settings as settings_impl, table
@@ -172,16 +180,16 @@ async def create_table(
         self,
         path: str,
         table_description: TableDescription,
-        settings: typing.Optional[settings_impl.BaseRequestSettings] = None,
-    ):
+        settings: Optional[settings_impl.BaseRequestSettings] = None,
+    ) -> ydb.Operation:
         """
         Create a YDB table.
 
         :param path: A table path
-        :param table_description: A description of table to create. An instance TableDescription
-        :param settings: An instance of BaseRequestSettings that describes how rpc should invoked.
+        :param table_description: TableDescription instanse.
+        :param settings: An instance of BaseRequestSettings that describes how rpc should be invoked.
 
-        :return: A description of created scheme entry or error otherwise.
+        :return: Operation or YDB error otherwise.
         """
 
         async def callee(session: Session):
@@ -192,32 +200,63 @@ async def callee(session: Session):
     async def drop_table(
         self,
         path: str,
-        settings: typing.Optional[settings_impl.BaseRequestSettings] = None,
-    ):
+        settings: Optional[settings_impl.BaseRequestSettings] = None,
+    ) -> ydb.Operation:
+        """
+        Drop a YDB table.
+
+        :param path: A table path
+        :param settings: An instance of BaseRequestSettings that describes how rpc should be invoked.
+
+        :return: Operation or YDB error otherwise.
+        """
+
         async def callee(session: Session):
             return await session.drop_table(path=path, settings=settings)
 
         return await self._pool.retry_operation(callee)
 
     async def alter_table(
         self,
-        path,
-        add_columns=None,
-        drop_columns=None,
-        settings=None,
-        alter_attributes=None,
-        add_indexes=None,
-        drop_indexes=None,
-        set_ttl_settings=None,
-        drop_ttl_settings=None,
-        add_column_families=None,
-        alter_column_families=None,
-        alter_storage_settings=None,
-        set_compaction_policy=None,
-        alter_partitioning_settings=None,
-        set_key_bloom_filter=None,
-        set_read_replicas_settings=None,
-    ):
+        path: str,
+        add_columns: Optional[List[ydb.Column]] = None,
+        drop_columns: Optional[List[str]] = None,
+        settings: Optional[settings_impl.BaseRequestSettings] = None,
+        alter_attributes: Optional[Optional[Dict[str, str]]] = None,
+        add_indexes: Optional[List[ydb.TableIndex]] = None,
+        drop_indexes: Optional[List[str]] = None,
+        set_ttl_settings: Optional[ydb.TtlSettings] = None,
+        drop_ttl_settings: Optional[Any] = None,
+        add_column_families: Optional[List[ydb.ColumnFamily]] = None,
+        alter_column_families: Optional[List[ydb.ColumnFamily]] = None,
+        alter_storage_settings: Optional[ydb.StorageSettings] = None,
+        set_compaction_policy: Optional[str] = None,
+        alter_partitioning_settings: Optional[ydb.PartitioningSettings] = None,
+        set_key_bloom_filter: Optional[ydb.FeatureFlag] = None,
+        set_read_replicas_settings: Optional[ydb.ReadReplicasSettings] = None,
+    ) -> ydb.Operation:
+        """
+        Alter a YDB table.
+
+        :param path: A table path
+        :param add_columns: List of ydb.Column to add
+        :param drop_columns: List of column names to drop
+        :param settings: An instance of BaseRequestSettings that describes how rpc should be invoked.
+        :param alter_attributes: Dict of attributes to alter
+        :param add_indexes: List of ydb.TableIndex to add
+        :param drop_indexes: List of index names to drop
+        :param set_ttl_settings: ydb.TtlSettings to set
+        :param drop_ttl_settings: Any to drop
+        :param add_column_families: List of ydb.ColumnFamily to add
+        :param alter_column_families: List of ydb.ColumnFamily to alter
+        :param alter_storage_settings: ydb.StorageSettings to alter
+        :param set_compaction_policy: Compaction policy
+        :param alter_partitioning_settings: ydb.PartitioningSettings to alter
+        :param set_key_bloom_filter: ydb.FeatureFlag to set key bloom filter
+
+        :return: Operation or YDB error otherwise.
+        """
+
         async def callee(session: Session):
             return await session.alter_table(
                 path=path,
@@ -240,13 +279,41 @@ async def callee(session: Session):
 
         return await self._pool.retry_operation(callee)
 
-    async def describe_table(self, path, settings=None):
+    async def describe_table(
+        self,
+        path: str,
+        settings: Optional[settings_impl.BaseRequestSettings] = None,
+    ) -> ydb.TableSchemeEntry:
+        """
+        Describe a YDB table.
+
+        :param path: A table path
+        :param settings: An instance of BaseRequestSettings that describes how rpc should be invoked.
+
+        :return: TableSchemeEntry or YDB error otherwise.
+        """
+
         async def callee(session: Session):
             return await session.describe_table(path=path, settings=settings)
 
         return await self._pool.retry_operation(callee)
 
-    async def copy_table(self, source_path, destination_path, settings=None):
+    async def copy_table(
+        self,
+        source_path: str,
+        destination_path: str,
+        settings: Optional[settings_impl.BaseRequestSettings] = None,
+    ) -> ydb.Operation:
+        """
+        Copy a YDB table.
+
+        :param source_path: A table path
+        :param destination_path: Destination table path
+        :param settings: An instance of BaseRequestSettings that describes how rpc should be invoked.
+
+        :return: Operation or YDB error otherwise.
+        """
+
         async def callee(session: Session):
             return await session.copy_table(
                 source_path=source_path,
@@ -256,13 +323,39 @@ async def callee(session: Session):
 
         return await self._pool.retry_operation(callee)
 
-    async def copy_tables(self, source_destination_pairs, settings=None):
+    async def copy_tables(
+        self,
+        source_destination_pairs: List[Tuple[str, str]],
+        settings: Optional[settings_impl.BaseRequestSettings] = None
+    ) -> ydb.Operation:
+        """
+        Copy a YDB tables.
+
+        :param source_destination_pairs: List of tuples (source_path, destination_path)
+        :param settings: An instance of BaseRequestSettings that describes how rpc should be invoked.
+
+        :return: Operation or YDB error otherwise.
+        """
+
         async def callee(session: Session):
             return await session.copy_tables(source_destination_pairs=source_destination_pairs, settings=settings)
 
         return await self._pool.retry_operation(callee)
 
-    async def rename_tables(self, rename_items, settings=None):
+    async def rename_tables(
+        self,
+        rename_items: List[Tuple[str, str]],
+        settings=None
+    ) -> ydb.Operation:
+        """
+        Rename a YDB tables.
+
+        :param rename_items: List of tuples (current_name, desired_name)
+        :param settings: An instance of BaseRequestSettings that describes how rpc should be invoked.
+
+        :return: Operation or YDB error otherwise.
+        """
+
         async def callee(session: Session):
             return await session.rename_tables(rename_items=rename_items, settings=settings)