smabacc: document protocol methods

Add docststrings to various protocol types. Some are a bit vague as
these are protocols not concrete types.

Signed-off-by: John Mulligan <[email protected]>

Author: phlogistonjohn

sambacc/config.py

@@ -193,10 +193,14 @@ def read_config_files(
 
 
 class SambaConfig(typing.Protocol):
+    """Minimal samba configuration protocol."""
+
     def global_options(self) -> typing.Iterable[typing.Tuple[str, str]]:
+        """Return global options for Samba."""
         ...  # pragma: no cover
 
     def shares(self) -> typing.Iterable[ShareConfig]:
+        """Return share configurations for Samba."""
         ...  # pragma: no cover
 
 

sambacc/ctdb.py

@@ -40,18 +40,25 @@
 
 
 class ClusterMetaObject(typing.Protocol):
+    "A Cluster Meta Object can load or dump persistent cluster descriptions."
+
     def load(self) -> typing.Any:
-        ...
+        """Load a JSON-compatible object."""
+        ...  # pragma: no cover
 
     def dump(self, data: typing.Any) -> None:
-        ...
+        """Dump (save) a JSON-compatible object."""
+        ...  # pragma: no cover
 
 
 class ClusterMeta(typing.Protocol):
+    """ClusterMeta manages access to persistent cluster descriptions."""
+
     def open(
         self, *, read: bool = True, write: bool = False, locked: bool = False
     ) -> typing.ContextManager[ClusterMetaObject]:
-        ...
+        """Return a context manager with access to a cluster meta object."""
+        ...  # pragma: no cover
 
 
 class NodeState(str, enum.Enum):

sambacc/leader.py

@@ -25,6 +25,7 @@ class LeaderStatus(typing.Protocol):
     """Fetches information about the current cluster leader."""
 
     def is_leader(self) -> bool:
+        """Return true if the current node is the leader."""
         ...  # pragma: no cover
 
 
@@ -35,9 +36,11 @@ class LeaderLocator(typing.Protocol):
     """
 
     def __enter__(self) -> LeaderStatus:
+        """Enter context manager. Returns LeaderStatus."""
         ...  # pragma: no cover
 
     def __exit__(
         self, exc_type: ExcType, exc_val: ExcValue, exc_tb: ExcTraceback
     ) -> bool:
+        """Exit context manager."""
         ...  # pragma: no cover

sambacc/opener.py

@@ -29,6 +29,7 @@ class Opener(typing.Protocol):
     """
 
     def open(self, path_or_uri: str) -> typing.IO:
+        """Open a specified resource by path or (pseudo) URI."""
         ...  # pragma: no cover
 
 

sambacc/simple_waiter.py

@@ -66,6 +66,7 @@ class Waiter(typing.Protocol):
     """Waiter protocol - interfaces common to all waiters."""
 
     def wait(self) -> None:
+        """Pause execution for a time."""
         ...  # pragma: no cover
 
     def acted(self) -> None:

sambacc/smbconf_api.py

@@ -21,12 +21,15 @@
 
 class ConfigStore(typing.Protocol):
     def __getitem__(self, name: str) -> list[tuple[str, str]]:
+        """Get an item, returning a config section."""
         ...  # pragma: no cover
 
     def __setitem__(self, name: str, value: list[tuple[str, str]]) -> None:
+        """Set a new config section."""
         ...  # pragma: no cover
 
     def __iter__(self) -> typing.Iterator[str]:
+        """Iterate over config sections in the store."""
         ...  # pragma: no cover