added docstrings

Author: Andrei Neagu

services/dynamic-sidecar/src/simcore_service_dynamic_sidecar/api/rest/containers.py

@@ -64,11 +64,13 @@ async def containers_docker_inspect(
     )
 
 
-@router.get(
-    "/containers/activity",
-)
+@router.get("/containers/activity")
 @cancel_on_disconnect
 async def get_containers_activity(request: Request) -> ActivityInfoOrNone:
+    """
+    If user service declared an inactivity hook, this enpoint provides
+    inforamtion about how much time has passed since the service became inactive.
+    """
     _ = request
     return await containers.get_containers_activity(app=request.app)
 

services/dynamic-sidecar/src/simcore_service_dynamic_sidecar/api/rpc/_containers.py

@@ -19,6 +19,9 @@ async def create_compose_spec(
     *,
     containers_compose_spec: ContainersComposeSpec,
 ) -> None:
+    """
+    Validates and stores the docker compose spec for the user services.
+    """
     await containers.create_compose_spec(
         app, containers_compose_spec=containers_compose_spec
     )
@@ -28,19 +31,38 @@ async def create_compose_spec(
 async def containers_docker_inspect(
     app: FastAPI, *, only_status: bool
 ) -> dict[str, Any]:
+    """
+    Returns entire docker inspect data, if only_state is True,
+    the status of the containers is returned
+    """
     return await containers.containers_docker_inspect(app, only_status=only_status)
 
 
 @router.expose()
 async def get_containers_activity(app: FastAPI) -> ActivityInfoOrNone:
+    """
+    If user service declared an inactivity hook, this enpoint provides
+    inforamtion about how much time has passed since the service became inactive.
+    """
     return await containers.get_containers_activity(app=app)
 
 
 @router.expose()
 async def get_containers_name(app: FastAPI, *, filters: str) -> str | dict[str, Any]:
+    """
+    Searches for the container's name given the network
+    on which the proxy communicates with it.
+    Supported filters:
+        network: matches against the exact network name
+            assigned to the container; `will include`
+            containers
+        exclude: matches if contained in the name of the
+            container; `will exclude` containers
+    """
     return await containers.get_containers_name(app=app, filters=filters)
 
 
 @router.expose()
 async def inspect_container(app: FastAPI, *, container_id: str) -> dict[str, Any]:
+    """Returns information about the container, like docker inspect command"""
     return await containers.inspect_container(app=app, container_id=container_id)

services/dynamic-sidecar/src/simcore_service_dynamic_sidecar/api/rpc/_containers_extension.py

@@ -11,6 +11,7 @@
 async def toggle_ports_io(
     app: FastAPI, *, enable_outputs: bool, enable_inputs: bool
 ) -> None:
+    """Enable/disable ports i/o"""
     await container_extensions.toggle_ports_io(
         app, enable_outputs=enable_outputs, enable_inputs=enable_inputs
     )
@@ -20,13 +21,20 @@ async def toggle_ports_io(
 async def create_output_dirs(
     app: FastAPI, *, outputs_labels: dict[str, ServiceOutput]
 ) -> None:
+    """
+    Creates the output directories declared by the docker images's labels.
+    It is more convenient to pass the labels from director-v2,
+    since it already has all the machinery to call into director-v0
+    to retrieve them.
+    """
     await container_extensions.create_output_dirs(app, outputs_labels=outputs_labels)
 
 
 @router.expose()
 async def attach_container_to_network(
     app: FastAPI, *, container_id: str, network_id: str, network_aliases: list[str]
 ) -> None:
+    """attach container to a network, if not already attached"""
     _ = app
     await container_extensions.attach_container_to_network(
         container_id=container_id,
@@ -39,6 +47,7 @@ async def attach_container_to_network(
 async def detach_container_from_network(
     app: FastAPI, *, container_id: str, network_id: str
 ) -> None:
+    """detach container from a network, if not already detached"""
     _ = app
     await container_extensions.detach_container_from_network(
         container_id=container_id, network_id=network_id

services/dynamic-sidecar/src/simcore_service_dynamic_sidecar/api/rpc/_containers_long_running_tasks.py

@@ -13,6 +13,7 @@
 async def pull_user_services_images(
     app: FastAPI, *, lrt_namespace: LRTNamespace
 ) -> TaskId:
+    """Pulls all the docker container images for the user services"""
     rpc_client = get_rabbitmq_rpc_client(app)
     return await containers_long_running_tasks.pull_user_services_images(
         rpc_client, lrt_namespace
@@ -23,6 +24,14 @@ async def pull_user_services_images(
 async def create_user_services(
     app: FastAPI, *, lrt_namespace: LRTNamespace, containers_create: ContainersCreate
 ) -> TaskId:
+    """
+    Starts the containers as defined in ContainerCreate by:
+    - cleaning up resources from previous runs if any
+    - starting the containers
+
+    Progress may be obtained through URL
+    Process may be cancelled through URL
+    """
     rpc_client = get_rabbitmq_rpc_client(app)
     return await containers_long_running_tasks.create_user_services(
         rpc_client, lrt_namespace, containers_create
@@ -31,6 +40,7 @@ async def create_user_services(
 
 @router.expose()
 async def remove_user_services(app: FastAPI, *, lrt_namespace: LRTNamespace) -> TaskId:
+    """Remove the previously started containers"""
     rpc_client = get_rabbitmq_rpc_client(app)
     return await containers_long_running_tasks.remove_user_services(
         rpc_client, lrt_namespace
@@ -41,6 +51,7 @@ async def remove_user_services(app: FastAPI, *, lrt_namespace: LRTNamespace) ->
 async def restore_user_services_state_paths(
     app: FastAPI, *, lrt_namespace: LRTNamespace
 ) -> TaskId:
+    """Restores the state of the dynamic service"""
     rpc_client = get_rabbitmq_rpc_client(app)
     return await containers_long_running_tasks.restore_user_services_state_paths(
         rpc_client, lrt_namespace
@@ -51,6 +62,7 @@ async def restore_user_services_state_paths(
 async def save_user_services_state_paths(
     app: FastAPI, *, lrt_namespace: LRTNamespace
 ) -> TaskId:
+    """Stores the state of the dynamic service"""
     rpc_client = get_rabbitmq_rpc_client(app)
     return await containers_long_running_tasks.save_user_services_state_paths(
         rpc_client, lrt_namespace
@@ -64,6 +76,7 @@ async def pull_user_services_input_ports(
     lrt_namespace: LRTNamespace,
     port_keys: list[str] | None,
 ) -> TaskId:
+    """Pull input ports data"""
     rpc_client = get_rabbitmq_rpc_client(app)
     return await containers_long_running_tasks.pull_user_services_input_ports(
         rpc_client, lrt_namespace, port_keys
@@ -77,6 +90,7 @@ async def pull_user_services_output_ports(
     lrt_namespace: LRTNamespace,
     port_keys: list[str] | None,
 ) -> TaskId:
+    """Pull output ports data"""
     rpc_client = get_rabbitmq_rpc_client(app)
     return await containers_long_running_tasks.pull_user_services_output_ports(
         rpc_client, lrt_namespace, port_keys
@@ -87,6 +101,7 @@ async def pull_user_services_output_ports(
 async def push_user_services_output_ports(
     app: FastAPI, *, lrt_namespace: LRTNamespace
 ) -> TaskId:
+    """Push output ports data"""
     rpc_client = get_rabbitmq_rpc_client(app)
     return await containers_long_running_tasks.push_user_services_output_ports(
         rpc_client, lrt_namespace
@@ -95,6 +110,7 @@ async def push_user_services_output_ports(
 
 @router.expose()
 async def restart_user_services(app: FastAPI, *, lrt_namespace: LRTNamespace) -> TaskId:
+    """Restarts previously started user services"""
     rpc_client = get_rabbitmq_rpc_client(app)
     return await containers_long_running_tasks.restart_user_services(
         rpc_client, lrt_namespace

services/dynamic-sidecar/src/simcore_service_dynamic_sidecar/api/rpc/_disk.py

@@ -8,4 +8,5 @@
 
 @router.expose()
 async def free_reserved_disk_space(_: FastAPI) -> None:
+    """Frees up reserved disk space"""
     disk.free_reserved_disk_space()

services/dynamic-sidecar/src/simcore_service_dynamic_sidecar/api/rpc/_disk_usage.py

@@ -15,6 +15,10 @@
 @router.expose()
 @validate_call(config={"arbitrary_types_allowed": True})
 async def update_disk_usage(app: FastAPI, *, usage: dict[str, DiskUsage]) -> None:
+    """
+    Updates the report disk usage to the forntend via external tooling.
+    Used by the efs guardian.
+    """
     disk_usage_monitor = get_disk_usage_monitor(app)
 
     if disk_usage_monitor is None:

services/dynamic-sidecar/src/simcore_service_dynamic_sidecar/api/rpc/_volumes.py

@@ -13,4 +13,5 @@
 async def update_volume_status(
     app: FastAPI, *, status: VolumeStatus, category: VolumeCategory
 ) -> None:
+    """Updates the state of the volume"""
     await volumes.update_volume_status(app, status=status, category=category)