Skip to content

files

FileResource

Bases: EntryResource

Representing a file.

Source code in optimade/models/files.py 
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
class FileResource(EntryResource):
    """Representing a file."""

    type: str = StrictField(
        "files",
        description="""The name of the type of an entry.

- **Type**: string.

- **Requirements/Conventions**:
    - **Support**: MUST be supported by all implementations, MUST NOT be `null`.
    - **Query**: MUST be a queryable property with support for all mandatory filter features.
    - **Response**: REQUIRED in the response.
    - MUST be an existing entry type.
    - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.

- **Examples**:
    - `"structures"`""",
        pattern="^files$",
        support=SupportLevel.MUST,
        queryable=SupportLevel.MUST,
    )

    attributes: FileResourceAttributes

attributes instance-attribute

id instance-attribute

meta = None class-attribute instance-attribute

model_config = ConfigDict(json_schema_extra=resource_json_schema_extra) class-attribute instance-attribute

relationships = None class-attribute instance-attribute

type = StrictField('files', description='The name of the type of an entry.\n\n- **Type**: string.\n\n- **Requirements/Conventions**:\n - **Support**: MUST be supported by all implementations, MUST NOT be `null`.\n - **Query**: MUST be a queryable property with support for all mandatory filter features.\n - **Response**: REQUIRED in the response.\n - MUST be an existing entry type.\n - The entry of type `<type>` and ID `<id>` MUST be returned in response to a request for `/<type>/<id>` under the versioned base URL.\n\n- **Examples**:\n - `"structures"`', pattern='^files$', support=(SupportLevel.MUST), queryable=(SupportLevel.MUST)) class-attribute instance-attribute

FileResourceAttributes

Bases: EntryResourceAttributes

This class contains the Field for the attributes used to represent a file, e.g. .

