Skip to content

flask_restx_marshmallow.type ¤

Type hints for flask_restx_marshmallow.

APISpec ¤

APISpec(
    title: str,
    version: str,
    openapi_version: str,
    plugins: Sequence[BasePlugin] = (),
    **options: Any,
)

Bases: APISpec

Stores metadata that describes a RESTful API using the OpenAPI specification.

Parameters:

Name Type Description Default

title ¤

 str

API title

 required

version ¤

 str

API version

 required

plugins ¤

 Iterable[Plugin]

Plugin instances. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject

 ()

openapi_version ¤

 str

OpenAPI Specification version. Should be in the form '2.x' or '3.x.x' to comply with the OpenAPI standard.

 required

options ¤

 Any

Optional top-level keys See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object

 {}

Stores metadata that describes a RESTful API using the OpenAPI specification.

Parameters:

Name Type Description Default

title ¤

 str

API title

 required

version ¤

 str

API version

 required

plugins ¤

 Iterable[Plugin]

Plugin instances. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject.

 ()

openapi_version ¤

 str

OpenAPI Specification version. Should be in the form '2.x' or '3.x.x' to comply with the OpenAPI standard.

 required

options ¤

 Any

Optional top-level keys See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object

 {}
Source code in flask_restx_marshmallow/type.py 
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
@override
def __init__(
    self,
    title: str,
    version: str,
    openapi_version: str,
    plugins: Sequence[BasePlugin] = (),
    **options: Any,
) -> None:
    """Stores metadata that describes a RESTful API using the OpenAPI specification.

    Args:
        title (str): API title
        version (str): API version
        plugins (Iterable[Plugin]): Plugin instances. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject.
        openapi_version (str): OpenAPI Specification version. Should be in the form\
            '2.x' or '3.x.x' to comply with the OpenAPI standard.
        options: Optional top-level keys See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object

    """
    super().__init__(title, version, openapi_version, plugins, **options)
    self.components = APISpecComponents(
        plugins=self.plugins,
        openapi_version=self.openapi_version,
    )

paths property ¤

paths: Mapping[str, PathItem]

Get paths.

tags property ¤

tags: list[Tag]

Get tags.

APISpecComponents ¤

Bases: Components

Stores components that describe objects used in the API.

ApiInitAPPKwargs ¤

Bases: TypedDict

Api init_app kwargs.

ApiInitKwargs ¤

Bases: TypedDict

Api init kwargs.

Apidoc ¤

Bases: TypedDict

apidoc values.

ClassSchemaKwargs ¤

Bases: TypedDict

Class schema kwargs.

Components ¤

Bases: TypedDict

components object.

Contact ¤

Bases: TypedDict

contact object.

Discriminator ¤

Bases: TypedDict

discriminator object.

Encoding ¤

Bases: TypedDict

encoding object.

Error dataclass ¤

Error(
    code: ResponseCode = ERROR,
    message: str | Mapping[str, list[str]] | None = None,
)

error response.

Source code in flask_restx_marshmallow/type.py 
197
198
199
200
201
202
@override
def __init__(
    self,
    code: ResponseCode = ResponseCode.ERROR,
    message: str | Mapping[str, list[str]] | None = None,
) -> "_Error": ...  # type: ignore[override]

__new__ ¤

__new__(
    code: ResponseCode = ERROR,
    message: str | Mapping[str, list[str]] | None = None,
) -> _Error

Error response.

Source code in flask_restx_marshmallow/type.py 
184
185
186
187
188
189
190
191
192
193
def __new__(
    cls,
    code: ResponseCode = ResponseCode.ERROR,
    message: str | Mapping[str, list[str]] | None = None,
) -> "_Error":
    """Error response."""
    instance = super().__new__(cls)
    instance.code = code
    instance.message = message
    return cast("_Error", filter_none(asdict(instance)))

Example ¤

Bases: TypedDict

example object.

ExternalDocs ¤

Bases: TypedDict

External Documentation Object.

FieldLocations ¤

Bases: NamedTuple

Non-body Field Locations.

GenericParameters ¤

GenericParameters(
    *,
    location: Location
    | Literal[
        "query",
        "header",
        "formData",
        "body",
        "cookie",
        "path",
    ]
    | None = None,
    **kwargs: Unpack[SchemaInitKwargs],
)

Bases: Parameters

Generic parameters.

Base Parameters.

Parameters:

Name Type Description Default

location ¤

 Location

location of the parameters. Defaults to None.

 None

kwargs ¤

 dict

other key word arguments.

 {}
Source code in flask_restx_marshmallow/parameter.py 
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
def __init__(
    self: Self,
    *,
    location: Location
    | Literal["query", "header", "formData", "body", "cookie", "path"]
    | None = None,
    **kwargs: Unpack["SchemaInitKwargs"],
) -> None:
    """Base Parameters.

    Args:
        location (Location, optional): location of the parameters. Defaults to None.
        kwargs (dict): other key word arguments.
    """
    super().__init__(**kwargs)
    self.location: (
        Location
        | Literal["query", "header", "formData", "body", "cookie", "path"]
        | None
    ) = location
    if location is not None:
        self.default_location = Location(location)
    for field in self.fields.values():
        field.load_only = True
        if location is not None:
            if isinstance(location, str):
                location = self.default_location
            set_location(field, location)

Meta ¤

Meta for Parameters.

__contains__ ¤

__contains__(field: str) -> bool

Whether field in self.fields.

Parameters:

Name Type Description Default

field ¤

 str

field name

 required

Returns:

Name Type Description
bool bool

whether field in self.fields
Source code in flask_restx_marshmallow/parameter.py 
 96
 97
 98
 99
100
101
102
103
104
105
def __contains__(self: Self, field: str) -> bool:
    """Whether field in self.fields.

    Args:
        field (str): field name

    Returns:
        bool: whether field in self.fields
    """
    return field in self.fields

__or__ ¤

__or__(other: Parameters) -> Parameters

Combine two schemas.

Parameters:

Name Type Description Default

other ¤

 Self

other schema

 required

Returns:

Name Type Description
Self Parameters

combined schema
Source code in flask_restx_marshmallow/parameter.py 
157
158
159
160
161
162
163
164
165
166
167
168
def __or__(self, other: "Parameters") -> "Parameters":
    """Combine two schemas.

    Args:
        other (Self): other schema

    Returns:
        Self: combined schema
    """
    return self.from_dict(other.fields, name=other.__class__.__name__)(
        location=other.location,
    )

__setitem__ ¤

__setitem__(key: str, value: Field) -> None

Set item.

Source code in flask_restx_marshmallow/parameter.py 
116
117
118
def __setitem__(self: Self, key: str, value: "Field") -> None:
    """Set item."""
    self.fields[key] = value

combine ¤

combine(other: Parameters) -> Parameters

Combine two schemas.

Parameters:

Name Type Description Default

other ¤

 Self

other schema

 required

Returns:

Name Type Description
Self Parameters

combined schema
Source code in flask_restx_marshmallow/parameter.py 
144
145
146
147
148
149
150
151
152
153
154
155
def combine(self: Self, other: "Parameters") -> "Parameters":
    """Combine two schemas.

    Args:
        other (Self): other schema

    Returns:
        Self: combined schema
    """
    return self.from_dict(other.fields, name=other.__class__.__name__)(
        location=other.location,
    )

copy_body_fields ¤

copy_body_fields() -> Parameters

Return a copy of this schema with only fields that location is body.

Source code in flask_restx_marshmallow/parameter.py 
120
121
122
123
124
125
126
127
128
129
130
def copy_body_fields(self: Self) -> "Parameters":
    """Return a copy of this schema with only fields that location is body."""
    return Parameters.from_dict(
        dict(
            filter(
                lambda field: get_location(field[1]) is Location.BODY,
                self.fields.items(),
            ),
        ),
        name=f"{type(self).__name__}Body",
    )(location=Location.BODY)

copy_form_fields ¤

copy_form_fields() -> Parameters

Return a copy of this schema with only fields that location is formdata.

Source code in flask_restx_marshmallow/parameter.py 
132
133
134
135
136
137
138
139
140
141
142
def copy_form_fields(self: Self) -> "Parameters":
    """Return a copy of this schema with only fields that location is formdata."""
    return Parameters.from_dict(
        dict(
            filter(
                lambda field: get_location(field[1]) is Location.FORM_DATA,
                self.fields.items(),
            ),
        ),
        name=f"{type(self).__name__}Form",
    )(location=Location.FORM_DATA)

field_locations ¤

field_locations() -> list[FieldLocations]

Get (field_name, location, is_multiple) for each non-body field.

Returns:

Type Description
list[FieldLocations]

list[FieldLocations]: field name, location, is multiple
Source code in flask_restx_marshmallow/parameter.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
@cached_property
def field_locations(self: Self) -> list[FieldLocations]:
    """Get (field_name, location, is_multiple) for each non-body field.

    Returns:
        list[FieldLocations]: field name, location, is multiple
    """
    return [
        FieldLocations(
            name,
            location or self.default_location,
            isinstance(field, List | Tuple),
        )
        for name, field in self.fields.items()
        if (location := get_location(field)) is not Location.BODY
    ]

items ¤

items() -> Iterable[tuple[str, dict]]

Make dict.

Yields:

Type Description
Iterable[tuple[str, dict]]

tuple[str, dict]: field name and field dict
Source code in flask_restx_marshmallow/parameter.py 
107
108
109
110
111
112
113
114
def items(self: Self) -> "Iterable[tuple[str, dict]]":
    """Make dict.

    Yields:
        tuple[str, dict]: field name and field dict
    """
    for key, value in self.fields.items():
        yield key, value.__dict__

locations ¤

locations() -> set[str]

Get locations.

Returns:

Type Description
set[str]

set[str]: locations
Source code in flask_restx_marshmallow/parameter.py 
67
68
69
70
71
72
73
74
75
76
77
@cached_property
def locations(self: Self) -> set[str]:
    """Get locations.

    Returns:
        set[str]: locations
    """
    return {
        get_location(field) or self.default_location
        for field in self.fields.values()
    }

Header ¤

Bases: TypedDict

header object.

HttpSecurityScheme ¤

Bases: TypedDict

http security scheme object.

Info ¤

Bases: TypedDict

info object.

License ¤

Bases: TypedDict

license object.

Bases: TypedDict

link object.

MarshmallowPlugin ¤

Bases: MarshmallowPlugin

APISpec plugin for translating marshmallow schemas to OpenAPI format.

MediaType ¤

Bases: TypedDict

mediaType object.

MutualTLSSecurityScheme ¤

Bases: TypedDict

mutualTLS security scheme object.

OAuth2SecurityScheme ¤

Bases: TypedDict

oauth2 security scheme object.

OAuthFlow ¤

Bases: TypedDict

oauth flow object.

OAuthFlows ¤

Bases: TypedDict

oauth flows object.

OneOf ¤

Bases: TypedDict

oneOf object.

OpenAPI ¤

Bases: TypedDict

openapi object.

OpenAPIConverter ¤

Bases: OpenAPIConverter

Patched OpenAPIConverter.

Adds methods for generating OpenAPI specification from marshmallow schemas and fields.

OpenIdConnectSecurityScheme ¤

Bases: TypedDict

openIdConnect security scheme object.

Operation ¤

Bases: TypedDict

operation object.

RequestBody ¤

Bases: TypedDict

requestBody object.

ResourceRoute ¤

Bases: NamedTuple

Resource route.

Result ¤

Result(items: list[T], total: int)

Bases: TypedDict

data.

Source code in flask_restx_marshmallow/type.py 
114
115
@override
def __init__(self, items: list[T], total: int) -> "Result[T]": ...  # type: ignore[override]

SchemaInitKwargs ¤

Bases: TypedDict

Schema init kwargs.

Server ¤

Bases: TypedDict

server object.

Success dataclass ¤

Success(
    code: ResponseCode = SUCCESS,
    message: str | None = None,
    result: Result[T] | T | None = None,
)

success response.

Source code in flask_restx_marshmallow/type.py 
161
162
163
164
165
166
167
@override
def __init__(
    self,
    code: ResponseCode = ResponseCode.SUCCESS,
    message: str | None = None,
    result: Result[T] | T | None = None,
) -> "_Success[T]": ...  # type: ignore[override]

__new__ ¤

__new__(
    code: ResponseCode = SUCCESS,
    message: str | None = None,
    result: Result[T] | T | None = None,
) -> _Success[T]

Success response.

Source code in flask_restx_marshmallow/type.py 
146
147
148
149
150
151
152
153
154
155
156
157
def __new__(
    cls,
    code: ResponseCode = ResponseCode.SUCCESS,
    message: str | None = None,
    result: Result[T] | T | None = None,
) -> "_Success[T]":
    """Success response."""
    instance = super().__new__(cls)
    instance.code = code
    instance.message = message
    instance.result = result
    return cast("_Success[T]", filter_none(asdict(instance)))

SwaggerResponse ¤

Bases: TypedDict

response object.

Tag ¤

Bases: TypedDict

tag object.

TupleResponse ¤

Bases: NamedTuple

tuple response.

Variable ¤

Bases: TypedDict

server variable object.

Warn dataclass ¤

Warn(
    code: ResponseCode = WARNING, message: str | None = None
)

warning response.

Source code in flask_restx_marshmallow/type.py 
232
233
234
235
236
237
@override
def __init__(
    self,
    code: ResponseCode = ResponseCode.WARNING,
    message: str | None = None,
) -> "_Warn": ...  # type: ignore[override]

__new__ ¤

__new__(
    code: ResponseCode = WARNING, message: str | None = None
) -> _Warn

Warning response.

Source code in flask_restx_marshmallow/type.py 
219
220
221
222
223
224
225
226
227
228
def __new__(
    cls,
    code: ResponseCode = ResponseCode.WARNING,
    message: str | None = None,
) -> "_Warn":
    """Warning response."""
    instance = super().__new__(cls)
    instance.code = code
    instance.message = message
    return cast("_Warn", filter_none(asdict(instance)))

Xml ¤

Bases: TypedDict

xml object.

filter_none ¤

filter_none(data: Mapping) -> dict

Filter None values.

Parameters:

Name Type Description Default

data ¤

 Mapping

data

 required

Returns:

Name Type Description
dict dict

filtered data
Source code in flask_restx_marshmallow/type.py 
118
119
120
121
122
123
124
125
126
127
def filter_none(data: Mapping) -> dict:
    """Filter None values.

    Args:
        data (Mapping): data

    Returns:
        dict: filtered data
    """
    return {k: v for k, v in data.items() if v is not None}