h%#dZddlmZddlZddlZddlmZddlmZddl m Z m Z ddl m Z mZmZdd lmZdd lmZdd ZGd d e Zy)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)SchemaResolverct|}t|tr|dn|}|j}|j dr |ddxs|}|j S)zZDefault schema name resolver function that strips 'Schema' from the end of the class name.rrNi)r isinstancelist__name__endswithstrip)schemaresolved schema_clsnames Z/var/www/html/engine/venv/lib/python3.12/site-packages/apispec/ext/marshmallow/__init__.pyresolverrYsS!&)H *8T :!J   D }}XCRy D ::<ceZdZdZeZeZ d d fd Zd fd Z dZ d dZ dZ dZ ddZ d dd Zdd ZxZS)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__ cxt||xst|_d|_d|_d|_d|_yN)super__init__rschema_name_resolverspecopenapi_version converter)selfr! __class__s rr zMarshmallowPlugin.__init__xs: $8$DH!$( /326/3 rct||||_|j|_|j |j|j ||_|j|j|j |_y)N)r#r!r")r#r$) r init_specr"r# Converterr!r$Resolverr)r%r"r&s rr(zMarshmallowPlugin.init_specsu $ #33 00!%!:!:(    00DNN&  rcb|jJd|jj|g|S)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) !init_spec has not yet been called)r$map_to_openapi_type)r% field_clsargss rr-z%MarshmallowPlugin.map_to_openapi_types60~~)N+NN)1t~~11)CdCCrc |yt|}t|}|j||jJd||jj|<|jj |}|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 r warn_if_schema_already_in_specr$refsschema2jsonschema)r%r_rkwargsschema_instance schema_key json_schemas r schema_helperzMarshmallowPlugin.schema_helpersr >1&9$_5  ++J7~~)N+NN)*.J'nn66G rc b|jJd|jj||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. r,rresolve_schema)r% parameterr5s rparameter_helperz"MarshmallowPlugin.parameter_helpers2}}(M*MM( $$Y/rc b|jJd|jj||S)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. r,)rresolve_response)r%responser5s rresponse_helperz!MarshmallowPlugin.response_helpers1}}(M*MM( &&x0rc X|jsJ|jj||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%headerr5s r header_helperzMarshmallowPlugin.header_helpers'}}} $$V, rc V|jsJ|jj|yr)rresolve_operations)r%path operationsr5s roperation_helperz"MarshmallowPlugin.operation_helpers" }}} ((4rc|jsJ||jjvr#tj|ddtdyy)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$r2warningswarn UserWarning)r%r7s rr1z0MarshmallowPlugin.warn_if_schema_already_in_specsL~~~ ,, , MMa=/"<<   -rr)r!z+typing.Callable[[type[Schema]], str] | NonereturnNone)r"rrQrR)rDdictr5 typing.Any)NN)rHz str | NonerIz dict | Noner5rTrQrR)r7tuplerQrR)r __module__ __qualname____doc__r r)r r*r r(r-r9r>rBrErJr1 __classcell__)r&s@rrrcs"!IHMQ 4I 4  4  D6*    "&55 5 5  5 rr)rz type[Schema]rQstr)rX __future__rtypingrN marshmallowrpackaging.versionrapispecrrcommonr r r openapir schema_resolverr rrrrrds?FR# %'PP%+R Rr