Source code in optimade/models/files.py 
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
class FileResourceAttributes(EntryResourceAttributes):
    """This class contains the Field for the attributes used to represent a file, e.g. ."""

    url: str = OptimadeField(
        ...,
        description="""The URL to get the contents of a file.
- **Type**: string
- **Requirements/Conventions**:

  - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.
  - **Response**: REQUIRED in the response.
  - The URL MUST point to the actual contents of a file (i.e. byte stream), not an intermediate (preview) representation.
    For example, if referring to a file on GitHub, a link should point to raw contents.

- **Examples**:

  - :val:`"https://example.org/files/cifs/1000000.cif"`
""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.OPTIONAL,
    )

    url_stable_until: datetime | None = OptimadeField(
        None,
        description="""Point in time until which the URL in `url` is guaranteed to stay stable.
- **Type**: timestamp
- **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.
  - :val:`null` means that there is no stability guarantee for the URL in `url`.
    Indefinite support could be communicated by providing a date sufficiently far in the future, for example, :val:`9999-12-31`.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    name: str = OptimadeField(
        ...,
        description="""Base name of a file.
- **Type**: string
- **Requirements/Conventions**:

  - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.
  - File name extension is an integral part of a file name and, if available, MUST be included.

- **Examples**:

  - :val:`"1000000.cif"`""",
        support=SupportLevel.MUST,
        queryable=SupportLevel.OPTIONAL,
    )

    size: int | None = OptimadeField(
        None,
        description="""Size of a file in bytes.
- **Type**: integer
- **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.
  - If provided, it MUST be guaranteed that either exact size of a file is given or its upper bound.
    This way if a client reserves a static buffer or truncates the download stream after this many bytes the whole file would be received.
    Such provision is included to allow the providers to serve on-the-fly compressed files.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    media_type: str | None = OptimadeField(
        None,
        description="""Media type identifier (also known as MIME type), for a file as per `RFC 6838 Media Type Specifications and Registration Procedures <https://datatracker.ietf.org/doc/html/rfc6838>`__.
- **Type**: string
- **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.

- **Examples**:

  - :val:`"chemical/x-cif"`""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    version: str | None = OptimadeField(
        None,
        description="""Version information of a file (e.g. commit, revision, timestamp).
- **Type**: string
- **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.
  - If provided, it MUST be guaranteed that file contents pertaining to the same combination of :field:`id` and :field:`version` are the same""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    modification_timestamp: datetime | None = OptimadeField(
        None,
        description="""Timestamp of the last modification of file contents.
  A modification is understood as an addition, change or deletion of one or more bytes, resulting in file contents different from the previous.
- **Type**: timestamp
- **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.
  - Timestamps of subsequent file modifications SHOULD be increasing (not earlier than previous timestamps).""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    description: str | None = OptimadeField(
        None,
        description="""Free-form description of a file.
- **Type**: string
- **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.

- **Examples**:

  - :val:`"POSCAR format file"`""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    checksums: dict[str, str] | None = OptimadeField(
        None,
        description="""Dictionary providing checksums of file contents.
* **Type**: dictionary with keys identifying checksum functions and values (strings) giving the actual checksums
* **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.
  - Supported dictionary keys: :property:`md5`, :property:`sha1`, :property:`sha224`, :property:`sha256`, :property:`sha384`, :property:`sha512`.
    Checksums outside this list MAY be used, but their names MUST be prefixed by database-provider-specific namespace prefix (see appendix `Database-Provider-Specific Namespace Prefixes`_).
""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    atime: datetime | None = OptimadeField(
        None,
        description="""Time of last access of a file as per POSIX standard.
- **Type**: timestamp
- **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    ctime: datetime | None = OptimadeField(
        None,
        description="""Time of last status change of a file as per POSIX standard.
- **Type**: timestamp
- **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.""",
        support=SupportLevel.OPTIONAL,
        queryable=SupportLevel.OPTIONAL,
    )

    mtime: datetime | None = OptimadeField(
        None,
        description=""" Time of last modification of a file as per POSIX standard.
- **Type**: timestamp
- **Requirements/Conventions**:

  - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.
  - **Query**: Support for queries on this property is OPTIONAL.
  - It should be noted that the values of :field:`last_modified`, :field:`modification_timestamp` and :field:`mtime` do not necessary match.
    :field:`last_modified` pertains to the modification of the OPTIMADE metadata, :field:`modification_timestamp` pertains to file contents and :field:`mtime` pertains to the modification of the file (not necessary changing its contents).
    For example, appending an empty string to a file would result in the change of :field:`mtime` in some operating systems, but this would not be deemed as a modification of its contents.
""",
        queryable=SupportLevel.OPTIONAL,
        support=SupportLevel.OPTIONAL,
    )

atime = OptimadeField(None, description='Time of last access of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.', support=(SupportLevel.OPTIONAL), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

checksums = OptimadeField(None, description='Dictionary providing checksums of file contents.\n* **Type**: dictionary with keys identifying checksum functions and values (strings) giving the actual checksums\n* **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Supported dictionary keys: :property:`md5`, :property:`sha1`, :property:`sha224`, :property:`sha256`, :property:`sha384`, :property:`sha512`.\n Checksums outside this list MAY be used, but their names MUST be prefixed by database-provider-specific namespace prefix (see appendix `Database-Provider-Specific Namespace Prefixes`_).\n', support=(SupportLevel.OPTIONAL), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

ctime = OptimadeField(None, description='Time of last status change of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.', support=(SupportLevel.OPTIONAL), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

description = OptimadeField(None, description='Free-form description of a file.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n\n - :val:`"POSCAR format file"`', support=(SupportLevel.OPTIONAL), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

immutable_id = None class-attribute instance-attribute

last_modified instance-attribute

media_type = OptimadeField(None, description='Media type identifier (also known as MIME type), for a file as per `RFC 6838 Media Type Specifications and Registration Procedures <https://datatracker.ietf.org/doc/html/rfc6838>`__.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n\n- **Examples**:\n\n - :val:`"chemical/x-cif"`', support=(SupportLevel.OPTIONAL), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

model_config = ConfigDict(extra='allow') class-attribute instance-attribute

modification_timestamp = OptimadeField(None, description='Timestamp of the last modification of file contents.\n A modification is understood as an addition, change or deletion of one or more bytes, resulting in file contents different from the previous.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - Timestamps of subsequent file modifications SHOULD be increasing (not earlier than previous timestamps).', support=(SupportLevel.OPTIONAL), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

mtime = OptimadeField(None, description=' Time of last modification of a file as per POSIX standard.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - It should be noted that the values of :field:`last_modified`, :field:`modification_timestamp` and :field:`mtime` do not necessary match.\n :field:`last_modified` pertains to the modification of the OPTIMADE metadata, :field:`modification_timestamp` pertains to file contents and :field:`mtime` pertains to the modification of the file (not necessary changing its contents).\n For example, appending an empty string to a file would result in the change of :field:`mtime` in some operating systems, but this would not be deemed as a modification of its contents.\n', queryable=(SupportLevel.OPTIONAL), support=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

name = OptimadeField(..., description='Base name of a file.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - File name extension is an integral part of a file name and, if available, MUST be included.\n\n- **Examples**:\n\n - :val:`"1000000.cif"`', support=(SupportLevel.MUST), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

size = OptimadeField(None, description='Size of a file in bytes.\n- **Type**: integer\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - If provided, it MUST be guaranteed that either exact size of a file is given or its upper bound.\n This way if a client reserves a static buffer or truncates the download stream after this many bytes the whole file would be received.\n Such provision is included to allow the providers to serve on-the-fly compressed files.', support=(SupportLevel.OPTIONAL), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

url = OptimadeField(..., description='The URL to get the contents of a file.\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: MUST be supported by all implementations, MUST NOT be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - **Response**: REQUIRED in the response.\n - The URL MUST point to the actual contents of a file (i.e. byte stream), not an intermediate (preview) representation.\n For example, if referring to a file on GitHub, a link should point to raw contents.\n\n- **Examples**:\n\n - :val:`"https://example.org/files/cifs/1000000.cif"`\n', support=(SupportLevel.MUST), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

url_stable_until = OptimadeField(None, description='Point in time until which the URL in `url` is guaranteed to stay stable.\n- **Type**: timestamp\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - :val:`null` means that there is no stability guarantee for the URL in `url`.\n Indefinite support could be communicated by providing a date sufficiently far in the future, for example, :val:`9999-12-31`.', support=(SupportLevel.OPTIONAL), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

version = OptimadeField(None, description='Version information of a file (e.g. commit, revision, timestamp).\n- **Type**: string\n- **Requirements/Conventions**:\n\n - **Support**: OPTIONAL support in implementations, i.e., MAY be :val:`null`.\n - **Query**: Support for queries on this property is OPTIONAL.\n - If provided, it MUST be guaranteed that file contents pertaining to the same combination of :field:`id` and :field:`version` are the same', support=(SupportLevel.OPTIONAL), queryable=(SupportLevel.OPTIONAL)) class-attribute instance-attribute

cast_immutable_id_to_str(value) classmethod

Convenience validator for casting immutable_id to a string.

Source code in optimade/models/entries.py 
121
122
123
124
125
126
127
128
@field_validator("immutable_id", mode="before")
@classmethod
def cast_immutable_id_to_str(cls, value: Any) -> str:
    """Convenience validator for casting `immutable_id` to a string."""
    if value is not None and not isinstance(value, str):
        value = str(value)

    return value

check_illegal_attributes_fields()

Source code in optimade/models/jsonapi.py 
330
331
332
333
334
335
336
337
338
@model_validator(mode="after")
def check_illegal_attributes_fields(self) -> "Attributes":
    illegal_fields = ("relationships", "links", "id", "type")
    for field in illegal_fields:
        if hasattr(self, field):
            raise ValueError(
                f"{illegal_fields} MUST NOT be fields under Attributes"
            )
    return self