U dr@sddlZddlZddlmZddlZddlZddlZddlZddlZddl m Z ddl m Z m Z ddlmZddlmZmZmZddlmZzddlmZWn ek rddlmZYnXdd lmZdd lmZdd lmZdd l m!Z!dd l"m#Z#m$Z$m%Z%m&Z&m'Z'ddl(m)Z*e*+dddkr8ddl,m-Z.n ddl,m.Z.ddl/m0Z0ddl1m2Z2m3Z3ddl4m5Z5ddl6m7Z7ddl8m9Z9ddl:m;Z;ddlZ>m?Z?ddl@mAZAddlBmCZCeDdZEdZFdeAfgZGeHeIZJGd d!d!eKZLGd"d#d#e9ZMd$d%ZNd&d'ZOdS)(N)chain) OrderedDict)wrapspartial) MethodType)url_forrequest current_app) make_response)_endpoint_from_view_func)got_request_exception) RefResolver)cached_property)Headers) HTTPExceptionMethodNotAllowedNotFound NotAcceptableInternalServerError) __version__.2)Response) BaseResponse)apidoc) ParseError MaskError) Namespace)PostmanCollectionV1)Resource)Swagger) default_id camel_to_dashunpack) output_json) HTTPStatusz(<.*>))zContent-Lengthapplication/jsonc@seZdZdZdddddddddddddeddddddd dddddd fd d Zd dZddZddZddZ ddZ ddZ ddZ ddZ ddZdd Zd!d"Zd#d$Zd%d&Zd'd(Zd)d*Zd+d,Zd-d.Zd/d0Zded1d2Zd3d4Zd5d6Zed7d8Zed9d:Zed;d<Zed=d>Z ed?d@Z!dAdBZ"dCdDZ#dEdFZ$dGdHZ%dIdJZ&dKdLZ'dMdNZ(dfdOdPZ)dgdQdRZ*edSdTZ+edUdVZ,e-dhdWdXZ.dYdZZ/d[d\Z0d]d^Z1d_d`Z2dadbZ3dcddZ4dS)iApia The main entry point for the application. You need to initialize it with a Flask Application: :: >>> app = Flask(__name__) >>> api = Api(app) Alternatively, you can use :meth:`init_app` to set the Flask application after it has been constructed. The endpoint parameter prefix all views and resources: - The API root/documentation will be ``{endpoint}.root`` - A resource registered as 'resource' will be available as ``{endpoint}.resource`` :param flask.Flask|flask.Blueprint app: the Flask application object or a Blueprint :param str version: The API version (used in Swagger documentation) :param str title: The API title (used in Swagger documentation) :param str description: The API description (used in Swagger documentation) :param str terms_url: The API terms page URL (used in Swagger documentation) :param str contact: A contact email for the API (used in Swagger documentation) :param str license: The license associated to the API (used in Swagger documentation) :param str license_url: The license page URL (used in Swagger documentation) :param str endpoint: The API base endpoint (default to 'api). :param str default: The default namespace base name (default to 'default') :param str default_label: The default namespace label (used in Swagger documentation) :param str default_mediatype: The default media type to return :param bool validate: Whether or not the API should perform input payload validation. :param bool ordered: Whether or not preserve order models and marshalling. :param str doc: The documentation path. If set to a false value, documentation is disabled. (Default to '/') :param list decorators: Decorators to attach to every resource :param bool catch_all_404s: Use :meth:`handle_error` to handle 404 errors throughout your app :param dict authorizations: A Swagger Authorizations declaration as dictionary :param bool serve_challenge_on_401: Serve basic authentication challenge with 401 responses (default 'False') :param FormatChecker format_checker: A jsonschema.FormatChecker object that is hooked into the Model validator. A default or a custom FormatChecker can be provided (e.g., with custom checkers), otherwise the default action is to not enforce any format validation. :param url_scheme: If set to a string (e.g. http, https), then the specs_url and base_url will explicitly use this scheme regardless of how the application is deployed. This is necessary for some deployments behind a reverse proxy. :param str default_swagger_filename: The default swagger filename. Nz1.0/defaultzDefault namespaceFr'z swagger.jsoncKsJ||_|p d|_||_||_||_| |_| |_||_||_| |_ | |_ ||_ ||_ ||_ | |_d|_d|_|ppg|_ttttti|_d|_i|_d|_||_g|_||_t|_tt |_!i|_"||_#||_$|r|ng|_%||_&||_'d|_(t)|_*g|_+d|_,d|_-|j.||d/|||dd|_0||_1|dk rF||_,|2|dS)NZAPIz{0}-declarationr))endpointvalidateapipath)3versiontitle description terms_urlcontact contact_email contact_urllicense license_urlauthorizationssecurityr"ordered _validate_doc _doc_view_default_error_handlertagsrrmask_parse_error_handlerrmask_error_handlererror_handlers_schemamodels _refresolverformat_checker namespacesdefault_swagger_filenamedictns_pathsDEFAULT_REPRESENTATIONSrepresentationsurlsprefixdefault_mediatype decoratorscatch_all_404sserve_challenge_on_401blueprint_setupset endpoints resourcesapp blueprint namespaceformatdefault_namespace url_schemeinit_app)selfrXr0r1r2r3r7r8r4r6r5r9r:docr"r*Z default_labelr-r@rOr;rPrQrRrSrGr]rIkwargsrb3/tmp/pip-unpacked-wheel-dt_sn2ih/flask_restx/api.py__init__msp    z Api.__init__cKs||_|d|j|_|d|j|_|d|j|_|d|j|_|d|j|_|d|j|_|d|j|_|d|j |_ |d |j |_ |d d |_ | || |z||jWntk r||YnX||_d S) a Allow to lazy register the API on a Flask application:: >>> app = Flask(__name__) >>> api = Api() >>> api.init_app(app) :param flask.Flask app: the Flask application object :param str title: The API title (used in Swagger documentation) :param str description: The API description (used in Swagger documentation) :param str terms_url: The API terms page URL (used in Swagger documentation) :param str contact: A contact email for the API (used in Swagger documentation) :param str license: The license associated to the API (used in Swagger documentation) :param str license_url: The license page URL (used in Swagger documentation) :param url_scheme: If set to a string (e.g. http, https), then the specs_url and base_url will explicitly use this scheme regardless of how the application is deployed. This is necessary for some deployments behind a reverse proxy. r1r2r3r4r6r5r7r8r]Z add_specsTN)rXgetr1r2r3r4r6r5r7r8r] _add_specs_register_specs _register_docrecord_deferred_blueprint_initAttributeError _init_apprY)r_rXrarbrbrcr^s$  z Api.init_appcCst|j|j|_t|j|j|_t|jdkrX|jD]"\}}}}|j|||f||q4|jD]}|||q^| ||j dk r|j n |j dd|_ |j dd|j dd|j d dd |j kr|j d |j d <td tdS) z Perform initialization actions with the given :class:`flask.Flask` object. :param flask.Flask app: The flask application object rNZRESTX_VALIDATEFZRESTX_MASK_HEADERzX-FieldsZRESTX_MASK_SWAGGERTZRESTX_INCLUDE_ALL_MODELSZERROR_404_HELPRESTX_ERROR_404_HELPzt'ERROR_404_HELP' config setting is deprecated and will be removed in the future. Use 'RESTX_ERROR_404_HELP' instead.)r error_routerZhandle_exceptionZhandle_user_exceptionlenrW_register_viewrH_configure_namespace_logger_register_apidocr<configre setdefaultwarningswarnDeprecationWarning)r_rXresourcerZrNransrbrbrcrls0    z Api._init_appcCs6zt|j|WStk r0td|YnXdS)NzApi does not have {0} attribute)getattrr\rkr[r_namerbrbrc __getattr__szApi.__getattr__cCs ||j|f}ddd|DS)ar This method is used to defer the construction of the final url in the case that the Api is created with a Blueprint. :param url_part: The part of the url the endpoint is registered with :param registration_prefix: The part of the url contributed by the blueprint. Generally speaking, BlueprintSetupState.url_prefix r+css|]}|r|VqdSNrb).0partrbrbrc )sz$Api._complete_url..)rOjoin)r_Zurl_partZregistration_prefixpartsrbrbrc _complete_urls zApi._complete_urlcCs2|jdi}|dds&|tjd|d<dS)NZrestxZapidoc_registeredFT) extensionsrtreZregister_blueprintr)r_rXconfrbrbrcrr+s  zApi._register_apidoccCs>|jr:td}|j|t|jd|j||fd|j|dS)Nspecsr))r,resource_class_args)rfstrrp SwaggerViewr\rIrVadd)r_app_or_blueprintr,rbrbrcrg1szApi._register_specscCs8|jr|jr||jd|j||jp*dd|jdS)Nr`r)root)rfr= add_url_rule render_docrO render_root)r_rrbrbrcrh>s zApi._register_doccOsp|dd}t|p|||}||d<|j||jdk rX|j|j||f||n|j||||f|S)Nr,) poprdefault_endpointrVrrXrprWappend)r_rZrxrNrar,rbrbrcregister_resourceDs   zApi.register_resourcecCs.|jjD]}|j|q|j|jjdSr~)loggerhandlers addHandlersetLevellevel)r_rXrZhandlerrbrbrcrqQs zApi._configure_namespace_loggercOs|ddpt|j}|dd}|di}|t|dikrl|j|jd} | |krld} t| || jf||_||_ | |j ||f||} t |j |j D] } | | } q|D]\} |jr|jr|jj| fd| i|qqt|j| }n || d }|j|fd| i|qdS) Nr,rrbresource_class_kwargsview_functionsZ view_classz2This endpoint (%s) is already set to the class %s. view_funcr+)rr#__name__rzr__dict__ ValueErrormediatypes_method mediatypesr,outputZas_viewrrQrYrTrrr)r_rXrxrZrNrar,rrZprevious_view_classmsgZ resource_func decoratorurlrulerbrbrcrpVsH     zApi._register_viewcstfdd}|S)z Wraps a resource (as a flask view function), for cases where the resource does not directly return a response object :param resource: The resource as a flask view function cs6||}t|tr|St|\}}}j|||dS)N)headers) isinstancerr$r )argsrarespdatacoderrxr_rbrcwrappers   zApi.output..wrapper)r)r_rxrrbrrcrsz Api.outputcOs|ddp|j}tjj|j|d}|dkr2t||jkr`|j||f||}||jd<|S|dkrtt |f||}d|jd<|St dS)a Looks up the representation transformer for the requested media type, invoking the transformer to create a response object. This defaults to default_mediatype if no transformer is found for the requested mediatype. If default_mediatype is None, a 406 Not Acceptable response will be sent as per RFC 2616 section 14.1 :param data: Python object containing response data to be transformed fallback_mediatypeN)r*z Content-Type text/plain) rrPraccept_mimetypes best_matchrMrroriginal_flask_make_responserr)r_rrrarP mediatyperrbrbrcr s"    zApi.make_responsecCs ||_|S)z)r_funcrbrbrc documentationszApi.documentationcCs|tjdSr~)abortr& NOT_FOUNDr_rbrbrcrszApi.render_rootcCs*|jr|S|js |tjt|S)z8Override this method to customize the documentation page)r>r=rr&rrZui_forrrbrbrcrs  zApi.render_doccCs\t|j}||jk r"dj||d}||jkrXd}dj||d}||jkrN|}qX|d7}q0|S)a Provide a default endpoint for a resource on a given namespace. Endpoints are ensured not to collide. Override this method specify a custom algorithm for default endpoint. :param Resource resource: the resource for which we want an endpoint :param Namespace namespace: the namespace holding the resource :returns str: An endpoint name z{ns.name}_{endpoint})ryr,z{base}_{suffix})basesuffixr)r#rr\r[rV)r_rxrZr,rZ new_endpointrbrbrcrs     zApi.default_endpointcCs |j|Sr~)rKre)r_ryrbrbrc get_ns_pathszApi.get_ns_pathcs"||p|jfdd|DS)Ncsg|] }|qSrbrb)rrr/rbrc szApi.ns_urls..)rr/)r_ryrNrbrrcns_urlssz Api.ns_urlscCs||jkr>|j|||jkr,|j||dk r>||j|<|jD]*}|||j}|j||jf||j qD|j D]\}}||j |<qz|j s|j dk r||j |dS)a This method registers resources from namespace for current instance of api. You can use argument path for definition custom prefix url for namespace. :param Namespace ns: the namespace :param path: registration prefix of namespace N)rHrZapisrKrWrrNrrxrarEitemsrYrXrq)r_ryr/rrNr|Z definitionrbrbrc add_namespaces       zApi.add_namespacecOs*|d|j|d<t||}|||S)z\ A namespace factory. :returns Namespace: a new namespace instance r;)rer;rr)r_rraryrbrbrcrZs  z Api.namespacecCs|jrd|jj|S|SdS)N{0}.{1})rYr[r|r{rbrbrcr,sz Api.endpointcCs(|jdkrdnd}t|d|j|dS)z The Swagger specifications relative url (ie. `swagger.json`). If the spec_url_scheme attribute is set, then the full url is provided instead (e.g. http://localhost/swaggger.json). :rtype: str NTrZ_scheme _external)r]rr,)r_Zexternalrbrbrc specs_urls z Api.specs_urlcCst|d|jddS)z@ The API base absolute url :rtype: str rTr)rr,r]rrbrbrcbase_url"sz Api.base_urlcCst|dddS)z3 The API path :rtype: str rF)r)rr,rrbrbrc base_path+sz Api.base_pathcCsJ|jsDzt||_Wn*tk rBd}t|d|iYSX|jS)zz The Swagger specifications/schema for this API :returns dict: the schema as a serializable dict zUnable to render schemaerror)rDr!as_dict Exceptionlog exception)r_rrbrbrc __schema__4s zApi.__schema__cCs>t}||j|jD] }|jD]\}}|||<q&q|Sr~)rupdaterCrHr)r_rvryrrrbrbrc_own_and_child_error_handlersFs    z!Api._own_and_child_error_handlerscs4tr&ttr&fdd}|S_SdS)z>A decorator to register an error handler for a given exceptioncs|j<|Sr~)rCrrr_rbrcrSs z!Api.errorhandler..wrapperN)inspectisclass issubclassrr?)r_rrrbrrc errorhandlerOs zApi.errorhandlercCs<|jr2||jjr.||jjddd}ndS||jkS)z Tests if an endpoint name (not path) belongs to this Api. Takes into account the Blueprint name part of the endpoint name. :param str endpoint: The name of the endpoint being checked :return: bool rrF)rY startswithr|splitrV)r_r,rbrbrc owns_endpoint]s zApi.owns_endpointc Cstt}z |Wnxtk rd}z0|jd}|j|dd\}}||jWYSd}~XYn,tk r||j YSt k rYnXdS)a5 Determine if error should be handled with FR or default Flask The goal is to return Flask error handlers for non-FR-related routes, and FR errors (with the correct media type) for FR endpoints. This method currently handles 404 and 405 errors. :return: bool rT)methodZ return_ruleN) r Zcreate_url_adapterrmatchrZ valid_methodsrr,rrRr)r_adaptereZvalid_route_methodr_rbrbrc_should_use_fr_error_handlerms     z Api._should_use_fr_error_handlercCs$|r dStjsdS|tjjS)zGEncapsulating the rules for whether the request was to a Flask endpointTF)rrZurl_rulerr,rrbrbrc _has_fr_routes zApi._has_fr_routec CsL|rDz ||WStk rB}z||WYSd}~XYnX||S)a This function decides whether the error occurred in a flask-restx endpoint or not. If it happened in a flask-restx endpoint, our handler will be dispatched. If it happened in an unrelated view, the app's original error handler will be dispatched. In the event that the error occurred in a flask-restx endpoint but the local handler can't resolve the situation, the router will fall back onto the original_handler as last resort. :param function original_handler: the original Flask error handler for the app :param Exception e: the exception raised while handling the request N)r handle_errorr)r_original_handlerrfrbrbrcrns  zApi.error_routercCs$tjd}|dk r|Stjp"tjS)a Returns the value of the ``PROPAGATE_EXCEPTIONS`` configuration value in case it's set, otherwise return true if app.debug or app.testing is set. This method was deprecated in Flask 2.3 but we still need it for our error handlers. ZPROPAGATE_EXCEPTIONSN)r rsreZtestingdebug)r_rrbrbrc_propagate_exceptionss zApi._propagate_exceptionscCs0t|tsD|rDt|t|jsDt\}}}||kr@n|tj dd}i}t }|j D]2\}} t||rf| |} t | tj\}} }qqftjt|dt|trt|j} |rdt|d| ji}|j}n<|jr||} t | tj\}} }ntj} |rd| ji}|r8| dt||d<t|d|} d} | tjkrzt}|ddkrnd}t|nr| tjkrtj d dr|r|| dd| d<n8| tjkr|jdkrt|j }|r|d nd } t!D]}|"|dq|j#| | || d }| tj$kr,|%|}|S) z Error handler for the API transforms a raised exception into a Flask response, with the appropriate HTTP status code and body. :param Exception e: the raised Exception object ZERROR_INCLUDE_MESSAGET)rmessager2rNrrmrr)r)&rrrtuplerkeyssysexc_infor rsrerrr$r&INTERNAL_SERVER_ERRORr sendZ_get_current_objectrrzphraseZ get_responserr?rZ log_exceptionr _help_on_404NOT_ACCEPTABLErPlistrMHEADERS_BLACKLISTrr UNAUTHORIZED unauthorized)r_rexc_type exc_valuetbZinclude_message_in_responseZ default_datarZ typecheckrresultrrrrZsupported_mediatypesheaderrrbrbrcrs              zApi.handle_errorc sptddtjDttj}|rld |rD| ddnddtjdd fd d |Dd f}|S) NcSs g|]}td|j|jfqS)r+)RE_RULESsubr)rrrbrbrcrsz$Api._help_on_404..r+rz. zYou have requested this URI [z] but did you mean z or c3s|]}|VqdSr~rb)rrrulesrbrcr"sz#Api._help_on_404..z ?) rJr Zurl_mapZ iter_rulesdifflibget_close_matchesrr/rrrstrip)r_rZ close_matchesrbrrcrs" zApi._help_on_404cCst||dj|dS)z Serialize the API as Postman collection (v1) :param bool urlvars: whether to include or not placeholders for query strings :param bool swagger: whether to include or not the swagger.json specifications )swagger)urlvars)rr)r_rrrbrbrc as_postman(szApi.as_postmancCstS)z6Store the input payload in the current request context)rZget_jsonrrbrbrcpayload2sz Api.payloadcCs|jst|j|_|jSr~)rFr Z from_schemarrrbrbrc refresolver7szApi.refresolvercKst|r||j}n|jr$|j|}|d|j|dkrBt|}|j}d|krbt|f|d}|jj |d|j j |f|fd|i|dS)a Method used to patch BlueprintSetupState.add_url_rule for setup state instance corresponding to this Api instance. Exists primarily to enable _complete_url's function. :param blueprint_setup: The BlueprintSetupState instance (self) :param rule: A string or callable that takes a string and returns a string(_complete_url) that is the url rule for the endpoint being registered :param endpoint: See BlueprintSetupState.add_url_rule :param view_func: See BlueprintSetupState.add_url_rule :param **options: See BlueprintSetupState.add_url_rule subdomainNdefaultsz%s.%s) callableZ url_prefixrtr r Z url_defaultsrJrrXrrYr|)rTrr,roptionsr rbrbrc#_blueprint_setup_add_url_rule_patch=s&  z'Api._blueprint_setup_add_url_rule_patchcCsF||_|jjdkr(|j|_ttj||_|js6td| |j dS)a Synchronize prefix between blueprint/api and registration options, then perform initialization with setup_state.app :class:`flask.Flask` object. When a :class:`flask_restx.Api` object is initialized with a blueprint, this method is recorded on the blueprint to be run when the blueprint is later registered to a :class:`flask.Flask` object. This method also monkeypatches BlueprintSetupState.add_url_rule with _blueprint_setup_add_url_rule_patch. :param setup_state: The setup state object passed to deferred functions during blueprint registration :type setup_state: flask.blueprints.BlueprintSetupState r z3flask-restx blueprints can only be registered once.N) rTrrZ_original_add_url_rulerr(r Zfirst_registrationrrlrX)r_Z setup_staterbrbrcrjas zApi._deferred_blueprint_initcs fddS)z1Return a method that returns a list of mediatypescsjgSr~)rrP)Z resource_clsrrbrc|z'Api.mediatypes_method..rbrrbrrcrzszApi.mediatypes_methodcCs ddttjtdddDS)z@Returns a list of requested mediatypes sent in the Accept headercSsg|] \}}|qSrbrb)rhqrbrbrcrsz"Api.mediatypes..rT)keyreverse)sortedrroperator itemgetterrrbrbrcr~szApi.mediatypescsfdd}|S)a  Allows additional representation transformers to be declared for the api. Transformers are functions that must be decorated with this method, passing the mediatype the transformer represents. Three arguments are passed to the transformer: * The data to be represented in the response body * The http status code * A dictionary of headers The transformer should convert the data appropriately for the mediatype and return a Flask response object. Ex:: @api.representation('application/xml') def xml(data, code, headers): resp = make_response(convert_data_to_xml(data), code) resp.headers.extend(headers) return resp cs|j<|Sr~)rMrrr_rbrcrs z#Api.representation..wrapperrb)r_rrrbrrcrepresentationszApi.representationcCs.|jr*tjdd}dd|}||jd<|S)z2Given a response, change it to ask for credentialsZHTTP_BASIC_AUTH_REALMz flask-restxz{0} realm="{1}"ZBasiczWWW-Authenticate)rSr rsrer[r)r_responserealm challengerbrbrcrs   zApi.unauthorizedcKs(|j}|jrd|jj|}t|f|S)zc Generates a URL to the given resource. Works like :func:`flask.url_for`. r)r,rYr[r|r)r_rxvaluesr,rbrbrcrsz Api.url_for)N)N)FF)NN)5r __module__ __qualname____doc__r"rdr^rlr}rrrrgrhrrqrprr rrrrrrrrZr,propertyrrrrrrrrrrrnrrrrrr staticmethodr rjrrrrrrbrbrbrcr(>s0 ]*%   4         b     #  r(c@s eZdZdZddZddZdS)rz)Render the Swagger specifications as JSONcCs |jj}|d|krtjntjfS)Nr)r.rr&rOK)r_ZschemarbrbrcreszSwaggerView.getcCsdgS)Nr'rbrrbrbrcrszSwaggerView.mediatypesN)rrrrrerrbrbrbrcrsrcCsdd|itjfS)zWhen a mask can't be parsedrzMask parse error: {0}r[r& BAD_REQUESTrrbrbrcrAsrAcCsdd|itjfS)zWhen any error occurs on maskrzMask error: {0}r#r%rbrbrcrBsrB)Prr itertoolsrloggingrrerru collectionsr functoolsrrtypesrZflaskrrr r rZ flask.helpersr ImportErrorZflask.scaffoldZ flask.signalsr Z jsonschemar Zwerkzeug.utilsrZwerkzeug.datastructuresrZwerkzeug.exceptionsrrrrrZwerkzeugrZwerkzeug_versionrZwerkzeug.wrappersrrr+rmaskrrrZrZpostmanrrxr rr!utilsr"r#r$rMr%Z_httpr&compilerrrL getLoggerrrobjectr(rrArBrbrbrbrcsb