fractal-server 2.17.1a0__py3-none-any.whl → 2.17.2__py3-none-any.whl

fractal_server/app/schemas/v2/resource.py

@@ -7,8 +7,8 @@ from typing import Self
 from pydantic import AfterValidator
 from pydantic import BaseModel
 from pydantic import Discriminator
-from pydantic import model_validator
 from pydantic import Tag
+from pydantic import model_validator
 from pydantic import validate_call
 from pydantic.types import AwareDatetime
 
@@ -21,23 +21,46 @@ from fractal_server.types import NonEmptyStr
 
 
 class ResourceType(StrEnum):
+    """
+    Enum for the possible resource types.
+    """
+
     SLURM_SUDO = "slurm_sudo"
+    """
+    Enum entry for resource type `slurm_sudo`.
+    """
+
     SLURM_SSH = "slurm_ssh"
+    """
+    Enum entry for resource type `slurm_ssh`.
+    """
+
     LOCAL = "local"
+    """
+    Enum entry for resource type `local`.
+    """
 
 
 def cast_serialize_pixi_settings(
-    v: dict[NonEmptyStr, Any],
+    value: dict[NonEmptyStr, Any],
 ) -> dict[NonEmptyStr, Any]:
     """
-    Validate current value, and enrich it with default values.
+    Cast/serialize round trip for `tasks_pixi_config` through the
+    `TasksPixiSettings` schema.
+
+    Arguments:
+        value: Current `tasks_pixi_config` value.
     """
-    if v != {}:
-        v = TasksPixiSettings(**v).model_dump()
-    return v
+    if value != {}:
+        value = TasksPixiSettings(**value).model_dump()
+    return value
 
 
-class _ValidResourceBase(BaseModel):
+class ValidResourceBase(BaseModel):
+    """
+    Base resource schema.
+    """
+
     type: ResourceType
     name: NonEmptyStr
 
@@ -61,27 +84,90 @@ class _ValidResourceBase(BaseModel):
             and self.type == ResourceType.SLURM_SSH
             and self.tasks_pixi_config["SLURM_CONFIG"] is None
         ):
-            raise ValueError(
-                "`tasks_pixi_config` must include `SLURM_CONFIG`."
-            )
+            raise ValueError("`tasks_pixi_config` must include `SLURM_CONFIG`.")
         return self
 
 
-class ValidResourceLocal(_ValidResourceBase):
+class ValidResourceLocal(ValidResourceBase):
+    """
+    Valid local resource.
+
+    Attributes:
+        name: Resource name.
+        type: Resource type.
+        tasks_python_config:
+            Configuration of Python interpreters used for task collection.
+        tasks_pixi_config:
+            Configuration of `pixi` interpreters used for task collection.
+        tasks_local_dir:
+            Local base folder for task environments.
+        jobs_local_dir:
+            Local base folder for job folders.
+        jobs_runner_config:
+            Runner configuration.
+
+    """
+
     type: Literal[ResourceType.LOCAL]
     jobs_runner_config: JobRunnerConfigLocal
     jobs_slurm_python_worker: None = None
     host: None = None
 
 
-class ValidResourceSlurmSudo(_ValidResourceBase):
+class ValidResourceSlurmSudo(ValidResourceBase):
+    """
+    Valid SLURM-sudo resource.
+
+    Attributes:
+        name: Resource name.
+        type: Resource type.
+        tasks_python_config:
+            Configuration of Python interpreters used for task collection.
+        tasks_pixi_config:
+            Configuration of `pixi` interpreters used for task collection.
+        tasks_local_dir:
+            Local base folder for task environments.
+        jobs_local_dir:
+            Local base folder for job folders.
+        jobs_runner_config:
+            Runner configuration.
+        jobs_poll_interval:
+            `squeue` polling interval.
+        jobs_slurm_python_worker:
+            Python worker to be used in SLURM jobs.
+    """
+
     type: Literal[ResourceType.SLURM_SUDO]
     jobs_slurm_python_worker: AbsolutePathStr
     jobs_runner_config: JobRunnerConfigSLURM
     host: None = None
 
 
