x/wsme
Code Issues Proposed changes

Document the tg1x and cornice adapters

Browse Source
This commit is contained in:
Christophe de Vienne 2013-01-30 15:48:35 +01:00
parent 0a77e3c307
commit c96f9360c5
2 changed files with 90 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
doc/integrate.rst
View File

@ -15,7 +15,8 @@ This decorator can have two different names depending on the adapter.
take care of calling the adequate decorators of the framework.
Generally this decorator is provided for frameworks that use
object-dispatch controllers, like Pecan_ or Turbogears_.
object-dispatch controllers, such as :ref:`adapter-pecan` and
:ref:`adapter-tg1`.
``@signature``
This decorator only set the function signature and returns a function
@ -23,7 +24,7 @@ This decorator can have two different names depending on the adapter.
Generally this decorator is provided for frameworks that expects functions
taking a request object as a single parameter and returning a response
object. This is the case of cornice_.
object. This is the case of :ref:`adapter-cornice`.
Additionnaly, if you want to enable additionnal protocols, you will need to
mount a :class:`WSRoot` instance somewhere in the application, generally
@ -87,9 +88,51 @@ Pyramid
The recommended way of using WSME inside Pyramid is to use cornice.
.. _adapter-cornice:
Cornice
-------
:mod:`wsmeext.cornice` -- Cornice adapter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. module:: wsmeext.cornice
.. function:: signature
Declare the parameters of a function and returns a function suitable for
cornice (ie that takes a request and returns a response).
Example
~~~~~~~
.. code-block:: python
from cornice import Service
from wsmeext.cornice import signature
import wsme.types
hello = Service(name='hello', path='/', description="Simplest app")
class Info(wsme.types.Base):
message = wsme.types.text
@hello.get()
@signature(Info)
def get_info():
"""Returns Hello in JSON or XML."""
return Info(message='Hello World')
@hello.post()
@signature(None, Info)
def set_info(info):
print("Got a message: %s" % info.message)
.. _adapter-pecan:
Pecan
-----
@ -98,12 +141,12 @@ Pecan
A pecan application is not able to mount another wsgi application on a
subpath. For that reason, additional protocols are not supported for now.
Api
~~~
:mod:`wsmeext.pecan` -- Pecan adapter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. module:: wsmeext.pecan
.. function:: wsexpose(return_type, \*arg_types, **options)
.. function:: wsexpose(return_type, \*arg_types, \*\*options)
See @\ :func:`signature` for parameters documentation.
@ -132,69 +175,73 @@ The `example <http://pecan.readthedocs.org/en/latest/rest.html#nesting-restcontr
class AuthorsController(RestController):
books = BooksController()
.. _adapter-tg1:
Turbogears 1.x
--------------
:mod:`wsme.tg1` -- TG1 adapter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The TG adapters have an api very similar to TGWebServices. Migrating from it
should be straightforward (a little howto migrate would not hurt though, and it
will be written as soon as possible).
.. module:: wsme.tg1
:mod:`wsmeext.tg11` -- TG 1.1 adapter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. class:: Controller(wsroot)
.. module:: wsmeext.tg11
A TG1 Controller that publish a :class:`wsme.WSRoot`.
.. function:: wsexpose(return_type, \*arg_types, \*\*options)
.. function:: adapt
See @\ :func:`signature` for parameters documentation.
Returns a :class:`Controller` that publish a :class:`wsme.WSRoot`.
Can be used on any function of a controller
instead of the expose decorator from TG.
:mod:`wsme.tg15` -- TG 1.5 adapter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. function:: wsvalidate(\*arg_types)
.. module:: wsme.tg15
Set the argument types of an exposed function. This decorator is provided
so that WSME is an almost drop-in replacement for TGWebServices. If
starting from scratch you can use \ :func:`expose` only
.. class:: Controller(wsroot)
.. function:: adapt(wsroot)
A TG1 Controller that publish a :class:`wsme.WSRoot`.
Returns a TG1 controller instance that publish a :class:`wsme.WSRoot`.
It can then be mounted on a TG1 controller.
.. function:: adapt
Because the adapt function modifies the cherrypy filters of the controller
the 'webpath' of the WSRoot instance must be consistent with the path it
will be mounted on.
Returns a :class:`Controller` that publish a :class:`wsme.WSRoot`.
:mod:`wsmeext.tg15` -- TG 1.5 adapter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. module:: wsmeext.tg15
This adapter has the exact same api as :mod:`wsmeext.tg11`.
Example
~~~~~~~
In a freshly quickstarted tg1 application (let's say, wsmedemo),
the prefered way is the following :
Create a new file, "wsmedemo/ws.py" :
.. code-block:: python
import wsme.tg1
from wsme import expose, validate, WSRoot
class WSController(WSRoot):
@expose(int)
@validate(int, int)
def multiply(self, a, b):
return a * b
Insert the ws controller in the controller tree, (file controllers.py):
In a freshly quickstarted tg1 application (let's say, wsmedemo), you can add
REST-ish functions anywhere in your controller tree. Here directly on the root,
in controllers.py:
.. code-block:: python
# ...
from wsmedemo.ws import WSController
import wsme.tg1
# For tg 1.5, import from wsmeext.tg15 instead :
from wsmeext.tg11 import wsexpose, WSRoot
class Root(controllers.RootController):
ws = wsme.tg1.adapt(
WSController(webpath='/ws', protocols=['restjson']))
# Having a WSRoot on /ws is only required to enable additional
# protocols. For REST-only services, it can be ignored.
ws = adapt(
WSRoot(webpath='/ws', protocols=['soap'])
)
# ...
@wsexpose(int, int, int)
def multiply(self, a, b):
return a * b
.. _Pecan: http://pecanpy.org/
.. _TurboGears: http://www.turbogears.org/

2
wsmeext/cornice.py
View File

@ -59,7 +59,7 @@ class WSMEXmlRenderer(object):
return et.tostring(data)
def wsexpose(*args, **kwargs):
def signature(*args, **kwargs):
sig = wsme.sig(*args, **kwargs)
def decorate(f):