From cdae01eac4c8da1fae3a45bf1095ba2488c752d2 Mon Sep 17 00:00:00 2001
From: Oleg Ovcharuk <vgvoleg@gmail.com>
Date: Tue, 10 Sep 2024 17:49:37 +0300
Subject: [PATCH] Add query tx modes to docs

---
 docs/apireference.rst                         | 38 +++++++++++++++++++
 .../grpcwrapper/ydb_query_public_types.py     | 22 +++++++++++
 ydb/query/__init__.py                         |  4 +-
 3 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/docs/apireference.rst b/docs/apireference.rst
index a20f7de3..f4f10cbd 100644
--- a/docs/apireference.rst
+++ b/docs/apireference.rst
@@ -128,6 +128,44 @@ QueryTxContext (AsyncIO)
     :undoc-members:
 
 
+Query Tx Mode
+^^^^^^^^^^^^^
+
+.. autoclass:: ydb.BaseQueryTxMode
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :exclude-members: name, to_proto
+
+
+.. autoclass:: ydb.QueryOnlineReadOnly
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :exclude-members: name, to_proto
+
+
+.. autoclass:: ydb.QuerySerializableReadWrite
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :exclude-members: name, to_proto
+
+
+.. autoclass:: ydb.QuerySnapshotReadOnly
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :exclude-members: name, to_proto
+
+
+.. autoclass:: ydb.QueryStaleReadOnly
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :exclude-members: name, to_proto
+
+
 ------------------------
 
 Table Service
diff --git a/ydb/_grpc/grpcwrapper/ydb_query_public_types.py b/ydb/_grpc/grpcwrapper/ydb_query_public_types.py
index d79a2967..23c3c4f9 100644
--- a/ydb/_grpc/grpcwrapper/ydb_query_public_types.py
+++ b/ydb/_grpc/grpcwrapper/ydb_query_public_types.py
@@ -11,6 +11,7 @@
 
 
 class BaseQueryTxMode(IToProto):
+    """Abstract class for Query Transaction Modes."""
     @property
     @abc.abstractmethod
     def name(self) -> str:
@@ -18,6 +19,10 @@ def name(self) -> str:
 
 
 class QuerySnapshotReadOnly(BaseQueryTxMode):
+    """All the read operations within a transaction access the database snapshot.
+    All the data reads are consistent. The snapshot is taken when the transaction begins,
+    meaning the transaction sees all changes committed before it began.
+    """
     def __init__(self):
         self._name = "snapshot_read_only"
 
@@ -30,6 +35,9 @@ def to_proto(self) -> ydb_query_pb2.SnapshotModeSettings:
 
 
 class QuerySerializableReadWrite(BaseQueryTxMode):
+    """This mode guarantees that the result of successful parallel transactions is equivalent
+    to their serial execution, and there are no read anomalies for successful transactions.
+    """
     def __init__(self):
         self._name = "serializable_read_write"
 
@@ -42,6 +50,15 @@ def to_proto(self) -> ydb_query_pb2.SerializableModeSettings:
 
 
 class QueryOnlineReadOnly(BaseQueryTxMode):
+    """Each read operation in the transaction is reading the data that is most recent at execution time.
+    The consistency of retrieved data depends on the allow_inconsistent_reads setting:
+        * false (consistent reads): Each individual read operation returns consistent data,
+          but no consistency is guaranteed between reads.
+          Reading the same table range twice may return different results.
+        * true (inconsistent reads): Even the data fetched by a particular
+          read operation may contain inconsistent results.
+    """
+
     def __init__(self, allow_inconsistent_reads: bool = False):
         self.allow_inconsistent_reads = allow_inconsistent_reads
         self._name = "online_read_only"
@@ -55,6 +72,11 @@ def to_proto(self) -> ydb_query_pb2.OnlineModeSettings:
 
 
 class QueryStaleReadOnly(BaseQueryTxMode):
+    """Read operations within a transaction may return results that are slightly out-of-date
+    (lagging by fractions of a second). Each individual read returns consistent data,
+    but no consistency between different reads is guaranteed.
+    """
+
     def __init__(self):
         self._name = "stale_read_only"
 
diff --git a/ydb/query/__init__.py b/ydb/query/__init__.py
index 7431332e..0f818789 100644
--- a/ydb/query/__init__.py
+++ b/ydb/query/__init__.py
@@ -1,10 +1,11 @@
 __all__ = [
+    "BaseQueryTxMode",
     "QueryOnlineReadOnly",
     "QuerySerializableReadWrite",
     "QuerySnapshotReadOnly",
     "QueryStaleReadOnly",
     "QuerySessionPool",
-    "QueryClientSync",
+    "QueryClientSettings",
     "QuerySession",
     "QueryTxContext",
 ]
@@ -20,6 +21,7 @@
 
 from .._grpc.grpcwrapper import common_utils
 from .._grpc.grpcwrapper.ydb_query_public_types import (
+    BaseQueryTxMode,
     QueryOnlineReadOnly,
     QuerySerializableReadWrite,
     QuerySnapshotReadOnly,