added docstrings

Author: daniel-sanche

google/cloud/bigtable/data/_async/_swappable_channel.py

@@ -95,11 +95,21 @@ def unsubscribe(self, callback):
     replace_symbols={"_AsyncWrappedChannel": "_WrappedChannel"},
 )
 class AsyncSwappableChannel(_AsyncWrappedChannel):
+    """
+    Provides a grpc channel wrapper, that allows the internal channel to be swapped out
+
+    Args:
+      - channel_fn: a nullary function that returns a new channel instance.
+            It should be a partial with all channel configuration arguments built-in
+    """
     def __init__(self, channel_fn: Callable[[], Channel]):
         self._channel_fn = channel_fn
         self._channel = channel_fn()
 
     def create_channel(self) -> Channel:
+        """
+        Create a fresh channel using the stored `channel_fn` partial
+        """
         new_channel = self._channel_fn()
         if CrossSync.is_async:
             # copy over interceptors
@@ -120,6 +130,9 @@ def create_channel(self) -> Channel:
         return new_channel
 
     def swap_channel(self, new_channel: Channel) -> Channel:
+        """
+        Replace the wrapped channel with a new instance. Typically created using `create_channel`
+        """
         old_channel = self._channel
         self._channel = new_channel
         return old_channel

google/cloud/bigtable/data/_async/client.py

@@ -245,6 +245,20 @@ def __init__(
 
     @CrossSync.convert(replace_symbols={"AsyncSwappableChannel": "SwappableChannel"})
     def _build_grpc_channel(self, *args, **kwargs) -> AsyncSwappableChannel:
+        """
+        This method is called by the gapic transport to create a grpc channel.
+
+        The init arguments passed down are captured in a partial used by AsyncSwappableChannel
+        to create new channel instances in the future, as part of the channel refresh logic
+
+        Emulators always use an inseucre channel
+
+        Args:
+          - *args: positional arguments passed by the gapic layer to create a new channel with
+          - **kwargs: keyword arguments passed by the gapic layer to create a new channel with
+        Returns:
+          a custom wrapped swappable channel
+        """
         if self._emulator_host is not None:
             # emulators use insecure channel
             create_channel_fn = partial(insecure_channel, self._emulator_host)

google/cloud/bigtable/data/_sync_autogen/_swappable_channel.py

@@ -72,15 +72,25 @@ def unsubscribe(self, callback):
 
 
 class SwappableChannel(_WrappedChannel):
+    """
+    Provides a grpc channel wrapper, that allows the internal channel to be swapped out
+
+    Args:
+      - channel_fn: a nullary function that returns a new channel instance.
+            It should be a partial with all channel configuration arguments built-in
+    """
+
     def __init__(self, channel_fn: Callable[[], Channel]):
         self._channel_fn = channel_fn
         self._channel = channel_fn()
 
     def create_channel(self) -> Channel:
+        """Create a fresh channel using the stored `channel_fn` partial"""
         new_channel = self._channel_fn()
         return new_channel
 
     def swap_channel(self, new_channel: Channel) -> Channel:
+        """Replace the wrapped channel with a new instance. Typically created using `create_channel`"""
         old_channel = self._channel
         self._channel = new_channel
         return old_channel

google/cloud/bigtable/data/_sync_autogen/client.py

@@ -179,6 +179,18 @@ def __init__(
                 )
 
     def _build_grpc_channel(self, *args, **kwargs) -> SwappableChannel:
+        """This method is called by the gapic transport to create a grpc channel.
+
+        The init arguments passed down are captured in a partial used by SwappableChannel
+        to create new channel instances in the future, as part of the channel refresh logic
+
+        Emulators always use an inseucre channel
+
+        Args:
+          - *args: positional arguments passed by the gapic layer to create a new channel with
+          - **kwargs: keyword arguments passed by the gapic layer to create a new channel with
+        Returns:
+          a custom wrapped swappable channel"""
         if self._emulator_host is not None:
             create_channel_fn = partial(insecure_channel, self._emulator_host)
         else: