1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
Integrating with a Framework
============================
General considerations
----------------------
Using WSME within another framework providing its own REST capabilities is
generally done by using a specific decorator to declare the function signature,
in addition to the framework's own way of declaring exposed functions.
This decorator can have two different names depending on the adapter.
``@wsexpose``
This decorator will declare the function signature *and*
take care of calling the adequate decorators of the framework.
Generally this decorator is provided for frameworks that use
object-dispatch controllers, such as :ref:`adapter-pecan`.
``@signature``
This decorator only sets the function signature and returns a function
that can be used by the host framework as a REST request target.
Generally this decorator is provided for frameworks that expect functions
taking a request object as a single parameter and returning a response
object. This is the case for :ref:`adapter-flask`.
If you want to enable additional protocols, you will need to
mount a :class:`WSRoot` instance somewhere in the application, generally
``/ws``. This subpath will then handle the additional protocols. In a future
version, a WSGI middleware will probably play this role.
.. note::
Not all the adapters are at the same level of maturity.
WSGI Application
----------------
The :func:`wsme.WSRoot.wsgiapp` function of WSRoot returns a WSGI
application.
Example
~~~~~~~
The following example assumes the REST protocol will be entirely handled by
WSME, which is the case if you write a WSME standalone application.
.. code-block:: python
from wsme import WSRoot, expose
class MyRoot(WSRoot):
@expose(unicode)
def helloworld(self):
return u"Hello World !"
root = MyRoot(protocols=['restjson'])
application = root.wsgiapp()
.. _adapter-flask:
Flask
-----
*"Flask is a microframework for Python based on Werkzeug, Jinja 2 and good
intentions. And before you ask: It's BSD licensed! "*
.. warning::
Flask support is limited to function signature handling. It does not
support additional protocols. This is a temporary limitation, if you have
needs on that matter please tell us at python-wsme@googlegroups.com.
:mod:`wsmeext.flask` -- Flask adapter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. module:: wsmeext.flask
.. function:: signature(return_type, \*arg_types, \*\*options)
See @\ :func:`signature` for parameters documentation.
Can be used on a function before routing it with flask.
Example
~~~~~~~
.. code-block:: python
from wsmeext.flask import signature
@app.route('/multiply')
@signature(int, int, int)
def multiply(a, b):
return a * b
.. _adapter-pecan:
Pecan
-----
*"*\ Pecan_ *was created to fill a void in the Python web-framework world –
a very lightweight framework that provides object-dispatch style routing.
Pecan does not aim to be a "full stack" framework, and therefore includes
no out of the box support for things like sessions or databases. Pecan
instead focuses on HTTP itself."*
.. warning::
A pecan application is not able to mount another WSGI application on a
subpath. For that reason, additional protocols are not supported for now,
until WSME provides a middleware that can do the same as a mounted
WSRoot.
:mod:`wsmeext.pecan` -- Pecan adapter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. module:: wsmeext.pecan
.. function:: wsexpose(return_type, \*arg_types, \*\*options)
See @\ :func:`signature` for parameters documentation.
Can be used on any function of a pecan
`RestController <http://pecan.readthedocs.org/en/latest/rest.html>`_
instead of the expose decorator from Pecan.
Configuration
~~~~~~~~~~~~~
WSME can be configured through the application configation, by adding a 'wsme'
configuration entry in ``config.py``:
.. code-block:: python
wsme = {
'debug': True
}
Valid configuration variables are :
- ``'debug'``: Whether or not to include exception tracebacks in the returned
server-side errors.
Example
~~~~~~~
The `example <http://pecan.readthedocs.org/en/latest/rest.html#nesting-restcontroller>`_ from the Pecan documentation becomes:
.. code-block:: python
from wsmeext.pecan import wsexpose
class BooksController(RestController):
@wsexpose(Book, int, int)
def get(self, author_id, id):
# ..
@wsexpose(Book, int, int, body=Book)
def put(self, author_id, id, book):
# ..
class AuthorsController(RestController):
books = BooksController()
.. _Pecan: http://pecanpy.org/
|
