Metadata-Version: 2.0
Name: flask-restplus
Version: 0.12.1
Summary: Fully featured framework for fast, easy and documented API development with Flask
Home-page: https://github.com/noirbizarre/flask-restplus
Author: Axel Haustant
Author-email: axel@data.gouv.fr
License: BSD-3-Clause
Description-Content-Type: UNKNOWN
Keywords: flask restplus rest api swagger openapi
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Environment :: Web Environment
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Software Distribution
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: BSD License
Requires-Dist: Flask (>=0.8)
Requires-Dist: aniso8601 (>=0.82)
Requires-Dist: jsonschema
Requires-Dist: pytz
Requires-Dist: six (>=1.3.0)
Requires-Dist: enum34; python_version < "3.4"
Provides-Extra: doc
Requires-Dist: Sphinx (==1.6.5); extra == 'doc'
Requires-Dist: alabaster (==0.7.10); extra == 'doc'
Requires-Dist: sphinx-issues (==0.3.1); extra == 'doc'
Provides-Extra: test
Requires-Dist: blinker; extra == 'test'
Requires-Dist: mock (==2.0.0); extra == 'test'
Requires-Dist: pytest (==3.2.3); extra == 'test'
Requires-Dist: pytest-benchmark (==3.1.1); extra == 'test'
Requires-Dist: pytest-cov (==2.5.1); extra == 'test'
Requires-Dist: pytest-faker (==2.0.0); extra == 'test'
Requires-Dist: pytest-flask (==0.10.0); extra == 'test'
Requires-Dist: pytest-mock (==1.6.3); extra == 'test'
Requires-Dist: pytest-profiling (==1.2.11); extra == 'test'
Requires-Dist: pytest-sugar (==0.9.0); extra == 'test'
Requires-Dist: tzlocal; extra == 'test'

==============
Flask RestPlus
==============

.. image:: https://secure.travis-ci.org/noirbizarre/flask-restplus.svg?tag=0.12.1
    :target: https://travis-ci.org/noirbizarre/flask-restplus?tag=0.12.1
    :alt: Build status
.. image:: https://coveralls.io/repos/noirbizarre/flask-restplus/badge.svg?tag=0.12.1
    :target: https://coveralls.io/r/noirbizarre/flask-restplus?tag=0.12.1
    :alt: Code coverage
.. image:: https://readthedocs.org/projects/flask-restplus/badge/?version=0.12.1
    :target: https://flask-restplus.readthedocs.io/en/0.12.1/
    :alt: Documentation status
.. image:: https://img.shields.io/pypi/l/flask-restplus.svg
    :target: https://pypi.org/project/flask-restplus
    :alt: License
.. image:: https://img.shields.io/pypi/pyversions/flask-restplus.svg
    :target: https://pypi.org/project/flask-restplus
    :alt: Supported Python versions
.. image:: https://badges.gitter.im/Join%20Chat.svg
   :alt: Join the chat at https://gitter.im/noirbizarre/flask-restplus
   :target: https://gitter.im/noirbizarre/flask-restplus?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

Flask-RESTPlus is an extension for `Flask`_ that adds support for quickly building REST APIs.
Flask-RESTPlus encourages best practices with minimal setup.
If you are familiar with Flask, Flask-RESTPlus should be easy to pick up.
It provides a coherent collection of decorators and tools to describe your API
and expose its documentation properly using `Swagger`_.


Compatibility
=============

Flask-RestPlus requires Python 2.7 or 3.4+.


Installation
============

You can install Flask-Restplus with pip:

.. code-block:: console

    $ pip install flask-restplus

or with easy_install:

.. code-block:: console

    $ easy_install flask-restplus


Quick start
===========

With Flask-Restplus, you only import the api instance to route and document your endpoints.

.. code-block:: python

    from flask import Flask
    from flask_restplus import Api, Resource, fields

    app = Flask(__name__)
    api = Api(app, version='1.0', title='TodoMVC API',
        description='A simple TodoMVC API',
    )

    ns = api.namespace('todos', description='TODO operations')

    todo = api.model('Todo', {
        'id': fields.Integer(readOnly=True, description='The task unique identifier'),
        'task': fields.String(required=True, description='The task details')
    })


    class TodoDAO(object):
        def __init__(self):
            self.counter = 0
            self.todos = []

        def get(self, id):
            for todo in self.todos:
                if todo['id'] == id:
                    return todo
            api.abort(404, "Todo {} doesn't exist".format(id))

        def create(self, data):
            todo = data
            todo['id'] = self.counter = self.counter + 1
            self.todos.append(todo)
            return todo

        def update(self, id, data):
            todo = self.get(id)
            todo.update(data)
            return todo

        def delete(self, id):
            todo = self.get(id)
            self.todos.remove(todo)


    DAO = TodoDAO()
    DAO.create({'task': 'Build an API'})
    DAO.create({'task': '?????'})
    DAO.create({'task': 'profit!'})


    @ns.route('/')
    class TodoList(Resource):
        '''Shows a list of all todos, and lets you POST to add new tasks'''
        @ns.doc('list_todos')
        @ns.marshal_list_with(todo)
        def get(self):
            '''List all tasks'''
            return DAO.todos

        @ns.doc('create_todo')
        @ns.expect(todo)
        @ns.marshal_with(todo, code=201)
        def post(self):
            '''Create a new task'''
            return DAO.create(api.payload), 201


    @ns.route('/<int:id>')
    @ns.response(404, 'Todo not found')
    @ns.param('id', 'The task identifier')
    class Todo(Resource):
        '''Show a single todo item and lets you delete them'''
        @ns.doc('get_todo')
        @ns.marshal_with(todo)
        def get(self, id):
            '''Fetch a given resource'''
            return DAO.get(id)

        @ns.doc('delete_todo')
        @ns.response(204, 'Todo deleted')
        def delete(self, id):
            '''Delete a task given its identifier'''
            DAO.delete(id)
            return '', 204

        @ns.expect(todo)
        @ns.marshal_with(todo)
        def put(self, id):
            '''Update a task given its identifier'''
            return DAO.update(id, api.payload)


    if __name__ == '__main__':
        app.run(debug=True)




Documentation
=============

The documentation is hosted `on Read the Docs <http://flask-restplus.readthedocs.io/en/latest/>`_


.. _Flask: http://flask.pocoo.org/
.. _Swagger: http://swagger.io/

Changelog
=========



0.12.1 (2018-09-28)
-------------------

- Fix missing changelog inprevious release
- Ensure definitions with both `$ref` and description (or other property) output is valid (using `allOf`)
- Added initial specifications schemas and validation support
- Ensure empty enums are not serialized (to have a valid specification)

0.12.0 (2018-09-27)
-------------------

- Fix Namespace decorators (`#475 <https://github.com/noirbizarre/flask-restplus/issues/475>`_)
- Do not serialize empty tags descriptions
- Ensure `consumes` is properly set when using form parameters on classes
- Ensure parameters are not duplicated (`#164 <https://github.com/noirbizarre/flask-restplus/issues/164>`_, `#196 <https://github.com/noirbizarre/flask-restplus/issues/196>`_, `#234 <https://github.com/noirbizarre/flask-restplus/issues/234>`_)
- Publish sources distribution (`#500 <https://github.com/noirbizarre/flask-restplus/issues/500>`_, `#515 <https://github.com/noirbizarre/flask-restplus/issues/515>`_)
- Fix late resources registeration (`#483 <https://github.com/noirbizarre/flask-restplus/issues/483>`_)
- Don't include namespaces without resources to the SWAGGER documentation (`#470 <https://github.com/noirbizarre/flask-restplus/issues/470>`_)
- Add support for checkbox validation input + consistent behavior between inputs and fields. (`#461 <https://github.com/noirbizarre/flask-restplus/issues/461>`_)
- Fix missing `enum34` dependency (`#444 <https://github.com/noirbizarre/flask-restplus/issues/444>`_)

0.11.0 (2018-05-16)
-------------------

- Add authorizations parsing to namespace (`#403 <https://github.com/noirbizarre/flask-restplus/issues/403>`_)
- Add vendor extensions support (`#97 <https://github.com/noirbizarre/flask-restplus/issues/97>`_)
- ``RequestParser`` arguments now support the ``split`` action
- Ensure default boolean value as `False` works with ``RequestParser`` (`#199 <https://github.com/noirbizarre/flask-restplus/issues/199>`_)
- Schema errors are not longuer hidden by `AttributeError: Api does not have __schema__ attribute` (`#194 <https://github.com/noirbizarre/flask-restplus/issues/194>`_)
- Add a new ``URL`` validator, more flexible and precise.
- Fix error bundling (`#175 <https://github.com/noirbizarre/flask-restplus/issues/175>`_, `#144 <https://github.com/noirbizarre/flask-restplus/issues/144>`_)
- Help message is now added to source error message instead of string interpolation (`#147 <https://github.com/noirbizarre/flask-restplus/issues/147>`_)
- Use pytest instead of nosetests
- Upgrade to Swagger-UI 3.4.0
- Fix typo in comments
- Add an optional key argument, ``skip_none``, in ``marshal_with`` and ``marshal``
- Fix masks not working correctly with Python 2.7 (`#217 <https://github.com/noirbizarre/flask-restplus/issues/217>`_)
- Fixed typos in doc/scaling
- Add docs for `allow_null` and ``Nested``
- Add Namespace.payload
- **Breaking**: everything is unordered by default because ordering has a serious impact on performances:
    - ``Api`` and ``Namespace`` now accept an optionnal ``ordered`` parameter
    - ``marshal_with`` and ``marshal`` now accept an optionnal ``ordered`` parameter

