docstrings for base interfaces

Author: vgvoleg

ydb/query/base.py

@@ -19,6 +19,20 @@
 from .. import _utilities
 
 
+class QuerySyntax(enum.IntEnum):
+    UNSPECIFIED = 0
+    YQL_V1 = 1
+    PG = 2
+
+
+class QueryExecMode(enum.IntEnum):
+    UNSPECIFIED = 0
+    PARSE = 10
+    VALIDATE = 20
+    EXPLAIN = 30
+    EXECUTE = 50
+
+
 class QueryClientSettings:
     pass
 
@@ -60,24 +74,60 @@ def set_attached(self, attached: bool) -> "IQuerySessionState":
 
 
 class IQuerySession(abc.ABC):
+    """Session object for Query Service. It is not recommended to control
+    session's lifecycle manually - use a QuerySessionPool is always a better choise.
+    """
+
     @abc.abstractmethod
     def __init__(self, driver: SupportedDriverType, settings: QueryClientSettings = None):
         pass
 
     @abc.abstractmethod
     def create(self) -> "IQuerySession":
+        """
+        Creates a Session of Query Service on server side and attaches it.
+
+        :return: Session object.
+        """
         pass
 
     @abc.abstractmethod
     def delete(self) -> None:
+        """
+        Deletes a Session of Query Service on server side and releases resources.
+
+        :return: None
+        """
         pass
 
     @abc.abstractmethod
     def transaction(self, tx_mode: BaseQueryTxMode) -> "IQueryTxContext":
+        """
+        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);
+         3) QuerySnapshotReadOnly();
+         4) QueryStaleReadOnly().
+
+        :return: transaction context manager.
+        """
         pass
 
 
 class IQueryTxContext(abc.ABC):
