diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 134 | ||||
| -rw-r--r-- | doc/_static/toggle.css | 10 | ||||
| -rw-r--r-- | doc/_static/toggle.js | 9 | ||||
| -rw-r--r-- | doc/_static/wsme.css | 27 | ||||
| -rw-r--r-- | doc/api.rst | 45 | ||||
| -rw-r--r-- | doc/changes.rst | 439 | ||||
| -rw-r--r-- | doc/conf.py | 259 | ||||
| -rw-r--r-- | doc/document.rst | 190 | ||||
| -rw-r--r-- | doc/functions.rst | 204 | ||||
| -rw-r--r-- | doc/gettingstarted.rst | 15 | ||||
| -rw-r--r-- | doc/index.rst | 27 | ||||
| -rw-r--r-- | doc/integrate.rst | 342 | ||||
| -rw-r--r-- | doc/make.bat | 155 | ||||
| -rw-r--r-- | doc/protocols.rst | 366 | ||||
| -rw-r--r-- | doc/requirements.txt | 3 | ||||
| -rw-r--r-- | doc/todo.rst | 31 | ||||
| -rw-r--r-- | doc/types.rst | 246 |
17 files changed, 0 insertions, 2502 deletions
diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 8cf843c..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,134 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -ziphtml: html - rm -f $(BUILDDIR)/wsme-documentation.zip - cd $(BUILDDIR)/html && zip -r ../wsme-documentation.zip . - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/WebServicesMadeEasy.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/WebServicesMadeEasy.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/WebServicesMadeEasy" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/WebServicesMadeEasy" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/_static/toggle.css b/doc/_static/toggle.css deleted file mode 100644 index df87bdc..0000000 --- a/doc/_static/toggle.css +++ /dev/null @@ -1,10 +0,0 @@ -dl.toggle dt { - background-color: #eeffcc; - border: 1px solid #ac9; - display: inline; -} - -dl.toggle dd { - display: none; -} - diff --git a/doc/_static/toggle.js b/doc/_static/toggle.js deleted file mode 100644 index 0c779ac..0000000 --- a/doc/_static/toggle.js +++ /dev/null @@ -1,9 +0,0 @@ -/*global $,document*/ -$(document).ready(function () { - "use strict"; - $("dl.toggle > dt").click( - function (event) { - $(this).next().toggle(250); - } - ); -}); diff --git a/doc/_static/wsme.css b/doc/_static/wsme.css deleted file mode 100644 index 09675f6..0000000 --- a/doc/_static/wsme.css +++ /dev/null @@ -1,27 +0,0 @@ -@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; -} - diff --git a/doc/api.rst b/doc/api.rst deleted file mode 100644 index dc61f98..0000000 --- a/doc/api.rst +++ /dev/null @@ -1,45 +0,0 @@ -API -=== - -Public API ----------- - -:mod:`wsme` -- Essentials -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. module:: wsme - -.. autoclass:: signature([return_type, [arg0_type, [arg1_type, ... ] ] ], body=None, status_code=None) - -.. autoclass:: wsme.types.Base -.. autoclass:: wsattr -.. autoclass:: wsproperty - -.. data:: Unset - - Default value of the complex type attributes. - -.. autoclass:: WSRoot - :members: - -Internals ---------- - -:mod:`wsme.types` -- Types -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: wsme.types - :members: register_type - -:mod:`wsme.api` -- API related api -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: wsme.api - :members: FunctionArgument, FunctionDefinition - -:mod:`wsme.rest.args` -- REST protocol argument handling -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. automodule:: wsme.rest.args - :members: - diff --git a/doc/changes.rst b/doc/changes.rst deleted file mode 100644 index 4ee6432..0000000 --- a/doc/changes.rst +++ /dev/null @@ -1,439 +0,0 @@ -Changes -======= - -0.9.4 (future) --------------- - -* SQLAlchemy support is deprecated and will be removed in one of the next - releases. It has never actually worked to begin with. - -0.8.0 (2015-08-25) ------------------- - -Changes that may break your app: - -* Returns 400 if unexpected attributes are added to complex types (#1277571). - -Other changes: - -* Returns 415 when Content-Type is invalid (#1419110) -* Returns 400 if a complex input type is not a json object (#1423634) -* Fix error reports with ArrayType and DictType invalid inputs (#1428185, #1428628) -* Update README - -0.7.0 (2015-05-13) ------------------- - -* Ensure UserType objects are converted to basetype -* Convert built-in types when passed as strings -* Multiple protocol accept or content-type matching -* Raise an InvalidInput if you get a ValueError from JSON data -* Remove unsupported python versions from setup.cfg -* Clean up setup.py and add requirements.txt -* Add full MIT license -* Fix i18n when formatting exception -* Cleanup up logging -* Make it possible to use the Response to return a non-default return type -* several fixes for SOAP protocol - -0.6.4 (2014-11-20) ------------------- - -- Include tests in the source distribution - -0.6.3 (2014-11-19) ------------------- - -- Disable universal wheels - -0.6.2 (2014-11-18) ------------------- - -* Flask adapter complex types now supports flask.ext.restful -* Allow disabling complex types auto-register -* Documentation edits -* Various documentation build fixes -* Fix passing Dict and Array based UserType as params - -0.6.1 (2014-05-02) ------------------- - -* Fix error: variable 'kw' referenced before assignment -* Fix default handling for zero values -* Fixing spelling mistakes -* A proper check of UuidType -* pecan: cleanup, use global vars and staticmethod -* args_from_args() to work with an instance of UserType - -0.6 (2014-02-06) ----------------- - -* Add 'readonly' parameter to wsattr -* Fix typos in documents and comments -* Support dynamic types -* Support building wheels (PEP-427) -* Fix a typo in the types documentation -* Add IntegerType and some classes for validation -* Use assertRaises() for negative tests -* Remove the duplicated error message from Enum -* Drop description from 403 flask test case -* Fix SyntaxWarning under Python 3 - -0.5b6 (2013-10-16) ------------------- - -* Add improved support for HTTP response codes in cornice apps. - -* Handle mandatory attributes - -* Fix error code returned when None is used in an Enum - -* Handle list and dict for body type in REST protocol - -* Fix Sphinx for Python 3 - -* Add custom error code to ClientSideError - -* Return a ClientSideError if unable to convert data - -* Validate body when using Pecan - - -0.5b5 (2013-09-16) ------------------- - -More packaging fixes. - -0.5b4 (2013-09-11) ------------------- - -Fixes some release-related files for the stackforge release process. -No user-facing bug fixes or features over what 0.5b3 provides. - -0.5b3 (2013-09-04) ------------------- - -The project moved to stackforge. Mind the new URLs for the repository, bug -report etc (see the documentation). - -* Allow non-default status code return with the pecan adapter - (Angus Salked). - -* Fix returning objects with object attributes set to None on rest-json - & ExtDirect. - -* Allow error details to be set on the Response object (experimental !). - -* Fix: Content-Type header is not set anymore when the return type is None - on the pecan adapter. - -* Support unicode message in ClientSideError (Mehdi Abaakouk). - -* Use pbr instead of d2to1 (Julien Danjou). - -* Python 3.3 support (Julien Danjou). - -* Pecan adapter: returned status can now be set on exceptions (Vitaly - Kostenko). - -* TG adapters: returned status can be set on exceptions (Ryan - Petrello). - -* six >= 1.4.0 support (Julien Danjou). - -* Require ordereddict from pypi for python < 2.6 (Ryan Petrello). - -* Make the code PEP8 compliant (Ryan Petrello). - -0.5b2 (2013-04-18) ------------------- - -* Changed the way datas of complex types are stored. In previous versions, an - attribute was added to the type for each attribute, its name being the - attribute name prefixed with '_'. - - Starting with this version, a single attribute _wsme_dataholder is added to - the instance. - - The motivation behind this change is to avoid adding too many attributes to - the object. - -* Add a special type 'HostRequest' that allow a function to ask for the host - framework request object in its arguments. - -* Pecan adapter: Debug mode (which returns the exception tracebacks to the - client) can be enabled by the pecan application configuration. - -* New adapter: wsmeext.flask, for the Flask_ framework. - -.. _Flask: http://flask.pocoo.org/ - -* Fix: the cornice adapter was not usable. - -* Fix: Submodules of wsmeext were missing in the packages. - -* Fix: The demo app was still depending on the WSME-Soap package (which has - been merged into WSME in 0.5b1). - -* Fix: A function with only on 'body' parameter would fail when being called. - -* Fix: Missing arguments were poorly reported by the frameworks adapters. - -0.5b1 (2013-01-30) ------------------- - -* Introduce a new kind of adapters that rely on the framework routing. - Adapters are provided for Pecan, TurboGears and cornice. - -* Reorganised the rest protocol implementation to ease the implementation of - adapters that rely only on the host framework routing system. - -* The default rest ``@expose`` decorator does not wrap the decorated function - anymore. If needed to expose a same function several times, a parameter - ``multiple_expose=True`` has been introduced. - -* Remove the wsme.release module - -* Fix == operator on ArrayType - -* Adapted the wsme.sphinxext module to work with the function exposed by the - ``wsme.pecan`` adapter. - -* Allow promotion of ``int`` to ``float`` on float attributes (Doug Hellman) - -* Add a ``samples_slot`` option to the ``.. autotype`` directive to - choose where the data samples whould be inserted (Doug Hellman). - -* Add ``sample()`` to ArrayType and DictType (Doug Hellman). - -* New syntax for object arrays as GET parameters, without brackets. Ex: - ``?o.f1=a&o.f1=b&o.f2=c&o.f2=d`` is an array of two objects: - [{'f1': 'a', 'f2': 'c']}, {'f1': 'b', 'f2': 'd']}. - -* @signature (and its @wsexpose frontends) has a new parameter: - ``ignore_extra_args``. - -* Fix boolean as input type support in the soap implementation (Craig - McDaniel). - -* Fix empty/nil strings distinction in soap (Craig McDaniel). - -* Improved unittests code coverage. - -* Ported the soap implementation to python 3. - -* Moved non-core features (adapters, sphinx extension) to the ``wsmeext`` module. - -* Change the GET parameter name for passing the request body as a parameter - is now from 'body' to '__body__' - -* The soap, extdirect and sqlalchemy packages have been merged into the main - package. - -* Changed the documentation theme to "Cloud". - -0.4 (2012-10-15) ----------------- - -* Automatically converts unicode strings to/from ascii bytes. - -* Use d2to1 to simplify setup.py. - -* Implements the SPORE specification. - -* Fixed a few things in the documentation - -0.4b1 (2012-09-14) ------------------- - -* Now supports Python 3.2 - -* String types handling is clearer. - -* New :class:`wsme.types.File` type. - -* Supports cross-referenced types. - -* Various bugfixes. - -* Tests code coverage is now over 95%. - -* RESTful protocol can now use the http method. - -* UserTypes can now be given a name that will be used in the - documentation. - -* Complex types can inherit :class:`wsme.types.Base`. They will - have a default constructor and be registered automatically. - -* Removed the wsme.wsgi.adapt function if favor of - :meth:`wsme.WSRoot.wsgiapp` - -Extensions -~~~~~~~~~~ - -wsme-soap - * Function names now starts with a lowercase letter. - - * Fixed issues with arrays (issue #3). - - * Fixed empty array handling. - - -wsme-sqlalchemy - This new extension makes it easy to create webservices on top - of a SQLAlchemy set of mapped classes. - -wsme-extdirect - * Implements server-side DataStore - (:class:`wsmeext.extdirect.datastore.DataStoreController`). - - * Add Store and Model javascript definition auto-generation - - * Add Store server-side based on SQLAlchemy mapped classes - (:class:`wsmeext.extdirect.sadatastore.SADataStoreController`). - -0.3 (2012-04-20) ----------------- - -* Initial Sphinx integration. - -0.3b2 (2012-03-29) ------------------- - -* Fixed issues with the TG1 adapter. - -* Now handle dict and UserType types as GET/POST params. - -* Better handling of application/x-www-form-urlencoded encoded POSTs - in rest protocols. - -* :class:`wsattr` now takes a 'default' parameter that will be returned - instead of 'Unset' if no value has been set. - -0.3b1 (2012-01-19) ------------------- - -* Per-call database transaction handling. - -* :class:`Unset` is now imported in the wsme module - -* Attributes of complex types can now have a different name in - the public api and in the implementation. - -* Complex arguments can now be sent as GET/POST params in the rest - protocols. - -* The restjson protocol do not nest the results in an object anymore. - -* Improved the documentation - -* Fix array attributes validation. - -* Fix date|time parsing errors. - -* Fix Unset values validation. - -* Fix registering of complex types inheriting form already - registered complex types. - -* Fix user types, str and None values encoding/decoding. - -0.2.0 (2011-10-29) ------------------- - -* Added batch-calls abilities. - -* Introduce a :class:`UnsetType` and a :data:`Unset` constant - so that non-mandatory attributes can remain unset (which is - different from null). - -* Fix: If a complex type was only used as an input type, it was - not registered. - -* Add support for user types. - -* Add an Enum type (which is a user type). - -* The 'binary' type is now a user type. - -* Complex types: - - - Fix inspection of complex types with inheritance. - - - Fix inspection of self-referencing complex types. - - - wsattr is now a python Descriptor, which makes it possible - to retrieve the attribute definition on a class while - manipulating values on the instance. - - - Add strong type validation on assignment (made possible by - the use of Descriptors). - -* ExtDirect: - - - Implements batch calls - - - Fix None values conversion - - - Fix transaction result : 'action' and 'method' were missing. - -0.1.1 (2011-10-20) ------------------- - -* Changed the internal API by introducing a CallContext object. - It makes it easier to implement some protocols that have - a transaction or call id that has to be returned. It will also - make it possible to implement batch-calls in a later version. - -* More test coverage. - -* Fix a problem with array attribute types not being registered. - -* Fix the mandatory / default detection on function arguments. - -* Fix issues with the SOAP protocol implementation which should now - work properly with a suds client. - -* Fix issues with the ExtDirect protocol implementation. - -0.1.0 (2011-10-14) ------------------- - -* Protocol insertion order now influence the protocol selection - -* Move the soap protocol implementation in a separate lib, - WSME-Soap - -* Introduce a new protocol ExtDirect in the WSME-ExtDirect lib. - -0.1.0a4 (2011-10-12) --------------------- - -* Change the way framework adapters works. Now the adapter modules - have a simple adapt function that adapt a :class:`wsme.WSRoot` - instance. This way a same root can be integrated in several - framework. - -* Protocol lookup now use entry points in the group ``[wsme.protocols]``. - -0.1.0a3 (2011-10-11) --------------------- - -* Add specialised WSRoot classes for easy integration as a - WSGI Application (:class:`wsme.wsgi.WSRoot`) or a - TurboGears 1.x controller (:class:`wsme.tg1.WSRoot`). - -* Improve the documentation. - -* More unit tests and code-coverage. - -0.1.0a2 (2011-10-07) --------------------- - -* Added support for arrays in all the protocols - -0.1.0a1 (2011-10-04) --------------------- - -Initial public release. diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index c4b5696..0000000 --- a/doc/conf.py +++ /dev/null @@ -1,259 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Web Services Made Easy documentation build configuration file, created by -# sphinx-quickstart on Sun Oct 2 20:27:45 2011. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('..')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'wsmeext.sphinxext', - 'sphinx.ext.intersphinx'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Web Services Made Easy' -copyright = u'2011, Christophe de Vienne' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -import pkg_resources -wsmedist = pkg_resources.require('WSME')[0] -version = wsmedist.version - -# The short X.Y version. -version = '.'.join(version.split('.')[:2]) -# The full version, including alpha/beta/rc tags. -release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -#html_theme = 'agogo' -#html_theme_options = { -# "pagewidth": "60em", -# "documentwidth": "40em", -#} - -#html_style = 'wsme.css' - -import cloud_sptheme as csp - -html_theme = 'cloud' -html_theme_path = [csp.get_theme_dir()] - -html_theme_options = { - "roottarget": "index", - "googleanalytics_id": "UA-8510502-6" -} - -# 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. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -html_title = "WSME %s" % release - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = "WSME" - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'WebServicesMadeEasydoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -latex_paper_size = 'a4' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'WebServicesMadeEasy.tex', u'Web Services Made Easy Documentation', - u'Christophe de Vienne', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -latex_preamble = ''' -\usepackage[T2A]{fontenc} -\usepackage[utf8]{inputenc} -''' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'webservicesmadeeasy', u'Web Services Made Easy Documentation', - [u'Christophe de Vienne'], 1) -] - - -autodoc_member_order = 'bysource' - -wsme_protocols = [ - 'restjson', 'restxml', 'soap', 'extdirect' -] - -intersphinx_mapping = { - 'python': ('http://docs.python.org/', None), - 'six': ('http://packages.python.org/six/', None), -} - - -def setup(app): - # confval directive taken from the sphinx doc - app.add_object_type('confval', 'confval', - objname='configuration value', - indextemplate='pair: %s; configuration value') diff --git a/doc/document.rst b/doc/document.rst deleted file mode 100644 index 39a54f2..0000000 --- a/doc/document.rst +++ /dev/null @@ -1,190 +0,0 @@ -Document your API -================= - -Web services without a proper documentation are usually useless. - -To make it easy to document your own API, WSME provides a Sphinx_ extension. - -Install the extension ---------------------- - -Here we consider that you already quick-started a sphinx project. - -#. In your ``conf.py`` file, add ``'ext'`` to your extensions, - and optionally set the enabled protocols. - - .. code-block:: python - - extensions = ['ext'] - - wsme_protocols = ['restjson', 'restxml', 'extdirect'] - -#. Copy :download:`toggle.js <_static/toggle.js>` - and :download:`toggle.css <_static/toggle.css>` - in your _static directory. - -The ``wsme`` domain -------------------- - -The extension will add a new Sphinx domain providing a few directives. - -Config values -~~~~~~~~~~~~~ - -.. confval:: wsme_protocols - - A list of strings that are WSME protocol names. If provided by an - additional package (for example WSME-Soap or WSME-ExtDirect), that package must - be installed. - - The types and services generated documentation will include code samples - for each of these protocols. - -.. confval:: wsme_root - - A string that is the full name of the service root controller. - It will be used - to determinate the relative path of the other controllers when they - are autodocumented, and calculate the complete webpath of the other - controllers. - -.. confval:: wsme_webpath - - A string that is the webpath where the :confval:`wsme_root` is mounted. - -Directives -~~~~~~~~~~ - -.. rst:directive:: .. root:: <WSRoot full path> - - Define the service root controller for this documentation source file. - To set it globally, see :confval:`wsme_root`. - - A ``webpath`` option allows override of :confval:`wsme_webpath`. - - Example: - - .. code-block:: rst - - .. wsme:root:: myapp.controllers.MyWSRoot - :webpath: /api - -.. rst:directive:: .. service:: name/space/ServiceName - - Declare a service. - -.. rst:directive:: .. type:: MyComplexType - - Equivalent to the :rst:dir:`py:class` directive to document a complex type - -.. rst:directive:: .. attribute:: aname - - Equivalent to the :rst:dir:`py:attribute` directive to document a complex type - attribute. It takes an additional ``:type:`` field. - -Example -~~~~~~~ - -.. list-table:: - :header-rows: 1 - - * - Source - - Result - - * - .. code-block:: rst - - .. wsme:root:: wsmeext.sphinxext.SampleService - :webpath: /api - - .. wsme:type:: MyType - - .. wsme:attribute:: test - - :type: int - - .. wsme:service:: name/space/SampleService - - .. wsme:function:: doit - - - .. wsme:root:: wsmeext.sphinxext.SampleService - :webpath: /api - - .. wsme:type:: MyType - - .. wsme:attribute:: test - - :type: int - - .. wsme:service:: name/space/SampleService - - .. wsme:function:: getType - - Returns a :wsme:type:`MyType <MyType>` - - -Autodoc directives -~~~~~~~~~~~~~~~~~~ - -Theses directives scan your code to generate the documentation from the -docstrings and your API types and controllers. - -.. rst:directive:: .. autotype:: myapp.MyType - - Generate the myapp.MyType documentation. - -.. rst:directive:: .. autoattribute:: myapp.MyType.aname - - Generate the myapp.MyType.aname documentation. - -.. rst:directive:: .. autoservice:: myapp.MyService - - Generate the myapp.MyService documentation. - -.. rst:directive:: .. autofunction:: myapp.MyService.myfunction - - Generate the myapp.MyService.myfunction documentation. - -Full Example ------------- - -Python source -~~~~~~~~~~~~~ - -.. literalinclude:: ../wsmeext/sphinxext.py - :lines: 69-96 - :language: python - -Documentation source -~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: rst - - .. default-domain:: wsmeext - - .. type:: int - - An integer - - .. autotype:: wsmeext.sphinxext.SampleType - :members: - - .. autoservice:: wsmeext.sphinxext.SampleService - :members: - -Result -~~~~~~ - -.. default-domain:: wsmeext - -.. type:: int - - An integer - -.. autotype:: wsmeext.sphinxext.SampleType - :members: - -.. autoservice:: wsmeext.sphinxext.SampleService - :members: - - -.. _Sphinx: http://sphinx.pocoo.org/ diff --git a/doc/functions.rst b/doc/functions.rst deleted file mode 100644 index da56d25..0000000 --- a/doc/functions.rst +++ /dev/null @@ -1,204 +0,0 @@ -Functions -========= - -WSME is based on the idea that most of the time the input and output of web -services are actually strictly typed. It uses this idea to ease the -implementation of the actual functions by handling those input/output. -It also proposes alternate protocols on top of a proper REST api. - -This chapter explains in detail how to 'sign' a function with WSME. - -The decorators --------------- - -Depending on the framework you are using, you will have to use either a -@\ :class:`wsme.signature` decorator or a @\ :class:`wsme.wsexpose` decorator. - -@signature -~~~~~~~~~~ - -The base @\ :class:`wsme.signature` decorator defines the return and argument types -of the function, and if needed a few more options. - -The Flask and Cornice adapters both propose a specific version of it, which -also wrap the function so that it becomes suitable for the host framework. - -In any case, the use of @\ :class:`wsme.signature` has the same meaning: tell WSME what is the -signature of the function. - -@wsexpose -~~~~~~~~~ - -The native Rest implementation, and the TG and Pecan adapters add a @\ :class:`wsme.wsexpose` -decorator. - -It does what @\ :class:`wsme.signature` does, *and* exposes the function in the routing system -of the host framework. - -This decorator is generally used in an object-dispatch routing context. - -.. note:: - - Since both decorators play the same role, the rest of this - document will alway use @signature. - -Signing a function ------------------- - -Signing a function is just a matter of decorating it with @signature: - -.. code-block:: python - - @signature(int, int, int) - def multiply(a, b): - return a * b - -In this trivial example, we tell WSME that the 'multiply' function returns an -integer, and takes two integer parameters. - -WSME will match the argument types by order to determine the exact type of each -named argument. This is important since most of the web service protocols don't -provide strict argument ordering but only named parameters. - -Optional arguments -~~~~~~~~~~~~~~~~~~ - -Defining an argument as optional is done by providing a default value: - -.. code-block:: python - - @signature(int, int, int): - def increment(value, delta=1): - return value + delta - -In this example, the caller may omit the 'delta' argument, and no -'MissingArgument' error will be raised. - -Additionally, this argument will be documented as optional by the sphinx -extension. - -Body argument -~~~~~~~~~~~~~ - -When defining a Rest CRUD API, we generally have a URL to which we POST data. - -For example: - -.. code-block:: python - - @signature(Author, Author) - def update_author(data): - # ... - return data - -Such a function will take at least one parameter, 'data', that is a structured -type. With the default way of handling parameters, the body of the request -would look like this: - -.. code-block:: javascript - - { - "data": - { - "id": 1, - "name": "Pierre-Joseph" - } - } - -If you think (and you should) that it has one extra level of nesting, the 'body' -argument is here for you:: - - @signature(Author, body=Author) - def update_author(data): - # ... - return data - -With this syntax, we can now post a simpler body: - -.. code-block:: javascript - - { - "id": 1, - "name": "Pierre-Joseph" - } - -Note that this does not prevent the function from having multiple parameters; it just requires -the body argument to be the last: - -.. code-block:: python - - @signature(Author, bool, body=Author) - def update_author(force_update=False, data=None): - # ... - return data - -In this case, the other arguments can be passed in the URL, in addition to the -body parameter. For example, a POST on ``/author/SOMEID?force_update=true``. - -Status code -~~~~~~~~~~~ - -The default status codes returned by WSME are 200, 400 (if the client sends invalid -inputs) and 500 (for server-side errors). - -Since a proper Rest API should use different return codes (201, etc), one can -use the 'status_code=' option of @signature to do so. - -.. code-block:: python - - @signature(Author, body=Author, status_code=201) - def create_author(data): - # ... - return data - -Of course this code will only be used if no error occurs. - -In case the function needs to change the status code on a per-request basis, it -can return a :class:`wsme.Response` object, allowing it to override the status -code: - -.. code-block:: python - - @signature(Author, body=Author, status_code=202) - def update_author(data): - # ... - response = Response(data) - if transaction_finished_and_successful: - response.status_code = 200 - return response - -Extra arguments -~~~~~~~~~~~~~~~ - -The default behavior of WSME is to reject requests that give extra/unknown -arguments. In some (rare) cases, this is undesirable. - -Adding 'ignore_extra_args=True' to @signature changes this behavior. - -.. note:: - - If using this option seems to solve your problem, please think twice - before using it! - -Accessing the request -~~~~~~~~~~~~~~~~~~~~~ - -Most of the time direct access to the request object should not be needed, but -in some cases it is. - -On frameworks that propose a global access to the current request it is not an -issue, but on frameworks like pyramid it is not the way to go. - -To handle this use case, WSME has a special type, :class:`HostRequest`: - -.. code-block:: python - - from wsme.types import HostRequest - - @signature(Author, HostRequest, body=Author) - def create_author(request, newauthor): - # ... - return newauthor - -In this example, the request object of the host framework will be passed as the -``request`` parameter of the create_author function. diff --git a/doc/gettingstarted.rst b/doc/gettingstarted.rst deleted file mode 100644 index 7a35600..0000000 --- a/doc/gettingstarted.rst +++ /dev/null @@ -1,15 +0,0 @@ -Getting Started -=============== - -For now here is just a working example. -You can find it in the examples directory of the source distribution. - -.. literalinclude:: ../examples/demo/demo.py - :language: python - -When running this example, the following soap client can interrogate -the web services: - -.. literalinclude:: ../examples/demo/client.py - :language: python - diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100644 index 7819d57..0000000 --- a/doc/index.rst +++ /dev/null @@ -1,27 +0,0 @@ - -.. include:: ../README.rst - -Contents --------- - -.. toctree:: - :maxdepth: 2 - - gettingstarted - api - types - functions - protocols - integrate - document - - todo - changes - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/integrate.rst b/doc/integrate.rst deleted file mode 100644 index 5adaaca..0000000 --- a/doc/integrate.rst +++ /dev/null @@ -1,342 +0,0 @@ -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` and - :ref:`adapter-tg1`. - -``@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-cornice` and - :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-cornice: - -Cornice -------- - -.. _cornice: http://cornice.readthedocs.org/en/latest/ - - *"* Cornice_ *provides helpers to build & document REST-ish Web Services with - Pyramid, with decent default behaviors. It takes care of following the HTTP - specification in an automated way where possible."* - - -: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). - -Configuration -~~~~~~~~~~~~~ - -To use WSME with Cornice you have to add a configuration option to your Pyramid application. - -.. code-block:: python - - from pyramid.config import Configurator - - - def make_app(): - config = Configurator() - config.include("cornice") - config.include("wsmeext.cornice") # This includes WSME cornice support - # ... - return config.make_wsgi_app() - -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-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/ - -.. _adapter-tg1: - -Turbogears 1.x --------------- - -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). - -:mod:`wsmeext.tg11` -- TG 1.1 adapter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. module:: wsmeext.tg11 - -.. function:: wsexpose(return_type, \*arg_types, \*\*options) - - See @\ :func:`signature` for parameters documentation. - - Can be used on any function of a controller - instead of the expose decorator from TG. - -.. function:: wsvalidate(\*arg_types) - - 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:`wsexpose` only - -.. function:: adapt(wsroot) - - Returns a TG1 controller instance that publish a :class:`wsme.WSRoot`. - It can then be mounted on a TG1 controller. - - 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. - -: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), you can add -REST-ish functions anywhere in your controller tree. Here directly on the root, -in controllers.py: - -.. code-block:: python - - # ... - - # For tg 1.5, import from wsmeext.tg15 instead : - from wsmeext.tg11 import wsexpose, WSRoot - - class Root(controllers.RootController): - # 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 - -.. _TurboGears: http://www.turbogears.org/ - -Other frameworks ----------------- - -Bottle -~~~~~~ - -No adapter is provided yet but it should not be hard to write one, by taking -example on the cornice adapter. - -This example only show how to mount a WSRoot inside a bottle application. - -.. code-block:: python - - import bottle - import wsme - - class MyRoot(wsme.WSRoot): - @wsme.expose(unicode) - def helloworld(self): - return u"Hello World !" - - root = MyRoot(webpath='/ws', protocols=['restjson']) - - bottle.mount('/ws', root.wsgiapp()) - bottle.run() - -Pyramid -~~~~~~~ - -The recommended way of using WSME inside Pyramid is to use -:ref:`adapter-cornice`. diff --git a/doc/make.bat b/doc/make.bat deleted file mode 100644 index a88e5fe..0000000 --- a/doc/make.bat +++ /dev/null @@ -1,155 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^<target^>` where ^<target^> is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\WebServicesMadeEasy.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\WebServicesMadeEasy.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end diff --git a/doc/protocols.rst b/doc/protocols.rst deleted file mode 100644 index a56a49d..0000000 --- a/doc/protocols.rst +++ /dev/null @@ -1,366 +0,0 @@ -Protocols -========= - -In this document the same webservice example will be used to -illustrate the different protocols. Its source code is in the -last chapter (:ref:`protocols-the-example`). - -REST ----- - -.. note:: - - This chapter applies for all adapters, not just the native REST - implementation. - -The two REST protocols share common characterics. - -Each function corresponds to distinct webpath that starts with the -root webpath, followed by the controllers names if any, and finally -the function name. - -The example's exposed functions will be mapped to the following paths: - -- ``/ws/persons/create`` -- ``/ws/persons/get`` -- ``/ws/persons/list`` -- ``/ws/persons/update`` -- ``/ws/persons/destroy`` - -In addition to this trivial function mapping, a `method` option can -be given to the `expose` decorator. In such a case, the function -name can be omitted by the caller, and the dispatch will look at the -HTTP method used in the request to select the correct function. - -The function parameters can be transmitted in two ways (if using -the HTTP method to select the function, one way or the other -may be usable) : - -#. As a GET query string or POST form parameters. - - Simple types are straight forward : - - ``/ws/person/get?id=5`` - - Complex types can be transmitted this way: - - ``/ws/person/update?p.id=1&p.name=Ross&p.hobbies[0]=Dinausaurs&p.hobbies[1]=Rachel`` - -#. In a Json or XML encoded POST body (see below) - -The result will be returned Json or XML encoded (see below). - -In case of error, a 400 or 500 status code is returned, and the -response body contains details about the error (see below). - -REST+Json ---------- - -:name: ``'restjson'`` - -Implements a REST+Json protocol. - -This protocol is selected if: - -- The request content-type is either 'text/javascript' or 'application/json' -- The request 'Accept' header contains 'text/javascript' or 'application/json' -- 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 -~~~~~ - -+---------------+-------------------------------+ -| Type | Json type | -+===============+===============================+ -| ``str`` | String | -+---------------+-------------------------------+ -| ``unicode`` | String | -+---------------+-------------------------------+ -| ``int`` | Number | -+---------------+-------------------------------+ -| ``float`` | Number | -+---------------+-------------------------------+ -| ``bool`` | Boolean | -+---------------+-------------------------------+ -| ``Decimal`` | String | -+---------------+-------------------------------+ -| ``date`` | String (YYYY-MM-DD) | -+---------------+-------------------------------+ -| ``time`` | String (hh:mm:ss) | -+---------------+-------------------------------+ -| ``datetime`` | String (YYYY-MM-DDThh:mm:ss) | -+---------------+-------------------------------+ -| Arrays | Array | -+---------------+-------------------------------+ -| None | null | -+---------------+-------------------------------+ -| Complex types | Object | -+---------------+-------------------------------+ - -Return -~~~~~~ - -The Json encoded result when the response code is 200, or a Json object -with error properties ('faulcode', 'faultstring' and 'debuginfo' if -available) on error. - -For example, the '/ws/person/get' result looks like: - -.. code-block:: javascript - - { - 'id': 2 - 'fistname': 'Monica', - 'lastname': 'Geller', - 'age': 28, - 'hobbies': [ - 'Food', - 'Cleaning' - ] - } - -And in case of error: - -.. code-block:: javascript - - { - 'faultcode': 'Client', - 'faultstring': 'id is missing' - } - -REST+XML --------- - -:name: ``'restxml'`` - -This protocol is selected if - -- The request content-type is 'text/xml' -- The request 'Accept' header contains 'text/xml' -- A trailing '.xml' is added to the path -- A 'wsmeproto=restxml' is added in the query string - -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`` | .. 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 -~~~~~~ - -A xml tree with a top 'result' element. - -.. code-block:: xml - - <result> - <id>1</id> - <firstname>Ross</firstname> - <lastname>Geller</lastname> - </result> - -Errors -~~~~~~ - -A xml tree with a top 'error' element, having 'faultcode', 'faultstring' -and 'debuginfo' subelements: - -.. code-block:: xml - - <error> - <faultcode>Client</faultcode> - <faultstring>id is missing</faultstring> - </error> - -SOAP ----- - -:name: ``'soap'`` - -Implements the SOAP protocol. - -A wsdl definition of the webservice is available at the 'api.wsdl' subpath. -(``/ws/api.wsdl`` in our example). - -The protocol is selected if the request matches one of the following condition: - -- The Content-Type is 'application/soap+xml' -- A header 'Soapaction' is present - -Options -~~~~~~~ - -:tns: Type namespace - -ExtDirect ---------- - -:name: ``extdirect`` - -Implements the `Ext Direct`_ protocol. - -The provider definition is made available at the ``/extdirect/api.js`` subpath. - -The router url is ``/extdirect/router[/subnamespace]``. - -Options -~~~~~~~ - -:namespace: Base namespace of the api. Used for the provider definition. -:params_notation: Default notation for function call parameters. Can be - overridden for individual functions by adding the - ``extdirect_params_notation`` extra option to @expose. - - The possible notations are : - - - ``'named'`` -- The function will take only one object parameter - in which each property will be one of the parameters. - - ``'positional'`` -- The function will take as many parameters as - the function has, and their position will determine which parameter - they are. - -expose extra options -~~~~~~~~~~~~~~~~~~~~ - -:extdirect_params_notation: Override the params_notation for a particular - 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') - diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index 57dd1d9..0000000 --- a/doc/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -sphinx -cloud_sptheme --r ../requirements.txt diff --git a/doc/todo.rst b/doc/todo.rst deleted file mode 100644 index 21a300b..0000000 --- a/doc/todo.rst +++ /dev/null @@ -1,31 +0,0 @@ -TODO -==== - -WSME is a work in progress. Here is a list of things that should -be done : - -- Use gevents for batch-calls - -- Implement new protocols : - - - json-rpc - - - xml-rpc - -- Implement adapters for other frameworks : - - - TurboGears 2 - - - Pylons - - - CherryPy - - - Flask - - - others ? - -- Add unittests for adapters - -- Address the authentication subject (which should be handled by - some other wsgi framework/middleware, but a little integration - could help). diff --git a/doc/types.rst b/doc/types.rst deleted file mode 100644 index 637a5b7..0000000 --- a/doc/types.rst +++ /dev/null @@ -1,246 +0,0 @@ -Types -===== - -Three kinds of data types can be used as input or output by WSME. - -Native types ------------- - -The native types are a fixed set of standard Python types that -different protocols map to their own basic types. - -The native types are : - - - .. wsme:type:: bytes - - A pure-ascii string (:py:class:`wsme.types.bytes` which is - :py:class:`str` in Python 2 and :py:class:`bytes` in Python 3). - - - - .. wsme:type:: text - - A unicode string (:py:class:`wsme.types.text` which is - :py:class:`unicode` in Python 2 and :py:class:`str` in Python 3). - - - .. wsme:type:: int - - An integer (:py:class:`int`) - - - .. wsme:type:: float - - A float (:py:class:`float`) - - - .. wsme:type:: bool - - A boolean (:py:class:`bool`) - - - .. wsme:type:: Decimal - - A fixed-width decimal (:py:class:`decimal.Decimal`) - - - .. wsme:type:: date - - A date (:py:class:`datetime.date`) - - - .. wsme:type:: datetime - - A date and time (:py:class:`datetime.datetime`) - - - .. wsme:type:: time - - A time (:py:class:`datetime.time`) - - - Arrays -- This is a special case. When stating a list - datatype, always state its content type as the unique element - of a list. Example:: - - class SomeWebService(object): - @expose([str]) - def getlist(self): - return ['a', 'b', 'c'] - - - Dictionaries -- Statically typed mappings are allowed. When exposing - a dictionary datatype, you can specify the key and value types, - with a restriction on the key value that must be a 'pod' type. - Example:: - - class SomeType(object): - amap = {str: SomeOthertype} - -There are other types that are supported out of the box. See the -:ref:`pre-defined-user-types`. - -User types ----------- - -User types allow you to define new, almost-native types. - -The idea is that you may have Python data that should be transported as base -types by the different protocols, but needs conversion to/from these base types, -or needs to validate data integrity. - -To define a user type, you just have to inherit from -:class:`wsme.types.UserType` and instantiate your new class. This instance -will be your new type and can be used as @\ :class:`wsme.expose` or -@\ :class:`wsme.validate` parameters. - -Note that protocols can choose to specifically handle a user type or -a base class of user types. This is case with the two pre-defined -user types, :class:`wsme.types.Enum` and :data:`wsme.types.binary`. - -.. _pre-defined-user-types: - -Pre-defined user types -~~~~~~~~~~~~~~~~~~~~~~ - -WSME provides some pre-defined user types: - -- :class:`binary <wsme.types.binary>` -- for transporting binary data as - base64 strings. -- :class:`Enum <wsme.types.Enum>` -- enforce that the values belongs to a - pre-defined list of values. - -These types are good examples of how to define user types. Have -a look at their source code! - -Here is a little example that combines :class:`binary <wsme.types.binary>` -and :class:`Enum <wsme.types.Enum>`:: - - ImageKind = Enum(str, 'jpeg', 'gif') - - class Image(object): - name = unicode - kind = ImageKind - data = binary - -.. data:: wsme.types.binary - - The :class:`wsme.types.BinaryType` instance to use when you need to - transfer base64 encoded data. - -.. autoclass:: wsme.types.BinaryType - -.. autoclass:: wsme.types.Enum - - -Complex types -------------- - -Complex types are structured types. They are defined as simple Python classes -and will be mapped to adequate structured types in the various protocols. - -A base class for structured types is provided, :class:`wsme.types.Base`, -but is not mandatory. The only thing it adds is a default constructor. - -The attributes that are set at the class level will be used by WSME to discover -the structure. These attributes can be: - - - A datatype -- Any native, user or complex type. - - A :class:`wsattr <wsme.wsattr>` -- This allows you to add more information about - the attribute, for example if it is mandatory. - - A :class:`wsproperty <wsme.wsproperty>` -- A special typed property. Works - like standard ``property`` with additional properties like - :class:`wsattr <wsme.wsattr>`. - -Attributes having a leading '_' in their name will be ignored, as well as the -attributes that are not in the above list. This means the type can have methods, -they will not get in the way. - -Example -~~~~~~~ - -:: - - Gender = wsme.types.Enum(str, 'male', 'female') - Title = wsme.types.Enum(str, 'M', 'Mrs') - - class Person(wsme.types.Base): - lastname = wsme.types.wsattr(unicode, mandatory=True) - firstname = wsme.types.wsattr(unicode, mandatory=True) - - age = int - gender = Gender - title = Title - - hobbies = [unicode] - -Rules -~~~~~ - -A few things you should know about complex types: - - - The class must have a default constructor -- - Since instances of the type will be created by the protocols when - used as input types, they must be instantiable without any argument. - - - Complex types are registered automatically - (and thus inspected) as soon a they are used in expose or validate, - even if they are nested in another complex type. - - If for some reason you need to control when type is inspected, you - can use :func:`wsme.types.register_type`. - - - The datatype attributes will be replaced. - - When using the 'short' way of defining attributes, ie setting a - simple data type, they will be replaced by a wsattr instance. - - So, when you write:: - - class Person(object): - name = unicode - - After type registration the class will actually be equivalent to:: - - class Person(object): - name = wsattr(unicode) - - You can still access the datatype by accessing the attribute on the - class, along with the other wsattr properties:: - - class Person(object): - name = unicode - - register_type(Person) - - assert Person.name.datatype is unicode - assert Person.name.key == "name" - assert Person.name.mandatory is False - - - The default value of instance attributes is - :data:`Unset <wsme.Unset>`. - - :: - - class Person(object): - name = wsattr(unicode) - - p = Person() - assert p.name is Unset - - This allows the protocol to make a clear distinction between null values - that will be transmitted, and unset values that will not be transmitted. - - For input values, it allows the code to know if the values were, or were not, - sent by the caller. - - - When 2 complex types refer to each other, their names can be - used as datatypes to avoid adding attributes afterwards: - - :: - - class A(object): - b = wsattr('B') - - class B(object): - a = wsattr(A) - - -Predefined Types -~~~~~~~~~~~~~~~~ - -.. default-domain:: wsme - -- .. autotype:: wsme.types.File - :members: - |