Skip to content

Core Models

Core Pydantic models used throughout DiracX for data validation and serialization.

models

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).

Attributes

SearchSpec = ScalarSearchSpec | VectorSearchSpec module-attribute

Classes

ScalarSearchOperator

Bases: StrEnum

Source code in diracx-core/src/diracx/core/models.py 
16
17
18
19
20
21
22
23
class ScalarSearchOperator(StrEnum):
    EQUAL = "eq"
    NOT_EQUAL = "neq"
    GREATER_THAN = "gt"
    LESS_THAN = "lt"
    LIKE = "like"
    NOT_LIKE = "not like"
    REGEX = "regex"
Attributes
EQUAL = 'eq' class-attribute instance-attribute
NOT_EQUAL = 'neq' class-attribute instance-attribute
GREATER_THAN = 'gt' class-attribute instance-attribute
LESS_THAN = 'lt' class-attribute instance-attribute
LIKE = 'like' class-attribute instance-attribute
NOT_LIKE = 'not like' class-attribute instance-attribute
REGEX = 'regex' class-attribute instance-attribute

VectorSearchOperator

Bases: StrEnum

Source code in diracx-core/src/diracx/core/models.py 
26
27
28
class VectorSearchOperator(StrEnum):
    IN = "in"
    NOT_IN = "not in"
Attributes
IN = 'in' class-attribute instance-attribute
NOT_IN = 'not in' class-attribute instance-attribute

ScalarSearchSpec

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
31
32
33
34
class ScalarSearchSpec(TypedDict):
    parameter: str
    operator: ScalarSearchOperator
    value: str | int
Attributes
parameter instance-attribute
operator instance-attribute
value instance-attribute

VectorSearchSpec

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
37
38
39
40
class VectorSearchSpec(TypedDict):
    parameter: str
    operator: VectorSearchOperator
    values: list[str] | list[int]
Attributes
parameter instance-attribute
operator instance-attribute
values instance-attribute

SortDirection

Bases: StrEnum

Source code in diracx-core/src/diracx/core/models.py 
46
47
48
class SortDirection(StrEnum):
    ASC = "asc"
    DESC = "desc"
Attributes
ASC = 'asc' class-attribute instance-attribute
DESC = 'desc' class-attribute instance-attribute

SortSpec

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
52
53
54
class SortSpec(TypedDict):
    parameter: str
    direction: SortDirection
Attributes
parameter instance-attribute
direction instance-attribute

InsertedJob

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
57
58
59
60
61
class InsertedJob(TypedDict):
    JobID: int
    Status: str
    MinorStatus: str
    TimeStamp: datetime
Attributes
JobID instance-attribute
Status instance-attribute
MinorStatus instance-attribute
TimeStamp instance-attribute

SummaryParams pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
64
65
66
class SummaryParams(BaseModel):
    grouping: list[str]
    search: list[SearchSpec] = []
Attributes
grouping pydantic-field
search = [] pydantic-field

SearchParams pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
70
71
72
73
74
class SearchParams(BaseModel):
    parameters: list[str] | None = None
    search: list[SearchSpec] = []
    sort: list[SortSpec] = []
    distinct: bool = False
Attributes
parameters = None pydantic-field
search = [] pydantic-field
sort = [] pydantic-field
distinct = False pydantic-field

JobParameters pydantic-model

Bases: BaseModel

Some of the most important parameters that can be set for a job.

Fields:

Validators:

Source code in diracx-core/src/diracx/core/models.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class JobParameters(BaseModel, populate_by_name=True, extra="allow"):
    """Some of the most important parameters that can be set for a job."""

    timestamp: datetime | None = None
    cpu_normalization_factor: int | None = Field(None, alias="CPUNormalizationFactor")
    norm_cpu_time_s: int | None = Field(None, alias="NormCPUTime(s)")
    total_cpu_time_s: int | None = Field(None, alias="TotalCPUTime(s)")
    host_name: str | None = Field(None, alias="HostName")
    grid_ce: str | None = Field(None, alias="GridCE")
    model_name: str | None = Field(None, alias="ModelName")
    pilot_agent: str | None = Field(None, alias="PilotAgent")
    pilot_reference: str | None = Field(None, alias="Pilot_Reference")
    memory_mb: int | None = Field(None, alias="Memory(MB)")
    local_account: str | None = Field(None, alias="LocalAccount")
    payload_pid: int | None = Field(None, alias="PayloadPID")
    ce_queue: str | None = Field(None, alias="CEQueue")
    batch_system: str | None = Field(None, alias="BatchSystem")
    job_type: str | None = Field(None, alias="JobType")
    job_status: str | None = Field(None, alias="JobStatus")

    @field_validator(
        "cpu_normalization_factor", "norm_cpu_time_s", "total_cpu_time_s", mode="before"
    )
    @classmethod
    def convert_cpu_fields_to_int(cls, v):
        """Convert string representation of float to integer for CPU-related fields."""
        if v is None:
            return v
        if isinstance(v, str):
            try:
                return int(float(v))
            except (ValueError, TypeError) as e:
                raise ValueError(f"Cannot convert '{v}' to integer") from e
        if isinstance(v, (int, float)):
            return int(v)
        return v
