Documentation

Author: Zvirovyi

src/charm.py

@@ -2,7 +2,7 @@
 # Copyright 2025 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-"""Charm the application."""
+"""Charm definiton."""
 
 import logging
 
@@ -20,7 +20,7 @@
 
 
 class CassandraCharm(TypedCharmBase[CharmConfig]):
-    """Charm the application."""
+    """Application charm."""
 
     config_type = CharmConfig
 

src/common/cassandra_client.py

@@ -16,7 +16,7 @@
 
 
 class CassandraClient:
-    """TODO."""
+    """Cassandra CQL client."""
 
     def __init__(self, hosts: list[str], user: str | None = None, password: str | None = None):
         self.execution_profile = ExecutionProfile(

src/core/config.py

@@ -2,7 +2,7 @@
 # Copyright 2025 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-"""Charm config definition."""
+"""Charm config."""
 
 from typing import Literal
 
@@ -13,15 +13,15 @@
 
 
 class CharmConfig(BaseConfigModel):
-    """Manager for the structured configuration."""
+    """Structured charm config."""
 
-    profile: ConfigProfile
     cluster_name: str
+    profile: ConfigProfile
 
     @field_validator("cluster_name")
     @classmethod
     def cluster_name_values(cls, value: str) -> str:
-        """TODO."""
+        """Validate cluster_name."""
         if len(value) == 0:
             raise ValueError("cluster_name cannot be empty")
 

src/core/state.py

@@ -2,7 +2,7 @@
 # Copyright 2025 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-"""TODO."""
+"""Application state definition."""
 
 import logging
 from enum import StrEnum
@@ -16,30 +16,36 @@
 from ops import Application, CharmBase, Object, Relation, Unit
 
 PEER_RELATION = "cassandra-peers"
-PEER_PORT = 7000
-CLIENT_PORT = 9042
+CASSANDRA_PEER_PORT = 7000
+CASSANDRA_CLIENT_PORT = 9042
 
 logger = logging.getLogger(__name__)
 
 
 class ClusterState(StrEnum):
-    """TODO."""
+    """Current state of the Cassandra cluster."""
 
     UNKNOWN = ""
+    """Cassandra cluster isn't yet initialized by the leader unit."""
     ACTIVE = "active"
+    """Cassandra cluster is initialized by the leader unit and active."""
 
 
 class UnitWorkloadState(StrEnum):
-    """TODO."""
+    """Current state of the Cassandra workload."""
 
     INSTALLING = ""
+    """Cassandra is installing."""
     WAITING_FOR_START = "waiting_for_start"
+    """Subordinate unit is waiting for leader to initialize cluster before it starts workload."""
     STARTING = "starting"
+    """Cassandra is starting."""
     ACTIVE = "active"
+    """Cassandra is active and ready."""
 
 
 class RelationState:
-    """Relation state object."""
+    """Basic class for relation bag mapping classes."""
 
     def __init__(
         self,
@@ -54,9 +60,8 @@ def __init__(
 
     def _field_setter_wrapper(self, field: str, value: str) -> None:
         if not self.relation:
-            logger.warning(
-                f"Field `{field}` were attempted to\
-                be written on the relation before it exists."
+            logger.error(
+                f"Field `{field}` were attempted to be written on the relation before it exists."
             )
             return
 
@@ -70,7 +75,10 @@ def _field_setter_wrapper(self, field: str, value: str) -> None:
 
 
 class UnitContext(RelationState):
-    """State/Relation data collection for a unit."""
+    """Unit context of the application state.
+
+    Provides mappings for the unit data bag of peer relation.
+    """
 
     def __init__(
         self,
@@ -88,14 +96,9 @@ def unit_id(self) -> int:
 
     @property
     def unit_name(self) -> str:
-        """The id of the unit from the unit name."""
+        """Unit name."""
         return self.unit.name
 
-    @property
-    def node_name(self) -> str:
-        """The Human-readable name for this cassandra cluster node."""
-        return f"{self.unit.app.name}{self.unit_id}"
-
     @property
     def hostname(self) -> str:
         """The hostname for the unit."""
@@ -116,17 +119,17 @@ def ip(self, value: str) -> None:
 
     @property
     def peer_url(self) -> str:
-        """The peer connection endpoint for the cassandra server."""
-        return f"{self.ip}:{PEER_PORT}"
+        """The internode connection endpoint for the cassandra server from unit IP."""
+        return f"{self.ip}:{CASSANDRA_PEER_PORT}"
 
     @property
     def client_url(self) -> str:
-        """The client connection endpoint for the cassandra server."""
-        return f"{self.ip}:{CLIENT_PORT}"
+        """The client connection endpoint for the cassandra server from unit IP."""
+        return f"{self.ip}:{CASSANDRA_CLIENT_PORT}"
 
     @property
     def workload_state(self) -> UnitWorkloadState:
-        """TODO."""
+        """Current state of the Cassandra workload."""
         return self.relation_data.get("workload_state", UnitWorkloadState.INSTALLING)
 
     @workload_state.setter
@@ -135,7 +138,10 @@ def workload_state(self, value: UnitWorkloadState) -> None:
 
 
 class ClusterContext(RelationState):
-    """State/Relation data collection for the cassandra application."""
+    """Cluster context of the application state.
+
+    Provides mappings for the application data bag of peer relation.
+    """
 
     def __init__(
         self,
@@ -148,7 +154,7 @@ def __init__(
 
     @property
     def seeds(self) -> list[str]:
-        """TODO."""
+        """List of peer urls of Cassandra seed nodes."""
         seeds = self.relation_data.get("seeds", "")
         return seeds.split(",") if seeds else []
 
@@ -158,22 +164,21 @@ def seeds(self, value: list[str]) -> None:
 
     @property
     def state(self) -> ClusterState:
-        """The cluster state ('new' or 'existing') of the cassandra cluster."""
+        """Current state of the Cassandra cluster."""
         return self.relation_data.get("cluster_state", ClusterState.UNKNOWN)
 
     @state.setter
     def state(self, value: ClusterState) -> None:
-        """TODO."""
         self._field_setter_wrapper("cluster_state", value.value)
 
     @property
     def is_active(self) -> bool:
-        """TODO."""
+        """Is Cassandra cluster state `ACTIVE`."""
         return self.state == ClusterState.ACTIVE
 
 
 class ApplicationState(Object):
-    """Global state object for the cassandra cluster."""
+    """Mappings for the charm relations that forms global application state."""
 
     def __init__(self, charm: CharmBase):
         super().__init__(parent=charm, key="charm_state")
@@ -185,12 +190,12 @@ def __init__(self, charm: CharmBase):
 
     @property
     def peer_relation(self) -> Relation | None:
-        """Get the cluster peer relation."""
+        """Cluster peer relation."""
         return self.model.get_relation(PEER_RELATION)
 
     @property
     def peer_relation_units(self) -> dict[Unit, DataPeerOtherUnitData]:
-        """Get unit data interface of all peer units from the cluster peer relation."""
+        """Unit data interface of all units in the cluster peer relation."""
         if not self.peer_relation or not self.peer_relation.units:
             return {}
 
@@ -201,7 +206,7 @@ def peer_relation_units(self) -> dict[Unit, DataPeerOtherUnitData]:
 
     @property
     def cluster(self) -> ClusterContext:
-        """Get the cluster context of the entire cassandra application."""
+        """Cluster context."""
         return ClusterContext(
             relation=self.peer_relation,
             data_interface=self.peer_app_interface,
@@ -210,7 +215,7 @@ def cluster(self) -> ClusterContext:
 
     @property
     def unit(self) -> UnitContext:
-        """Get the server state of this unit."""
+        """This unit context."""
         return UnitContext(
             relation=self.peer_relation,
             data_interface=self.peer_unit_interface,
@@ -219,24 +224,17 @@ def unit(self) -> UnitContext:
 
     @property
     def units(self) -> set[UnitContext]:
-        """Get all nodes/units in the current peer relation, including this unit itself.
-
-        Note: This is not to be confused with the list of cluster members.
-
-        Returns:
-            Set of CassandraUnitContexts with their unit data.
-        """
-        if not self.peer_relation:
-            return set()
+        """Contexts of all the units in the cluster peer relation, including this unit itself."""
+        return {self.unit, *self.other_units}
 
+    @property
+    def other_units(self) -> set[UnitContext]:
+        """Contexts of other units in the cluster peer relation."""
         return {
-            self.unit,
-            *(
-                UnitContext(
-                    relation=self.peer_relation,
-                    data_interface=data_interface,
-                    component=unit,
-                )
-                for unit, data_interface in self.peer_relation_units.items()
-            ),
+            UnitContext(
+                relation=self.peer_relation,
+                data_interface=data_interface,
+                component=unit,
+            )
+            for unit, data_interface in self.peer_relation_units.items()
         }

src/core/statuses.py

@@ -2,7 +2,7 @@
 # Copyright 2025 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-"""TODO."""
+"""Charm statuses."""
 
 from enum import Enum
 

src/core/workload.py

@@ -2,7 +2,7 @@
 # Copyright 2025 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-"""TODO."""
+"""Workload definition."""
 
 from abc import ABC, abstractmethod
 from typing import Literal

src/workload.py

@@ -2,7 +2,7 @@
 # Copyright 2025 Canonical Ltd.
 # See LICENSE file for licensing details.
 
-"""TODO."""
+"""Workload VM Implementation."""
 
 import logging
 import subprocess