-class ValidResourceSlurmSSH(_ValidResourceBase):
+class ValidResourceSlurmSSH(ValidResourceBase):
+    """
+    Valid SLURM-SSH resource.
+
+    Attributes:
+        name: Resource name
+        type: Resource type.
+        tasks_python_config:
+            Configuration of Python interpreters used for task collection.
+        tasks_pixi_config:
+            Configuration of `pixi` interpreters used for task collection.
+        tasks_local_dir:
+            Local base folder for task environments.
+        jobs_local_dir:
+            Local base folder for job folders.
+        jobs_runner_config:
+            Runner configuration.
+        jobs_poll_interval:
+            `squeue` polling interval.
+        jobs_slurm_python_worker:
+            Python worker to be used in SLURM jobs.
+        host:
+            Hostname or IP address of remote SLURM cluster.
+    """
+
     type: Literal[ResourceType.SLURM_SSH]
     host: NonEmptyStr
     jobs_slurm_python_worker: AbsolutePathStr
@@ -101,9 +187,16 @@ ResourceCreate = Annotated[
     | Annotated[ValidResourceSlurmSSH, Tag(ResourceType.SLURM_SSH)],
     Discriminator(get_discriminator_value),
 ]
+"""
+Schema for resources in API request bodies.
+"""
 
 
 class ResourceRead(BaseModel):
+    """
+    Schema for resources in API response bodies.
+    """
+
     id: int
 
     type: str
@@ -131,6 +224,9 @@ def cast_serialize_resource(_data: ResourceCreate) -> dict[str, Any]:
     We use `@validate_call` because `ResourceCreate` is a `Union` type and it
     cannot be instantiated directly.
 
+    Args:
+        _data:
+
     Return:
         Serialized version of a valid resource object.
     """

fractal_server/app/schemas/v2/task.py

@@ -14,7 +14,6 @@ from fractal_server.types import ListUniqueNonEmptyString
 from fractal_server.types import NonEmptyStr
 from fractal_server.types import TypeFilters
 
-
 logger = set_logger(__name__)
 
 

fractal_server/app/schemas/v2/task_collection.py

@@ -86,7 +86,7 @@ class TaskCollectPipV2(BaseModel):
     def validate_pinned_package_versions(cls, value):
         if value is not None:
             for pkg, version in value.items():
-                validate_cmd(pkg)
+                validate_cmd(pkg, allow_char="[]")
                 validate_cmd(version)
         return value
 

fractal_server/app/schemas/v2/workflowtask.py

@@ -5,14 +5,15 @@ from pydantic import ConfigDict
 from pydantic import Field
 from pydantic import model_validator
 
+from fractal_server.types import DictStrAny
+from fractal_server.types import TypeFilters
+from fractal_server.types import WorkflowTaskArgument
+
 from .task import TaskExportV2
 from .task import TaskImportV2
 from .task import TaskImportV2Legacy
 from .task import TaskReadV2
 from .task import TaskType
-from fractal_server.types import DictStrAny
-from fractal_server.types import TypeFilters
-from fractal_server.types import WorkflowTaskArgument
 
 
 class WorkflowTaskCreateV2(BaseModel):

fractal_server/app/security/__init__.py

@@ -15,6 +15,7 @@ registers the client and the relative routes.
 
 All routes are registered under the `auth/` prefix.
 """
+
 import contextlib
 from collections.abc import AsyncGenerator
 from typing import Any
@@ -39,7 +40,7 @@ from sqlalchemy.orm import selectinload
 from sqlmodel import func
 from sqlmodel import select
 
-from ..db import get_async_db
+from fractal_server.app.db import get_async_db
 from fractal_server.app.db import get_sync_db
 from fractal_server.app.models import LinkUserGroup
 from fractal_server.app.models import OAuthAccount
@@ -275,9 +276,7 @@ class UserManager(IntegerIDMixin, BaseUserManager[UserOAuth, int]):
                 )
             except exceptions.UserNotExists:
                 # (0) Log
-                logger.warning(
-                    f"Self-registration attempt by {account_email}."
-                )
+                logger.warning(f"Self-registration attempt by {account_email}.")
 
                 # (1) Prepare user-facing error message
                 error_msg = (
@@ -459,9 +458,7 @@ def _create_first_group():
         )
         return
 
