Document a bit
This commit is contained in:
Christophe de Vienne
parent
3f6796f3bb
commit
fc94201b0c
27
doc/_static/wsme.css
vendored
Normal file
27
doc/_static/wsme.css
vendored
Normal file
@ -0,0 +1,27 @@
|
||||
@import "agogo.css";
|
||||
|
||||
table.docutils {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
border: 1;
|
||||
}
|
||||
|
||||
table.docutils th {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
border: 0;
|
||||
}
|
||||
|
||||
table.docutils thead tr {
|
||||
}
|
||||
|
||||
table.docutils td {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
border: 0;
|
||||
}
|
||||
|
||||
table.docutils tr.row-odd {
|
||||
background: #EEEEEC;
|
||||
}
|
||||
|
||||
@ -18,6 +18,9 @@ Public API
|
||||
.. autoclass:: wsproperty
|
||||
.. autoclass:: wsattr
|
||||
|
||||
.. data:: Unset
|
||||
|
||||
Default value of the complex type attributes.
|
||||
|
||||
Internals
|
||||
---------
|
||||
|
||||
@ -14,18 +14,16 @@ next
|
||||
|
||||
* The restjson protocol do not nest the results in an object anymore.
|
||||
|
||||
* Fixes
|
||||
* Fix array attributes validation.
|
||||
|
||||
* Fix array attributes validation.
|
||||
* Fix date|time parsing errors.
|
||||
|
||||
* Fix date|time parsing errors.
|
||||
* Fix Unset values validation.
|
||||
|
||||
* Fix Unset values validation.
|
||||
* Fix registering of complex types inheriting form already
|
||||
registered complex types.
|
||||
|
||||
* Fix registering of complex types inheriting form already
|
||||
registered complex types.
|
||||
|
||||
* Fix user types, str and None values encoding/decoding.
|
||||
* Fix user types, str and None values encoding/decoding.
|
||||
|
||||
0.2.0 (2011-10-29)
|
||||
------------------
|
||||
|
||||
@ -94,6 +94,8 @@ pygments_style = 'sphinx'
|
||||
# a list of builtin themes.
|
||||
html_theme = 'agogo'
|
||||
|
||||
html_style = 'wsme.css'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
|
||||
@ -1,78 +1,9 @@
|
||||
Protocols
|
||||
=========
|
||||
|
||||
The example
|
||||
-----------
|
||||
|
||||
In this document the same webservice example will be used to
|
||||
illustrate the different protocols:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class Person(object):
|
||||
id = int
|
||||
lastname = unicode
|
||||
firstname = unicode
|
||||
age = int
|
||||
|
||||
hobbies = [unicode]
|
||||
|
||||
def __init__(self, id=None, lastname=None, firstname=None, age=None,
|
||||
hobbies=None):
|
||||
if id:
|
||||
self.id = id
|
||||
if lastname:
|
||||
self.lastname = lastname
|
||||
if firstname:
|
||||
self.firstname = firstname
|
||||
if age:
|
||||
self.age = age
|
||||
if hobbies:
|
||||
self.hobbies = hobbies
|
||||
|
||||
persons = {
|
||||
1: Person(1, "Geller", "Ross", 30, ["Dinosaurs", "Rachel"]),
|
||||
2: Person(2, "Geller", "Monica", 28, ["Food", "Cleaning"])
|
||||
}
|
||||
|
||||
class PersonController(object):
|
||||
@expose(Person)
|
||||
@validate(int)
|
||||
def get(self, id):
|
||||
return persons[id]
|
||||
|
||||
@expose([Person])
|
||||
def list(self):
|
||||
return persons.values()
|
||||
|
||||
@expose(Person)
|
||||
@validate(Person)
|
||||
def update(self, p):
|
||||
if p.id is Unset:
|
||||
raise ClientSideError("id is missing")
|
||||
persons[p.id] = p
|
||||
return p
|
||||
|
||||
@expose(Person)
|
||||
@validate(Person)
|
||||
def create(self, p):
|
||||
if p.id is not Unset:
|
||||
raise ClientSideError("I don't want an id")
|
||||
p.id = max(persons.keys()) + 1
|
||||
persons[p.id] = p
|
||||
return p
|
||||
|
||||
@expose()
|
||||
@validate(int)
|
||||
def destroy(self, id):
|
||||
if id not in persons:
|
||||
raise ClientSideError("Unknown ID")
|
||||
|
||||
|
||||
class WS(WSRoot):
|
||||
person = PersonController()
|
||||
|
||||
root = WS(webpath='ws')
|
||||
illustrate the different protocols. Its source code is in the
|
||||
last chapter (:ref:`protocols-the-example`).
|
||||
|
||||
REST
|
||||
----
|
||||
@ -104,7 +35,7 @@ The function parameters can be transmitted in two ways :
|
||||
|
||||
``/ws/person/get?id=5``
|
||||
|
||||
Complex types, although not yet implemented, should work this way:
|
||||
Complex types can be transmitted this way:
|
||||
|
||||
``/ws/person/update?p.id=1&p.name=Ross&p.hobbies[0]=Dinausaurs&p.hobbies[1]=Rachel``
|
||||
|
||||
@ -129,6 +60,12 @@ This protocol is selected if:
|
||||
- A trailing '.json' is added to the path
|
||||
- A 'wsmeproto=restjson' is added in the query string
|
||||
|
||||
Options
|
||||
~~~~~~~
|
||||
|
||||
:nest_result: Nest the encoded result in a result param of an object.
|
||||
For example, a result of ``2`` would be ``{'result': 2}``
|
||||
|
||||
Types
|
||||
~~~~~
|
||||
|
||||
@ -163,7 +100,7 @@ Types
|
||||
Return
|
||||
~~~~~~
|
||||
|
||||
A json object with a single 'result' property, OR a json object
|
||||
The json encoded result when the response code is 200, OR a json object
|
||||
with error properties ('faulcode', 'faultstring' and 'debuginfo' if
|
||||
available).
|
||||
|
||||
@ -172,16 +109,14 @@ For example, the /ws/person/get result looks like:
|
||||
.. code-block:: javascript
|
||||
|
||||
{
|
||||
'result': {
|
||||
'id': 2
|
||||
'fistname': 'Monica',
|
||||
'lastname': 'Geller',
|
||||
'age': 28,
|
||||
'hobbies': [
|
||||
'Food',
|
||||
'Cleaning'
|
||||
]
|
||||
}
|
||||
'id': 2
|
||||
'fistname': 'Monica',
|
||||
'lastname': 'Geller',
|
||||
'age': 28,
|
||||
'hobbies': [
|
||||
'Food',
|
||||
'Cleaning'
|
||||
]
|
||||
}
|
||||
|
||||
And in case of error:
|
||||
@ -208,51 +143,63 @@ This protocol is selected if
|
||||
Types
|
||||
~~~~~
|
||||
|
||||
+---------------+------------------------------------+
|
||||
| Type | XML example |
|
||||
+===============+====================================+
|
||||
| ``str`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>a string</value> |
|
||||
+---------------+------------------------------------+
|
||||
| ``unicode`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>a string</value> |
|
||||
+---------------+------------------------------------+
|
||||
| ``int`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>5</value> |
|
||||
+---------------+------------------------------------+
|
||||
| ``float`` | <value>3.14</value> |
|
||||
+---------------+------------------------------------+
|
||||
| ``bool`` | <value>true</value> |
|
||||
+---------------+------------------------------------+
|
||||
| ``Decimal`` | <value>5.46</value> |
|
||||
+---------------+------------------------------------+
|
||||
| ``date`` | <value>2010-04-27</value> |
|
||||
+---------------+------------------------------------+
|
||||
| ``time`` | <value>12:54:18</value> |
|
||||
+---------------+------------------------------------+
|
||||
| ``datetime`` | <value>2010-04-27T12:54:18</value> |
|
||||
+---------------+------------------------------------+
|
||||
| Arrays | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value> |
|
||||
| | <item>Dinausaurs<item> |
|
||||
| | <item>Rachel<item> |
|
||||
| | </value> |
|
||||
+---------------+------------------------------------+
|
||||
| None | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value nil="true"/> |
|
||||
+---------------+------------------------------------+
|
||||
| Complex types | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value> |
|
||||
| | <id>1</id> |
|
||||
| | <fistname>1</fistname> |
|
||||
| | </value> |
|
||||
+---------------+------------------------------------+
|
||||
+---------------+----------------------------------------+
|
||||
| Type | XML example |
|
||||
+===============+========================================+
|
||||
| ``str`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>a string</value> |
|
||||
+---------------+----------------------------------------+
|
||||
| ``unicode`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>a string</value> |
|
||||
+---------------+----------------------------------------+
|
||||
| ``int`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>5</value> |
|
||||
+---------------+----------------------------------------+
|
||||
| ``float`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>3.14</value> |
|
||||
+---------------+----------------------------------------+
|
||||
| ``bool`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>true</value> |
|
||||
+---------------+----------------------------------------+
|
||||
| ``Decimal`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>5.46</value> |
|
||||
+---------------+----------------------------------------+
|
||||
| ``date`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>2010-04-27</value> |
|
||||
+---------------+----------------------------------------+
|
||||
| ``time`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>12:54:18</value> |
|
||||
+---------------+----------------------------------------+
|
||||
| ``datetime`` | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value>2010-04-27T12:54:18</value> |
|
||||
+---------------+----------------------------------------+
|
||||
| Arrays | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value> |
|
||||
| | <item>Dinausaurs<item> |
|
||||
| | <item>Rachel<item> |
|
||||
| | </value> |
|
||||
+---------------+----------------------------------------+
|
||||
| None | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value nil="true"/> |
|
||||
+---------------+----------------------------------------+
|
||||
| Complex types | .. code-block:: xml |
|
||||
| | |
|
||||
| | <value> |
|
||||
| | <id>1</id> |
|
||||
| | <fistname>Ross</fistname> |
|
||||
| | </value> |
|
||||
+---------------+----------------------------------------+
|
||||
|
||||
Return
|
||||
~~~~~~
|
||||
@ -336,3 +283,79 @@ expose extra options
|
||||
function.
|
||||
|
||||
.. _Ext Direct: http://www.sencha.com/products/extjs/extdirect
|
||||
|
||||
.. _protocols-the-example:
|
||||
|
||||
The example
|
||||
-----------
|
||||
|
||||
In this document the same webservice example will be used to
|
||||
illustrate the different protocols:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
class Person(object):
|
||||
id = int
|
||||
lastname = unicode
|
||||
firstname = unicode
|
||||
age = int
|
||||
|
||||
hobbies = [unicode]
|
||||
|
||||
def __init__(self, id=None, lastname=None, firstname=None, age=None,
|
||||
hobbies=None):
|
||||
if id:
|
||||
self.id = id
|
||||
if lastname:
|
||||
self.lastname = lastname
|
||||
if firstname:
|
||||
self.firstname = firstname
|
||||
if age:
|
||||
self.age = age
|
||||
if hobbies:
|
||||
self.hobbies = hobbies
|
||||
|
||||
persons = {
|
||||
1: Person(1, "Geller", "Ross", 30, ["Dinosaurs", "Rachel"]),
|
||||
2: Person(2, "Geller", "Monica", 28, ["Food", "Cleaning"])
|
||||
}
|
||||
|
||||
class PersonController(object):
|
||||
@expose(Person)
|
||||
@validate(int)
|
||||
def get(self, id):
|
||||
return persons[id]
|
||||
|
||||
@expose([Person])
|
||||
def list(self):
|
||||
return persons.values()
|
||||
|
||||
@expose(Person)
|
||||
@validate(Person)
|
||||
def update(self, p):
|
||||
if p.id is Unset:
|
||||
raise ClientSideError("id is missing")
|
||||
persons[p.id] = p
|
||||
return p
|
||||
|
||||
@expose(Person)
|
||||
@validate(Person)
|
||||
def create(self, p):
|
||||
if p.id is not Unset:
|
||||
raise ClientSideError("I don't want an id")
|
||||
p.id = max(persons.keys()) + 1
|
||||
persons[p.id] = p
|
||||
return p
|
||||
|
||||
@expose()
|
||||
@validate(int)
|
||||
def destroy(self, id):
|
||||
if id not in persons:
|
||||
raise ClientSideError("Unknown ID")
|
||||
|
||||
|
||||
class WS(WSRoot):
|
||||
person = PersonController()
|
||||
|
||||
root = WS(webpath='ws')
|
||||
|
||||
|
||||
@ -167,7 +167,8 @@ A few things you should know about complex types:
|
||||
assert Person.name.key == "name"
|
||||
assert Person.name.mandatory is False
|
||||
|
||||
- The default value of instances attributes is :data:`Unset <wsme.types.Unset>`.
|
||||
- The default value of instances attributes is
|
||||
:data:`Unset <wsme.Unset>`.
|
||||
|
||||
::
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user