+    """
+    An object that provides a simple transaction context manager that allows statements execution
+    in a transaction. You don't have to open transaction explicitly, because context manager encapsulates
+    transaction control logic, and opens new transaction if:
+     1) By explicit .begin();
+     2) On execution of a first statement, which is strictly recommended method, because that avoids
+     useless round trip
+
+    This context manager is not thread-safe, so you should not manipulate on it concurrently.
+    """
+
     @abc.abstractmethod
     def __init__(
         self,
@@ -90,36 +140,109 @@ def __init__(
 
     @abc.abstractmethod
     def __enter__(self):
+        """
+        Enters a context manager and returns a transaction
+
+        :return: A transaction instance
+        """
         pass
 
     @abc.abstractmethod
     def __exit__(self, *args, **kwargs):
+        """
+        Closes a transaction context manager and rollbacks transaction if
+        it is not rolled back explicitly
+        """
         pass
 
     @property
     @abc.abstractmethod
     def session_id(self):
+        """
+        A transaction's session id
+
+        :return: A transaction's session id
+        """
         pass
 
     @property
     @abc.abstractmethod
     def tx_id(self):
+        """
+        Returns a id of open transaction or None otherwise
+
+        :return: A id of open transaction or None otherwise
+        """
         pass
 
     @abc.abstractmethod
     def begin(settings: QueryClientSettings = None):
+        """
+        Explicitly begins a transaction
+
+        :param settings: A request settings
+
+        :return: None
+        """
         pass
 
     @abc.abstractmethod
     def commit(settings: QueryClientSettings = None):
+        """
+        Calls commit on a transaction if it is open. If transaction execution
+        failed then this method raises PreconditionFailed.
+
+        :param settings: A request settings
+
+        :return: A committed transaction or exception if commit is failed
+        """
         pass
 
     @abc.abstractmethod
     def rollback(settings: QueryClientSettings = None):
+        """
+        Calls rollback on a transaction if it is open. If transaction execution
+        failed then this method raises PreconditionFailed.
+
+        :param settings: A request settings
+
+        :return: A rolled back transaction or exception if rollback is failed
+        """
         pass
 
     @abc.abstractmethod
-    def execute(query: str, commit_tx=False):
+    def execute(
+        self,
+        query: str,
+        commit_tx: bool = False,
+        tx_mode: BaseQueryTxMode = None,
+        syntax: QuerySyntax = None,
+        exec_mode: QueryExecMode = None,
+        parameters: dict = None,
+        concurrent_result_sets: bool = False,
+    ):
+        """
+        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 tx_mode: Transaction mode, which is a one from the following choises:
+         1) QuerySerializableReadWrite() which is default mode;
+         2) QueryOnlineReadOnly(allow_inconsistent_reads=False);
+         3) QuerySnapshotReadOnly();
+         4) QueryStaleReadOnly().
+        :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
+        """
         pass
 
 
@@ -132,20 +255,6 @@ def session(self) -> IQuerySession:
         pass
 
 
-class QuerySyntax(enum.IntEnum):
-    UNSPECIFIED = 0
-    YQL_V1 = 1
-    PG = 2
-
-
-class QueryExecMode(enum.IntEnum):
-    UNSPECIFIED = 0
-    PARSE = 10
-    VALIDATE = 20
-    EXPLAIN = 30
-    EXECUTE = 50
-
-
 def create_execute_query_request(
     query: str,
     session_id: str,

ydb/query/pool.py

@@ -17,10 +17,12 @@ def __init__(self, driver: base.SupportedDriverType):
         """
         :param driver: A driver instance
         """
+
         self._driver = driver
 
     def checkout(self):
         """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: RetrySettings = None, *args, **kwargs):
@@ -31,6 +33,7 @@ def retry_operation_sync(self, callee: Callable, retry_settings: RetrySettings =
 
         :return: Result sets or exception in case of execution errors.
         """
+
         retry_settings = RetrySettings() if retry_settings is None else retry_settings
 
         def wrapped_callee():
@@ -47,6 +50,7 @@ def execute_with_retries(self, query: str, retry_settings: RetrySettings = None,
 
         :return: Result sets or exception in case of execution errors.
         """
+
         retry_settings = RetrySettings() if retry_settings is None else retry_settings
         with self.checkout() as session:
 

ydb/query/session.py

@@ -181,6 +181,10 @@ def _execute_call(
 
 
 class QuerySessionSync(BaseQuerySession):
+    """Session object for Query Service. It is not recommended to control
+    session's lifecycle manually - use a QuerySessionPool is always a better choise.
+    """
+
     _stream = None
 
     def _attach(self):
@@ -214,6 +218,11 @@ def _check_session_status_loop(self, status_stream):
             pass
 
     def delete(self) -> None:
+        """
+        Deletes a Session of Query Service on server side and releases resources.
+
+        :return: None
+        """
         if self._state._already_in(QuerySessionStateEnum.CLOSED):
             return
 
@@ -222,6 +231,11 @@ def delete(self) -> None:
         self._stream.cancel()
 
     def create(self) -> "QuerySessionSync":
+        """
+        Creates a Session of Query Service on server side and attaches it.
+
+        :return: QuerySessionSync object.
+        """
         if self._state._already_in(QuerySessionStateEnum.CREATED):
             return
 
@@ -232,6 +246,17 @@ def create(self) -> "QuerySessionSync":
         return self
 
     def transaction(self, tx_mode: base.BaseQueryTxMode = None) -> base.IQueryTxContext:
+        """
+        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);
+         3) QuerySnapshotReadOnly();
+         4) QueryStaleReadOnly().
+
+        :return transaction context manager.
+
+        """
         self._state._check_session_ready_to_use()
 
         return BaseTxContext(
@@ -251,6 +276,22 @@ def execute(
         concurrent_result_sets: bool = False,
         empty_tx_control: bool = False,
     ):
+        """
+        Sends a query to Query Service
+        :param query: (YQL or SQL text) to be executed.
+        :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);
+         3) QuerySnapshotReadOnly();
+         4) QueryStaleReadOnly().
+        :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 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._state._check_session_ready_to_use()
 
         stream_it = self._execute_call(