Skip to content

query

Data models related to OPTIMADE queries.

QUERY_PARAMETERS = {'annotations': {name: FieldInfo.from_annotation(parameter.annotation)for (name, parameter) in inspect.signature(EntryListingQueryParams).parameters.items()}, 'defaults': EntryListingQueryParams()} module-attribute

Entry listing URL query parameters from the optimade package (EntryListingQueryParams).

OPTIMADEQueryParameters

Bases: BaseModel

Common OPTIMADE entry listing endpoint query parameters.

Source code in oteapi_optimade/models/query.py 
 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
class OPTIMADEQueryParameters(BaseModel, validate_assignment=True):
    """Common OPTIMADE entry listing endpoint query parameters."""

    filter: Annotated[
        Optional[str],
        Field(
            description=QUERY_PARAMETERS["annotations"]["filter"].description,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].filter or None
    )
    response_format: Annotated[
        Optional[str],
        Field(
            description=QUERY_PARAMETERS["annotations"]["response_format"].description,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].response_format or None
    )
    email_address: Annotated[
        Optional[EmailStr],
        Field(
            description=QUERY_PARAMETERS["annotations"]["email_address"].description,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].email_address or None
    )
    response_fields: Annotated[
        Optional[str],
        Field(
            description=QUERY_PARAMETERS["annotations"]["response_fields"].description,
            pattern=QUERY_PARAMETERS["annotations"]["response_fields"]
            .metadata[0]
            .pattern,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].response_fields or None
    )
    sort: Annotated[
        Optional[str],
        Field(
            description=QUERY_PARAMETERS["annotations"]["sort"].description,
            pattern=QUERY_PARAMETERS["annotations"]["sort"].metadata[0].pattern,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].sort or None
    )
    page_limit: Annotated[
        Optional[int],
        Field(
            description=QUERY_PARAMETERS["annotations"]["page_limit"].description,
            ge=QUERY_PARAMETERS["annotations"]["page_limit"].metadata[0].ge,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].page_limit or None
    )
    page_offset: Annotated[
        Optional[int],
        Field(
            description=QUERY_PARAMETERS["annotations"]["page_offset"].description,
            ge=QUERY_PARAMETERS["annotations"]["page_offset"].metadata[0].ge,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].page_offset or None
    )
    page_number: Annotated[
        Optional[int],
        Field(
            description=QUERY_PARAMETERS["annotations"]["page_number"].description,
            # ge=QUERY_PARAMETERS["annotations"]["page_number"].metadata[0].ge,
            # This constraint is only 'RECOMMENDED' in the specification, so should not
            # be included here or in the OpenAPI schema.
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].page_number or None
    )
    page_cursor: Annotated[
        Optional[int],
        Field(
            description=QUERY_PARAMETERS["annotations"]["page_cursor"].description,
            ge=QUERY_PARAMETERS["annotations"]["page_cursor"].metadata[0].ge,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].page_cursor or None
    )
    page_above: Annotated[
        Optional[int],
        Field(
            description=QUERY_PARAMETERS["annotations"]["page_above"].description,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].page_above or None
    )
    page_below: Annotated[
        Optional[int],
        Field(
            description=QUERY_PARAMETERS["annotations"]["page_below"].description,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].page_below or None
    )
    include: Annotated[
        Optional[str],
        Field(
            description=QUERY_PARAMETERS["annotations"]["include"].description,
        ),
    ] = (
        QUERY_PARAMETERS["defaults"].include or None
    )
    # api_hint is not yet initialized in `EntryListingQueryParams`.
    # These values are copied verbatim from `optimade==0.16.10`.
    api_hint: Annotated[
        Optional[str],
        Field(
            description=(
                "If the client provides the parameter, the value SHOULD have the format "
                "`vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a"
                " minor version of the API. For example, if a client appends "
                "`api_hint=v1.0` to the query string, the hint provided is for major "
                "version 1 and minor version 0."
            ),
            pattern=r"(v[0-9]+(\.[0-9]+)?)?",
        ),
    ] = ""

    def generate_query_string(self) -> str:
        """Generate a valid URL query string based on the set fields."""
        res = {}
        for field, value in self.model_dump().items():
            if value or field in self.model_fields_set:
                res[field] = unquote(value) if isinstance(value, str) else value
        return urlencode(res, quote_via=quote)

