chore: update docstrings

Author: fstagni

.github/workflows/update_chart_version.py

@@ -101,7 +101,7 @@ def update_values_yaml(values_path: Path, diracx_version: str) -> None:
 
 
 def main() -> None:
-    """Main function."""
+    """Run the Main."""
     parser = argparse.ArgumentParser(
         description="Update chart versions for DiracX release"
     )

diracx-core/src/diracx/core/config/sources.py

@@ -1,4 +1,4 @@
-"""This module implements the logic of the configuration server side.
+"""Module to implement the logic of the configuration server side.
 
 This is where all the backend abstraction and the caching logic takes place.
 """
@@ -44,7 +44,7 @@ def is_running_in_async_context():
 
 
 def _apply_default_scheme(value: str) -> str:
-    """Applies the default git+file:// scheme if not present."""
+    """Apply the default git+file:// scheme if not present."""
     if isinstance(value, str) and "://" not in value:
         value = f"git+file://{value}"
     return value
@@ -88,14 +88,18 @@ def __init__(self, *, backend_url: ConfigSourceUrl) -> None:
 
     @abstractmethod
     def latest_revision(self) -> tuple[str, datetime]:
-        """Must return:
+        """Abstract method.
+
+        Must return:
         * a unique hash as a string, representing the last version
         * a datetime object corresponding to when the version dates.
         """
 
     @abstractmethod
     def read_raw(self, hexsha: str, modified: datetime) -> Config:
-        """Return the Config object that corresponds to the
+        """Abstract method.
+
+        Return the Config object that corresponds to the
         specific hash
         The `modified` parameter is just added as a attribute to the config.
         """
@@ -114,10 +118,7 @@ def create(cls):
     def create_from_url(
         cls, *, backend_url: ConfigSourceUrl | Path | str
     ) -> "ConfigSource":
-        """Factory method to produce a concrete instance depending on
-        the backend URL scheme.
-
-        """
+        """Produce a concrete instance depending on the backend URL scheme."""
         url = TypeAdapter(ConfigSourceUrl).validate_python(str(backend_url))
         return cls.__registry[url.scheme](backend_url=url)
 
@@ -234,7 +235,8 @@ def get_git_branch_from_url(self, backend_url: ConfigSourceUrl) -> str:
 
 
 class LocalGitConfigSource(BaseGitConfigSource):
-    """The configuration is stored on a local git repository
+    """The configuration is stored on a local git repository.
+
     When running on multiple servers, the filesystem must be shared.
     """
 

diracx-core/src/diracx/core/extensions.py

@@ -63,7 +63,7 @@ def select_from_extension(*, group: str, name: str | None = None) -> list[EntryP
 def supports_extending(
     group: str, name: str
 ) -> Callable[[Callable[P, T]], Callable[P, T]]:
-    """Decorator to replace a function with an extension implementation.
+    """Replace a function with an extension implementation.
 
     This decorator looks for an entry point in the specified group and name,
     and if found, replaces the decorated function with the extension's implementation.

diracx-core/src/diracx/core/models.py

@@ -1,6 +1,6 @@
-"""Models are used to define the data structure of the requests and responses
-for the DiracX API. They are shared between the client components (cli, api) and
-services components (db, logic, routers).
+"""Models used to define the data structure of the requests and responses for the DiracX API.
+
+They are shared between the client components (cli, api) and services components (db, logic, routers).
 """
 
 from __future__ import annotations

diracx-core/src/diracx/core/preferences.py

@@ -58,5 +58,5 @@ def validate_log_level(cls, v: str):
 
 @lru_cache(maxsize=1)
 def get_diracx_preferences() -> DiracxPreferences:
-    """Caches the preferences."""
+    """Cache the preferences."""
     return DiracxPreferences()

diracx-core/src/diracx/core/properties.py

@@ -1,6 +1,4 @@
-"""Just listing the possible Properties
-This module contains list of Properties that can be assigned to users and groups.
-"""
+"""Module containing the list of Properties that can be assigned to users and groups."""
 
 from __future__ import annotations
 

diracx-core/src/diracx/core/settings.py

@@ -107,7 +107,7 @@ def __init__(self, data: str):
 
 
 def _apply_default_scheme(value: str) -> str:
-    """Applies the default file:// scheme if not present."""
+    """Apply the default file:// scheme if not present."""
     if isinstance(value, str) and "://" not in value:
         value = f"file://{value}"
     return value
@@ -125,7 +125,7 @@ def create(cls) -> Self:
 
     @contextlib.asynccontextmanager
     async def lifetime_function(self) -> AsyncIterator[None]:
-        """A context manager that can be used to run code at startup and shutdown."""
+        """Context manager to run code at startup and shutdown."""
         yield
 
 