Breaking changes
~~~~~~~~~~~~~~~~

- Drop python 2.6 support
- Improve header handling (`#119 <https://github.com/noirbizarre/flask-restplus/issues/119>`_):
    - `@api.header` only document response headers on all responses
    - `@api.response` accept an optionnal `headers` argument to document response specific headers
    - request header are handled by the `@api.expect` decorator

0.10.1 (2017-03-04)
-------------------

- Fix a typo in ``__init__`` breaking ``from flask_restplus import *`` (`#242 <https://github.com/noirbizarre/flask-restplus/issues/242>`_)
- Basic support for custom URL converters (`#243 <https://github.com/noirbizarre/flask-restplus/issues/243>`_)
- Support custom response classes inheriting from ``BaseResponse`` (`#245 <https://github.com/noirbizarre/flask-restplus/issues/245>`_)
- Allow models to preserve order (`#135 <https://github.com/noirbizarre/flask-restplus/issues/135>`_)

0.10.0 (2017-02-12)
-------------------

- Allows to specify a custom mount path on namespace registration
- Allow to express models as raw schemas
- Upgraded to Swagger-UI 2.2.6
- Support Swagger-UI translations
- Fix prefix trailing slash stripping in Postman doc generation (`#232 <https://github.com/noirbizarre/flask-restplus/issues/232>`_)
- Add validation for lists in the expect decorator (`#231 <https://github.com/noirbizarre/flask-restplus/issues/231>`_)

0.9.2 (2016-04-22)
------------------

- Same version but a PyPI bug force reupload.

0.9.1 (2016-04-22)
------------------

- Added some Swagger-UI Oauth configurations:
    - `SWAGGER_UI_OAUTH_CLIENT_ID`
    - `SWAGGER_UI_OAUTH_REALM`
    - `SWAGGER_UI_OAUTH_APP_NAME`
- Expose ``type: object`` in Swagger schemas (`#157 <https://github.com/noirbizarre/flask-restplus/issues/157>`_)
- Fix an issue with error handlers (`#141 <https://github.com/noirbizarre/flask-restplus/issues/141>`_)
- Fix an issue with Postman export when using OAuth (`#151 <https://github.com/noirbizarre/flask-restplus/issues/151>`_)
- Miscellenaous code and documentation fixes
- Remove last flask-restful references (unless needed) and add missing attributions

0.9.0 (2016-02-22)
------------------

- Make ``Namespace`` behave like ``Blueprint`` for ``Flask``
- Deprecated ``parser`` and ``body`` parameters for ``expect`` in ``doc`` decorator
- Deprecated ``Model.extend`` in favor of ``Model.clone``
- Added the ``param`` decorator
- Honour method restrictions in Swagger documentation (`#93 <https://github.com/noirbizarre/flask-restplus/issues/93>`_)
- Improved documentation

0.8.6 (2015-12-26)
------------------

- Handle callable on API infos
- Handle documentation on error handlers
- Drop/merge flask_restful ``flask_restful.RequestParser``
- Handle ``RequestParser`` into ``expect`` decorator
- Handle schema for ``inputs`` parsers
- Added some inputs:
    - ``email``
    - ``ip``
    - ``ipv4``
    - ``ipv6``


0.8.5 (2015-12-12)
------------------

- Handle mask on ``Polymorph`` field
- Handle mask on inherited models
- Replace `flask_restful.abort` by ``flask_restplus.errors.abort``
- Replace `flask_restful.unpack` by ``flask_restplus.utils.unpack``
- **Breaking changes**:
    - Renamed ``ApiModel`` into ``Model``
    - Renamed ``ApiNamespace`` into ``Namespace``


0.8.4 (2015-12-07)
------------------

- Drop/merge `flask_restful.Resource` resolving a recursion problem
- Allow any `callable` as field `default`, `min`, `max`...
- Added ``Date`` field
- Improve error handling for inconsistent masks
- Handle model level default mask
- support colons and dashes in mask field names
- **Breaking changes**:
   - Renamed `exceptions` module into `errors`
   - Renamed `RestException` into ``RestError``
   - Renamed `MarshallingException` into ``MarshallingError``
   - ``DateTime`` field always output datetime

0.8.3 (2015-12-05)
------------------

- Drop/merge flask-restful fields
- Drop/merge flask-restplus inputs
- Update Swagger-UI to version 2.1.3
- Use minified version of Swagger-UI if ``DEBUG=False``
- Blueprint subdomain support (static only)
- Added support for default fields mask

0.8.2 (2015-12-01)
------------------