-    function_logger.info(
-        f"START, name '{settings.FRACTAL_DEFAULT_GROUP_NAME}'"
-    )
+    function_logger.info(f"START, name '{settings.FRACTAL_DEFAULT_GROUP_NAME}'")
     with next(get_sync_db()) as db:
         group_all = db.execute(
             select(UserGroup).where(

fractal_server/app/security/signup_email.py

@@ -36,9 +36,9 @@ def send_fractal_email_or_log_failure(
                 for recipient in email_settings.recipients
             ]
         )
-        mail_msg[
-            "Subject"
-        ] = f"[Fractal, {email_settings.instance_name}] {subject}"
+        mail_msg["Subject"] = (
+            f"[Fractal, {email_settings.instance_name}] {subject}"
+        )
         with smtplib.SMTP(
             email_settings.smtp_server,
             email_settings.port,
@@ -61,6 +61,5 @@ def send_fractal_email_or_log_failure(
 
     except Exception as e:
         logger.error(
-            "Could not send self-registration email, "
-            f"original error: {str(e)}."
+            f"Could not send self-registration email, original error: {str(e)}."
         )

fractal_server/app/shutdown.py

@@ -12,44 +12,48 @@ from fractal_server.syringe import Inject
 
 
 async def cleanup_after_shutdown(*, jobsV2: list[int], logger_name: str):
+    settings = Inject(get_settings)
     logger = get_logger(logger_name)
     logger.info("Cleanup function after shutdown")
-    stm_v2 = (
+    stm_objects = (
         select(JobV2)
         .where(JobV2.id.in_(jobsV2))
         .where(JobV2.status == JobStatusTypeV2.SUBMITTED)
     )
+    stm_ids = (
+        select(JobV2.id)
+        .where(JobV2.id.in_(jobsV2))
+        .where(JobV2.status == JobStatusTypeV2.SUBMITTED)
+    )
 
     async for session in get_async_db():
-        jobsV2_db = (await session.execute(stm_v2)).scalars().all()
-
-        for job in jobsV2_db:
+        # Write shutdown file for all jobs
+        jobs = (await session.execute(stm_objects)).scalars().all()
+        for job in jobs:
             _write_shutdown_file(job=job)
 
-        settings = Inject(get_settings)
-
+        # Wait for completion of all job - with a timeout
+        interval = settings.FRACTAL_GRACEFUL_SHUTDOWN_TIME / 20
         t_start = time.perf_counter()
         while (
             time.perf_counter() - t_start
-        ) < settings.FRACTAL_GRACEFUL_SHUTDOWN_TIME:  # 30 seconds
-            logger.info("Waiting 3 seconds before checking")
-            time.sleep(3)
-            jobsV2_db = (await session.execute(stm_v2)).scalars().all()
-
-            if len(jobsV2_db) == 0:
-                logger.info(
-                    "All jobs associated to this app are "
-                    "either done or failed. Exit."
-                )
+        ) <= settings.FRACTAL_GRACEFUL_SHUTDOWN_TIME:
+            job_ids = (await session.execute(stm_ids)).scalars().all()
+            if len(job_ids) == 0:
+                logger.info("All jobs are either done or failed. Exit.")
                 return
             else:
-                logger.info(f"Some jobs are still 'submitted' {jobsV2_db=}")
+                logger.info(f"Some jobs are still 'submitted': {job_ids=}")
+                logger.info(f"Wait {interval:.4f} seconds before next check.")
+                time.sleep(interval)
         logger.info(
             "Graceful shutdown reached its maximum time, "
-            "but some jobs are still submitted"
+            "but some jobs are still submitted."
         )
 
-        for job in jobsV2_db:
+        # Mark jobs as failed and update their logs.
+        jobs = (await session.execute(stm_objects)).scalars().all()
+        for job in jobs:
             job.status = "failed"
             job.log = (job.log or "") + "\nJob stopped due to app shutdown\n"
             session.add(job)

fractal_server/config/_data.py

@@ -5,9 +5,10 @@ from pydantic import model_validator
 from pydantic_settings import BaseSettings
 from pydantic_settings import SettingsConfigDict
 
-from ._settings_config import SETTINGS_CONFIG_DICT
 from fractal_server.types import AbsolutePathStr
 
+from ._settings_config import SETTINGS_CONFIG_DICT
+
 
 class DataAuthScheme(StrEnum):
     VIEWER_PATHS = "viewer-paths"
@@ -18,37 +19,47 @@ class DataAuthScheme(StrEnum):
 class DataSettings(BaseSettings):
     """
     Settings for the `fractal-data` integration.
-    """
 
-    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)
-
-    FRACTAL_DATA_AUTH_SCHEME: DataAuthScheme = "none"
-    """
-    Defines how the list of allowed viewer paths is built.
+    See https://github.com/fractal-analytics-platform/fractal-data.
 
-    This variable affects the `GET /auth/current-user/allowed-viewer-paths/`
-    response, which is then consumed by
-    [fractal-data](https://github.com/fractal-analytics-platform/fractal-data).
+    Attributes:
+        FRACTAL_DATA_AUTH_SCHEME:
+            Defines how the list of allowed viewer paths is built.
 
-    Options:
+            This variable affects the
+            `GET /auth/current-user/allowed-viewer-paths/` response, which is
+            then consumed by
+            [fractal-data](https://github.com/fractal-analytics-platform/fractal-data).
 
-    - "viewer-paths": The list of allowed viewer paths will include the user's
-      `project_dir` along with any path defined in user groups' `viewer_paths`
-      attributes.
-    - "users-folders": The list will consist of the user's `project_dir` and a
-       user-specific folder. The user folder is constructed by concatenating
-       the base folder `FRACTAL_DATA_BASE_FOLDER` with the user's profile
-       `username`.
-    - "none": An empty list will be returned, indicating no access to
-       viewer paths. Useful when vizarr viewer is not used.
+            Options:
+                <ul>
+                <li> `"viewer-paths"`: The list of allowed viewer paths will
+                    include the user's `project_dir` along with any path
+                    defined in  UserGroups `viewer_paths` attributes.
+                </li>
+                <li> `"users-folders"`: The list will consist of the user's
+                    `project_dir` and a user-specific folder. The user folder
+                    is constructed by concatenating the base folder
+                    `FRACTAL_DATA_BASE_FOLDER` with the user's profile
+                    `username`.
+                </li>
+                <li> `"none"`: An empty list will be returned, indicating no
+                    access to viewer paths. Useful when vizarr viewer is not
+                    used.
+                </li>
+                </ul>
+        FRACTAL_DATA_BASE_FOLDER:
+            Base path to Zarr files that will be served by
+            fractal-vizarr-viewer.
+            This variable is required and used only when
+            `FRACTAL_DATA_AUTHORIZATION_SCHEME` is set to `"users-folders"`.
     """
 
+    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)
+
+    FRACTAL_DATA_AUTH_SCHEME: DataAuthScheme = "none"
+
     FRACTAL_DATA_BASE_FOLDER: AbsolutePathStr | None = None
-    """
-    Base path to Zarr files that will be served by fractal-vizarr-viewer;
-    This variable is required and used only when
-    FRACTAL_DATA_AUTHORIZATION_SCHEME is set to "users-folders".
-    """
 
     @model_validator(mode="after")
     def check(self: Self) -> Self:

fractal_server/config/_database.py

@@ -1,45 +1,44 @@
+from typing import Literal
+
 from pydantic import SecretStr
 from pydantic.types import NonNegativeInt
 from pydantic_settings import BaseSettings
 from pydantic_settings import SettingsConfigDict
 from sqlalchemy.engine import URL
 
-from ._settings_config import SETTINGS_CONFIG_DICT
 from fractal_server.types import NonEmptyStr
 
+from ._settings_config import SETTINGS_CONFIG_DICT
+
 
 class DatabaseSettings(BaseSettings):
     """
     Minimal set of configurations needed for operating on the database (e.g
     for schema migrations).
+
+    Attributes:
+        DB_ECHO:
+            If `"true"`, make database operations verbose.
+        POSTGRES_USER:
+            User to use when connecting to the PostgreSQL database.
+        POSTGRES_PASSWORD:
+            Password to use when connecting to the PostgreSQL database.
+        POSTGRES_HOST:
+            URL to the PostgreSQL server or path to a UNIX domain socket.
+        POSTGRES_PORT:
+            Port number to use when connecting to the PostgreSQL server.
+        POSTGRES_DB:
+            Name of the PostgreSQL database to connect to.
     """
 
     model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)
 
