o FDi%#@sdZddlmZddlZddlZddlmZddlmZddl m Z m Z ddl m Z mZmZdd lmZdd lmZdddZGddde ZdS)a marshmallow plugin for apispec. Allows passing a marshmallow `Schema` to `spec.components.schema `, `spec.components.parameter `, `spec.components.response ` (for response and headers schemas) and `spec.path ` (for responses and response headers). Requires marshmallow>=3.13.0. ``MarshmallowPlugin`` maps marshmallow ``Field`` classes with OpenAPI types and formats. It inspects field attributes to automatically document properties such as read/write-only, range and length constraints, etc. OpenAPI properties can also be passed as metadata to the ``Field`` instance if they can't be inferred from the field attributes (`description`,...), or to override automatic documentation (`readOnly`,...). A metadata attribute is used in the documentation either if it is a valid OpenAPI property, or if it starts with `"x-"` (vendor extension). .. warning:: ``MarshmallowPlugin`` infers the ``default`` property from the ``load_default`` attribute of the ``Field`` (unless ``load_default`` is a callable). Since default values are entered in deserialized form, the value displayed in the doc is serialized by the ``Field`` instance. This may lead to inaccurate documentation in very specific cases. The default value to display in the documentation can be specified explicitly by passing ``default`` as field metadata. :: from pprint import pprint import datetime as dt from apispec import APISpec from apispec.ext.marshmallow import MarshmallowPlugin from marshmallow import Schema, fields spec = APISpec( title="Example App", version="1.0.0", openapi_version="3.0.2", plugins=[MarshmallowPlugin()], ) class UserSchema(Schema): id = fields.Int(dump_only=True) name = fields.Str(metadata={"description": "The user's name"}) created = fields.DateTime( dump_only=True, dump_default=dt.datetime.utcnow, metadata={"default": "The current datetime"}, ) spec.components.schema("User", schema=UserSchema) pprint(spec.to_dict()["components"]["schemas"]) # {'User': {'properties': {'created': {'default': 'The current datetime', # 'format': 'date-time', # 'readOnly': True, # 'type': 'string'}, # 'id': {'readOnly': True, # 'type': 'integer'}, # 'name': {'description': "The user's name", # 'type': 'string'}}, # 'type': 'object'}} ) annotationsN)Schema)Version)APISpec BasePlugin)make_schema_keyresolve_schema_clsresolve_schema_instance)OpenAPIConverter)SchemaResolverschema type[Schema]returnstrcCsFt|}t|tr |dn|}|j}|dr|ddp|}|S)zZDefault schema name resolver function that strips 'Schema' from the end of the class name.rrNi)r isinstancelist__name__endswithstrip)r resolved schema_clsnamerY/var/www/Datamplify/venv/lib/python3.10/site-packages/apispec/ext/marshmallow/__init__.pyresolverYs  rcseZdZdZeZeZ d%d&fdd Zd'fd d Z d dZ d%ddZ ddZ ddZ d(ddZ  d)d*dd Zd+d#d$ZZS),MarshmallowPluginaAPISpec plugin for translating marshmallow schemas to OpenAPI/JSONSchema format. :param callable schema_name_resolver: Callable to generate the schema definition name. Receives the `Schema` class and returns the name to be used in refs within the generated spec. When working with circular referencing this function must must not return `None` for schemas in a circular reference chain. Example: :: from apispec.ext.marshmallow.common import resolve_schema_cls def schema_name_resolver(schema): schema_cls = resolve_schema_cls(schema) return schema_cls.__name__ Nschema_name_resolver+typing.Callable[[type[Schema]], str] | NonerNonecs0t|pt|_d|_d|_d|_d|_dSN)super__init__rrspecopenapi_version converter)selfr __class__rrr"xs   zMarshmallowPlugin.__init__r#rcsHt|||_|j|_|j|j|j|d|_|j|j|jd|_dS)N)r$rr#)r$r%) r! init_specr#r$ Converterrr%Resolverr)r&r#r'rrr)s  zMarshmallowPlugin.init_speccGs&|jdus Jd|jj|g|RS)a|Set mapping for custom field class. :param type field_cls: Field class to set mapping for. ``*args`` can be: - a pair of the form ``(type, format)`` - a core marshmallow field type (in which case we reuse that type's mapping) Examples: :: # Override Integer mapping class Int32(Integer): # ... ma_plugin.map_to_openapi_type(Int32, 'string', 'int32') # Map to ('integer', None) like Integer class IntegerLike(Integer): # ... ma_plugin.map_to_openapi_type(IntegerLike, Integer) N!init_spec has not yet been called)r%map_to_openapi_type)r& field_clsargsrrrr-sz%MarshmallowPlugin.map_to_openapi_typecKsT|durdSt|}t|}|||jdusJd||jj|<|j|}|S)zDefinition helper that allows using a marshmallow :class:`Schema ` to provide OpenAPI metadata. :param type|Schema schema: A marshmallow Schema class or instance. Nr,)r rwarn_if_schema_already_in_specr%refsschema2jsonschema)r&r_r kwargsschema_instance schema_key json_schemarrr schema_helpers   zMarshmallowPlugin.schema_helpercK"|jdus Jd|j||S)zParameter component helper that allows using a marshmallow :class:`Schema ` in parameter definition. :param dict parameter: parameter fields. May contain a marshmallow Schema class or instance. Nr,rresolve_schema)r& parameterr4rrrparameter_helper z"MarshmallowPlugin.parameter_helpercKr9)zResponse component helper that allows using a marshmallow :class:`Schema ` in response definition. :param dict parameter: response fields. May contain a marshmallow Schema class or instance. Nr,)rresolve_response)r&responser4rrrresponse_helperr>z!MarshmallowPlugin.response_helperheaderdictr4 typing.AnycKs|jsJ|j||S)zHeader component helper that allows using a marshmallow :class:`Schema ` in header definition. :param dict header: header fields. May contain a marshmallow Schema class or instance. r:)r&rBr4rrr header_helpers  zMarshmallowPlugin.header_helperpath str | None operations dict | NonecKs|jsJ|j|dSr )rresolve_operations)r&rFrHr4rrroperation_helpers z"MarshmallowPlugin.operation_helperr6tuplecCs8|jsJ||jjvrtj|ddtdddSdS)zZMethod to warn the user if the schema has already been added to the spec. rzb has already been added to the spec. Adding it twice may cause references to not resolve properly.) stacklevelN)r%r1warningswarn UserWarning)r&r6rrrr0s    z0MarshmallowPlugin.warn_if_schema_already_in_specr )rrrr)r#rrr)rBrCr4rD)NN)rFrGrHrIr4rDrr)r6rLrr)r __module__ __qualname____doc__r r*r r+r"r)r-r8r=rArErKr0 __classcell__rrr'rrcs       r)r rrr)rT __future__rtypingrO marshmallowrpackaging.versionrapispecrrcommonrr r openapir schema_resolverr rrrrrrs I