diracx-core/src/diracx/core/utils.py

@@ -237,7 +237,7 @@ def get(self, key: str, populate_func: Callable[[], T], blocking: bool = True) -
         raise NotReadyError(f"Cache key {key} is not ready yet.")
 
     def _work(self, key: str, populate_func: Callable[[], Any]) -> None:
-        """Internal method to execute the populate_func and update caches.
+        """Execute the populate_func and update caches.
 
         This method is intended to be run in a separate thread. It calls the
         populate_func, stores the result in both caches, and cleans up the

diracx-db/src/diracx/db/os/utils.py

@@ -30,7 +30,7 @@ class OpenSearchDBUnavailableError(DBUnavailableError, OpenSearchDBError):
 
 
 class BaseOSDB(metaclass=ABCMeta):
-    """This should be the base class of all the OpenSearch DiracX DBs.
+    """Base class of all the OpenSearch DiracX DBs.
 
     The details covered here should be handled automatically by the service and
     task machinery of DiracX and this documentation exists for informational
@@ -121,26 +121,19 @@ def available_urls(cls) -> dict[str, dict[str, Any]]:
 
     @classmethod
     def session(cls) -> Self:
-        """This is just a fake method such that the Dependency overwrite has
-        a hash to use.
-        """
+        """Fake method such that the Dependency overwrite has a hash to use."""
         raise NotImplementedError("This should never be called")
 
     @property
     def client(self) -> AsyncOpenSearch:
-        """Just a getter for _client, making sure we entered
-        the context manager.
-        """
+        """Just a getter for _client, making sure we entered the context manager."""
         if self._client is None:
             raise RuntimeError(f"{self.__class__} was used before entering")
         return self._client
 
     @contextlib.asynccontextmanager
     async def client_context(self) -> AsyncIterator[None]:
-        """Context manage to manage the client lifecycle.
-        This is called when starting fastapi.
-
-        """
+        """Context manager to manage the client lifecycle. This is called when starting fastapi."""
         assert self._client is None, "client_context cannot be nested"
         async with AsyncOpenSearch(**self._connection_kwargs) as self._client:
             try:
@@ -150,6 +143,7 @@ async def client_context(self) -> AsyncIterator[None]:
 
     async def ping(self):
         """Check whether the connection to the DB is still working.
+
         We could enable the ``pre_ping`` in the engine, but this would
         be ran at every query.
         """
@@ -159,7 +153,8 @@ async def ping(self):
             )
 
     async def __aenter__(self):
-        """This is entered on every request.
+        """Entered on every request.
+
         At the moment it does nothing, however, we keep it here
         in case we ever want to use OpenSearch equivalent of a transaction.
         """

diracx-db/src/diracx/db/sql/auth/db.py

@@ -38,7 +38,9 @@ class AuthDB(BaseSQLDB):
 
     @classmethod
     async def post_create(cls, conn: AsyncConnection) -> None:
-        """Create partitions if it is a MySQL DB and it does not have
+        """Create partitions.
+
+        If it is a MySQL DB and it does not have
         it yet and the table does not have any data yet.
         We do this as a post_create step as sqlalchemy does not support
         partition so well.
@@ -115,7 +117,7 @@ async def device_flow_validate_user_code(
         return (await self.conn.execute(stmt)).scalar_one()
 
     async def get_device_flow(self, device_code: str):
-        """:raises: NoResultFound"""
+        """raise: NoResultFound."""
         # The with_for_update
         # prevents that the token is retrieved
         # multiple time concurrently
@@ -137,7 +139,7 @@ async def update_device_flow_status(
     async def device_flow_insert_id_token(
         self, user_code: str, id_token: dict[str, str], max_validity: int
     ) -> None:
-        """:raises: AuthorizationError if no such code or status not pending"""
+        """raise: AuthorizationError if no such code or status not pending."""
         stmt = update(DeviceFlows)
         stmt = stmt.where(
             DeviceFlows.user_code == user_code,
@@ -211,7 +213,8 @@ async def insert_authorization_flow(
     async def authorization_flow_insert_id_token(
         self, uuid: str, id_token: dict[str, str], max_validity: int
     ) -> tuple[str, str]:
-        """Returns code, redirect_uri
+        """Return code, redirect_uri.
+
         :raises: AuthorizationError if no such uuid or status not pending.
         """
         # Hash the code to avoid leaking information
@@ -268,8 +271,9 @@ async def insert_refresh_token(
         subject: str,
         scope: str,
     ) -> None:
-        """Insert a refresh token in the DB as well as user attributes
-        required to generate access tokens.
+        """Insert a refresh token in the DB.
+
+        As well as user attributes required to generate access tokens.
         """
         # Insert values into the DB
         stmt = insert(RefreshTokens).values(