api_hint: Annotated[Optional[str], Field(description='If the client provides the parameter, the value SHOULD have the format `vMAJOR` or `vMAJOR.MINOR`, where MAJOR is a major version and MINOR is a minor version of the API. For example, if a client appends `api_hint=v1.0` to the query string, the hint provided is for major version 1 and minor version 0.', pattern='(v[0-9]+(\\.[0-9]+)?)?')] = '' class-attribute instance-attribute

email_address: Annotated[Optional[EmailStr], Field(description=QUERY_PARAMETERS['annotations']['email_address'].description)] = QUERY_PARAMETERS['defaults'].email_address or None class-attribute instance-attribute

filter: Annotated[Optional[str], Field(description=QUERY_PARAMETERS['annotations']['filter'].description)] = QUERY_PARAMETERS['defaults'].filter or None class-attribute instance-attribute

include: Annotated[Optional[str], Field(description=QUERY_PARAMETERS['annotations']['include'].description)] = QUERY_PARAMETERS['defaults'].include or None class-attribute instance-attribute

page_above: Annotated[Optional[int], Field(description=QUERY_PARAMETERS['annotations']['page_above'].description)] = QUERY_PARAMETERS['defaults'].page_above or None class-attribute instance-attribute

page_below: Annotated[Optional[int], Field(description=QUERY_PARAMETERS['annotations']['page_below'].description)] = QUERY_PARAMETERS['defaults'].page_below or None class-attribute instance-attribute

page_cursor: Annotated[Optional[int], Field(description=QUERY_PARAMETERS['annotations']['page_cursor'].description, ge=QUERY_PARAMETERS['annotations']['page_cursor'].metadata[0].ge)] = QUERY_PARAMETERS['defaults'].page_cursor or None class-attribute instance-attribute

page_limit: Annotated[Optional[int], Field(description=QUERY_PARAMETERS['annotations']['page_limit'].description, ge=QUERY_PARAMETERS['annotations']['page_limit'].metadata[0].ge)] = QUERY_PARAMETERS['defaults'].page_limit or None class-attribute instance-attribute

page_number: Annotated[Optional[int], Field(description=QUERY_PARAMETERS['annotations']['page_number'].description)] = QUERY_PARAMETERS['defaults'].page_number or None class-attribute instance-attribute

page_offset: Annotated[Optional[int], Field(description=QUERY_PARAMETERS['annotations']['page_offset'].description, ge=QUERY_PARAMETERS['annotations']['page_offset'].metadata[0].ge)] = QUERY_PARAMETERS['defaults'].page_offset or None class-attribute instance-attribute

response_fields: Annotated[Optional[str], Field(description=QUERY_PARAMETERS['annotations']['response_fields'].description, pattern=QUERY_PARAMETERS['annotations']['response_fields'].metadata[0].pattern)] = QUERY_PARAMETERS['defaults'].response_fields or None class-attribute instance-attribute

response_format: Annotated[Optional[str], Field(description=QUERY_PARAMETERS['annotations']['response_format'].description)] = QUERY_PARAMETERS['defaults'].response_format or None class-attribute instance-attribute

sort: Annotated[Optional[str], Field(description=QUERY_PARAMETERS['annotations']['sort'].description, pattern=QUERY_PARAMETERS['annotations']['sort'].metadata[0].pattern)] = QUERY_PARAMETERS['defaults'].sort or None class-attribute instance-attribute

generate_query_string()

Generate a valid URL query string based on the set fields.

Source code in oteapi_optimade/models/query.py 
151
152
153
154
155
156
157
def generate_query_string(self) -> str:
    """Generate a valid URL query string based on the set fields."""
    res = {}
    for field, value in self.model_dump().items():
        if value or field in self.model_fields_set:
            res[field] = unquote(value) if isinstance(value, str) else value
    return urlencode(res, quote_via=quote)