refactor docstrings

Author: vgvoleg

ydb/aio/query/pool.py

@@ -44,6 +44,13 @@ async def _create_new_session(self):
         return session
 
     async def acquire(self) -> QuerySession:
+        """WARNING: This API is experimental and could be changed.
+
+        Acquire a session from Session Pool.
+
+        :return A QuerySession object.
+        """
+
         if self._should_stop.is_set():
             logger.error("An attempt to take session from closed session pool.")
             raise RuntimeError("An attempt to take session from closed session pool.")
@@ -79,12 +86,18 @@ async def acquire(self) -> QuerySession:
         return session
 
     async def release(self, session: QuerySession) -> None:
+        """WARNING: This API is experimental and could be changed.
+
+        Release a session back to Session Pool.
+        """
+
         self._queue.put_nowait(session)
         logger.debug("Session returned to queue: %s", session._state.session_id)
 
     def checkout(self) -> "SimpleQuerySessionCheckoutAsync":
         """WARNING: This API is experimental and could be changed.
-        Return a Session context manager, that opens session on enter and closes session on exit.
+
+        Return a Session context manager, that acquires session on enter and releases session on exit.
         """
 
         return SimpleQuerySessionCheckoutAsync(self)
@@ -93,6 +106,7 @@ async def retry_operation_async(
         self, callee: Callable, retry_settings: Optional[RetrySettings] = None, *args, **kwargs
     ):
         """WARNING: This API is experimental and could be changed.
+
         Special interface to execute a bunch of commands with session in a safe, retriable way.
 
         :param callee: A function, that works with session.
@@ -118,6 +132,7 @@ async def execute_with_retries(
         **kwargs,
     ) -> List[convert.ResultSet]:
         """WARNING: This API is experimental and could be changed.
+
         Special interface to execute a one-shot queries in a safe, retriable way.
         Note: this method loads all data from stream before return, do not use this
         method with huge read queries.

ydb/aio/query/session.py

@@ -116,6 +116,7 @@ async def execute(
         """WARNING: This API is experimental and could be changed.
 
         Sends a query to Query Service
+
         :param query: (YQL or SQL text) to be executed.
         :param syntax: Syntax of the query, which is a one from the following choises:
          1) QuerySyntax.YQL_V1, which is default;

ydb/aio/query/transaction.py

@@ -114,6 +114,7 @@ async def execute(
         """WARNING: This API is experimental and could be changed.
 
         Sends a query to Query Service
+
         :param query: (YQL or SQL text) to be executed.
         :param parameters: dict with parameters and YDB types;
         :param commit_tx: A special flag that allows transaction commit.

ydb/query/pool.py

@@ -29,7 +29,8 @@ class QuerySessionPool:
 
     def __init__(self, driver: common_utils.SupportedDriverType, size: int = 100):
         """
-        :param driver: A driver instance
+        :param driver: A driver instance.
+        :param size: Max size of Session Pool.
         """
 
         logger.warning("QuerySessionPool is an experimental API, which could be changed.")
@@ -47,6 +48,15 @@ def _create_new_session(self, timeout: Optional[float]):
         return session
 
     def acquire(self, timeout: Optional[float] = None) -> QuerySession:
+        """WARNING: This API is experimental and could be changed.
+
+        Acquire a session from Session Pool.
+
+        :param timeout: A timeout to wait in seconds.
+
+        :return A QuerySession object.
+        """
+
         start = time.monotonic()
 
         lock_acquire_timeout = timeout if timeout is not None else -1
@@ -92,18 +102,27 @@ def acquire(self, timeout: Optional[float] = None) -> QuerySession:
                 self._lock.release()
 
     def release(self, session: QuerySession) -> None:
+        """WARNING: This API is experimental and could be changed.
+
+        Release a session back to Session Pool.
+        """
+
         self._queue.put_nowait(session)
         logger.debug("Session returned to queue: %s", session._state.session_id)
 
     def checkout(self, timeout: Optional[float] = None) -> "SimpleQuerySessionCheckout":
         """WARNING: This API is experimental and could be changed.
-        Return a Session context manager, that opens session on enter and closes session on exit.
+
+        Return a Session context manager, that acquires session on enter and releases session on exit.
+
+        :param timeout: A timeout to wait in seconds.
         """
 
         return SimpleQuerySessionCheckout(self, timeout)
 
     def retry_operation_sync(self, callee: Callable, retry_settings: Optional[RetrySettings] = None, *args, **kwargs):
         """WARNING: This API is experimental and could be changed.
+
         Special interface to execute a bunch of commands with session in a safe, retriable way.
 
         :param callee: A function, that works with session.
@@ -129,6 +148,7 @@ def execute_with_retries(
         **kwargs,
     ) -> List[convert.ResultSet]:
         """WARNING: This API is experimental and could be changed.
+
         Special interface to execute a one-shot queries in a safe, retriable way.
         Note: this method loads all data from stream before return, do not use this
         method with huge read queries.

ydb/query/session.py

@@ -269,6 +269,7 @@ def transaction(self, tx_mode: Optional[base.BaseQueryTxMode] = None) -> QueryTx
         """WARNING: This API is experimental and could be changed.
 
         Creates a transaction context manager with specified transaction mode.
+
         :param tx_mode: Transaction mode, which is a one from the following choises:
          1) QuerySerializableReadWrite() which is default mode;
          2) QueryOnlineReadOnly(allow_inconsistent_reads=False);
@@ -301,6 +302,7 @@ def execute(
         """WARNING: This API is experimental and could be changed.
 
         Sends a query to Query Service
+
         :param query: (YQL or SQL text) to be executed.
         :param syntax: Syntax of the query, which is a one from the following choises:
          1) QuerySyntax.YQL_V1, which is default;

ydb/query/transaction.py

@@ -394,6 +394,7 @@ def execute(
         """WARNING: This API is experimental and could be changed.
 
         Sends a query to Query Service
+
         :param query: (YQL or SQL text) to be executed.
         :param parameters: dict with parameters and YDB types;
         :param commit_tx: A special flag that allows transaction commit.