Skip to content

fields

A collection of Annotated Pydantic fields used in the YouSleep project.

AnalysisConfigIdStr = Annotated[str, Field(min_length=4, max_length=64, pattern='^[a-z-]*\\d*$', examples=['u-sleep-research-v1'], description="The machine-readable identifier of the analysis configuration. Must be between 4 and 64 characters long. Must contain only lowercase letters, hyphens ('-'), and optionally end with digits (e.g., 'u-sleep-research-v1'). The id names one lineage of comparable results and never changes once registered.")] module-attribute

A string that represents the unique identifier of an analysis configuration.

AnalysisConfigNameStr = Annotated[str, Field(min_length=4, max_length=64, pattern='^[A-Z]{1}[a-zA-Z -]*\\d*$', examples=['U-Sleep Research v1'], description="The user friendly name of the analysis. Can include spaces and hypens. Must be between 4 and 64 characters long. Must start with an uppercase letter and afterwards contain only alphabetical characters, spaces or hypens ('-'). Cannot end in a space nor a hyphen. Can end with digits, such as 'v2', to name a second lineage of the same method.")] module-attribute

A string that represents the name of an analysis configuration.

ChannelName = Annotated[str, StringConstraints(min_length=1, max_length=16)] module-attribute

A string that represents the name of a channel.

ClockTimeStr = Annotated[str, Field(pattern='^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$')] module-attribute

A wall-clock time spelled "HH:MM" or "HH:MM:SS" (24-hour).

DescriptionStr = Annotated[str, Field(min_length=3, max_length=256, description='The user friendly description. Must be 3 to 256 characters long.')] module-attribute

A string that represents a description.

GroupLabelStr = Annotated[str, StringConstraints(min_length=1, max_length=255)] module-attribute

A report group label: a study tag, a stratum label or a longitudinal bucket.

NameString = Annotated[str, StringConstraints(strip_whitespace=True, min_length=3, max_length=64, pattern="^[a-zA-Z0-9][a-zA-Z0-9 '_.\\-]*[a-zA-Z0-9'_.\\-]$")] module-attribute

A string that represents the name of an item (project, study, analysis, etc.).

Allows alphanumeric characters, spaces, apostrophes, underscores, periods, and hyphens. Must start with an alphanumeric character and cannot end with a space. Rejects characters that would cause URL or security issues (/, ?, #, %, <, >, \, ;, ").

NewPasswordStr = Annotated[str, Field(min_length=8, max_length=72), AfterValidator(_fits_bcrypt_limit)] module-attribute

A NEW password: at least 8 characters, at most 72 UTF-8 bytes.

The server's password policy enforces the complexity rules; this type carries the length contract so clients fail fast instead of round-tripping.

ParameterKeyStr = Annotated[str, Field(min_length=2, max_length=64, pattern='^[a-z][a-z0-9_-]*[a-z0-9]$', description='The machine key of a parameter: lowercase letters, digits, hyphens and underscores, 2 to 64 characters, starting with a letter. It names the parameter in requests, in the analysis manifest and in the parameter hash.')] module-attribute

A string that identifies a parameter to machines (requests, manifests, hashes).

ParameterNameStr = Annotated[str, Field(min_length=3, max_length=32, pattern='^[A-Z]{1}[a-z ]*[^ ]$', description='The user friendly name of the parameter. Can be 3 to 32 characters long. Must start with an uppercase letter and afterwards contain only lowercase alphabetical characters and spaces. Cannot end in a space.')] module-attribute

A string that represents the name of a parameter.

StripAndRequire = AfterValidator(_strip_and_require) module-attribute

Annotated metadata for a required free-text field: trims surrounding whitespace and rejects a value that is blank once trimmed.

List it AFTER the field's own Field(...) constraints inside Annotated so that length errors keep precedence over the blank error.

TagString = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1, max_length=40, pattern='^[a-zA-Z0-9](?:[a-zA-Z0-9 _.\\-]*[a-zA-Z0-9_.\\-])?$')] module-attribute

A string that represents a single tag/label on an item (project, study, etc.).

Human-readable: allows letters, digits, spaces, hyphens ('-'), underscores ('_') and periods ('.'). Must start with an alphanumeric character; leading/trailing whitespace is stripped. Between 1 and 40 characters. Other punctuation (/, ?, #, %, <, >, etc.) is rejected for URL/storage safety. Clients should collapse internal whitespace to single spaces and de-duplicate tags case-insensitively.

TagsSet = set[TagString] module-attribute

A set of tag strings associated with an item (project, study etc.)