Merge pull request #464 from ydb-platform/docstrings_experimental_warning

Add docstrings about experimental API

Author: vgvoleg

ydb/query/base.py

@@ -103,7 +103,8 @@ def __init__(self, driver: SupportedDriverType, settings: Optional[QueryClientSe
 
     @abc.abstractmethod
     def create(self) -> "IQuerySession":
-        """
+        """WARNING: This API is experimental and could be changed.
+
         Creates a Session of Query Service on server side and attaches it.
 
         :return: Session object.
@@ -112,7 +113,8 @@ def create(self) -> "IQuerySession":
 
     @abc.abstractmethod
     def delete(self) -> None:
-        """
+        """WARNING: This API is experimental and could be changed.
+
         Deletes a Session of Query Service on server side and releases resources.
 
         :return: None
@@ -121,7 +123,8 @@ def delete(self) -> None:
 
     @abc.abstractmethod
     def transaction(self, tx_mode: Optional[BaseQueryTxMode] = None) -> "IQueryTxContext":
-        """
+        """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:
@@ -143,7 +146,8 @@ def execute(
         parameters: Optional[dict] = None,
         concurrent_result_sets: Optional[bool] = False,
     ) -> Iterator:
-        """
+        """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:
@@ -235,7 +239,8 @@ def tx_id(self) -> Optional[str]:
 
     @abc.abstractmethod
     def begin(self, settings: Optional[QueryClientSettings] = None) -> None:
-        """
+        """WARNING: This API is experimental and could be changed.
+
         Explicitly begins a transaction
 
         :param settings: A request settings
@@ -246,7 +251,8 @@ def begin(self, settings: Optional[QueryClientSettings] = None) -> None:
 
     @abc.abstractmethod
     def commit(self, settings: Optional[QueryClientSettings] = None) -> None:
-        """
+        """WARNING: This API is experimental and could be changed.
+
         Calls commit on a transaction if it is open. If transaction execution
         failed then this method raises PreconditionFailed.
 
@@ -258,7 +264,8 @@ def commit(self, settings: Optional[QueryClientSettings] = None) -> None:
 
     @abc.abstractmethod
     def rollback(self, settings: Optional[QueryClientSettings] = None) -> None:
-        """
+        """WARNING: This API is experimental and could be changed.
+
         Calls rollback on a transaction if it is open. If transaction execution
         failed then this method raises PreconditionFailed.
 
@@ -278,7 +285,8 @@ def execute(
         parameters: Optional[dict] = None,
         concurrent_result_sets: Optional[bool] = False,
     ) -> Iterator:
-        """
+        """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 commit_tx: A special flag that allows transaction commit.

ydb/query/pool.py

@@ -30,12 +30,15 @@ def __init__(self, driver: base.SupportedDriverType):
         self._driver = driver
 
     def checkout(self) -> "SimpleQuerySessionCheckout":
-        """Return a Session context manager, that opens session on enter and closes session on exit."""
+        """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 SimpleQuerySessionCheckout(self)
 
     def retry_operation_sync(self, callee: Callable, retry_settings: Optional[RetrySettings] = None, *args, **kwargs):
-        """Special interface to execute a bunch of commands with session in a safe, retriable way.
+        """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.
         :param retry_settings: RetrySettings object.
@@ -54,7 +57,8 @@ def wrapped_callee():
     def execute_with_retries(
         self, query: str, retry_settings: Optional[RetrySettings] = None, *args, **kwargs
     ) -> List[convert.ResultSet]:
-        """Special interface to execute a one-shot queries in a safe, retriable way.
+        """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

@@ -227,7 +227,8 @@ def _check_session_status_loop(self, status_stream: _utilities.SyncResponseItera
             pass
 
     def delete(self) -> None:
-        """
+        """WARNING: This API is experimental and could be changed.
+
         Deletes a Session of Query Service on server side and releases resources.
 
         :return: None
@@ -240,7 +241,8 @@ def delete(self) -> None:
         self._stream.cancel()
 
     def create(self) -> "QuerySessionSync":
-        """
+        """WARNING: This API is experimental and could be changed.
+
         Creates a Session of Query Service on server side and attaches it.
 
         :return: QuerySessionSync object.
@@ -255,7 +257,8 @@ def create(self) -> "QuerySessionSync":
         return self
 
     def transaction(self, tx_mode: Optional[base.BaseQueryTxMode] = None) -> base.IQueryTxContext:
-        """
+        """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;
@@ -285,7 +288,8 @@ def execute(
         parameters: dict = None,
         concurrent_result_sets: bool = False,
     ) -> base.SyncResponseContextIterator:
-        """
+        """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:

ydb/query/transaction.py

@@ -314,7 +314,8 @@ def _move_to_commited(self) -> None:
         self._tx_state._change_state(QueryTxStateEnum.COMMITTED)
 
     def begin(self, settings: Optional[base.QueryClientSettings] = None) -> None:
-        """
+        """WARNING: This API is experimental and could be changed.
+
         Explicitly begins a transaction
 
         :param settings: A request settings
@@ -326,7 +327,8 @@ def begin(self, settings: Optional[base.QueryClientSettings] = None) -> None:
         self._begin_call(settings)
 
     def commit(self, settings: Optional[base.QueryClientSettings] = None) -> None:
-        """
+        """WARNING: This API is experimental and could be changed.
+
         Calls commit on a transaction if it is open otherwise is no-op. If transaction execution
         failed then this method raises PreconditionFailed.
 
@@ -369,7 +371,24 @@ def execute(
         parameters: Optional[dict] = None,
         concurrent_result_sets: Optional[bool] = False,
     ) -> base.SyncResponseContextIterator:
-
+        """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 commit_tx: A special flag that allows transaction commit.
+        :param syntax: Syntax of the query, which is a one from the following choises:
+         1) QuerySyntax.YQL_V1, which is default;
+         2) QuerySyntax.PG.
+        :param exec_mode: Exec mode of the query, which is a one from the following choises:
+         1) QueryExecMode.EXECUTE, which is default;
+         2) QueryExecMode.EXPLAIN;
+         3) QueryExecMode.VALIDATE;
+         4) QueryExecMode.PARSE.
+        :param parameters: dict with parameters and YDB types;
+        :param concurrent_result_sets: A flag to allow YDB mix parts of different result sets. Default is False;
+
+        :return: Iterator with result sets
+        """
         self._ensure_prev_stream_finished()
         self._tx_state._check_tx_ready_to_use()