--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/thirdparty/google_appengine/lib/webob/docs/differences.txt Tue Aug 26 21:49:54 2008 +0000
@@ -0,0 +1,590 @@
+Differences Between WebOb and Other Systems
++++++++++++++++++++++++++++++++++++++++++++
+
+This document points out some of the API differences between the
+Request and Response object, and the objects in other systems.
+
+.. contents::
+
+paste.wsgiwrappers and Pylons
+=============================
+
+The Pylons ``request`` and ``response`` object are based on
+``paste.wsgiwrappers.WSGIRequest`` and ``WSGIResponse``
+
+There is no concept of ``defaults`` in WebOb. In Paste/Pylons these
+serve as threadlocal settings that control certain policies on the
+request and response object. In WebOb you should make your own
+subclasses to control policy (though in many ways simply being
+explicit elsewhere removes the need for this policy).
+
+Request
+-------
+
+``body``:
+ This is a file-like object in WSGIRequest. In WebOb it is a
+ string (to match Response.body) and the file-like object is
+ available through ``req.body_file``
+
+``languages()``:
+ This is available through ``req.accept_language``, particularly
+ ``req.accept_language.best_matches(fallback_language)``
+
+``match_accept(mimetypes)``:
+ This is available through ``req.accept.first_match(mimetypes)``;
+ or if you trust the client's quality ratings, you can use
+ ``req.accept.best_match(mimetypes)``
+
+``errors``:
+ This controls how unicode decode errors are handled; it is now
+ named ``unicode_errors``
+
+There are also many extra methods and attributes on WebOb Request
+objects.
+
+Response
+--------
+
+default ``content_type``:
+ The base Response object has no default content_type or charset.
+ You can set ``default_content_type`` in a subclass.
+
+``determine_charset()``:
+ Is now available as ``res.charset``
+
+``has_header(header)``:
+ Should be done with ``header in res.headers``
+
+``get_content()`` and ``wsgi_response()``:
+ These are gone; you should use ``res.body`` or ``res(environ,
+ start_response)``
+
+``write(content)``:
+ Available in ``res.body_file.write(content)``.
+
+``flush()`` and ``tell()``:
+ Not available.
+
+There are also many extra methods and attributes on WebOb Response
+objects.
+
+Django
+======
+
+This is a quick summary from reading `the Django documentation
+<http://www.djangoproject.com/documentation/request_response/>`_.
+
+Request
+-------
+
+``encoding``:
+ Is ``req.charset``
+
+``REQUEST``:
+ Is ``req.params``
+
+``FILES``:
+ File uploads are ``cgi.FieldStorage`` objects directly in
+ ``res.POST``
+
+``META``:
+ Is ``req.environ``
+
+``user``:
+ No equivalent (too connected to application model for WebOb).
+ There is ``req.remote_user``, which is only ever a string.
+
+``session``:
+ No equivalent
+
+``raw_post_data``:
+ Available with ``req.body``
+
+``__getitem__(key)``:
+ You have to use ``req.params``
+
+``is_secure()``:
+ No equivalent; you could use ``req.scheme == 'https'``.
+
+QueryDict
+---------
+
+QueryDict is the way Django represents the multi-key dictionary-like
+objects that are request variables (query string and POST body
+variables). The equivalent in WebOb is MultiDict.
+
+Mutability:
+ WebOb dictionaries are sometimes mutable (req.GET is,
+ req.params is not)
+
+Ordering:
+ I believe Django does not order the keys fully; MultiDict is a
+ full ordering. Methods that iterate over the parameters iterate
+ over keys in their order in the original request.
+
+``keys()``, ``items()``, ``values()`` (plus ``iter*``):
+ These return all values in MultiDict, but only the last value for
+ a QueryDict. That is, given ``a=1&a=2`` with MultiDict
+ ``d.items()`` returns ``[('a', '1'), ('a', '2')]``, but QueryDict
+ returns ``[('a', '1')]``
+
+``getlist(key)``:
+ Available as ``d.getall(key)``
+
+``setlist(key)``:
+ No direct equivalent
+
+``appendlist(key, value)``:
+ Available as ``d.add(key, value)``
+
+``setlistdefault(key, default_list)``:
+ No direct equivalent
+
+``lists()``:
+ Is ``d.dict_of_lists()``
+
+The MultiDict object has a ``d.getone(key)`` method, that raises
+KeyError if there is not exactly one key. There is a method
+``d.mixed()`` which returns a version where values are lists *if*
+there are multiple values for a list. This is similar to how many
+cgi-based request forms are represented.
+
+Response
+--------
+
+Constructor:
+ Totally different. The WebOb Response object should probably be
+ subclassed for direct application use; in WebOb it does not
+ *prefer* HTML or anything normal web application conventions
+
+dictionary-like:
+ The Django response object is somewhat dictionary-like, setting
+ headers. The equivalent dictionary-like object is
+ ``res.headers``. In WebOb this is a MultiDict.
+
+``has_header(header)``:
+ Use ``header in res.headers``
+
+``write(content)``:
+ As ``res.body_file.write(content)``
+
+``flush()``, ``tell()``:
+ Not available
+
+``content``:
+ Use ``res.body`` for the ``str`` value, ``res.unicode_body`` for
+ the ``unicode`` value
+
+Response Subclasses
+-------------------
+
+These are generally like ``webob.exc`` objects.
+``HttpResponseNotModified`` is ``HTTPNotModified``; this naming
+translation generally works.
+
+CherryPy/TurboGears
+===================
+
+The `CherryPy request object
+<http://www.cherrypy.org/wiki/RequestObject>`_ is also used by
+TurboGears 1.x.
+
+Request
+-------
+
+``app``:
+ No equivalent
+
+``base``:
+ ``req.application_url``
+
+``close()``:
+ No equivalent
+
+``closed``:
+ No equivalent
+
+``config``:
+ No equivalent
+
+``cookie``:
+ A ``SimpleCookie`` object in CherryPy; a dictionary in WebOb
+ (``SimpleCookie`` can represent cookie parameters, but cookie
+ parameters are only sent with responses not requests)
+
+``dispatch``:
+ No equivalent (this is the object dispatcher in CherryPy).
+
+``error_page``, ``error_response``, ``handle_error``:
+ No equivalent
+
+``get_resource()``:
+ Similar to ``req.get_response(app)``
+
+``handler``:
+ No equivalent
+
+``headers``, ``header_list``:
+ The WSGI environment represents headers as a dictionary, available
+ through ``req.headers`` (no list form is available in the request).
+
+``hooks``:
+ No equivalent
+
+``local``:
+ No equivalent
+
+``methods_with_bodies``:
+ This represents methods where CherryPy will automatically try to
+ read the request body. WebOb lazily reads POST requests with the
+ correct content type, and no other bodies.
+
+``namespaces``:
+ No equivalent
+
+``protocol``:
+ As ``req.environ['SERVER_PROTOCOL']``
+
+``query_string``:
+ As ``req.query_string``
+
+``remote``:
+ ``remote.ip`` is like ``req.remote_addr``. ``remote.port`` is not
+ available. ``remote.name`` is in
+ ``req.environ.get('REMOTE_HOST')``
+
+``request_line``:
+ No equivalent
+
+``respond()``:
+ A method that is somewhat similar to ``req.get_response()``.
+
+``rfile``:
+ ``req.body_file``
+
+``run``:
+ No equivalent
+
+``server_protocol``:
+ As ``req.environ['SERVER_PROTOCOL']``
+
+``show_tracebacks``:
+ No equivalent
+
+``throw_errors``:
+ No equivalent
+
+``throws``:
+ No equivalent
+
+``toolmaps``:
+ No equivalent
+
+``wsgi_environ``:
+ As ``req.environ``
+
+Response
+--------
+
+From information `from the wiki
+<http://www.cherrypy.org/wiki/ResponseObject>`_.
+
+``body``:
+ This is an iterable in CherryPy, a string in WebOb;
+ ``res.app_iter`` gives an iterable in WebOb.
+
+``check_timeout``:
+ No equivalent
+
+``collapse_body()``:
+ This turns a stream/iterator body into a single string. Accessing
+ ``res.body`` will do this automatically.
+
+``cookie``:
+ Accessible through ``res.set_cookie(...)``, ``res.delete_cookie``,
+ ``res.unset_cookie()``
+
+``finalize()``:
+ No equivalent
+
+``header_list``:
+ In ``res.headerlist``
+
+``stream``:
+ This can make CherryPy stream the response body out directory.
+ There is direct no equivalent; you can use a dynamically generated
+ iterator to do something similar.
+
+``time``:
+ No equivalent
+
+``timed_out``:
+ No equivalent
+
+Yaro
+====
+
+`Yaro <http://lukearno.com/projects/yaro/>`_ is a small wrapper around
+the WSGI environment, much like WebOb in scope.
+
+The WebOb objects have many more methods and attributes. The Yaro
+Response object is a much smaller subset of WebOb's Response.
+
+Request
+-------
+
+``query``:
+ As ``req.GET``
+
+``form``:
+ As ``req.POST``
+
+``cookie``:
+ A ``SimpleCookie`` object in Yaro; a dictionary in WebOb
+ (``SimpleCookie`` can represent cookie parameters, but cookie
+ parameters are only sent with responses not requests)
+
+``uri``:
+ Returns a URI object, no equivalent (only string URIs available).
+
+``redirect``:
+ Not available (response-related). ``webob.exc.HTTPFound()`` can
+ be useful here.
+
+``forward(yaroapp)``, ``wsgi_forward(wsgiapp)``:
+ Available with ``req.get_response(app)`` and
+ ``req.call_application(app)``. In both cases it is a WSGI
+ application in WebOb, there is no special kind of communication;
+ ``req.call_application()`` just returns a ``webob.Response`` object.
+
+``res``:
+ The request object in WebOb *may* have a ``req.response``
+ attribute.
+
+Werkzeug
+========
+
+Probably not that many people know about this library, which is a
+offshoot of `Pocoo <http://pocoo.org>`_, and used to go by another
+name (Columbrid?) This library is based around WSGI, similar to Paste
+and Yaro.
+
+This is take from the `wrapper documentation
+<http://werkzeug.pocoo.org/documentation/wrappers>`_.
+
+Request
+-------
+
+path:
+ As ``req.path_info``
+args:
+ As ``req.GET``
+form:
+ As ``req.POST``
+values:
+ As ``req.params``
+files:
+ In ``req.POST`` (as FieldStorage objects)
+data:
+ In ``req.body_file``
+
+Response
+--------
+
+response:
+ In ``res.body`` (settable as ``res.body`` or ``res.app_iter``)
+status:
+ In ``res.status_int``
+mimetype:
+ In ``res.content_type``
+write(data):
+ With ``res.body_file.write(data)``
+
+Zope 3
+======
+
+From the Zope 3 interfaces for the `Request
+<http://apidoc.zope.org/++apidoc++/Interface/zope.publisher.interfaces.browser.IBrowserRequest/index.html>`_
+and `Response
+<http://apidoc.zope.org/++apidoc++/Interface/zope.publisher.interfaces.http.IHTTPResponse/index.html>`_.
+
+Request
+-------
+
+``locale``, ``setupLocale()``:
+ This is not fully calculated, but information is available in
+ ``req.accept_languages``.
+
+``principal``, ``setPrincipal(principal)``:
+ ``req.remote_user`` gives the username, but there is no standard
+ place for a user *object*.
+
+``publication``, ``setPublication()``,
+ These are associated with the object publishing system in Zope.
+ This kind of publishing system is outside the scope of WebOb.
+
+``traverse(object)``, ``getTraversalStack()``, ``setTraversalStack()``:
+ These all relate to traversal, which is part of the publishing
+ system.
+
+``processInputs()``, ``setPathSuffix(steps)``:
+ Also associated with traversal and preparing the request.
+
+``environment``:
+ In ``req.environ``
+
+``bodyStream``:
+ In ``req.body_file``
+
+``interaction``:
+ This is the security context for the request; all the possible
+ participants or principals in the request. There's no
+ equivalent.
+
+``annotations``:
+ Extra information associated with the request. This would
+ generally go in custom keys of ``req.environ``, or if you set
+ attributes those attributes are stored in
+ ``req.environ['webob.adhoc_attrs']``.
+
+``debug``:
+ There is no standard debug flag for WebOb.
+
+``__getitem__(key)``, ``get(key)``, etc:
+ These treat the request like a dictionary, which WebOb does not
+ do. They seem to take values from the environment, not
+ parameters. Also on the Zope request object is ``items()``,
+ ``__contains__(key)``, ``__iter__()``, ``keys()``, ``__len__()``,
+ ``values()``.
+
+``getPositionalArguments()``:
+ I'm not sure what the equivalent would be, as there are no
+ positional arguments during instantiation (it doesn't fit into
+ WSGI). Maybe ``wsgiorg.urlvars``?
+
+``retry()``, ``supportsRetry()``:
+ Creates a new request that can be used to retry a request.
+ Similar to ``req.copy()``.
+
+``close()``, ``hold(obj)``:
+ This closes resources associated with the request, including any
+ "held" objects. There's nothing similar.
+
+Response
+--------
+
+``authUser``:
+ Not sure what this is or does.
+
+``reset()``:
+ No direct equivalent; you'd have to do ``res.headers = [];
+ res.body = ''; res.status = 200``
+
+``setCookie(name, value, **kw)``:
+ Is ``res.set_cookie(...)``.
+
+``getCookie(name)``:
+ No equivalent. Hm.
+
+``expireCookie(name)``:
+ Is ``res.delete_cookie(name)``.
+
+``appendToCookie(name, value)``:
+ This appends the value to any existing cookie (separating values
+ with a colon). WebOb does not do this.
+
+``setStatus(status)``:
+ Availble by setting ``res.status`` (can be set to an integer or a
+ string of "code reason").
+
+``getHeader(name, default=None)``:
+ Is ``res.headers.get(name)``.
+
+``getStatus()``:
+ Is ``res.status_int`` (or ``res.status`` to include reason)
+
+``addHeader(name, value)``:
+ Is ``res.headers.add(name, value)`` (in Zope and WebOb, this does
+ not clobber any previous value).
+
+``getHeaders()``:
+ Is ``res.headerlist``.
+
+``setHeader(name, value)``:
+ Is ``res.headers[name] = value``.
+
+``getStatusString()``:
+ Is ``res.status``.
+
+``consumeBody()``:
+ This consumes any non-string body to turn the body into a single
+ string. Any access to ``res.body`` will do this (e.g., when you
+ have set the ``res.app_iter``).
+
+``internalError()``:
+ This is available with ``webob.exc.HTTP*()``.
+
+``handleException(exc_info)``:
+ This is provided with a tool like ``paste.exceptions``.
+
+``consumeBodyIter()``:
+ This returns the iterable for the body, even if the body was a
+ string. Anytime you access ``res.app_iter`` you will get an
+ iterable. ``res.body`` and ``res.app_iter`` can be interchanged
+ and accessed as many times as you want, unlike the Zope
+ equivalents.
+
+``setResult(result)``:
+ You can achieve the same thing through ``res.body = result``, or
+ ``res.app_iter = result``. ``res.body`` accepts None, a unicode
+ string (*if* you have set a charset) or a normal string.
+ ``res.app_iter`` only accepts None and an interable. You can't
+ update all of a response with one call.
+
+ Like in Zope, WebOb updates Content-Length. Unlike Zope, it does
+ not automatically calculate a charset.
+
+
+mod_python
+==========
+
+Some key attributes from the `mod_python
+<http://modpython.org/live/current/doc-html/pyapi-mprequest-mem.html>`_
+request object.
+
+Request
+-------
+
+``req.uri``:
+ In ``req.path``.
+
+``req.user``:
+ In ``req.remote_user``.
+
+``req.get_remote_host()``:
+ In ``req.environ['REMOTE_ADDR']`` or ``req.remote_addr``.
+
+``req.headers_in.get('referer')``:
+ In ``req.headers.get('referer')`` or ``req.referer`` (same pattern
+ for other request headers, presumably).
+
+Response
+--------
+
+``util.redirect`` or ``req.status = apache.HTTP_MOVED_TEMPORARILY``:
+
+.. code-block::
+
+ from webob.exc import HTTPMovedTemporarily()
+ exc = HTTPMovedTemporarily(location=url)
+ return exc(environ, start_response)
+
+``req.content_type = "application/x-csv"`` and
+``req.headers_out.add('Content-Disposition', 'attachment;filename=somefile.csv'):
+
+.. code-block::
+
+ res = req.ResponseClass()
+ res.content_type = 'application/x-csv'
+ res.headers.add('Content-Disposition', 'attachment;filename=somefile.csv')
+ return res(environ, start_response)