query_params¶
CONFIG: ServerConfig = ServerConfig()
module-attribute
¶
This singleton loads the config from a hierarchy of sources (see
customise_sources
)
and makes it importable in the server code.
BadRequest
¶
Bases: OptimadeHTTPException
400 Bad Request
Source code in optimade/exceptions.py
57 58 59 60 61 |
|
BaseQueryParams
¶
Bases: ABC
A base class for query parameters that provides validation via the check_params
method.
Attributes:
Name | Type | Description |
---|---|---|
unsupported_params |
list[str]
|
Any string parameter listed here will raise a warning when passed to the check_params methods. Useful for disabling optional OPTIMADE query parameters that are not implemented by the server, e.g., cursor-based pagination. |
Source code in optimade/server/query_params.py
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 |
|
check_params(query_params)
¶
This method checks whether all the query parameters that are specified
in the URL string are implemented in the relevant *QueryParams
class.
This method handles four cases:
- If a query parameter is passed that is not defined in the relevant
*QueryParams
class, and it is not prefixed with a known provider prefix, then aBadRequest
is raised. - If a query parameter is passed that is not defined in the relevant
*QueryParams
class, that is prefixed with a known provider prefix, then the parameter is silently ignored - If a query parameter is passed that is not defined in the relevant
*QueryParams
class, that is prefixed with an unknown provider prefix, then aUnknownProviderQueryParameter
warning is emitted. - If a query parameter is passed that is on the
unsupported_params
list for the inherited class, then aQueryParamNotUsed
warning is emitted.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
query_params |
Iterable[str]
|
An iterable of the request's string query parameters. |
required |
Raises:
Type | Description |
---|---|
`BadRequest`
|
if the query parameter was not found in the relevant class, or if it does not have a valid prefix. |
Source code in optimade/server/query_params.py
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 |
|
BaseResourceMapper
¶
Generic Resource Mapper that defines and performs the mapping between objects in the database and the resource objects defined by the specification.
Attributes:
Name | Type | Description |
---|---|---|
ALIASES |
tuple[tuple[str, str], ...]
|
a tuple of aliases between
OPTIMADE field names and the field names in the database ,
e.g. |
LENGTH_ALIASES |
tuple[tuple[str, str], ...]
|
a tuple of aliases between
a field name and another field that defines its length, to be used
when querying, e.g. |
ENTRY_RESOURCE_CLASS |
type[EntryResource]
|
The entry type that this mapper corresponds to. |
PROVIDER_FIELDS |
tuple[str, ...]
|
a tuple of extra field names that this mapper should support when querying with the database prefix. |
TOP_LEVEL_NON_ATTRIBUTES_FIELDS |
set[str]
|
the set of top-level field names common to all endpoints. |
SUPPORTED_PREFIXES |
set[str]
|
The set of prefixes registered by this mapper. |
ALL_ATTRIBUTES |
set[str]
|
The set of attributes defined across the entry resource class and the server configuration. |
ENTRY_RESOURCE_ATTRIBUTES |
dict[str, Any]
|
A dictionary of attributes and their definitions defined by the schema of the entry resource class. |
ENDPOINT |
str
|
The expected endpoint name for this resource, as defined by
the |
Source code in optimade/server/mappers/entries.py
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 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 |
|
ALL_ATTRIBUTES()
¶
Returns all attributes served by this entry.
Source code in optimade/server/mappers/entries.py
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 |
|
ENDPOINT()
cached
¶
Returns the expected endpoint for this mapper, corresponding
to the type
property of the resource class.
Source code in optimade/server/mappers/entries.py
161 162 163 164 165 166 167 168 169 170 171 |
|
ENTRY_RESOURCE_ATTRIBUTES()
¶
Returns the dictionary of attributes defined by the underlying entry resource class.
Source code in optimade/server/mappers/entries.py
154 155 156 157 158 159 |
|
SUPPORTED_PREFIXES()
cached
¶
A set of prefixes handled by this entry type.
Note
This implementation only includes the provider prefix, but in the future this property may be extended to include other namespaces (for serving fields from, e.g., other providers or domain-specific terms).
Source code in optimade/server/mappers/entries.py
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 |
|
alias_for(field)
cached
classmethod
¶
Return aliased field name.
Deprecated
This method is deprecated could be removed without further warning. Please use
get_backend_field()
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
field |
str
|
OPTIMADE field name. |
required |
Returns:
Type | Description |
---|---|
str
|
Aliased field as found in |
Source code in optimade/server/mappers/entries.py
239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 |
|
alias_of(field)
cached
classmethod
¶
Return de-aliased field name, if it exists, otherwise return the input field name.
Deprecated
This method is deprecated could be removed without further warning. Please use
get_optimade_field()
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
field |
str
|
Field name to be de-aliased. |
required |
Returns:
Type | Description |
---|---|
str
|
De-aliased field name, falling back to returning |
Source code in optimade/server/mappers/entries.py
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 |
|
all_aliases()
cached
classmethod
¶
Returns all of the associated aliases for this entry type, including those defined by the server config. The first member of each tuple is the OPTIMADE-compliant field name, the second is the backend-specific field name.
Returns:
Type | Description |
---|---|
Iterable[tuple[str, str]]
|
A tuple of alias tuples. |
Source code in optimade/server/mappers/entries.py
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 |
|
all_length_aliases()
cached
classmethod
¶
Returns all of the associated length aliases for this class, including those defined by the server config.
Returns:
Type | Description |
---|---|
tuple[tuple[str, str], ...]
|
A tuple of length alias tuples. |
Source code in optimade/server/mappers/entries.py
173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 |
|
deserialize(results)
classmethod
¶
Converts the raw database entries for this class into serialized models, mapping the data along the way.
Source code in optimade/server/mappers/entries.py
367 368 369 370 371 372 373 374 375 376 377 378 |
|
get_backend_field(optimade_field)
cached
classmethod
¶
Return the field name configured for the particular underlying database for the passed OPTIMADE field name, that would be used in an API filter.
Aliases are read from
all_aliases()
.
If a dot-separated OPTIMADE field is provided, e.g., species.mass
, only the first part will be mapped.
This means for an (OPTIMADE, DB) alias of (species
, kinds
), get_backend_fields("species.mass")
will return kinds.mass
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
optimade_field |
str
|
The OPTIMADE field to attempt to map to the backend-specific field. |
required |
Examples:
>>> get_backend_field("chemical_formula_anonymous")
'formula_anon'
>>> get_backend_field("formula_anon")
'formula_anon'
>>> get_backend_field("_exmpl_custom_provider_field")
'custom_provider_field'
Returns:
Type | Description |
---|---|
str
|
The mapped field name to be used in the query to the backend. |
Source code in optimade/server/mappers/entries.py
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 |
|
get_optimade_field(backend_field)
cached
classmethod
¶
Return the corresponding OPTIMADE field name for the underlying database field, ready to be used to construct the OPTIMADE-compliant JSON response.
Aliases are read from
all_aliases()
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
backend_field |
str
|
The backend field to attempt to map to an OPTIMADE field. |
required |
Examples:
>>> get_optimade_field("chemical_formula_anonymous")
'chemical_formula_anonymous'
>>> get_optimade_field("formula_anon")
'chemical_formula_anonymous'
>>> get_optimade_field("custom_provider_field")
'_exmpl_custom_provider_field'
Returns:
Type | Description |
---|---|
str
|
The mapped field name to be used in an OPTIMADE-compliant response. |
Source code in optimade/server/mappers/entries.py
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 |
|
get_required_fields()
cached
classmethod
¶
Get REQUIRED response fields.
Returns:
Type | Description |
---|---|
set
|
REQUIRED response fields. |
Source code in optimade/server/mappers/entries.py
312 313 314 315 316 317 318 319 320 321 |
|
length_alias_for(field)
cached
classmethod
¶
Returns the length alias for the particular field,
or None
if no such alias is found.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
field |
str
|
OPTIMADE field name. |
required |
Returns:
Type | Description |
---|---|
Optional[str]
|
Aliased field as found in |
Source code in optimade/server/mappers/entries.py
189 190 191 192 193 194 195 196 197 198 199 200 201 202 |
|
map_back(doc)
classmethod
¶
Map properties from MongoDB to OPTIMADE.
Starting from a MongoDB document doc
, map the DB fields to the corresponding OPTIMADE fields.
Then, the fields are all added to the top-level field "attributes",
with the exception of other top-level fields, defined in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS
.
All fields not in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS
+ "attributes" will be removed.
Finally, the type
is given the value of the specified cls.ENDPOINT
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
doc |
dict
|
A resource object in MongoDB format. |
required |
Returns:
Type | Description |
---|---|
dict
|
A resource object in OPTIMADE format. |
Source code in optimade/server/mappers/entries.py
323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 |
|
EntryListingQueryParams
¶
Bases: BaseQueryParams
Common query params for all Entry listing endpoints.
Attributes:
Name | Type | Description |
---|---|---|
filter |
str
|
A filter string, in the format described in section API Filtering Format Specification of the specification. |
response_format |
str
|
The output format requested (see section Response Format). Defaults to the format string 'json', which specifies the standard output format described in this specification. Example: |
email_address |
EmailStr
|
An email address of the user making the request. The email SHOULD be that of a person and not an automatic system. Example: |
response_fields |
str
|
A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present. Example: |
sort |
str
|
If supporting sortable queries, an implementation MUST use the An implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification. If an implementation supports sorting for an entry listing endpoint, then the |
page_limit |
int
|
Sets a numerical limit on the number of entries returned.
See JSON API 1.0.
The API implementation MUST return no more than the number specified.
It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers
(in which case an error code -- Example: |
page_offset |
int
|
RECOMMENDED for use with offset-based pagination: using Example: Skip 50 structures and fetch up to 100: |
page_number |
int
|
RECOMMENDED for use with page-based pagination: using Example: Fetch page 2 of up to 50 structures per page: |
page_cursor |
int
|
RECOMMENDED for use with cursor-based pagination: using |
page_above |
str
|
RECOMMENDED for use with value-based pagination: using Example: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by
increasing |
page_below |
str
|
RECOMMENDED for use with value-based pagination: using |
include |
str
|
A server MAY implement the JSON API concept of returning compound documents
by utilizing the All related resource objects MUST be returned as part of an array value for the top-level The value of The default value for Note: A query with the parameter |
api_hint |
str
|
If the client provides the parameter, the value SHOULD have the format |
Source code in optimade/server/query_params.py
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 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 |
|
check_params(query_params)
¶
This method checks whether all the query parameters that are specified
in the URL string are implemented in the relevant *QueryParams
class.
This method handles four cases:
- If a query parameter is passed that is not defined in the relevant
*QueryParams
class, and it is not prefixed with a known provider prefix, then aBadRequest
is raised. - If a query parameter is passed that is not defined in the relevant
*QueryParams
class, that is prefixed with a known provider prefix, then the parameter is silently ignored - If a query parameter is passed that is not defined in the relevant
*QueryParams
class, that is prefixed with an unknown provider prefix, then aUnknownProviderQueryParameter
warning is emitted. - If a query parameter is passed that is on the
unsupported_params
list for the inherited class, then aQueryParamNotUsed
warning is emitted.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
query_params |
Iterable[str]
|
An iterable of the request's string query parameters. |
required |
Raises:
Type | Description |
---|---|
`BadRequest`
|
if the query parameter was not found in the relevant class, or if it does not have a valid prefix. |
Source code in optimade/server/query_params.py
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 |
|
QueryParamNotUsed
¶
Bases: OptimadeWarning
A query parameter is not used in this request.
Source code in optimade/warnings.py
62 63 |
|
SingleEntryQueryParams
¶
Bases: BaseQueryParams
Common query params for single entry endpoints.
Attributes:
Name | Type | Description |
---|---|---|
response_format |
str
|
The output format requested (see section Response Format). Defaults to the format string 'json', which specifies the standard output format described in this specification. Example: |
email_address |
EmailStr
|
An email address of the user making the request. The email SHOULD be that of a person and not an automatic system. Example: |
response_fields |
str
|
A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present. Example: |
include |
str
|
A server MAY implement the JSON API concept of returning compound documents
by utilizing the All related resource objects MUST be returned as part of an array value for the top-level The value of The default value for Note: A query with the parameter |
api_hint |
str
|
If the client provides the parameter, the value SHOULD have the format |
Source code in optimade/server/query_params.py
286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 |
|
check_params(query_params)
¶
This method checks whether all the query parameters that are specified
in the URL string are implemented in the relevant *QueryParams
class.
This method handles four cases:
- If a query parameter is passed that is not defined in the relevant
*QueryParams
class, and it is not prefixed with a known provider prefix, then aBadRequest
is raised. - If a query parameter is passed that is not defined in the relevant
*QueryParams
class, that is prefixed with a known provider prefix, then the parameter is silently ignored - If a query parameter is passed that is not defined in the relevant
*QueryParams
class, that is prefixed with an unknown provider prefix, then aUnknownProviderQueryParameter
warning is emitted. - If a query parameter is passed that is on the
unsupported_params
list for the inherited class, then aQueryParamNotUsed
warning is emitted.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
query_params |
Iterable[str]
|
An iterable of the request's string query parameters. |
required |
Raises:
Type | Description |
---|---|
`BadRequest`
|
if the query parameter was not found in the relevant class, or if it does not have a valid prefix. |
Source code in optimade/server/query_params.py
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 |
|
UnknownProviderQueryParameter
¶
Bases: OptimadeWarning
A provider-specific query parameter has been requested in the query with a prefix not recognised by this implementation.
Source code in optimade/warnings.py
85 86 87 88 89 |
|