schemas

AbsolutePathStr = Annotated[NonEmptyStr, AfterValidator(val_absolute_path)] module-attribute

String representing an absolute path.

ListUniqueNonEmptyString = Annotated[list[NonEmptyStr], AfterValidator(val_unique_list)] module-attribute

List of unique non-empty-string items.

ListUniqueNonNegativeInt = Annotated[list[NonNegativeInt], AfterValidator(val_unique_list)] module-attribute

List of unique non-negative-integer items.

NonEmptyStr = Annotated[str, StringConstraints(min_length=1, strip_whitespace=True)] module-attribute

A non-empty string, with no leading/trailing whitespaces.

OAuthAccountRead

Bases: BaseModel

Schema for storing essential OAuthAccount information within UserRead.oauth_accounts.

ATTRIBUTE	DESCRIPTION
id	ID of the row in fractal-owned oauthaccount table. TYPE: int
account_email	Email associated to OAuth account TYPE: str
oauth_name	Name of the OAuth provider (e.g. github) TYPE: str

Source code in fractal_server/app/schemas/user.py

class OAuthAccountRead(BaseModel):
    """
    Schema for storing essential `OAuthAccount` information within
    `UserRead.oauth_accounts`.

    Attributes:
        id: ID of the row in fractal-owned `oauthaccount` table.
        account_email: Email associated to OAuth account
        oauth_name: Name of the OAuth provider (e.g. `github`)
    """

    id: int
    account_email: str
    oauth_name: str

UserCreate

Bases: BaseUserCreate

Schema for User creation.

ATTRIBUTE	DESCRIPTION
profile_id	TYPE: int | None

Source code in fractal_server/app/schemas/user.py

class UserCreate(schemas.BaseUserCreate):
    """
    Schema for `User` creation.

    Attributes:
        profile_id:
    """

    profile_id: int | None = None
    project_dir: Annotated[AbsolutePathStr, AfterValidator(_validate_cmd)]
    slurm_accounts: list[str] = Field(default_factory=list)

UserGroupCreate

Bases: BaseModel

Schema for UserGroup creation

ATTRIBUTE	DESCRIPTION
name	Group name TYPE: NonEmptyStr

Source code in fractal_server/app/schemas/user_group.py

class UserGroupCreate(BaseModel):
    """
    Schema for `UserGroup` creation

    Attributes:
        name: Group name
    """

    model_config = ConfigDict(extra="forbid")

    name: NonEmptyStr
    viewer_paths: ListUniqueAbsolutePathStr = Field(default_factory=list)

UserGroupRead

Bases: BaseModel

Schema for UserGroup read

NOTE: user_ids does not correspond to a column of the UserGroup table, but it is rather computed dynamically in relevant endpoints.

ATTRIBUTE	DESCRIPTION
id	Group ID TYPE: int
name	Group name TYPE: str
timestamp_created	Creation timestamp TYPE: AwareDatetime
user_ids	IDs of users of this group TYPE: list[int] | None

Source code in fractal_server/app/schemas/user_group.py

class UserGroupRead(BaseModel):
    """
    Schema for `UserGroup` read

    NOTE: `user_ids` does not correspond to a column of the `UserGroup` table,
    but it is rather computed dynamically in relevant endpoints.

    Attributes:
        id: Group ID
        name: Group name
        timestamp_created: Creation timestamp
        user_ids: IDs of users of this group
    """

    id: int
    name: str
    timestamp_created: AwareDatetime
    user_ids: list[int] | None = None
    viewer_paths: list[str]

    @field_serializer("timestamp_created")
    def serialize_datetime(v: datetime) -> str:
        return v.isoformat()

UserGroupUpdate

Bases: BaseModel

Schema for UserGroup update

Source code in fractal_server/app/schemas/user_group.py

class UserGroupUpdate(BaseModel):
    """
    Schema for `UserGroup` update
    """

    model_config = ConfigDict(extra="forbid")

    viewer_paths: ListUniqueAbsolutePathStr = None

UserRead

Bases: BaseUser[int]

Schema for User read from database.