-    DB_ECHO: bool = False
-    """
-    If `True`, make database operations verbose.
-    """
+    DB_ECHO: Literal["true", "false"] = "false"
     POSTGRES_USER: NonEmptyStr | None = None
-    """
-    User to use when connecting to the PostgreSQL database.
-    """
     POSTGRES_PASSWORD: SecretStr | None = None
-    """
-    Password to use when connecting to the PostgreSQL database.
-    """
     POSTGRES_HOST: NonEmptyStr = "localhost"
-    """
-    URL to the PostgreSQL server or path to a UNIX domain socket.
-    """
     POSTGRES_PORT: NonNegativeInt = 5432
-    """
-    Port number to use when connecting to the PostgreSQL server.
-    """
     POSTGRES_DB: NonEmptyStr
-    """
-    Name of the PostgreSQL database to connect to.
-    """
 
     @property
     def DATABASE_URL(self) -> URL:

fractal_server/config/_email.py

@@ -4,8 +4,8 @@ from typing import Self
 from pydantic import BaseModel
 from pydantic import EmailStr
 from pydantic import Field
-from pydantic import model_validator
 from pydantic import SecretStr
+from pydantic import model_validator
 from pydantic_settings import BaseSettings
 from pydantic_settings import SettingsConfigDict
 
@@ -17,14 +17,14 @@ class PublicEmailSettings(BaseModel):
     Schema for `EmailSettings.public`, namely the ready-to-use settings.
 
     Attributes:
-        sender: Sender email address
-        recipients: List of recipients email address
-        smtp_server: SMTP server address
-        port: SMTP server port
-        password: Sender password
-        instance_name: Name of SMTP server instance
-        use_starttls: Whether to use the security protocol
-        use_login: Whether to use login
+        sender: Sender email address.
+        recipients: List of recipients email address.
+        smtp_server: SMTP server address.
+        port: SMTP server port.
+        password: Sender password.
+        instance_name: Name of SMTP server instance.
+        use_starttls: Whether to use the security protocol.
+        use_login: Whether to use login.
     """
 
     sender: EmailStr
@@ -40,50 +40,42 @@ class PublicEmailSettings(BaseModel):
 class EmailSettings(BaseSettings):
     """
     Class with settings for email-sending feature.
+
+    Attributes:
+        FRACTAL_EMAIL_SENDER:
+            Address of the OAuth-signup email sender.
+        FRACTAL_EMAIL_PASSWORD:
+            Password for the OAuth-signup email sender.
+        FRACTAL_EMAIL_SMTP_SERVER:
+            SMTP server for the OAuth-signup emails.
+        FRACTAL_EMAIL_SMTP_PORT:
+            SMTP server port for the OAuth-signup emails.
+        FRACTAL_EMAIL_INSTANCE_NAME:
+            Fractal instance name, to be included in the OAuth-signup emails.
+        FRACTAL_EMAIL_RECIPIENTS:
+            Comma-separated list of recipients of the OAuth-signup emails.
+        FRACTAL_EMAIL_USE_STARTTLS:
+            Whether to use StartTLS when using the SMTP server.
+        FRACTAL_EMAIL_USE_LOGIN:
+            Whether to use login when using the SMTP server.
+            If 'true', FRACTAL_EMAIL_PASSWORD  must be provided.
     """
 
     model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)
 
     FRACTAL_EMAIL_SENDER: EmailStr | None = None
-    """
-    Address of the OAuth-signup email sender.
-    """
     FRACTAL_EMAIL_PASSWORD: SecretStr | None = None
-    """
-    Password for the OAuth-signup email sender.
-    """
     FRACTAL_EMAIL_SMTP_SERVER: str | None = None
-    """
-    SMTP server for the OAuth-signup emails.
-    """
     FRACTAL_EMAIL_SMTP_PORT: int | None = None
-    """
-    SMTP server port for the OAuth-signup emails.
-    """
     FRACTAL_EMAIL_INSTANCE_NAME: str | None = None
-    """
-    Fractal instance name, to be included in the OAuth-signup emails.
-    """
     FRACTAL_EMAIL_RECIPIENTS: str | None = None
-    """
-    Comma-separated list of recipients of the OAuth-signup emails.
-    """
     FRACTAL_EMAIL_USE_STARTTLS: Literal["true", "false"] = "true"
-    """
-    Whether to use StartTLS when using the SMTP server.
-    Accepted values: 'true', 'false'.
-    """
     FRACTAL_EMAIL_USE_LOGIN: Literal["true", "false"] = "true"
-    """
-    Whether to use login when using the SMTP server.
-    If 'true', FRACTAL_EMAIL_PASSWORD  must be provided.
-    Accepted values: 'true', 'false'.
-    """
 
     public: PublicEmailSettings | None = None
     """
-    The validated field which is actually used in `fractal-server
-    (automatically populated upon creation).
+    The validated field which is actually used in `fractal-server`,
+    automatically populated upon creation.
     """
 
     @model_validator(mode="after")