- Skip unknown fields in mask when applied on a model
- Added `*` token to fields mask (all remaining fields)
- Ensure generated endpoints does not collide
- Drop/merge flask-restful `Api.handler_error()`

0.8.1 (2015-11-27)
------------------

- Refactor Swagger UI handling:
    - allow to register a custom view with ``@api.documentation``
    - allow to register a custom URL with the ``doc`` parameter
    - allow to disable documentation with ``doc=False``
- Added fields mask support through header (see: `Fields Masks Documentation <http://flask-restplus.readthedocs.org/en/stable/mask.html>`_)
- Expose ``flask_restful.inputs`` module on ``flask_restplus.inputs``
- Added support for some missing fields and attributes:
    - ``host`` root field (filed only if ``SERVER_NAME`` config is set)
    - custom ``tags`` root field
    - ``exclusiveMinimum`` and ``exclusiveMaximum`` number field attributes
    - ``multipleOf`` number field attribute
    - ``minLength`` and ``maxLength`` string field attributes
    - ``pattern`` string field attribute
    - ``minItems`` and ``maxItems`` list field attributes
    - ``uniqueItems`` list field attribute
- Allow to override the default error handler
- Fixes


0.8.0
-----

- Added payload validation (initial implementation based on jsonschema)
- Added ``@api.deprecated`` to mark resources or methods as deprecated
- Added ``@api.header`` decorator shortcut to document headers
- Added Postman export
- Fix compatibility with flask-restful 0.3.4
- Allow to specify an exemple a custom fields with ``__schema_example__``
- Added support for ``PATCH`` method in Swagger UI
- Upgraded to Swagger UI 2.1.2
- Handle enum as callable
- Allow to configure ``docExpansion`` with the ``SWAGGER_UI_DOC_EXPANSION`` parameter


0.7.2
-----

- Compatibility with flask-restful 0.3.3
- Fix action=append handling in RequestParser
- Upgraded to SwaggerUI 2.1.8-M1
- Miscellaneous fixes


0.7.1
-----

- Fix ``@api.marshal_with_list()`` keyword arguments handling.


0.7.0
-----

- Expose models and fields schema through the ``__schema__`` attribute
- Drop support for model as class
- Added ``@api.errorhandler()`` to register custom error handlers
- Added ``@api.response()`` shortcut decorator
- Fix list nested models missing in definitions


0.6.0
-----

- Python 2.6 support
- Experimental polymorphism support (single inheritance only)
    - Added ``Polymorph`` field
    - Added ``discriminator`` attribute support on ``String`` fields
    - Added ``api.inherit()`` method
- Added ``ClassName`` field

0.5.1
-----

- Fix for parameter with schema (do not set type=string)


0.5.0
-----

- Allow shorter syntax to set operation id: ``@api.doc('my-operation')``
- Added a shortcut to specify the expected input model: ``@api.expect(my_fields)``
- Added ``title`` attribute to fields
- Added ``@api.extend()`` to extend models
- Ensure coherence between ``required`` and ``allow_null`` for ``NestedField``
- Support list of primitive types and list of models as body
- Upgraded to latest version of Swagger UI
- Fixes


0.4.2
-----

- Rename apidoc blueprint into restplus_doc to avoid collisions


0.4.1
-----

- Added ``SWAGGER_VALIDATOR_URL`` config parameter
- Added ``readonly`` field parameter
- Upgraded to latest version of Swagger UI


0.4.0
-----

- Port to Flask-Restful 0.3+
- Use the default Blueprint/App mecanism
- Allow to hide some ressources or methods using ``@api.doc(False)`` or ``@api.hide``
- Allow to globally customize the default operationId with the ``default_id`` callable parameter

0.3.0
-----

- Switch to Swagger 2.0 (Major breakage)
    - ``notes`` documentation is now ``description``
    - ``nickname`` documentation is now ``id``
    - new responses declaration format
- Added missing ``body`` parameter to document ``body`` input
- Last release before Flask-Restful 0.3+ compatibility switch


0.2.4
-----

- Handle ``description`` and ``required`` attributes on ``fields.List``

0.2.3
-----

- Fix custom fields registeration

0.2.2
-----

- Fix model list in declaration

0.2.1
-----

- Allow to type custom fields with ``Api.model``
- Handle custom fields into ``fieds.List``

0.2
---

- Upgraded to SwaggerUI 0.2.22
- Support additional field documentation attributes: ``required``, ``description``, ``enum``, ``min``, ``max`` and ``default``
- Initial support for model in RequestParser

0.1.3
-----

- Fix ``Api.marshal()`` shortcut

0.1.2
-----

- Added ``Api.marshal_with()`` and ``Api.marshal_list_with()`` decorators
- Added ``Api.marshal()`` shortcut


0.1.1
-----

- Use ``zip_safe=False`` for proper packaging.


0.1
---

- Initial release