Attributes
timestamp = None pydantic-field
cpu_normalization_factor = None pydantic-field
norm_cpu_time_s = None pydantic-field
total_cpu_time_s = None pydantic-field
host_name = None pydantic-field
grid_ce = None pydantic-field
model_name = None pydantic-field
pilot_agent = None pydantic-field
pilot_reference = None pydantic-field
memory_mb = None pydantic-field
local_account = None pydantic-field
payload_pid = None pydantic-field
ce_queue = None pydantic-field
batch_system = None pydantic-field
job_type = None pydantic-field
job_status = None pydantic-field
Functions
convert_cpu_fields_to_int(v) pydantic-validator

Convert string representation of float to integer for CPU-related fields.

Source code in diracx-core/src/diracx/core/models.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
@field_validator(
    "cpu_normalization_factor", "norm_cpu_time_s", "total_cpu_time_s", mode="before"
)
@classmethod
def convert_cpu_fields_to_int(cls, v):
    """Convert string representation of float to integer for CPU-related fields."""
    if v is None:
        return v
    if isinstance(v, str):
        try:
            return int(float(v))
        except (ValueError, TypeError) as e:
            raise ValueError(f"Cannot convert '{v}' to integer") from e
    if isinstance(v, (int, float)):
        return int(v)
    return v

JobAttributes pydantic-model

Bases: BaseModel

All the attributes that can be set for a job.

Fields:

Source code in diracx-core/src/diracx/core/models.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
class JobAttributes(BaseModel, populate_by_name=True, extra="forbid"):
    """All the attributes that can be set for a job."""

    job_type: str | None = Field(None, alias="JobType")
    job_group: str | None = Field(None, alias="JobGroup")
    site: str | None = Field(None, alias="Site")
    job_name: str | None = Field(None, alias="JobName")
    owner: str | None = Field(None, alias="Owner")
    owner_group: str | None = Field(None, alias="OwnerGroup")
    vo: str | None = Field(None, alias="VO")
    submission_time: datetime | None = Field(None, alias="SubmissionTime")
    reschedule_time: datetime | None = Field(None, alias="RescheduleTime")
    last_update_time: datetime | None = Field(None, alias="LastUpdateTime")
    start_exec_time: datetime | None = Field(None, alias="StartExecTime")
    heart_beat_time: datetime | None = Field(None, alias="HeartBeatTime")
    end_exec_time: datetime | None = Field(None, alias="EndExecTime")
    status: str | None = Field(None, alias="Status")
    minor_status: str | None = Field(None, alias="MinorStatus")
    application_status: str | None = Field(None, alias="ApplicationStatus")
    user_priority: int | None = Field(None, alias="UserPriority")
    reschedule_counter: int | None = Field(None, alias="RescheduleCounter")
    verified_flag: bool | None = Field(None, alias="VerifiedFlag")
    accounted_flag: bool | str | None = Field(None, alias="AccountedFlag")
Attributes
job_type = None pydantic-field
job_group = None pydantic-field
site = None pydantic-field
job_name = None pydantic-field
owner = None pydantic-field
owner_group = None pydantic-field
vo = None pydantic-field
submission_time = None pydantic-field
reschedule_time = None pydantic-field
last_update_time = None pydantic-field
start_exec_time = None pydantic-field
heart_beat_time = None pydantic-field
end_exec_time = None pydantic-field
status = None pydantic-field
minor_status = None pydantic-field
application_status = None pydantic-field
user_priority = None pydantic-field
reschedule_counter = None pydantic-field
verified_flag = None pydantic-field
accounted_flag = None pydantic-field

JobMetaData pydantic-model

Bases: JobAttributes, JobParameters

A model that combines both JobAttributes and JobParameters.

Fields:

Validators:

Source code in diracx-core/src/diracx/core/models.py 
141
142
class JobMetaData(JobAttributes, JobParameters, extra="allow"):
    """A model that combines both JobAttributes and JobParameters."""

JobStatus

Bases: StrEnum

Source code in diracx-core/src/diracx/core/models.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
class JobStatus(StrEnum):
    SUBMITTING = "Submitting"
    RECEIVED = "Received"
    CHECKING = "Checking"
    STAGING = "Staging"
    WAITING = "Waiting"
    MATCHED = "Matched"
    RUNNING = "Running"
    STALLED = "Stalled"
    COMPLETING = "Completing"
    DONE = "Done"
    COMPLETED = "Completed"
    FAILED = "Failed"
    DELETED = "Deleted"
    KILLED = "Killed"
    RESCHEDULED = "Rescheduled"
Attributes
SUBMITTING = 'Submitting' class-attribute instance-attribute
RECEIVED = 'Received' class-attribute instance-attribute
CHECKING = 'Checking' class-attribute instance-attribute
STAGING = 'Staging' class-attribute instance-attribute
WAITING = 'Waiting' class-attribute instance-attribute
MATCHED = 'Matched' class-attribute instance-attribute
RUNNING = 'Running' class-attribute instance-attribute
STALLED = 'Stalled' class-attribute instance-attribute
COMPLETING = 'Completing' class-attribute instance-attribute
DONE = 'Done' class-attribute instance-attribute
COMPLETED = 'Completed' class-attribute instance-attribute
FAILED = 'Failed' class-attribute instance-attribute
DELETED = 'Deleted' class-attribute instance-attribute
KILLED = 'Killed' class-attribute instance-attribute
RESCHEDULED = 'Rescheduled' class-attribute instance-attribute

JobMinorStatus

Bases: StrEnum

Source code in diracx-core/src/diracx/core/models.py 
163
164
165
class JobMinorStatus(StrEnum):
    MAX_RESCHEDULING = "Maximum of reschedulings reached"
    RESCHEDULED = "Job Rescheduled"
Attributes
MAX_RESCHEDULING = 'Maximum of reschedulings reached' class-attribute instance-attribute
RESCHEDULED = 'Job Rescheduled' class-attribute instance-attribute

JobLoggingRecord pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
168
169
170
171
172
173
174
class JobLoggingRecord(BaseModel):
    job_id: int
    status: JobStatus | Literal["idem"]
    minor_status: str
    application_status: str
    date: datetime
    source: str
Attributes
job_id pydantic-field
status pydantic-field
minor_status pydantic-field
application_status pydantic-field
date pydantic-field
source pydantic-field

JobStatusUpdate pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
177
178
179
180
181
class JobStatusUpdate(BaseModel):
    Status: JobStatus | None = None
    MinorStatus: str | None = None
    ApplicationStatus: str | None = None
    Source: str = "Unknown"
Attributes
Status = None pydantic-field
MinorStatus = None pydantic-field
ApplicationStatus = None pydantic-field
Source = 'Unknown' pydantic-field

LimitedJobStatusReturn pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
184
185
186
187
class LimitedJobStatusReturn(BaseModel):
    Status: JobStatus
    MinorStatus: str
    ApplicationStatus: str
Attributes
Status pydantic-field
MinorStatus pydantic-field
ApplicationStatus pydantic-field

JobStatusReturn pydantic-model

Bases: LimitedJobStatusReturn

Fields:

Source code in diracx-core/src/diracx/core/models.py 
190
191
192
class JobStatusReturn(LimitedJobStatusReturn):
    StatusTime: datetime
    Source: str
Attributes
StatusTime pydantic-field
Source pydantic-field

SetJobStatusReturn pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
class SetJobStatusReturn(BaseModel):
    class SetJobStatusReturnSuccess(BaseModel):
        """Successful new status change."""

        Status: JobStatus | None = None
        MinorStatus: str | None = None
        ApplicationStatus: str | None = None
        HeartBeatTime: datetime | None = None
        StartExecTime: datetime | None = None
        EndExecTime: datetime | None = None
        LastUpdateTime: datetime | None = None

    success: dict[int, SetJobStatusReturnSuccess]
    failed: dict[int, dict[str, str]]
Attributes
success pydantic-field
failed pydantic-field
Classes
SetJobStatusReturnSuccess pydantic-model

Bases: BaseModel

Successful new status change.

Fields:

Source code in diracx-core/src/diracx/core/models.py 
196
197
198
199
200
201
202
203
204
205
class SetJobStatusReturnSuccess(BaseModel):
    """Successful new status change."""

    Status: JobStatus | None = None
    MinorStatus: str | None = None
    ApplicationStatus: str | None = None
    HeartBeatTime: datetime | None = None
    StartExecTime: datetime | None = None
    EndExecTime: datetime | None = None
    LastUpdateTime: datetime | None = None
Attributes
Status = None pydantic-field
MinorStatus = None pydantic-field
ApplicationStatus = None pydantic-field
HeartBeatTime = None pydantic-field
StartExecTime = None pydantic-field
EndExecTime = None pydantic-field
LastUpdateTime = None pydantic-field

UserInfo pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
211
212
213
214
215
class UserInfo(BaseModel):
    sub: str  # dirac generated vo:sub
    preferred_username: str
    dirac_group: str
    vo: str
Attributes
sub pydantic-field
preferred_username pydantic-field
dirac_group pydantic-field
vo pydantic-field

ChecksumAlgorithm

Bases: StrEnum

Source code in diracx-core/src/diracx/core/models.py 
218
219
class ChecksumAlgorithm(StrEnum):
    SHA256 = "sha256"
Attributes
SHA256 = 'sha256' class-attribute instance-attribute

SandboxFormat

Bases: StrEnum

Source code in diracx-core/src/diracx/core/models.py 
222
223
224
class SandboxFormat(StrEnum):
    TAR_BZ2 = "tar.bz2"
    TAR_ZST = "tar.zst"
Attributes
TAR_BZ2 = 'tar.bz2' class-attribute instance-attribute
TAR_ZST = 'tar.zst' class-attribute instance-attribute

SandboxInfo pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
227
228
229
230
231
class SandboxInfo(BaseModel):
    checksum_algorithm: ChecksumAlgorithm
    checksum: str = Field(pattern=r"^[0-9a-fA-F]{64}$")
    size: int = Field(ge=1)
    format: SandboxFormat
Attributes
checksum_algorithm pydantic-field
checksum pydantic-field
size pydantic-field
format pydantic-field

SandboxType

Bases: StrEnum

Source code in diracx-core/src/diracx/core/models.py 
234
235
236
class SandboxType(StrEnum):
    Input = "Input"
    Output = "Output"
Attributes
Input = 'Input' class-attribute instance-attribute
Output = 'Output' class-attribute instance-attribute

SandboxDownloadResponse pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
239
240
241
class SandboxDownloadResponse(BaseModel):
    url: str
    expires_in: int
Attributes
url pydantic-field
expires_in pydantic-field

SandboxUploadResponse pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
244
245
246
247
class SandboxUploadResponse(BaseModel):
    pfn: str
    url: str | None = None
    fields: dict[str, str] = {}
Attributes
pfn pydantic-field
url = None pydantic-field
fields = {} pydantic-field

TokenTypeHint

Bases: StrEnum

Token type hints for RFC7009 revocation endpoint.

Source code in diracx-core/src/diracx/core/models.py 
250
251
252
253
254
class TokenTypeHint(StrEnum):
    """Token type hints for RFC7009 revocation endpoint."""

    access_token = "access_token"  # noqa: S105
    refresh_token = "refresh_token"  # noqa: S105
Attributes
access_token = 'access_token' class-attribute instance-attribute
refresh_token = 'refresh_token' class-attribute instance-attribute

GrantType

Bases: StrEnum

Grant types for OAuth2.

Source code in diracx-core/src/diracx/core/models.py 
257
258
259
260
261
262
class GrantType(StrEnum):
    """Grant types for OAuth2."""

    authorization_code = "authorization_code"
    device_code = "urn:ietf:params:oauth:grant-type:device_code"
    refresh_token = "refresh_token"  # noqa: S105   # False positive of Bandit about hard coded password
Attributes
authorization_code = 'authorization_code' class-attribute instance-attribute
device_code = 'urn:ietf:params:oauth:grant-type:device_code' class-attribute instance-attribute
refresh_token = 'refresh_token' class-attribute instance-attribute

InitiateDeviceFlowResponse

Bases: TypedDict

Response for the device flow initiation.

Source code in diracx-core/src/diracx/core/models.py 
265
266
267
268
269
270
271
272
class InitiateDeviceFlowResponse(TypedDict):
    """Response for the device flow initiation."""

    user_code: str
    device_code: str
    verification_uri_complete: str
    verification_uri: str
    expires_in: int
