added docstrings

.cross_sync/generate.py

@@ -15,6 +15,13 @@
 from typing import Sequence
 import ast
 from dataclasses import dataclass, field
+"""
+Entrypoint for initiating an async -> sync conversion using CrossSync
+
+Finds all python files rooted in a given directory, and uses
+transformers.CrossSyncClassDecoratorHandler to handle any CrossSync class
+decorators found in the files.
+"""
 
 
 @dataclass

.cross_sync/transformers.py

@@ -11,6 +11,19 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""
+Provides a set of ast.NodeTransformer subclasses that are composed to generate
+async code into sync code.
+
+At a high level:
+- The main entrypoint is CrossSyncClassDecoratorHandler, which is used to find classes
+annotated with @CrossSync.export_sync.
+- SymbolReplacer is used to swap out CrossSync.X with CrossSync._Sync_Impl.X
+- RmAioFunctions is then called on the class, to strip out asyncio keywords
+marked with CrossSync.rm_aio (using AsyncToSync to handle the actual transformation)
+- Finally, CrossSyncMethodDecoratorHandler is called to find methods annotated
+with AstDecorators, and call decorator.sync_ast_transform on each one to fully transform the class.
+"""
 from __future__ import annotations
 
 import ast

google/cloud/bigtable/data/_sync/_cross_sync/_decorators.py

@@ -11,6 +11,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""
+Contains a set of AstDecorator classes, which define the behavior of CrossSync decorators.
+Each AstDecorator class is used through @CrossSync.<decorator_name>
+"""
 from __future__ import annotations
 from typing import TYPE_CHECKING
 
@@ -23,7 +27,7 @@ class AstDecorator:
     """
     Helper class for CrossSync decorators used for guiding ast transformations.
 
-    CrossSync decorations are accessed in two ways:
+    AstDecorators are accessed in two ways:
     1. The decorations are used directly as method decorations in the async client,
         wrapping existing classes and methods
     2. The decorations are read back when processing the AST transformations when

google/cloud/bigtable/data/_sync/_cross_sync/cross_sync.py

@@ -12,6 +12,31 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+"""
+CrossSync provides a toolset for sharing logic between async and sync codebases, including:
+- A set of decorators for annotating async classes and functions 
+    (@CrossSync.export_sync, @CrossSync.convert, @CrossSync.drop_method, ...)
+- A set of wrappers to wrap common objects and types that have corresponding async and sync implementations
+    (CrossSync.Queue, CrossSync.Condition, CrossSync.Future, ...)
+- A set of function implementations for common async operations that can be used in both async and sync codebases
+    (CrossSync.gather_partials, CrossSync.wait, CrossSync.condition_wait, ...)
+- CrossSync.rm_aio(), which is used to annotate regions of the code containing async keywords to strip
+
+A separate module will use CrossSync annotations to generate a corresponding sync
+class based on a decorated async class.
+
+Usage Example:
+```python
+@CrossSync.export_sync(path="path/to/sync_module.py")
+
+    @CrossSync.convert
+    async def async_func(self, arg: int) -> int:
+        await CrossSync.sleep(1)
+        return arg
+```
+"""
+
+
 from __future__ import annotations
 
 from typing import (
@@ -223,6 +248,12 @@ def verify_async_event_loop() -> None:
 
     @staticmethod
     def rm_aio(statement: Any) -> Any:
+        """
+        Used to annotate regions of the code containing async keywords to strip
+
+        All async keywords inside an rm_aio call are removed, along with
+        `async with` and `async for` statements containing CrossSync.rm_aio() in the body
+        """
         return statement
 
     class _Sync_Impl: