@|hW- dZddlmZddlZddlZddlZddlmZddlm Z ddl m Z ddl m Z dd lmZmZmZmZdd lmZd d d d dddddZGddeZy)aUtilities for generating OpenAPI Specification (fka Swagger) entities from marshmallow :class:`Schemas ` and :class:`Fields `. .. warning:: This module is treated as private API. Users should not need to use this module directly. ) annotationsN) is_collection)Version)APISpec) APISpecError) get_fieldsget_unique_schema_namemake_schema_keyresolve_schema_instance)FieldConverterMixinpathquerybodyheadercookieformData) match_infor querystringjsonheaderscookiesformfilesceZdZdZ ddZddZddZdZdddd  dd Z dd Z dd Z dd Z dZ dddZ dZy)OpenAPIConverteraAdds methods for generating OpenAPI specification from marshmallow schemas and fields. :param Version|str openapi_version: The OpenAPI version to use. Should be in the form '2.x' or '3.x.x' to comply with the OpenAPI standard. :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. :param APISpec spec: An initialized spec. Nested schemas will be added to the spec ct|tr t|n||_||_||_|j |ji|_yN) isinstancestrropenapi_versionschema_name_resolverspecinit_attribute_functions"init_parameter_attribute_functionsrefs)selfr!r"r#s ^/var/www/html/test/engine/venv/lib/python3.12/site-packages/apispec/ext/marshmallow/openapi.py__init__zOpenAPIConverter.__init__6sS/3/ O $   %9!  %%' //1 c>|j|jg|_yr)field2required list2paramparameter_attribute_functions)r's r(r%z3OpenAPIConverter.init_parameter_attribute_functionsHs    OO. *r*c|j|}t||j||jj |y)aGMethod to add a field parameter function to the list of field parameter functions that will be called on a field to convert it to a field parameter. :param func func: the field parameter function to add The attribute function will be bound to the `OpenAPIConverter ` instance. It will be called for each field in a schema with `self ` and a `field ` instance positional arguments and `ret ` keyword argument. May mutate `ret`. User added field parameter functions will be called after all built-in field parameter functions in the order they were added. N)__get__setattr__name__r.append)r'func bound_funcs r( add_parameter_attribute_functionz1OpenAPIConverter.add_parameter_attribute_functionNs6"\\$' dmmZ0 **11*=r*c t|}t |}||j vr|j |}|s& |j|}t|ddrd|dS|St|jj|}|jjj|||j|S#tjj$r|cYSwxYw#t$r}td|d|d}~wwxYw) aReturn the OpenAPI representation of a marshmallow Schema. Adds the schema to the spec if it isn't already present. Typically will return a dictionary with the reference to the schema's path in the spec unless the `schema_name_resolver` returns `None`, in which case the returned dictionary will contain a JSON Schema Object representation of the schema. :param schema: schema to add to the spec z'Name resolver returned None for schema z which is part of a chain of circular referencing schemas. Please ensure that the schema_name_resolver passed to MarshmallowPlugin returns a string for all circular referencing schemas.NmanyFarraytypeitems)schema)r marshmallow exceptions RegistryErrorr r&r"schema2jsonschema RuntimeErrorrgetattrr r# componentsr= get_ref_dict)r'r=schema_instance schema_keyname json_schemaexcs r(resolve_nested_schemaz&OpenAPIConverter.resolve_nested_schemacs  5f=O %_5 TYY &,,V4D "&"8"8"IK6651$+kBB"")$))*>*>ED II ' 'V ' <  11+%%33 M $&A&J00  s( B7C7CC C:%C55C:rFN)rHrequired descriptionc Ltj||}|dk(r ||||j|d}|r||d<|gSt|ddrJdt |d}|j D cgc]'\}} |j | | jxs|| )c} }Scc} }w) aAReturn an array of OpenAPI parameters given a given marshmallow :class:`Schema `. If `location` is "body", then return an array of a single parameter; else return an array of a parameter for each included field in the :class:`Schema `. In OpenAPI 3, only "query", "header", "path" or "cookie" are allowed for the location of parameters. "requestBody" is used when fields are in the body. https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject r)inrLrHr=rMr8FzNSchemas with many=True are only supported for 'json' location (aka 'in: body')T)exclude_dump_only)rHlocation)__location_map__getrKrCr r<_field2parameterdata_key) r'r=rQrHrLrMparamfields field_name field_objs r(schema2parametersz"OpenAPIConverter.schema2parameterss&$''(; v $44V< E '2m$7N FE  \ [ \ Fd;*0  & I  ! !''5:! "    s0,B cF||d}|j|}|jjdkr|j|n5d|vr|j d|d<d|vr|j d|d<||d<|j D]}|j||||S)zReturn an OpenAPI parameter as a `dict`, given a marshmallow :class:`Field `. https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject )rOrHrM deprecatedr=)ret)field2propertyr!majorupdatepopr.)r'fieldrHrQr^propparam_attr_funcs r(rTz!OpenAPIConverter._field2parameters$T2""5)    % % ) JJt $%)XXm%<M"t#$(HH\$:L! CM#AA 8O JJu#6 7 8 r*c i}t|jdd}|jxr | xst|xr|j|v|d<|S)zReturn the dictionary of OpenAPI parameter attributes for a required field. :param Field field: A marshmallow field. :rtype: dict partialFrL)rCparentrLrrH)r'rckwargsr^rgs r(r,zOpenAPIConverter.field2requiredsT%,, 59.. K QM'2Puzz7P J r*c i}t|tjjr*|jj dkrd|d<|Sd|d<d|d<|S)zReturn a dictionary of parameter properties from :class:`List rWListr!r`)r'rcrir^s r(r-zOpenAPIConverter.list2params^ e[//44 5##))A-*1&' "&I%G  r*ctt|}t|dd}t|dd}|j||}t|dr|j|d<t|dr|j |d<t|dr=|j tjk7r |j tjk(|d<|S) aReturn the JSON Schema Object for a given marshmallow :class:`Schema ` instance. Schema may optionally provide the ``title`` and ``description`` class Meta options. https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject :param Schema schema: A marshmallow Schema instance :rtype: dict, a JSON Schema Object MetaNrgrgtitlerMunknownadditionalProperties) r rCfields2jsonschemahasattrrsrMrtr>EXCLUDEINCLUDE)r'r=rWrqrg jsonschemas r(rAz"OpenAPIConverter.schema2jsonschemasF#vvt,&)T2++FG+D 4 !"&**Jw  4 '(,(8(8J} % 4 # 8K8K(K15ATAT1TJ- .r*rrcBdid}|jD]o\}}|jxs|}|j|}||d|<|js<|rt |sJ||vsO|j dgj |qd|vr|dj|S)aReturn the JSON Schema Object given a mapping between field names and :class:`Field ` objects. :param dict fields: A dictionary of field name field object pairs :param bool|tuple partial: Whether to override a field's required flag. If `True` no fields will be set as required. If an iterable fields in the iterable will not be marked as required. :rtype: dict, a JSON Schema Object object)r; propertiesr}rL)r<rUr_rLr setdefaultr3sort)r'rWrgrzrXrYobserved_field_namerds r(rvz"OpenAPIConverter.fields2jsonschema s'b9 %+\\^ V !J "+"4"4"B &&y1D<@J| $%8 9!!!'*z/H))*b9@@ATU V  # z " ' ' )r*ct|}|jjjd|j|}t |ddrd|dS|S)zdMethod to create a dictionary containing a JSON reference to the schema in the spec r=r8Fr9r:)r r#rDget_refr&rC)r'r=rG ref_schemas r(rEzOpenAPIConverter.get_ref_dict&sP%V, YY))11(DIIj*%2X"&-  -  -  - ^-8;GJ 2 - 9C    2488r*r)r __future__rtypingr>marshmallow.exceptionsmarshmallow.utilsrpackaging.versionrapispecrapispec.exceptionsrcommonr r r r field_converterr rRrrr*r(rsd# +%+ 1     D*Dr*