ATTRIBUTE	DESCRIPTION
group_ids_names	TYPE: list[tuple[int, str]] | None
oauth_accounts	TYPE: list[OAuthAccountRead]
profile_id	TYPE: int | None

Source code in fractal_server/app/schemas/user.py

class UserRead(schemas.BaseUser[int]):
    """
    Schema for `User` read from database.

    Attributes:
        group_ids_names:
        oauth_accounts:
        profile_id:
    """

    group_ids_names: list[tuple[int, str]] | None = None
    oauth_accounts: list[OAuthAccountRead]
    profile_id: int | None = None
    project_dir: str
    slurm_accounts: list[str]

UserUpdate

Bases: BaseUserUpdate

Schema for User update.

ATTRIBUTE	DESCRIPTION
password	TYPE: NonEmptyStr
email	TYPE: EmailStr
is_active	TYPE: bool
is_superuser	TYPE: bool
is_verified	TYPE: bool
profile_id	TYPE: int | None
project_dir	TYPE: Annotated[AbsolutePathStr, AfterValidator(_validate_cmd)]
slurm_accounts	TYPE: ListUniqueNonEmptyString

Source code in fractal_server/app/schemas/user.py

class UserUpdate(schemas.BaseUserUpdate):
    """
    Schema for `User` update.

    Attributes:
        password:
        email:
        is_active:
        is_superuser:
        is_verified:
        profile_id:
        project_dir:
        slurm_accounts:
    """

    model_config = ConfigDict(extra="forbid")
    password: NonEmptyStr = None
    email: EmailStr = None
    is_active: bool = None
    is_superuser: bool = None
    is_verified: bool = None
    profile_id: int | None = None
    project_dir: Annotated[
        AbsolutePathStr, AfterValidator(_validate_cmd)
    ] = None
    slurm_accounts: ListUniqueNonEmptyString = None

UserUpdateGroups

Bases: BaseModel

Schema for POST /auth/users/{user_id}/set-groups/

Source code in fractal_server/app/schemas/user.py

class UserUpdateGroups(BaseModel):
    """
    Schema for `POST /auth/users/{user_id}/set-groups/`

    """

    model_config = ConfigDict(extra="forbid")

    group_ids: ListUniqueNonNegativeInt = Field(min_length=1)

UserUpdateStrict

Bases: BaseModel

Schema for User self-editing.

ATTRIBUTE	DESCRIPTION
slurm_accounts	TYPE: ListUniqueNonEmptyString

Source code in fractal_server/app/schemas/user.py

class UserUpdateStrict(BaseModel):
    """
    Schema for `User` self-editing.

    Attributes:
        slurm_accounts:
    """

    model_config = ConfigDict(extra="forbid")
    slurm_accounts: ListUniqueNonEmptyString = None

validate_cmd(command, *, allow_char=None, attribute_name='Command')

Assert that the provided command does not contain any of the forbidden characters for commands (fractal_server.string_tools.NOT_ALLOWED_FOR_COMMANDS)

PARAMETER	DESCRIPTION
command	command to validate. TYPE: str
allow_char	chars to accept among the forbidden ones TYPE: str | None DEFAULT: None
attribute_name	Name of the attribute, to be used in error message. TYPE: str DEFAULT: 'Command'

Source code in fractal_server/string_tools.py

def validate_cmd(
    command: str,
    *,
    allow_char: str | None = None,
    attribute_name: str = "Command",
):
    """
    Assert that the provided `command` does not contain any of the forbidden
    characters for commands
    (fractal_server.string_tools.__NOT_ALLOWED_FOR_COMMANDS__)

    Args:
        command: command to validate.
        allow_char: chars to accept among the forbidden ones
        attribute_name: Name of the attribute, to be used in error message.
    """
    if not isinstance(command, str):
        raise ValueError(f"{command=} is not a string.")
    forbidden = set(__NOT_ALLOWED_FOR_COMMANDS__)
    if allow_char is not None:
        forbidden = forbidden - set(allow_char)
    if not forbidden.isdisjoint(set(command)):
        raise ValueError(
            f"{attribute_name} must not contain any of this characters: "
            f"'{forbidden}'\n"
            f"Provided {attribute_name.lower()}: '{command}'."
        )