mirror of
https://github.com/sprockets/sprockets.mixins.mediatype.git
synced 2024-12-27 20:24:39 +00:00
Clean up documentation.
This commit is contained in:
parent
7305cad7e7
commit
123793cd86
8 changed files with 208 additions and 184 deletions
116
README.rst
116
README.rst
|
@ -1,93 +1,57 @@
|
|||
sprockets.mixins.media_type
|
||||
===========================
|
||||
A mixin that performs Content-Type negotiation and request/response (de)serialization.
|
||||
A mixin that performs Content-Type negotiation and request/response
|
||||
(de)serialization.
|
||||
|
||||
|Version| |Downloads| |Status| |Coverage| |License|
|
||||
This mix-in adds two methods to a ``tornado.web.RequestHandler`` instance:
|
||||
|
||||
Installation
|
||||
------------
|
||||
``sprockets.mixins.media_type`` is available on the
|
||||
`Python Package Index <https://pypi.python.org/pypi/sprockets.mixins.media_type>`_
|
||||
and can be installed via ``pip`` or ``easy_install``:
|
||||
- ``get_request_body() -> dict``: deserializes the request body according
|
||||
to the HTTP ``Content-Type`` header and returns the deserialized body.
|
||||
- ``send_response(object)``: serializes the response into the content type
|
||||
requested by the ``Accept`` header.
|
||||
|
||||
.. code:: bash
|
||||
Support for a content types is enabled by calling either the
|
||||
``add_binary_content_type`` or ``add_text_content_type`` function with the
|
||||
``tornado.web.Application`` instance, the content type, encoding and decoding
|
||||
functions as parameters:
|
||||
|
||||
pip install sprockets.mixins.media_type
|
||||
.. code-block:: python
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
http://sprocketsmixinsmedia-type.readthedocs.org/en/latest/
|
||||
import json
|
||||
|
||||
Example
|
||||
-------
|
||||
The following example demonstrates how to use the Mix-in to handle media
|
||||
type validation and serialization.
|
||||
from sprockets.mixins import media_type
|
||||
from tornado import web
|
||||
|
||||
.. code:: python
|
||||
def make_application():
|
||||
application = web.Application([
|
||||
# insert your handlers here
|
||||
])
|
||||
|
||||
from tornado import web, gen
|
||||
from sprockets.mixins import media_type
|
||||
media_type.add_text_content_type(application,
|
||||
'application/json', 'utf-8',
|
||||
json.dumps, json.loads)
|
||||
|
||||
return application
|
||||
|
||||
class MyRequestHandler(media_type.MediaTypeMixin, web.RequestHandler):
|
||||
The *add content type* functions will add a attribute to the ``Application``
|
||||
instance that the mix-in uses to manipulate the request and response bodies.
|
||||
|
||||
@gen.coroutine
|
||||
def post(self, **kwargs):
|
||||
# Validate the Content-Type header using the Mix-in
|
||||
if not self.is_valid_content_type():
|
||||
self.set_status(415, 'Unsupported content type')
|
||||
self.finish()
|
||||
return
|
||||
.. code-block:: python
|
||||
|
||||
# Deserialize your request payload
|
||||
data = self.decode_request()
|
||||
from sprockets.mixins import media_type
|
||||
from tornado import web
|
||||
|
||||
# Ensure that you get some data out of it!
|
||||
if not data:
|
||||
self.set_status(400)
|
||||
self.finish()
|
||||
return
|
||||
class SomeHandler(media_type.ContentMixin, web.RequestHandler):
|
||||
def get(self):
|
||||
self.send_response({'data': 'value'})
|
||||
self.finish()
|
||||
|
||||
# Manipulate your data and do business stuff with it
|
||||
data.pop('the_key')
|
||||
def post(self):
|
||||
body = self.get_request_body()
|
||||
# do whatever
|
||||
self.send_response({'action': 'performed'})
|
||||
self.finish()
|
||||
|
||||
self.set_status(200)
|
||||
|
||||
# Automatically serialize your data using the HTTP Accept headers
|
||||
self.write(data)
|
||||
|
||||
@gen.coroutine
|
||||
def get(self, some_id):
|
||||
# Validate the Accept headers using the Mix-in
|
||||
if not self.is_valid_accept_header():
|
||||
self.set_status(406, 'Invalid Accept header')
|
||||
self.finish()
|
||||
return
|
||||
|
||||
# Maybe do some lookups from the database or get some data from somewhere
|
||||
data = {'some_id': some_id}
|
||||
|
||||
self.set_status(200)
|
||||
|
||||
# Automatically serialize your data using the HTTP Accept headers
|
||||
self.write(data)
|
||||
|
||||
|
||||
Version History
|
||||
---------------
|
||||
Available at http://sprocketsmixinsmedia-type.readthedocs.org/en/latest//en/latest/history.html
|
||||
|
||||
.. |Version| image:: https://img.shields.io/pypi/v/sprockets.mixins.media_type.svg?
|
||||
:target: http://badge.fury.io/py/sprockets.mixins.media_type
|
||||
|
||||
.. |Status| image:: https://img.shields.io/travis/sprockets/sprockets.mixins.media_type.svg?
|
||||
:target: https://travis-ci.org/sprockets/sprockets.mixins.media_type
|
||||
|
||||
.. |Coverage| image:: https://img.shields.io/codecov/c/github/sprockets/sprockets.mixins.media_type.svg?
|
||||
:target: https://codecov.io/github/sprockets/sprockets.mixins.media_type?branch=master
|
||||
|
||||
.. |Downloads| image:: https://img.shields.io/pypi/dm/sprockets.mixins.media_type.svg?
|
||||
:target: https://pypi.python.org/pypi/sprockets.mixins.media_type
|
||||
|
||||
.. |License| image:: http://img.shields.io/:license-mit-blue.svg
|
||||
:target: http://doge.mit-license.org
|
||||
Based on the settings stored in the ``Application`` instance and the HTTP
|
||||
headers, the request and response data will be handled correctly or the
|
||||
appropriate HTTP exceptions will be raised.
|
||||
|
|
19
docs/api.rst
19
docs/api.rst
|
@ -1,2 +1,19 @@
|
|||
.. automodule:: sprockets.mixins.media_type
|
||||
API Documentation
|
||||
=================
|
||||
.. currentmodule:: sprockets.mixins.media_type
|
||||
|
||||
Content Type Handling
|
||||
---------------------
|
||||
.. autoclass:: ContentMixin
|
||||
:members:
|
||||
|
||||
Content Type Registration
|
||||
-------------------------
|
||||
.. autofunction:: set_default_content_type
|
||||
|
||||
.. autofunction:: add_binary_content_type
|
||||
|
||||
.. autofunction:: add_text_content_type
|
||||
|
||||
.. autoclass:: ContentSettings
|
||||
:members:
|
||||
|
|
22
docs/conf.py
22
docs/conf.py
|
@ -1,9 +1,11 @@
|
|||
import alabaster
|
||||
from sprockets.mixins.media_type import __version__
|
||||
|
||||
needs_sphinx = '1.0'
|
||||
extensions = ['sphinx.ext.autodoc',
|
||||
'sphinx.ext.viewcode',
|
||||
'sphinx.ext.intersphinx']
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinxcontrib.autohttp.tornado']
|
||||
source_suffix = '.rst'
|
||||
master_doc = 'index'
|
||||
project = 'sprockets.mixins.media_type'
|
||||
|
@ -11,8 +13,26 @@ copyright = '2015, AWeber Communications'
|
|||
release = __version__
|
||||
version = '.'.join(release.split('.')[0:1])
|
||||
|
||||
pygments_style = 'sphinx'
|
||||
html_theme = 'alabaster'
|
||||
html_style = 'custom.css'
|
||||
html_static_path = ['static']
|
||||
html_theme_path = [alabaster.get_path()]
|
||||
html_sidebars = {
|
||||
'**': ['about.html', 'navigation.html'],
|
||||
}
|
||||
html_theme_options = {
|
||||
'github_user': 'sprockets',
|
||||
'github_repo': 'sprockets.mixins.media_type',
|
||||
'description': 'Content-Type negotation mix-in',
|
||||
'github_banner': True,
|
||||
'travis_button': True,
|
||||
'sidebar_width': '230px',
|
||||
}
|
||||
|
||||
intersphinx_mapping = {
|
||||
'python': ('https://docs.python.org/', None),
|
||||
'requests': ('https://requests.readthedocs.org/en/latest/', None),
|
||||
'sprockets': ('https://sprockets.readthedocs.org/en/latest/', None),
|
||||
'tornado': ('http://tornadoweb.org/en/latest/', None),
|
||||
}
|
||||
|
|
112
docs/contributing.rst
Normal file
112
docs/contributing.rst
Normal file
|
@ -0,0 +1,112 @@
|
|||
How to Contribute
|
||||
=================
|
||||
Do you want to contribute fixes or improvements?
|
||||
|
||||
**AWesome!** *Thank you very much, and let's get started.*
|
||||
|
||||
Set up a development environment
|
||||
--------------------------------
|
||||
The first thing that you need is a development environment so that you can
|
||||
run the test suite, update the documentation, and everything else that is
|
||||
involved in contributing. The easiest way to do that is to create a virtual
|
||||
environment for your endevours::
|
||||
|
||||
$ virtualenv -p python2.7 env
|
||||
|
||||
Don't worry about writing code against previous versions of Python unless
|
||||
you you don't have a choice. That is why we run our tests through `tox`_.
|
||||
If you don't have a choice, then install `virtualenv`_ to create the
|
||||
environment instead. The next step is to install the development tools
|
||||
that this project uses. These are listed in *requires/development.txt*::
|
||||
|
||||
$ env/bin/pip install -qr requires/development.txt
|
||||
|
||||
At this point, you will have everything that you need to develop at your
|
||||
disposal. *setup.py* is the swiss-army knife in your development tool
|
||||
chest. It provides the following commands:
|
||||
|
||||
**./setup.py nosetests**
|
||||
Run the test suite using `nose`_ and generate a nice coverage report.
|
||||
|
||||
**./setup.py build_sphinx**
|
||||
Generate the documentation using `sphinx`_.
|
||||
|
||||
**./setup.py flake8**
|
||||
Run `flake8`_ over the code and report style violations.
|
||||
|
||||
If any of the preceding commands give you problems, then you will have to
|
||||
fix them **before** your pull request will be accepted.
|
||||
|
||||
Running Tests
|
||||
-------------
|
||||
The easiest (and quickest) way to run the test suite is to use the
|
||||
*nosetests* command. It will run the test suite against the currently
|
||||
installed python version and report not only the test result but the
|
||||
test coverage as well::
|
||||
|
||||
$ ./setup.py nosetests
|
||||
|
||||
running nosetests
|
||||
running egg_info
|
||||
writing dependency_links to sprockets.mixins.media_type.egg-info/dependency_links.txt
|
||||
writing top-level names to sprockets.mixins.media_type.egg-info/top_level.txt
|
||||
writing sprockets.mixins.media_type.egg-info/PKG-INFO
|
||||
reading manifest file 'sprockets.mixins.media_type.egg-info/SOURCES.txt'
|
||||
reading manifest template 'MANIFEST.in'
|
||||
warning: no previously-included files matching '__pycache__'...
|
||||
warning: no previously-included files matching '*.swp' found ...
|
||||
writing manifest file 'sprockets.mixins.media_type.egg-info/SOURCES.txt'
|
||||
...
|
||||
|
||||
Name Stmts Miss Branch BrMiss Cover Missing
|
||||
----------------------------------------------------------------------
|
||||
...
|
||||
----------------------------------------------------------------------
|
||||
TOTAL 95 2 59 2 97%
|
||||
----------------------------------------------------------------------
|
||||
Ran 44 tests in 0.054s
|
||||
|
||||
OK
|
||||
|
||||
That's the quick way to run tests. The slightly longer way is to run
|
||||
the `detox`_ utility. It will run the test suite against all of the
|
||||
supported python versions in parallel. This is essentially what Travis-CI
|
||||
will do when you issue a pull request anyway::
|
||||
|
||||
$ env/bin/detox
|
||||
py27 recreate: /.../sprockets.mixins.media_type/build/tox/py27
|
||||
GLOB sdist-make: /.../sprockets.mixins.media_type/setup.py
|
||||
py34 recreate: /.../sprockets.mixins.media_type/build/tox/py34
|
||||
py27 installdeps: -rtest-requirements.txt, mock
|
||||
py34 installdeps: -rtest-requirements.txt
|
||||
py27 inst: /.../sprockets.mixins.media_type/build/tox/dist/sprockets.mixins.media_type-0.0.0.zip
|
||||
py27 runtests: PYTHONHASHSEED='2156646470'
|
||||
py27 runtests: commands[0] | /../sprockets.mixins.media_type/build/tox/py27/bin/nosetests
|
||||
py34 inst: /../sprockets.mixins.media_type/.build/tox/dist/sprockets.mixins.media_type-0.0.0.zip
|
||||
py34 runtests: PYTHONHASHSEED='2156646470'
|
||||
py34 runtests: commands[0] | /.../sprockets.mixins.media_type/build/tox/py34/bin/nosetests
|
||||
_________________________________ summary _________________________________
|
||||
py27: commands succeeded
|
||||
py34: commands succeeded
|
||||
congratulations :)
|
||||
|
||||
This is what you want to see. Now you can make your modifications and keep
|
||||
the tests passing.
|
||||
|
||||
Submitting a Pull Request
|
||||
-------------------------
|
||||
Once you have made your modifications, gotten all of the tests to pass,
|
||||
and added any necessary documentation, it is time to contribute back for
|
||||
posterity. You've probably already cloned this repository and created a
|
||||
new branch. If you haven't, then checkout what you have as a branch and
|
||||
roll back *master* to where you found it. Then push your repository up
|
||||
to github and issue a pull request. Describe your changes in the request,
|
||||
if Travis isn't too annoyed someone will review it, and eventually merge
|
||||
it back.
|
||||
|
||||
.. _flake8: http://flake8.readthedocs.org/
|
||||
.. _nose: http://nose.readthedocs.org/
|
||||
.. _sphinx: http://sphinx-doc.org/
|
||||
.. _detox: http://testrun.org/tox/
|
||||
.. _tox: http://testrun.org/tox/
|
||||
.. _virtualenv: http://virtualenv.pypa.io/
|
|
@ -1,54 +1,4 @@
|
|||
Examples
|
||||
========
|
||||
|
||||
The following example demonstrates how to use the Mix-in to handle media
|
||||
type validation and serialization.
|
||||
|
||||
.. code:: python
|
||||
|
||||
from tornado import web, gen
|
||||
from sprockets.mixins import media_type
|
||||
|
||||
|
||||
class MyRequestHandler(media_type.MediaTypeMixin, web.RequestHandler):
|
||||
|
||||
@gen.coroutine
|
||||
def post(self, **kwargs):
|
||||
# Validate the Content-Type header using the Mix-in
|
||||
if not self.is_valid_content_type():
|
||||
self.set_status(415, 'Unsupported content type')
|
||||
self.finish()
|
||||
return
|
||||
|
||||
# Deserialize your request payload
|
||||
data = self.decode_request()
|
||||
|
||||
# Ensure that you get some data out of it!
|
||||
if not data:
|
||||
self.set_status(400)
|
||||
self.finish()
|
||||
return
|
||||
|
||||
# Manipulate your data and do business stuff with it
|
||||
data.pop('the_key')
|
||||
|
||||
self.set_status(200)
|
||||
|
||||
# Automatically serialize your data using the HTTP Accept headers
|
||||
self.write(data)
|
||||
|
||||
@gen.coroutine
|
||||
def get(self, some_id):
|
||||
# Validate the Accept headers using the Mix-in
|
||||
if not self.is_valid_accept_header():
|
||||
self.set_status(406, 'Invalid Accept header')
|
||||
self.finish()
|
||||
return
|
||||
|
||||
# Maybe do some lookups from the database or get some data from somewhere
|
||||
data = {'some_id': some_id}
|
||||
|
||||
self.set_status(200)
|
||||
|
||||
# Automatically serialize your data using the HTTP Accept headers
|
||||
self.write(data)
|
||||
.. literalinclude:: ../examples.py
|
||||
|
|
|
@ -1,61 +1,16 @@
|
|||
sprockets.mixins.media_type
|
||||
===========================
|
||||
A mixin that performs Content-Type negotiation and request/response (de)serialization.
|
||||
.. include:: ../README.rst
|
||||
|
||||
|Version| |Downloads| |Status| |Coverage| |License|
|
||||
|
||||
Installation
|
||||
------------
|
||||
``sprockets.mixins.media_type`` is available on the
|
||||
`Python Package Index <https://pypi.python.org/pypi/sprockets.mixins.media_type>`_
|
||||
and can be installed via ``pip`` or ``easy_install``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
pip install sprockets.mixins.media_type
|
||||
|
||||
API Documentation
|
||||
-----------------
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
api
|
||||
examples
|
||||
|
||||
Version History
|
||||
---------------
|
||||
See :doc:`history`
|
||||
|
||||
Issues
|
||||
------
|
||||
Please report any issues to the Github project at `https://github.com/sprockets/sprockets.mixins.media_type/issues <https://github.com/sprockets/sprockets.mixins.media_type/issues>`_
|
||||
|
||||
Source
|
||||
------
|
||||
``sprockets.mixins.media_type`` source is available on Github at `https://github.com/sprockets/sprockets.mixins.media_type <https://github.com/sprockets/sprockets.mixins.media_type>`_
|
||||
Examples
|
||||
--------
|
||||
.. literalinclude:: ../examples.py
|
||||
|
||||
License
|
||||
-------
|
||||
``sprockets.mixins.media_type`` is released under the `3-Clause BSD license <https://github.com/sprockets/sprockets.mixins.media_type/blob/master/LICENSE>`_.
|
||||
.. include:: ../LICENSE
|
||||
|
||||
Indices and tables
|
||||
------------------
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
.. |Version| image:: https://img.shields.io/pypi/v/sprockets.mixins.media_type.svg?
|
||||
:target: http://badge.fury.io/py/sprockets.mixins.media_type
|
||||
|
||||
.. |Status| image:: https://img.shields.io/travis/sprockets/sprockets.mixins.media_type.svg?
|
||||
:target: https://travis-ci.org/sprockets/sprockets.mixins.media_type
|
||||
|
||||
.. |Coverage| image:: https://img.shields.io/codecov/c/github/sprockets/sprockets.mixins.media_type.svg?
|
||||
:target: https://codecov.io/github/sprockets/sprockets.mixins.media_type?branch=master
|
||||
|
||||
.. |Downloads| image:: https://img.shields.io/pypi/dm/sprockets.mixins.media_type.svg?
|
||||
:target: https://pypi.python.org/pypi/sprockets.mixins.media_type
|
||||
|
||||
.. |License| image:: http://img.shields.io/:license-mit-blue.svg
|
||||
:target: http://doge.mit-license.org
|
||||
api
|
||||
contributing
|
||||
history
|
||||
|
|
4
docs/static/custom.css
vendored
Normal file
4
docs/static/custom.css
vendored
Normal file
|
@ -0,0 +1,4 @@
|
|||
@import url("alabaster.css");
|
||||
h1.logo {
|
||||
font-size: 12pt;
|
||||
}
|
|
@ -1,2 +1,4 @@
|
|||
-r testing.txt
|
||||
-r installation.txt
|
||||
sphinx>=1.2,<2
|
||||
sphinxcontrib-httpdomain>=1.3,<2
|
||||
|
|
Loading…
Reference in a new issue