def __init__(self, app=None, prefix='', default_mediatype='application/json', decorators=None, catch_all_404s=False, serve_challenge_on_401=False, url_part_order='bae', errors=None): self.representations = OrderedDict(DEFAULT_REPRESENTATIONS) self.urls = {} self.prefix = prefix self.default_mediatype = default_mediatype self.decorators = decorators if decorators else [] self.catch_all_404s = catch_all_404s self.serve_challenge_on_401 = serve_challenge_on_401 self.url_part_order = url_part_order self.errors = errors or {} self.blueprint_setup = None self.endpoints = set() self.resources = [] self.app = None self.blueprint = None if app is not None: self.app = app self.init_app(app)
def marshal(data, fields, envelope=None): """Takes raw data (in the form of a dict, list, object) and a dict of fields to output and filters the data based on those fields. :param data: the actual object(s) from which the fields are taken from :param fields: a dict of whose keys will make up the final serialized response output :param envelope: optional key that will be used to envelop the serialized response >>> from flask_restful import fields, marshal >>> data = { 'a': 100, 'b': 'foo' } >>> mfields = { 'a': fields.Raw } >>> marshal(data, mfields) OrderedDict([('a', 100)]) >>> marshal(data, mfields, envelope='data') OrderedDict([('data', OrderedDict([('a', 100)]))]) """ def make(cls): if isinstance(cls, type): return cls() return cls if isinstance(data, (list, tuple)): return (OrderedDict([(envelope, [marshal(d, fields) for d in data])]) if envelope else [marshal(d, fields) for d in data]) items = ((k, marshal(data, v) if isinstance(v, dict) else make(v).output( k, data)) for k, v in fields.items()) return OrderedDict([(envelope, OrderedDict(items)) ]) if envelope else OrderedDict(items)
def test_list_of_nested(self): obj = {'list': [{'a': 1, 'b': 1}, {'a': 2, 'b': 1}, {'a': 3, 'b': 1}]} field = fields.List(fields.Nested({'a': fields.Integer})) self.assertEqual([ OrderedDict([('a', 1)]), OrderedDict([('a', 2)]), OrderedDict([('a', 3)]) ], field.output('list', obj))
def test_list_of_raw(self): obj = {'list': [{'a': 1, 'b': 1}, {'a': 2, 'b': 1}, {'a': 3, 'b': 1}]} field = fields.List(fields.Raw) self.assertEquals([OrderedDict([('a', 1), ('b', 1), ]), OrderedDict([('a', 2), ('b', 1), ]), OrderedDict([('a', 3), ('b', 1), ])], field.output('list', obj)) obj = {'list': [1, 2, 'a']} field = fields.List(fields.Raw) self.assertEquals([1, 2, 'a'], field.output('list', obj))
def dispatch_request(self, *args, **kwargs): """Overridden to support list and create method names, and improved decorator handling for methods """ method = self._get_method_for_request() try: resp = method(*args, **kwargs) except Exception: if apm.is_initialized: apm.capture_exception() resp = ({ 'message': 'Server Error' }, HTTPStatus.INTERNAL_SERVER_ERROR, {}) traceback.print_exc() if isinstance(resp, Response): return resp representations = self.representations or OrderedDict() mediatype = request.accept_mimetypes.best_match(representations, default=None) if mediatype in representations: data, code, headers = unpack(resp) resp = representations[mediatype](data, code, headers) resp.headers['Content-Type'] = mediatype return resp return resp
def dispatch_request(self, *args, **kwargs): meth = getattr(type(self), request.method.lower(), None) if meth is None and request.method == "HEAD": meth = getattr(type(self), "get", None) assert meth is not None, "Unimplemented method %r" % request.method if isinstance(self.method_decorators, Mapping): decorators = self.method_decorators.get( "*", []) + self.method_decorators.get(request.method.lower(), []) else: decorators = self.method_decorators for decorator in decorators: meth = decorator(meth) resp = meth(self, *args, **kwargs) if isinstance(resp, Response): return resp representations = self.representations or OrderedDict() mediatype = request.accept_mimetypes.best_match(representations, default=None) if mediatype in representations: data, code, headers = unpack(resp) resp = representations[mediatype](data, code, headers) resp.headers["Content-Type"] = mediatype return resp return resp
def dispatch_request(self, *args, **kwargs): # Taken from flask #noinspection PyUnresolvedReferences meth = getattr(self, request.method.lower(), None) if meth is None and request.method == 'HEAD': meth = getattr(self, 'get', None) assert meth is not None, 'Unimplemented method %r' % request.method if isinstance(self.method_decorators, Mapping): decorators = self.method_decorators.get(request.method.lower(), []) else: decorators = self.method_decorators for decorator in decorators: meth = decorator(meth) resp = meth(*args, **kwargs) if isinstance(resp, ResponseBase): # There may be a better way to test return resp representations = self.representations or OrderedDict() #noinspection PyUnresolvedReferences mediatype = request.accept_mimetypes.best_match(representations, default=None) if mediatype in representations: data, code, headers = unpack(resp) resp = representations[mediatype](data, code, headers) resp.headers['Content-Type'] = mediatype return resp return resp
def _add_oas_req_params(self, resource, path_item, method, exposing_instance, is_jsonapi_rpc, swagger_url): """ Add the request parameters to the swagger (filter, sort) """ method_doc = path_item[method] parameters = [] for parameter in method_doc.get("parameters", []): object_id = "{%s}" % parameter.get("name") if method == "get": # Get the jsonapi included resources, ie the exposed relationships param = resource.get_swagger_include() parameters.append(param) # Get the jsonapi fields[], ie the exposed attributes/columns # only required for collections though param = resource.get_swagger_fields() parameters.append(param) # # Add the sort, filter parameters to the swagger doc when retrieving a collection # if method == "get" and not (exposing_instance or is_jsonapi_rpc): # limit parameter specifies the number of items to return parameters += default_paging_parameters() param = resource.get_swagger_sort() parameters.append(param) parameters += list(resource.get_swagger_filters()) if not (parameter.get("in") == "path" and object_id not in swagger_url) and parameter not in parameters: # Only if a path param is in path url then we add the param parameters.append(parameter) unique_params = OrderedDict() # rm duplicates for param in parameters: unique_params[param["name"]] = param method_doc["parameters"] = list(unique_params.values()) path_item[method] = method_doc
def __init__( self, app, host="localhost", port=5000, prefix="", description="SAFRSAPI", json_encoder=SAFRSJSONEncoder, swaggerui_blueprint=True, **kwargs, ): """ http://jsonapi.org/format/#content-negotiation-servers Servers MUST send all JSON:API data in response documents with the header Content-Type: application/vnd.api+json without any media type parameters. Servers MUST respond with a 415 Unsupported Media Type status code if a request specifies the header Content-Type: application/vnd.api+json with any media type parameters. Servers MUST respond with a 406 Not Acceptable status code if a request’s Accept header contains the JSON:API media type and all instances of that media type are modified with media type parameters. """ self._custom_swagger = kwargs.pop("custom_swagger", {}) kwargs["default_mediatype"] = "application/vnd.api+json" safrs.SAFRS(app, prefix=prefix, json_encoder=json_encoder, swaggerui_blueprint=swaggerui_blueprint, **kwargs) # the host shown in the swagger ui # this host may be different from the hostname of the server and # sometimes we don't want to show the port (eg when proxied) # in that case the port may be None if port: host = f"{host}:{port}" super().__init__( app, api_spec_url=kwargs.pop("api_spec_url", "/swagger"), host=host, description=description, prefix=prefix, base_path=prefix, **kwargs, ) self.init_app(app) self.representations = OrderedDict(DEFAULT_REPRESENTATIONS) self.update_spec()
def marshal(data, fields, envelope=None, strip_none=False): """Takes raw data (in the form of a dict, list, object) and a dict of fields to output and filters the data based on those fields. :param data: the actual object(s) from which the fields are taken from :param fields: a dict of whose keys will make up the final serialized response output :param envelope: optional key that will be used to envelop the serialized response :param strip_none: optional key that will strip serialized None data. Default: False >>> from flask_restful import fields, marshal >>> data = { 'a': 100, 'b': 'foo' } >>> mfields = { 'a': fields.Raw } >>> marshal(data, mfields) OrderedDict([('a', 100)]) >>> marshal(data, mfields, envelope='data') OrderedDict([('data', OrderedDict([('a', 100)]))]) """ def make(cls): if isinstance(cls, type): return cls() return cls if isinstance(data, (list, tuple)): return (OrderedDict([(envelope, [marshal(d, fields, strip_none=strip_none) for d in data])]) if envelope else [marshal(d, fields, strip_none=strip_none) for d in data]) if isinstance(data, (float, int, str)): return (OrderedDict([(envelope, data)]) if envelope else data) items = ((k, marshal(data, v, strip_none=strip_none) if isinstance(v, dict) else make(v).output(k, data)) for k, v in fields.items()) if strip_none == True or (current_app and current_app.config.get("RESTFUL_MARSHAL_STRIP_NONE", False) == True): # strip None values newItems = OrderedDict() allItems = OrderedDict(items) for k in allItems: if allItems[k] is not None: newItems[k] = allItems[k] items = newItems else: items = OrderedDict(items) return (OrderedDict([(envelope, items)]) if envelope else items)
def __init__(self, *args, **kwargs): """ http://jsonapi.org/format/#content-negotiation-servers Servers MUST send all JSON:API data in response documents with the header Content-Type: application/vnd.api+json without any media type parameters. Servers MUST respond with a 415 Unsupported Media Type status code if a request specifies the header Content-Type: application/vnd.api+json with any media type parameters. Servers MUST respond with a 406 Not Acceptable status code if a request’s Accept header contains the JSON:API media type and all instances of that media type are modified with media type parameters. """ custom_swagger = kwargs.pop("custom_swagger", {}) kwargs["default_mediatype"] = "application/vnd.api+json" super(Api, self).__init__(*args, **kwargs) self.representations = OrderedDict(DEFAULT_REPRESENTATIONS) self.update_spec(custom_swagger)
def dispatch_request(self, *args, **kwargs): """Overridden to support list and create method names, and improved decorator handling for methods """ method = self._get_method_for_request() resp = method(*args, **kwargs) if isinstance(resp, Response): return resp representations = self.representations or OrderedDict() mediatype = request.accept_mimetypes.best_match(representations, default=None) if mediatype in representations: data, code, headers = unpack(resp) resp = representations[mediatype](data, code, headers) resp.headers['Content-Type'] = mediatype return resp return resp
def dispatch_request(self, *args, **kwargs): # Taken from flask meth = getattr(self, request.method.lower(), None) if meth is None and request.method == 'HEAD': meth = getattr(self, 'get', None) assert meth is not None, 'Unimplemented method %r' % request.method for decorator in self.method_decorators: meth = decorator(meth) try: increment(total_requests) except Exception as exc: pass # this is where actual method starts resp = meth(*args, **kwargs) # this is where actual method ends if isinstance(resp, ResponseBase): # There may be a better way to test return resp representations = self.representations or OrderedDict() mediatype = request.accept_mimetypes.best_match(representations, default=None) if mediatype in representations: data, code, headers = unpack(resp) resp = representations[mediatype](data, code, headers) resp.headers['Content-Type'] = mediatype return resp return resp
# -*- coding:utf-8 -*- from app.utils.api import RestfulApi from . import app from .controllers import Case from flask_restful.utils import OrderedDict from flask_restful.representations.json import output_json RESOURCES = ([Case, '/api/success_case', '/api/success_case/<string:action>'], ) api = RestfulApi(app, default_mediatype='application/json; charset=UTF-8') api.representations = OrderedDict([('application/json; charset=UTF-8', output_json)]) api.add_resources(RESOURCES)
def add_resource(self, resource, *urls, **kwargs): """ This method is partly copied from flask_restful_swagger_2/__init__.py I changed it because we don't need path id examples when there's no {id} in the path. We also have to filter out the unwanted parameters """ # # This function has grown out of proportion and should be refactored, disable lint warning for now # # pylint: disable=too-many-nested-blocks,too-many-statements, too-many-locals # kwargs.pop("relationship", False) # relationship object SAFRS_INSTANCE_SUFFIX = get_config("OBJECT_ID_SUFFIX") + "}" path_item = collections.OrderedDict() definitions = {} resource_methods = kwargs.get("methods", HTTP_METHODS) kwargs.pop("safrs_object", None) is_jsonapi_rpc = kwargs.pop( "jsonapi_rpc", False) # check if the exposed method is a jsonapi_rpc method deprecated = kwargs.pop("deprecated", False) # TBD!! for method in self.get_resource_methods(resource): if deprecated: continue if not method.upper() in resource_methods: continue f = getattr(resource, method, None) if not f: continue operation = getattr(f, "__swagger_operation_object", None) if operation: # operation, definitions_ = self._extract_schemas(operation) operation, definitions_ = Extractor.extract(operation) path_item[method] = operation definitions.update(definitions_) summary = parse_method_doc(f, operation) if summary: operation["summary"] = summary.split("<br/>")[0] try: validate_definitions_object(definitions) except FRSValidationError: safrs.log.critical("Validation failed for {}".format(definitions)) exit() self._swagger_object["definitions"].update(definitions) if path_item: for url in urls: if not url.startswith("/"): raise ValidationError("paths must start with a /") swagger_url = extract_swagger_path(url) # exposing_instance tells us whether we're exposing an instance (as opposed to a collection) exposing_instance = swagger_url.strip("/").endswith( SAFRS_INSTANCE_SUFFIX) for method in self.get_resource_methods(resource): if method == "post" and exposing_instance: # POSTing to an instance isn't jsonapi-compliant (https://jsonapi.org/format/#crud-creating-client-ids) # "A server MUST return 403 Forbidden in response to an # unsupported request to create a resource with a client-generated ID" # the method has already been added before, remove it & continue path_item.pop(method, None) continue method_doc = copy.deepcopy(path_item.get(method)) if not method_doc: continue collection_summary = method_doc.pop( "collection_summary", method_doc.get("summary", None)) if not exposing_instance and collection_summary: method_doc["summary"] = collection_summary parameters = [] for parameter in method_doc.get("parameters", []): object_id = "{%s}" % parameter.get("name") if method == "get": # Get the jsonapi included resources, ie the exposed relationships param = resource.get_swagger_include() parameters.append(param) # Get the jsonapi fields[], ie the exposed attributes/columns param = resource.get_swagger_fields() parameters.append(param) # # Add the sort, filter parameters to the swagger doc when retrieving a collection # if method == "get" and not (exposing_instance or is_jsonapi_rpc): # limit parameter specifies the number of items to return parameters += default_paging_parameters() param = resource.get_swagger_sort() parameters.append(param) parameters += list(resource.get_swagger_filters()) if not (parameter.get("in") == "path" and object_id not in swagger_url ) and parameter not in parameters: # Only if a path param is in path url then we add the param parameters.append(parameter) unique_params = OrderedDict() # rm duplicates for param in parameters: unique_params[param["name"]] = param method_doc["parameters"] = list(unique_params.values()) method_doc["operationId"] = self.get_operation_id( path_item.get(method).get("summary", "")) path_item[method] = method_doc instance_schema = method_doc.get("responses", {}).get("200", {}) if instance_schema and exposing_instance and method_doc[ "responses"]["200"].get("schema", None): method_doc["responses"]["200"][ "schema"] = resource.SAFRSObject.swagger_models[ "instance"].reference() # add this later method_doc["responses"]["200"]["schema"] = {} try: validate_path_item_object(path_item) except FRSValidationError as exc: safrs.log.exception(exc) safrs.log.critical( "Validation failed for {}".format(path_item)) exit() self._swagger_object["paths"][swagger_url] = path_item # Check whether we manage to convert to json try: json.dumps(self._swagger_object) except Exception: safrs.log.critical("Json encoding failed for") # safrs.log.debug(self._swagger_object) # disable API methods that were not set by the SAFRSObject for http_method in HTTP_METHODS: hm = http_method.lower() if hm not in self.get_resource_methods(resource): setattr(resource, hm, lambda x: ({}, HTTPStatus.METHOD_NOT_ALLOWED)) # pylint: disable=bad-super-call super(FRSApiBase, self).add_resource(resource, *urls, **kwargs)
class Api(object): """ The main entry point for the application. You need to initialize it with a Flask Application: :: >>> app = Flask(__name__) >>> api = restful.Api(app) Alternatively, you can use :meth:`init_app` to set the Flask application after it has been constructed. :param app: the Flask application object :type app: flask.Flask :param prefix: Prefix all routes with a value, eg v1 or 2010-04-01 :type prefix: str :param default_mediatype: The default media type to return :type default_mediatype: str :param decorators: Decorators to attach to every resource :type decorators: list :param catch_all_404s: Use :meth:`handle_error` to handle 404 errors throughout your app :param serve_challenge_on_401: Whether to serve a challenge response to clients on receiving 401. This usually leads to a username/password popup in web browers. :param url_part_order: A string that controls the order that the pieces of the url are concatenated when the full url is constructed. 'b' is the blueprint (or blueprint registration) prefix, 'a' is the api prefix, and 'e' is the path component the endpoint is added with :type catch_all_404s: bool :param errors: A dictionary to define a custom response for each exception or error raised during a request :type errors: dict """ def __init__(self, app=None, prefix='', default_mediatype='application/json', decorators=None, catch_all_404s=False, serve_challenge_on_401=False, url_part_order='bae', errors=None): self.representations = OrderedDict(DEFAULT_REPRESENTATIONS) self.urls = {} self.prefix = prefix self.default_mediatype = default_mediatype self.decorators = decorators if decorators else [] self.catch_all_404s = catch_all_404s self.serve_challenge_on_401 = serve_challenge_on_401 self.url_part_order = url_part_order self.errors = errors or {} self.blueprint_setup = None self.endpoints = set() self.resources = [] self.app = None self.blueprint = None if app is not None: self.app = app self.init_app(app) def init_app(self, app): """Initialize this class with the given :class:`flask.Flask` application or :class:`flask.Blueprint` object. :param app: the Flask application or blueprint object :type app: flask.Flask :type app: flask.Blueprint Examples:: api = Api() api.add_resource(...) api.init_app(app) """ # If app is a blueprint, defer the initialization try: app.record(self._deferred_blueprint_init) # Flask.Blueprint has a 'record' attribute, Flask.Api does not except AttributeError: self._init_app(app) else: self.blueprint = app def _complete_url(self, url_part, registration_prefix): """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 """ parts = { 'b': registration_prefix, 'a': self.prefix, 'e': url_part } return ''.join(parts[key] for key in self.url_part_order if parts[key]) @staticmethod def _blueprint_setup_add_url_rule_patch(blueprint_setup, rule, endpoint=None, view_func=None, **options): """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 """ if callable(rule): rule = rule(blueprint_setup.url_prefix) elif blueprint_setup.url_prefix: rule = blueprint_setup.url_prefix + rule options.setdefault('subdomain', blueprint_setup.subdomain) if endpoint is None: endpoint = _endpoint_from_view_func(view_func) defaults = blueprint_setup.url_defaults if 'defaults' in options: defaults = dict(defaults, **options.pop('defaults')) blueprint_setup.app.add_url_rule(rule, '%s.%s' % (blueprint_setup.blueprint.name, endpoint), view_func, defaults=defaults, **options) def _deferred_blueprint_init(self, setup_state): """Synchronize prefix between blueprint/api and registration options, then perform initialization with setup_state.app :class:`flask.Flask` object. When a :class:`flask_restful.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 """ self.blueprint_setup = setup_state if setup_state.add_url_rule.__name__ != '_blueprint_setup_add_url_rule_patch': setup_state._original_add_url_rule = setup_state.add_url_rule setup_state.add_url_rule = MethodType(Api._blueprint_setup_add_url_rule_patch, setup_state) if not setup_state.first_registration: raise ValueError('flask-restful blueprints can only be registered once.') self._init_app(setup_state.app) def _init_app(self, app): """Perform initialization actions with the given :class:`flask.Flask` object. :param app: The flask application object :type app: flask.Flask """ app.handle_exception = partial(self.error_router, app.handle_exception) app.handle_user_exception = partial(self.error_router, app.handle_user_exception) if len(self.resources) > 0: for resource, urls, kwargs in self.resources: self._register_view(app, resource, *urls, **kwargs) def owns_endpoint(self, endpoint): """Tests if an endpoint name (not path) belongs to this Api. Takes in to account the Blueprint name part of the endpoint name. :param endpoint: The name of the endpoint being checked :return: bool """ if self.blueprint: if endpoint.startswith(self.blueprint.name): endpoint = endpoint.split(self.blueprint.name + '.', 1)[-1] else: return False return endpoint in self.endpoints def _should_use_fr_error_handler(self): """ 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 """ adapter = current_app.create_url_adapter(request) try: adapter.match() except MethodNotAllowed as e: # Check if the other HTTP methods at this url would hit the Api valid_route_method = e.valid_methods[0] rule, _ = adapter.match(method=valid_route_method, return_rule=True) return self.owns_endpoint(rule.endpoint) except NotFound: return self.catch_all_404s except: # Werkzeug throws other kinds of exceptions, such as Redirect pass def _has_fr_route(self): """Encapsulating the rules for whether the request was to a Flask endpoint""" # 404's, 405's, which might not have a url_rule if self._should_use_fr_error_handler(): return True # for all other errors, just check if FR dispatched the route if not request.url_rule: return False return self.owns_endpoint(request.url_rule.endpoint) def error_router(self, original_handler, e): """This function decides whether the error occured in a flask-restful endpoint or not. If it happened in a flask-restful 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-restful endpoint but the local handler can't resolve the situation, the router will fall back onto the original_handler as last resort. :param original_handler: the original Flask error handler for the app :type original_handler: function :param e: the exception raised while handling the request :type e: Exception """ if self._has_fr_route(): try: return self.handle_error(e) except Exception: pass # Fall through to original handler return original_handler(e) def handle_error(self, e): """Error handler for the API transforms a raised exception into a Flask response, with the appropriate HTTP status code and body. :param e: the raised Exception object :type e: Exception """ got_request_exception.send(current_app._get_current_object(), exception=e) if not isinstance(e, HTTPException) and current_app.propagate_exceptions: exc_type, exc_value, tb = sys.exc_info() if exc_value is e: raise else: raise e if isinstance(e, HTTPException): code = e.code default_data = { 'message': getattr(e, 'description', http_status_message(code)) } else: code = 500 default_data = { 'message': http_status_message(code), } data = getattr(e, 'data', default_data) headers = {} if code >= 500: exc_info = sys.exc_info() if exc_info[1] is None: exc_info = None current_app.log_exception(exc_info) help_on_404 = current_app.config.get("ERROR_404_HELP", True) if code == 404 and help_on_404: rules = dict([(re.sub('(<.*>)', '', rule.rule), rule.rule) for rule in current_app.url_map.iter_rules()]) close_matches = difflib.get_close_matches(request.path, rules.keys()) if close_matches: # If we already have a message, add punctuation and continue it. if "message" in data: data["message"] = data["message"].rstrip('.') + '. ' else: data["message"] = "" data['message'] += 'You have requested this URI [' + request.path + \ '] but did you mean ' + \ ' or '.join(( rules[match] for match in close_matches) ) + ' ?' if code == 405: headers['Allow'] = e.valid_methods error_cls_name = type(e).__name__ if error_cls_name in self.errors: custom_data = self.errors.get(error_cls_name, {}) code = custom_data.get('status', 500) data.update(custom_data) if code == 406 and self.default_mediatype is None: # if we are handling NotAcceptable (406), make sure that # make_response uses a representation we support as the # default mediatype (so that make_response doesn't throw # another NotAcceptable error). supported_mediatypes = list(self.representations.keys()) fallback_mediatype = supported_mediatypes[0] if supported_mediatypes else "text/plain" resp = self.make_response( data, code, headers, fallback_mediatype = fallback_mediatype ) else: resp = self.make_response(data, code, headers) if code == 401: resp = self.unauthorized(resp) return resp def mediatypes_method(self): """Return a method that returns a list of mediatypes """ return lambda resource_cls: self.mediatypes() + [self.default_mediatype] def add_resource(self, resource, *urls, **kwargs): """Adds a resource to the api. :param resource: the class name of your resource :type resource: :class:`Resource` :param urls: one or more url routes to match for the resource, standard flask routing rules apply. Any url variables will be passed to the resource method as args. :type urls: str :param endpoint: endpoint name (defaults to :meth:`Resource.__name__.lower` Can be used to reference this route in :class:`fields.Url` fields :type endpoint: str :param resource_class_args: args to be forwarded to the constructor of the resource. :type resource_class_args: tuple :param resource_class_kwargs: kwargs to be forwarded to the constructor of the resource. :type resource_class_kwargs: dict Additional keyword arguments not specified above will be passed as-is to :meth:`flask.Flask.add_url_rule`. Examples:: api.add_resource(HelloWorld, '/', '/hello') api.add_resource(Foo, '/foo', endpoint="foo") api.add_resource(FooSpecial, '/special/foo', endpoint="foo") """ if self.app is not None: self._register_view(self.app, resource, *urls, **kwargs) else: self.resources.append((resource, urls, kwargs)) def resource(self, *urls, **kwargs): """Wraps a :class:`~flask_restful.Resource` class, adding it to the api. Parameters are the same as :meth:`~flask_restful.Api.add_resource`. Example:: app = Flask(__name__) api = restful.Api(app) @api.resource('/foo') class Foo(Resource): def get(self): return 'Hello, World!' """ def decorator(cls): self.add_resource(cls, *urls, **kwargs) return cls return decorator def _register_view(self, app, resource, *urls, **kwargs): endpoint = kwargs.pop('endpoint', None) or resource.__name__.lower() self.endpoints.add(endpoint) resource_class_args = kwargs.pop('resource_class_args', ()) resource_class_kwargs = kwargs.pop('resource_class_kwargs', {}) # NOTE: 'view_functions' is cleaned up from Blueprint class in Flask 1.0 if endpoint in getattr(app, 'view_functions', {}): previous_view_class = app.view_functions[endpoint].__dict__['view_class'] # if you override the endpoint with a different class, avoid the collision by raising an exception if previous_view_class != resource: raise ValueError('This endpoint (%s) is already set to the class %s.' % (endpoint, previous_view_class.__name__)) resource.mediatypes = self.mediatypes_method() # Hacky resource.endpoint = endpoint resource_func = self.output(resource.as_view(endpoint, *resource_class_args, **resource_class_kwargs)) for decorator in self.decorators: resource_func = decorator(resource_func) for url in urls: # If this Api has a blueprint if self.blueprint: # And this Api has been setup if self.blueprint_setup: # Set the rule to a string directly, as the blueprint is already # set up. self.blueprint_setup.add_url_rule(url, view_func=resource_func, **kwargs) continue else: # Set the rule to a function that expects the blueprint prefix # to construct the final url. Allows deferment of url finalization # in the case that the associated Blueprint has not yet been # registered to an application, so we can wait for the registration # prefix rule = partial(self._complete_url, url) else: # If we've got no Blueprint, just build a url with no prefix rule = self._complete_url(url, '') # Add the url to the application or blueprint app.add_url_rule(rule, view_func=resource_func, **kwargs) def output(self, resource): """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 """ @wraps(resource) def wrapper(*args, **kwargs): resp = resource(*args, **kwargs) if isinstance(resp, ResponseBase): # There may be a better way to test return resp data, code, headers = unpack(resp) return self.make_response(data, code, headers=headers) return wrapper def url_for(self, resource, **values): """Generates a URL to the given resource. Works like :func:`flask.url_for`.""" endpoint = resource.endpoint if self.blueprint: endpoint = '{0}.{1}'.format(self.blueprint.name, endpoint) return url_for(endpoint, **values) def make_response(self, data, *args, **kwargs): """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 """ default_mediatype = kwargs.pop('fallback_mediatype', None) or self.default_mediatype mediatype = request.accept_mimetypes.best_match( self.representations, default=default_mediatype, ) if mediatype is None: raise NotAcceptable() if mediatype in self.representations: resp = self.representations[mediatype](data, *args, **kwargs) resp.headers['Content-Type'] = mediatype return resp elif mediatype == 'text/plain': resp = original_flask_make_response(str(data), *args, **kwargs) resp.headers['Content-Type'] = 'text/plain' return resp else: raise InternalServerError() def mediatypes(self): """Returns a list of requested mediatypes sent in the Accept header""" return [h for h, q in sorted(request.accept_mimetypes, key=operator.itemgetter(1), reverse=True)] def representation(self, mediatype): """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 """ def wrapper(func): self.representations[mediatype] = func return func return wrapper def unauthorized(self, response): """ Given a response, change it to ask for credentials """ if self.serve_challenge_on_401: realm = current_app.config.get("HTTP_BASIC_AUTH_REALM", "flask-restful") challenge = u"{0} realm=\"{1}\"".format("Basic", realm) response.headers['WWW-Authenticate'] = challenge return response
class Api(object): """ The main entry point for the application. You need to initialize it with a Flask Application: :: >>> app = Flask(__name__) >>> api = restful.Api(app) Alternatively, you can use :meth:`init_app` to set the Flask application after it has been constructed. :param app: the Flask application object :type app: flask.Flask or flask.Blueprint :param prefix: Prefix all routes with a value, eg v1 or 2010-04-01 :type prefix: str :param default_mediatype: The default media type to return :type default_mediatype: str :param decorators: Decorators to attach to every resource :type decorators: list :param catch_all_404s: Use :meth:`handle_error` to handle 404 errors throughout your app :param serve_challenge_on_401: Whether to serve a challenge response to clients on receiving 401. This usually leads to a username/password popup in web browsers. :param url_part_order: A string that controls the order that the pieces of the url are concatenated when the full url is constructed. 'b' is the blueprint (or blueprint registration) prefix, 'a' is the api prefix, and 'e' is the path component the endpoint is added with :type catch_all_404s: bool :param errors: A dictionary to define a custom response for each exception or error raised during a request :type errors: dict """ def __init__(self, app=None, prefix='', default_mediatype='application/json', decorators=None, catch_all_404s=False, serve_challenge_on_401=False, url_part_order='bae', errors=None): self.representations = OrderedDict(DEFAULT_REPRESENTATIONS) self.urls = {} self.prefix = prefix self.default_mediatype = default_mediatype self.decorators = decorators if decorators else [] self.catch_all_404s = catch_all_404s self.serve_challenge_on_401 = serve_challenge_on_401 self.url_part_order = url_part_order self.errors = errors or {} self.blueprint_setup = None self.endpoints = set() self.resources = [] self.app = None self.blueprint = None if app is not None: self.app = app self.init_app(app) def init_app(self, app): """Initialize this class with the given :class:`flask.Flask` application or :class:`flask.Blueprint` object. :param app: the Flask application or blueprint object :type app: flask.Flask :type app: flask.Blueprint Examples:: api = Api() api.add_resource(...) api.init_app(app) """ # If app is a blueprint, defer the initialization try: app.record(self._deferred_blueprint_init) # Flask.Blueprint has a 'record' attribute, Flask.Api does not except AttributeError: self._init_app(app) else: self.blueprint = app def _complete_url(self, url_part, registration_prefix): """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 """ parts = {'b': registration_prefix, 'a': self.prefix, 'e': url_part} return ''.join(parts[key] for key in self.url_part_order if parts[key]) @staticmethod def _blueprint_setup_add_url_rule_patch(blueprint_setup, rule, endpoint=None, view_func=None, **options): """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 """ if callable(rule): rule = rule(blueprint_setup.url_prefix) elif blueprint_setup.url_prefix: rule = blueprint_setup.url_prefix + rule options.setdefault('subdomain', blueprint_setup.subdomain) if endpoint is None: endpoint = _endpoint_from_view_func(view_func) defaults = blueprint_setup.url_defaults if 'defaults' in options: defaults = dict(defaults, **options.pop('defaults')) blueprint_setup.app.add_url_rule( rule, '%s.%s' % (blueprint_setup.blueprint.name, endpoint), view_func, defaults=defaults, **options) def _deferred_blueprint_init(self, setup_state): """Synchronize prefix between blueprint/api and registration options, then perform initialization with setup_state.app :class:`flask.Flask` object. When a :class:`flask_restful.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 """ self.blueprint_setup = setup_state if setup_state.add_url_rule.__name__ != '_blueprint_setup_add_url_rule_patch': setup_state._original_add_url_rule = setup_state.add_url_rule setup_state.add_url_rule = MethodType( Api._blueprint_setup_add_url_rule_patch, setup_state) if not setup_state.first_registration: raise ValueError( 'flask-restful blueprints can only be registered once.') self._init_app(setup_state.app) def _init_app(self, app): """Perform initialization actions with the given :class:`flask.Flask` object. :param app: The flask application object :type app: flask.Flask """ app.handle_exception = partial(self.error_router, app.handle_exception) app.handle_user_exception = partial(self.error_router, app.handle_user_exception) if len(self.resources) > 0: for resource, urls, kwargs in self.resources: self._register_view(app, resource, *urls, **kwargs) def owns_endpoint(self, endpoint): """Tests if an endpoint name (not path) belongs to this Api. Takes in to account the Blueprint name part of the endpoint name. :param endpoint: The name of the endpoint being checked :return: bool """ if self.blueprint: if endpoint.startswith(self.blueprint.name): endpoint = endpoint.split(self.blueprint.name + '.', 1)[-1] else: return False return endpoint in self.endpoints def _should_use_fr_error_handler(self): """ 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 """ adapter = current_app.create_url_adapter(request) try: adapter.match() except MethodNotAllowed as e: # Check if the other HTTP methods at this url would hit the Api valid_route_method = e.valid_methods[0] rule, _ = adapter.match(method=valid_route_method, return_rule=True) return self.owns_endpoint(rule.endpoint) except NotFound: return self.catch_all_404s except: # Werkzeug throws other kinds of exceptions, such as Redirect pass def _has_fr_route(self): """Encapsulating the rules for whether the request was to a Flask endpoint""" # 404's, 405's, which might not have a url_rule if self._should_use_fr_error_handler(): return True # for all other errors, just check if FR dispatched the route if not request.url_rule: return False return self.owns_endpoint(request.url_rule.endpoint) def error_router(self, original_handler, e): """This function decides whether the error occured in a flask-restful endpoint or not. If it happened in a flask-restful 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-restful endpoint but the local handler can't resolve the situation, the router will fall back onto the original_handler as last resort. :param original_handler: the original Flask error handler for the app :type original_handler: function :param e: the exception raised while handling the request :type e: Exception """ if self._has_fr_route(): try: return self.handle_error(e) except Exception: pass # Fall through to original handler return original_handler(e) def handle_error(self, e): """Error handler for the API transforms a raised exception into a Flask response, with the appropriate HTTP status code and body. :param e: the raised Exception object :type e: Exception """ got_request_exception.send(current_app._get_current_object(), exception=e) if not isinstance(e, HTTPException) and current_app.propagate_exceptions: exc_type, exc_value, tb = sys.exc_info() if exc_value is e: raise else: raise e headers = Headers() if isinstance(e, HTTPException): if e.response is not None: # If HTTPException is initialized with a response, then return e.get_response(). # This prevents specified error response from being overridden. # eg. HTTPException(response=Response("Hello World")) resp = e.get_response() return resp code = e.code default_data = { 'message': getattr(e, 'description', http_status_message(code)) } headers = e.get_response().headers else: code = 500 default_data = { 'message': http_status_message(code), } # Werkzeug exceptions generate a content-length header which is added # to the response in addition to the actual content-length header # https://github.com/flask-restful/flask-restful/issues/534 remove_headers = ('Content-Length', ) for header in remove_headers: headers.pop(header, None) data = getattr(e, 'data', default_data) if code and code >= 500: exc_info = sys.exc_info() if exc_info[1] is None: exc_info = None current_app.log_exception(exc_info) error_cls_name = type(e).__name__ if error_cls_name in self.errors: custom_data = self.errors.get(error_cls_name, {}) code = custom_data.get('status', 500) data.update(custom_data) if code == 406 and self.default_mediatype is None: # if we are handling NotAcceptable (406), make sure that # make_response uses a representation we support as the # default mediatype (so that make_response doesn't throw # another NotAcceptable error). supported_mediatypes = list(self.representations.keys()) fallback_mediatype = supported_mediatypes[ 0] if supported_mediatypes else "text/plain" resp = self.make_response(data, code, headers, fallback_mediatype=fallback_mediatype) else: resp = self.make_response(data, code, headers) if code == 401: resp = self.unauthorized(resp) return resp def mediatypes_method(self): """Return a method that returns a list of mediatypes """ return lambda resource_cls: self.mediatypes( ) + [self.default_mediatype] def add_resource(self, resource, *urls, **kwargs): """Adds a resource to the api. :param resource: the class name of your resource :type resource: :class:`Type[Resource]` :param urls: one or more url routes to match for the resource, standard flask routing rules apply. Any url variables will be passed to the resource method as args. :type urls: str :param endpoint: endpoint name (defaults to :meth:`Resource.__name__.lower` Can be used to reference this route in :class:`fields.Url` fields :type endpoint: str :param resource_class_args: args to be forwarded to the constructor of the resource. :type resource_class_args: tuple :param resource_class_kwargs: kwargs to be forwarded to the constructor of the resource. :type resource_class_kwargs: dict Additional keyword arguments not specified above will be passed as-is to :meth:`flask.Flask.add_url_rule`. Examples:: api.add_resource(HelloWorld, '/', '/hello') api.add_resource(Foo, '/foo', endpoint="foo") api.add_resource(FooSpecial, '/special/foo', endpoint="foo") """ if self.app is not None: self._register_view(self.app, resource, *urls, **kwargs) else: self.resources.append((resource, urls, kwargs)) def resource(self, *urls, **kwargs): """Wraps a :class:`~flask_restful.Resource` class, adding it to the api. Parameters are the same as :meth:`~flask_restful.Api.add_resource`. Example:: app = Flask(__name__) api = restful.Api(app) @api.resource('/foo') class Foo(Resource): def get(self): return 'Hello, World!' """ def decorator(cls): self.add_resource(cls, *urls, **kwargs) return cls return decorator def _register_view(self, app, resource, *urls, **kwargs): endpoint = kwargs.pop('endpoint', None) or resource.__name__.lower() self.endpoints.add(endpoint) resource_class_args = kwargs.pop('resource_class_args', ()) resource_class_kwargs = kwargs.pop('resource_class_kwargs', {}) # NOTE: 'view_functions' is cleaned up from Blueprint class in Flask 1.0 if endpoint in getattr(app, 'view_functions', {}): previous_view_class = app.view_functions[endpoint].__dict__[ 'view_class'] # if you override the endpoint with a different class, avoid the collision by raising an exception if previous_view_class != resource: raise ValueError( 'This endpoint (%s) is already set to the class %s.' % (endpoint, previous_view_class.__name__)) resource.mediatypes = self.mediatypes_method() # Hacky resource.endpoint = endpoint resource_func = self.output( resource.as_view(endpoint, *resource_class_args, **resource_class_kwargs)) for decorator in self.decorators: resource_func = decorator(resource_func) for url in urls: # If this Api has a blueprint if self.blueprint: # And this Api has been setup if self.blueprint_setup: # Set the rule to a string directly, as the blueprint is already # set up. self.blueprint_setup.add_url_rule(url, view_func=resource_func, **kwargs) continue else: # Set the rule to a function that expects the blueprint prefix # to construct the final url. Allows deferment of url finalization # in the case that the associated Blueprint has not yet been # registered to an application, so we can wait for the registration # prefix rule = partial(self._complete_url, url) else: # If we've got no Blueprint, just build a url with no prefix rule = self._complete_url(url, '') # Add the url to the application or blueprint app.add_url_rule(rule, view_func=resource_func, **kwargs) def output(self, resource): """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 """ @wraps(resource) def wrapper(*args, **kwargs): resp = resource(*args, **kwargs) if isinstance(resp, ResponseBase): # There may be a better way to test return resp data, code, headers = unpack(resp) return self.make_response(data, code, headers=headers) return wrapper def url_for(self, resource, **values): """Generates a URL to the given resource. Works like :func:`flask.url_for`.""" endpoint = resource.endpoint if self.blueprint: endpoint = '{0}.{1}'.format(self.blueprint.name, endpoint) return url_for(endpoint, **values) def make_response(self, data, *args, **kwargs): """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 """ default_mediatype = kwargs.pop('fallback_mediatype', None) or self.default_mediatype mediatype = request.accept_mimetypes.best_match( self.representations, default=default_mediatype, ) if mediatype is None: raise NotAcceptable() if mediatype in self.representations: resp = self.representations[mediatype](data, *args, **kwargs) resp.headers['Content-Type'] = mediatype return resp elif mediatype == 'text/plain': resp = original_flask_make_response(str(data), *args, **kwargs) resp.headers['Content-Type'] = 'text/plain' return resp else: raise InternalServerError() def mediatypes(self): """Returns a list of requested mediatypes sent in the Accept header""" return [ h for h, q in sorted(request.accept_mimetypes, key=operator.itemgetter(1), reverse=True) ] def representation(self, mediatype): """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 """ def wrapper(func): self.representations[mediatype] = func return func return wrapper def unauthorized(self, response): """ Given a response, change it to ask for credentials """ if self.serve_challenge_on_401: realm = current_app.config.get("HTTP_BASIC_AUTH_REALM", "flask-restful") challenge = u"{0} realm=\"{1}\"".format("Basic", realm) response.headers['WWW-Authenticate'] = challenge return response