Attributes
user_code instance-attribute
device_code instance-attribute
verification_uri_complete instance-attribute
verification_uri instance-attribute
expires_in instance-attribute

OpenIDConfiguration

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
275
276
277
278
279
280
281
282
283
284
285
286
287
288
class OpenIDConfiguration(TypedDict):
    issuer: str
    token_endpoint: str
    userinfo_endpoint: str
    authorization_endpoint: str
    device_authorization_endpoint: str
    revocation_endpoint: str
    jwks_uri: str
    grant_types_supported: list[str]
    scopes_supported: list[str]
    response_types_supported: list[str]
    token_endpoint_auth_signing_alg_values_supported: list[str]
    token_endpoint_auth_methods_supported: list[str]
    code_challenge_methods_supported: list[str]
Attributes
issuer instance-attribute
token_endpoint instance-attribute
userinfo_endpoint instance-attribute
authorization_endpoint instance-attribute
device_authorization_endpoint instance-attribute
revocation_endpoint instance-attribute
jwks_uri instance-attribute
grant_types_supported instance-attribute
scopes_supported instance-attribute
response_types_supported instance-attribute
token_endpoint_auth_signing_alg_values_supported instance-attribute
token_endpoint_auth_methods_supported instance-attribute
code_challenge_methods_supported instance-attribute

TokenPayload

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
291
292
293
294
class TokenPayload(TypedDict):
    jti: str
    exp: datetime
    dirac_policies: dict
Attributes
jti instance-attribute
exp instance-attribute
dirac_policies instance-attribute

TokenResponse pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
297
298
299
300
301
302
class TokenResponse(BaseModel):
    # Based on RFC 6749
    access_token: str
    expires_in: int
    token_type: str = "Bearer"  # noqa: S105
    refresh_token: str | None = None
Attributes
access_token pydantic-field
expires_in pydantic-field
token_type = 'Bearer' pydantic-field
refresh_token = None pydantic-field

AccessTokenPayload

Bases: TokenPayload

Source code in diracx-core/src/diracx/core/models.py 
305
306
307
308
309
310
311
class AccessTokenPayload(TokenPayload):
    sub: str
    vo: str
    iss: str
    dirac_properties: list[str]
    preferred_username: str
    dirac_group: str
Attributes
sub instance-attribute
vo instance-attribute
iss instance-attribute
dirac_properties instance-attribute
preferred_username instance-attribute
dirac_group instance-attribute

RefreshTokenPayload

Bases: TokenPayload

Source code in diracx-core/src/diracx/core/models.py 
314
315
class RefreshTokenPayload(TokenPayload):
    legacy_exchange: bool
Attributes
legacy_exchange instance-attribute

SupportInfo

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
318
319
320
321
class SupportInfo(TypedDict):
    message: str
    webpage: str | None
    email: str | None
Attributes
message instance-attribute
webpage instance-attribute
email instance-attribute

GroupInfo

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
324
325
class GroupInfo(TypedDict):
    properties: list[str]
Attributes
properties instance-attribute

VOInfo

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
328
329
330
331
class VOInfo(TypedDict):
    groups: dict[str, GroupInfo]
    support: SupportInfo
    default_group: str
Attributes
groups instance-attribute
support instance-attribute
default_group instance-attribute

Metadata

Bases: TypedDict

Source code in diracx-core/src/diracx/core/models.py 
334
335
class Metadata(TypedDict):
    virtual_organizations: dict[str, VOInfo]
Attributes
virtual_organizations instance-attribute

HeartbeatData pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
338
339
340
341
342
343
344
345
class HeartbeatData(BaseModel, extra="forbid"):
    LoadAverage: float | None = None
    MemoryUsed: float | None = None
    Vsize: float | None = None
    AvailableDiskSpace: float | None = None
    CPUConsumed: float | None = None
    WallClockTime: float | None = None
    StandardOutput: str | None = None
Attributes
LoadAverage = None pydantic-field
MemoryUsed = None pydantic-field
Vsize = None pydantic-field
AvailableDiskSpace = None pydantic-field
CPUConsumed = None pydantic-field
WallClockTime = None pydantic-field
StandardOutput = None pydantic-field

JobCommand pydantic-model

Bases: BaseModel

Fields:

Source code in diracx-core/src/diracx/core/models.py 
348
349
350
351
class JobCommand(BaseModel):
    job_id: int
    command: Literal["Kill"]
    arguments: str | None = None
Attributes
job_id pydantic-field
command pydantic-field
arguments = None pydantic-field