diff --git a/docs/api.rst b/docs/api.rst index 429368b9..5dc461ec 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,7 +3,7 @@ API Docs ======== -.. module:: flask.ext.restful +.. module:: flask_restful .. autofunction:: marshal diff --git a/docs/extending.rst b/docs/extending.rst index d6b1ac1a..799280d9 100644 --- a/docs/extending.rst +++ b/docs/extending.rst @@ -3,7 +3,7 @@ Extending Flask-RESTful ======================= -.. currentmodule:: flask.ext.restful +.. currentmodule:: flask_restful We realize that everyone has different needs in a REST framework. Flask-RESTful tries to be as flexible as possible, but sometimes you might @@ -150,7 +150,7 @@ provide your own output functions. :: Resource Method Decorators -------------------------- -There is a property on the :class:`~flask.ext.restful.Resource` class called +There is a property on the :class:`~flask_restful.Resource` class called ``method_decorators``. You can subclass the Resource and add your own decorators that will be added to all ``method`` functions in resource. For instance, if you want to build custom authentication into every request. :: @@ -183,11 +183,11 @@ Error handling is a tricky problem. Your Flask application may be wearing multiple hats, yet you want to handle all Flask-RESTful errors with the correct content type and error syntax as your 200-level requests. -Flask-RESTful will call the :meth:`~flask.ext.restful.Api.handle_error` +Flask-RESTful will call the :meth:`~flask_restful.Api.handle_error` function on any 400 or 500 error that happens on a Flask-RESTful route, and leave other routes alone. You may want your app to return an error message with the correct media type on 404 Not Found errors; in which case, use the -`catch_all_404s` parameter of the :class:`~flask.ext.restful.Api` constructor. :: +`catch_all_404s` parameter of the :class:`~flask_restful.Api` constructor. :: app = Flask(__name__) api = flask_restful.Api(app, catch_all_404s=True) @@ -228,7 +228,7 @@ Including the `'status'` key will set the Response's status code. If not specified it will default to 500. Once your ``errors`` dictionary is defined, simply pass it to the -:class:`~flask.ext.restful.Api` constructor. :: +:class:`~flask_restful.Api` constructor. :: app = Flask(__name__) api = flask_restful.Api(app, errors=errors) diff --git a/docs/fields.rst b/docs/fields.rst index d2ca7130..94bed314 100644 --- a/docs/fields.rst +++ b/docs/fields.rst @@ -3,7 +3,7 @@ Output Fields =============== -.. currentmodule:: flask.ext.restful +.. currentmodule:: flask_restful Flask-RESTful provides an easy way to control what data you actually render in @@ -24,7 +24,7 @@ will format & return the value for that field. This example has three fields: two are :class:`~fields.String` and one is a :class:`~fields.DateTime`, formatted as an RFC 822 date string (ISO 8601 is supported as well) :: - from flask.ext.restful import Resource, fields, marshal_with + from flask_restful import Resource, fields, marshal_with resource_fields = { 'name': fields.String, @@ -52,8 +52,8 @@ Note: :class:`marshal_with` is a convenience decorator, that is functionally equivalent to :: class Todo(Resource): - def get(self, **kwargs): - return marshal(db_get_todo(), resource_fields), 200 + def get(self, **kwargs): + return marshal(db_get_todo(), resource_fields), 200 This explicit expression can be used to return HTTP status codes other than 200 along with a successful response (see :func:`abort` for errors). @@ -70,7 +70,7 @@ name. To configure this mapping, use the ``attribute`` keyword argument. :: 'address': fields.String, } -A lambda can also be specified as the ``attribute`` :: +A lambda (or any callable) can also be specified as the ``attribute`` :: fields = { 'name': fields.String(attribute=lambda x: x._private_name), @@ -154,7 +154,7 @@ Complex Structures You can have a flat structure that :meth:`marshal` will transform to a nested structure :: - >>> from flask.ext.restful import fields, marshal + >>> from flask_restful import fields, marshal >>> import json >>> >>> resource_fields = {'name': fields.String} @@ -179,7 +179,7 @@ List Field You can also unmarshal fields as lists :: - >>> from flask.ext.restful import fields, marshal + >>> from flask_restful import fields, marshal >>> import json >>> >>> resource_fields = {'name': fields.String, 'first_names': fields.List(fields.String)} @@ -196,7 +196,7 @@ While nesting fields using dicts can turn a flat data object into a nested response, you can use :class:`~fields.Nested` to unmarshal nested data structures and render them appropriately. :: - >>> from flask.ext.restful import fields, marshal + >>> from flask_restful import fields, marshal >>> import json >>> >>> address_fields = {} diff --git a/docs/index.rst b/docs/index.rst index f2317230..c0136113 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,11 +3,11 @@ Flask-RESTful ============= -.. module:: flask.ext.restful +.. module:: flask_restful **Flask-RESTful** is an extension for Flask that adds support for quickly building REST APIs. It is a lightweight abstraction that works with your existing ORM/libraries. Flask-RESTful encourages best practices with minimal -setup. If you are familiar with Flask, Flask-RESTful should be easy to pick up. +setup. If you are familiar with Flask, Flask-RESTful should be easy to pick up. .. include:: contents.rst.inc diff --git a/docs/installation.rst b/docs/installation.rst index 3001a8f0..f875fdbd 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -3,7 +3,7 @@ Installation ============ -.. currentmodule:: flask.ext.restful +.. currentmodule:: flask_restful Install Flask-RESTful with ``pip`` :: diff --git a/docs/intermediate-usage.rst b/docs/intermediate-usage.rst index fc68f398..f07f2fe4 100644 --- a/docs/intermediate-usage.rst +++ b/docs/intermediate-usage.rst @@ -3,7 +3,7 @@ Intermediate Usage ================== -.. currentmodule:: flask.ext.restful +.. currentmodule:: flask_restful This page covers building a slightly more complex Flask-RESTful app that will cover out some best practices when setting up a real-world Flask-RESTful-based @@ -42,9 +42,9 @@ example, any custom input/output types your resources need to get the job done. In the resource files, you just have your resource objects. So here's what ``foo.py`` might look like: :: - from flask.ext import restful + from flask_restful import Resource - class Foo(restful.Resource): + class Foo(Resource): def get(self): pass def post(self): @@ -53,13 +53,13 @@ In the resource files, you just have your resource objects. So here's what The key to this setup lies in ``app.py``: :: from flask import Flask - from flask.ext import restful + from flask_restful import Api from myapi.resources.foo import Foo from myapi.resources.bar import Bar from myapi.resources.baz import Baz app = Flask(__name__) - api = restful.Api(app) + api = Api(app) api.add_resource(Foo, '/Foo', '/Foo/') api.add_resource(Bar, '/Bar', '/Bar/') @@ -82,7 +82,7 @@ why you should use them. Here's an example of how to link an :class:`Api` up to a :class:`~flask.Blueprint`. :: from flask import Flask, Blueprint - from flask.ext.restful import Api, Resource, url_for + from flask_restful import Api, Resource, url_for app = Flask(__name__) api_bp = Blueprint('api', __name__) @@ -106,8 +106,7 @@ Elsewhere in the documentation, we've described how to use the reqparse example in detail. Here we'll set up a resource with multiple input parameters that exercise a larger amount of options. We'll define a resource named "User". :: - from flask.ext import restful - from flask.ext.restful import fields, marshal_with, reqparse + from flask_restful import fields, marshal_with, reqparse, Resource def email(email_str): """ return True if email_str is a valid email """ @@ -147,7 +146,7 @@ exercise a larger amount of options. We'll define a resource named "User". :: }), } - class User(restful.Resource): + class User(Resource): @marshal_with(user_fields) def post(self): diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 4acc8a49..47126056 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -3,7 +3,7 @@ Quickstart ========== -.. currentmodule:: flask.ext.restful +.. currentmodule:: flask_restful It's time to write your first REST API. This guide assumes you have a working understanding of `Flask `_, and that you have already @@ -18,12 +18,12 @@ A Minimal API A minimal Flask-RESTful API looks like this: :: from flask import Flask - from flask.ext import restful + from flask_restful import Resource, Api app = Flask(__name__) - api = restful.Api(app) + api = Api(app) - class HelloWorld(restful.Resource): + class HelloWorld(Resource): def get(self): return {'hello': 'world'} @@ -62,7 +62,7 @@ your resource. A basic CRUD resource for a todo application (of course) looks like this: :: from flask import Flask, request - from flask.ext.restful import Resource, Api + from flask_restful import Resource, Api app = Flask(__name__) api = Api(app) @@ -152,7 +152,7 @@ form encoded data), it's still a pain to validate form data. Flask-RESTful has built-in support for request data validation using a library similar to `argparse `_. :: - from flask.ext.restful import reqparse + from flask_restful import reqparse parser = reqparse.RequestParser() parser.add_argument('rate', type=int, help='Rate to charge for this resource') @@ -190,7 +190,7 @@ problem, Flask-RESTful provides the :class:`fields` module and the use the ``fields`` module to describe the structure of your response. :: from collections import OrderedDict - from flask.ext.restful import fields, marshal_with + from flask_restful import fields, marshal_with resource_fields = { 'task': fields.String, @@ -224,7 +224,7 @@ Full Example Save this example in api.py :: from flask import Flask - from flask.ext.restful import reqparse, abort, Api, Resource + from flask_restful import reqparse, abort, Api, Resource app = Flask(__name__) api = Api(app) diff --git a/docs/reqparse.rst b/docs/reqparse.rst index a560ff5b..5c52fac7 100644 --- a/docs/reqparse.rst +++ b/docs/reqparse.rst @@ -3,7 +3,7 @@ Request Parsing =============== -.. currentmodule:: flask.ext.restful +.. currentmodule:: flask_restful Flask-RESTful's request parsing interface, :mod:`reqparse`, is modeled after the `argparse `_ interface. @@ -17,7 +17,7 @@ Here's a simple example of the request parser. It looks for two arguments in the :attr:`flask.Request.values` dict: one of type ``int``, and the other of type ``str`` :: - from flask.ext.restful import reqparse + from flask_restful import reqparse parser = reqparse.RequestParser() parser.add_argument('rate', type=int, help='Rate cannot be converted') @@ -117,7 +117,7 @@ also overwrite any argument in the parent with :meth:`~reqparse.RequestParser.replace_argument`, or remove it completely with :meth:`~reqparse.RequestParser.remove_argument`. For example: :: - from flask.ext.restful import RequestParser + from flask_restful import RequestParser parser = RequestParser() parser.add_argument('foo', type=int) diff --git a/examples/todo.py b/examples/todo.py index 283a6421..860cd62d 100644 --- a/examples/todo.py +++ b/examples/todo.py @@ -1,5 +1,5 @@ from flask import Flask -from flask.ext.restful import reqparse, abort, Api, Resource +from flask_restful import reqparse, abort, Api, Resource app = Flask(__name__) api = Api(app) diff --git a/examples/todo_simple.py b/examples/todo_simple.py index 72388c54..a4236ac2 100644 --- a/examples/todo_simple.py +++ b/examples/todo_simple.py @@ -1,5 +1,5 @@ from flask import Flask, request -from flask.ext.restful import Resource, Api +from flask_restful import Resource, Api app = Flask(__name__) api = Api(app) diff --git a/examples/xml_representation.py b/examples/xml_representation.py index d4c5ccba..7810d925 100644 --- a/examples/xml_representation.py +++ b/examples/xml_representation.py @@ -1,7 +1,7 @@ # needs: pip install python-simplexml from simplexml import dumps from flask import make_response, Flask -from flask.ext.restful import Api, Resource +from flask_restful import Api, Resource def output_xml(data, code, headers=None): """Makes a Flask response with a XML encoded body""" diff --git a/flask_restful/__init__.py b/flask_restful/__init__.py index 0810a57a..3fc32bd9 100644 --- a/flask_restful/__init__.py +++ b/flask_restful/__init__.py @@ -10,8 +10,8 @@ from werkzeug.exceptions import HTTPException, MethodNotAllowed, NotFound, NotAcceptable, InternalServerError from werkzeug.http import HTTP_STATUS_CODES from werkzeug.wrappers import Response as ResponseBase -from flask.ext.restful.utils import error_data, unpack, OrderedDict -from flask.ext.restful.representations.json import output_json +from flask_restful.utils import error_data, unpack, OrderedDict +from flask_restful.representations.json import output_json import sys from flask.helpers import _endpoint_from_view_func from types import MethodType @@ -376,8 +376,8 @@ def add_resource(self, resource, *urls, **kwargs): self.resources.append((resource, urls, kwargs)) def resource(self, *urls, **kwargs): - """Wraps a :class:`~flask.ext.restful.Resource` class, adding it to the - api. Parameters are the same as :meth:`~flask.ext.restful.Api.add_resource`. + """Wraps a :class:`~flask_restful.Resource` class, adding it to the + api. Parameters are the same as :meth:`~flask_restful.Api.add_resource`. Example:: @@ -463,14 +463,14 @@ 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 + 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, + self.representations, default=default_mediatype, ) if mediatype is None: @@ -535,7 +535,7 @@ class Resource(MethodView): the API will return a response with status 405 Method Not Allowed. Otherwise the appropriate method is called and passed all arguments from the url rule used when adding the resource to an Api instance. See - :meth:`~flask.ext.restful.Api.add_resource` for details. + :meth:`~flask_restful.Api.add_resource` for details. """ representations = None method_decorators = [] @@ -581,7 +581,7 @@ def marshal(data, fields, envelope=None): response - >>> from flask.ext.restful import fields, marshal + >>> from flask_restful import fields, marshal >>> data = { 'a': 100, 'b': 'foo' } >>> mfields = { 'a': fields.Raw } @@ -611,7 +611,7 @@ def make(cls): class marshal_with(object): """A decorator that apply marshalling to the return values of your methods. - >>> from flask.ext.restful import fields, marshal_with + >>> from flask_restful import fields, marshal_with >>> mfields = { 'a': fields.Raw } >>> @marshal_with(mfields) ... def get(): @@ -629,7 +629,7 @@ class marshal_with(object): >>> get() OrderedDict([('data', OrderedDict([('a', 100)]))]) - see :meth:`flask.ext.restful.marshal` + see :meth:`flask_restful.marshal` """ def __init__(self, fields, envelope=None): """ @@ -657,7 +657,7 @@ class marshal_with_field(object): """ A decorator that formats the return values of your methods with a single field. - >>> from flask.ext.restful import marshal_with_field, fields + >>> from flask_restful import marshal_with_field, fields >>> @marshal_with_field(fields.List(fields.Integer)) ... def get(): ... return ['1', 2, 3.0] @@ -665,7 +665,7 @@ class marshal_with_field(object): >>> get() [1, 2, 3] - see :meth:`flask.ext.restful.marshal_with` + see :meth:`flask_restful.marshal_with` """ def __init__(self, field): """ diff --git a/tests/test_api.py b/tests/test_api.py index 02901278..c7c740fe 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -8,7 +8,7 @@ from unittest.mock import Mock, patch import flask import werkzeug -from flask.ext.restful.utils import http_status_message, error_data, unpack +from flask_restful.utils import http_status_message, error_data, unpack import flask_restful import flask_restful.fields from flask_restful import OrderedDict @@ -796,7 +796,7 @@ def get(self): # 1. Set the settings dict() with some value # 2. Patch the json.dumps function in the module with a Mock object. - from flask.ext.restful.representations import json as json_rep + from flask_restful.representations import json as json_rep json_dumps_mock = Mock(return_value='bar') new_settings = {'indent': 123} diff --git a/tests/test_fields.py b/tests/test_fields.py index 2ccc952d..c238891a 100644 --- a/tests/test_fields.py +++ b/tests/test_fields.py @@ -3,8 +3,8 @@ import pytz import unittest from mock import Mock -from flask.ext.restful.fields import MarshallingException -from flask.ext.restful.utils import OrderedDict +from flask_restful.fields import MarshallingException +from flask_restful.utils import OrderedDict from flask_restful import fields from datetime import datetime, timedelta, tzinfo from flask import Flask, Blueprint