Documentation.

Author: Zvirovyi

src/core/state.py

@@ -173,7 +173,7 @@ def state(self, value: ClusterState) -> None:
 
     @property
     def is_active(self) -> bool:
-        """Is Cassandra cluster state `ACTIVE`."""
+        """Whether Cassandra cluster state is `ACTIVE`."""
         return self.state == ClusterState.ACTIVE
 
 

src/core/workload.py

@@ -13,104 +13,85 @@
 
 
 class CassandraPaths:
-    """TODO."""
+    """Filesystem paths of the Cassandra workload."""
 
     env: pathops.PathProtocol
     config_dir: pathops.PathProtocol
     data_dir: pathops.PathProtocol
 
     @property
     def config(self) -> pathops.PathProtocol:
-        """TODO."""
+        """Main config file."""
         return self.config_dir / "cassandra.yaml"
 
     @property
     def commitlog_directory(self) -> pathops.PathProtocol:
-        """TODO."""
+        """Commitlog data directory."""
         return self.data_dir / "commitlog"
 
     @property
     def data_file_directory(self) -> pathops.PathProtocol:
-        """TODO."""
+        """Main data directory."""
         return self.data_dir / "data"
 
     @property
     def hints_directory(self) -> pathops.PathProtocol:
-        """TODO."""
+        """Hints data directory."""
         return self.data_dir / "hints"
 
     @property
     def saved_caches_directory(self) -> pathops.PathProtocol:
-        """TODO."""
+        """Saved caches data directory."""
         return self.data_dir / "saved_caches"
 
 
 class WorkloadBase(ABC):
-    """Base interface for common workload operations."""
+    """Base interface for workload operations."""
 
     substrate: Substrate
     cassandra_paths: CassandraPaths
 
     @abstractmethod
     def start(self) -> None:
-        """Start the workload service."""
+        """Start Cassandra service."""
         pass
 
     @abstractmethod
     def install(self) -> None:
-        """Install the cassandra snap."""
+        """Install Cassandra."""
         pass
 
     @abstractmethod
-    def alive(self) -> bool:
-        """Check if the workload is running.
-
-        Returns:
-            bool: True if the workload is running, False otherwise.
-        """
+    def is_alive(self) -> bool:
+        """Whether Cassandra service running."""
         pass
 
     @abstractmethod
     def stop(self) -> None:
-        """Stop the workload service."""
+        """Stop Cassandra service."""
         pass
 
     @abstractmethod
     def restart(self) -> None:
-        """Restart the workload service."""
+        """Restart Cassandra service."""
         pass
 
     @abstractmethod
     def remove_file(self, file: str) -> None:
-        """Remove a file.
-
-        Args:
-            file (str): Path to the file.
-        """
+        """Remove file."""
         pass
 
     @abstractmethod
     def remove_directory(self, directory: str) -> None:
-        """Remove a directory.
-
-        Args:
-            directory (str): Path to the directory.
-        """
+        """Remove directory recursively."""
         pass
 
     @abstractmethod
     def path_exists(self, path: str) -> bool:
-        """Check if a file or directory exists.
-
-        Args:
-            path (str): Path to the file or directory.
-
-        Returns:
-            bool: True if the file or directory exists, False otherwise.
-        """
+        """Check if file or directory exists."""
         pass
 
     @abstractmethod
     def exec(self, command: list[str], suppress_error_log: bool = False) -> tuple[str, str]:
-        """Run a command on the workload substrate."""
+        """Execute command."""
         pass

src/events/cassandra.py

@@ -2,7 +2,7 @@
 # Copyright 2025 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-"""TODO."""
+"""Handler for main Cassandra charm events."""
 
 import logging
 
@@ -28,7 +28,7 @@
 
 
 class CassandraEvents(Object):
-    """Handle all base and cassandra related events."""
+    """Handler for main Cassandra charm events."""
 
     def __init__(
         self,
@@ -152,7 +152,11 @@ def _on_collect_app_status(self, event: CollectStatusEvent) -> None:
         event.add_status(Status.ACTIVE.value)
 
     def _update_network_address(self) -> bool:
-        """TODO."""
+        """Update hostname & ip in this unit context.
+
+        Returns:
+            whether the hostname or ip changed.
+        """
         old_ip = self.state.unit.ip
         old_hostname = self.state.unit.hostname
         self.state.unit.ip, self.state.unit.hostname = self.cluster_manager.network_address()

src/managers/cluster.py

@@ -2,7 +2,7 @@
 # Copyright 2025 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-"""TODO."""
+"""Cluster manager."""
 
 import logging
 import socket
@@ -16,22 +16,22 @@
 
 
 class ClusterManager:
-    """Manage cluster members, quorum and authorization."""
+    """Manager of Cassandra cluster, including this unit."""
 
     def __init__(self, workload: WorkloadBase):
         self._workload = workload
         pass
 
     @property
     def is_healthy(self) -> bool:
-        """TODO."""
+        """Whether Cassandra healthy and ready in this unit."""
         try:
             stdout, _ = self._workload.exec([_NODETOOL, "info"], suppress_error_log=True)
             return "Native Transport active: true" in stdout
         except ExecError:
             return False
 
     def network_address(self) -> tuple[str, str]:
-        """TODO."""
+        """Get hostname and IP of this unit."""
         hostname = socket.gethostname()
         return socket.gethostbyname(hostname), hostname

src/managers/config.py

@@ -2,7 +2,7 @@
 # Copyright 2025 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-"""Manager for handling configuration building + writing."""
+"""Config manager."""
 
 import logging
 from typing import Iterable
@@ -15,7 +15,7 @@
 
 
 class ConfigManager:
-    """Handle the configuration of Cassandra."""
+    """Manager of config files."""
 
     def __init__(
         self,
@@ -26,7 +26,7 @@ def __init__(
     def render_cassandra_config(
         self, cluster_name: str, listen_address: str, seeds: list[str]
     ) -> None:
-        """TODO."""
+        """Generate and write cassandra config."""
         config = {
             "allocate_tokens_for_local_replication_factor": 3,
             "authenticator": "AllowAllAuthenticator",
@@ -87,7 +87,7 @@ def render_cassandra_config(
         )
 
     def render_env(self, cassandra_limit_memory_mb: int | None) -> None:
-        """TODO."""
+        """Update environment config."""
         self.workload.cassandra_paths.env.write_text(
             self._render_env(
                 [

src/workload.py

@@ -51,7 +51,6 @@ def start(self) -> None:
 
     @override
     def install(self) -> None:
-        """Install the cassandra snap."""
         logger.debug("Installing & configuring Cassandra snap")
         self._cassandra_snap.ensure(snap.SnapState.Present, revision=SNAP_REVISION)
         self._cassandra_snap.connect("process-control")
@@ -60,7 +59,7 @@ def install(self) -> None:
         self._cassandra_snap.hold()
 
     @override
-    def alive(self) -> bool:
+    def is_alive(self) -> bool:
         try:
             return bool(self._cassandra_snap.services[SNAP_SERVICE]["active"])
         except KeyError: