google_appengine/lib/webob/docs/differences.txt

   1 Differences Between WebOb and Other Systems
   2 +++++++++++++++++++++++++++++++++++++++++++
   3
   4 This document points out some of the API differences between the
   5 Request and Response object, and the objects in other systems.
   6
   7 .. contents::
   8
   9 paste.wsgiwrappers and Pylons
  10 =============================
  11
  12 The Pylons ``request`` and ``response`` object are based on
  13 ``paste.wsgiwrappers.WSGIRequest`` and ``WSGIResponse``
  14
  15 There is no concept of ``defaults`` in WebOb.  In Paste/Pylons these
  16 serve as threadlocal settings that control certain policies on the
  17 request and response object.  In WebOb you should make your own
  18 subclasses to control policy (though in many ways simply being
  19 explicit elsewhere removes the need for this policy).
  20
  21 Request
  22 -------
  23
  24 ``body``:
  25     This is a file-like object in WSGIRequest.  In WebOb it is a
  26     string (to match Response.body) and the file-like object is
  27     available through ``req.body_file``
  28
  29 ``languages()``:
  30     This is available through ``req.accept_language``, particularly
  31     ``req.accept_language.best_matches(fallback_language)``
  32
  33 ``match_accept(mimetypes)``:
  34     This is available through ``req.accept.first_match(mimetypes)``;
  35     or if you trust the client's quality ratings, you can use
  36     ``req.accept.best_match(mimetypes)``
  37
  38 ``errors``:
  39     This controls how unicode decode errors are handled; it is now
  40     named ``unicode_errors``
  41
  42 There are also many extra methods and attributes on WebOb Request
  43 objects.
  44
  45 Response
  46 --------
  47
  48 default ``content_type``:
  49     The base Response object has no default content_type or charset.
  50     You can set ``default_content_type`` in a subclass.
  51
  52 ``determine_charset()``:
  53     Is now available as ``res.charset``
  54
  55 ``has_header(header)``:
  56     Should be done with ``header in res.headers``
  57
  58 ``get_content()`` and ``wsgi_response()``:
  59     These are gone; you should use ``res.body`` or ``res(environ,
  60     start_response)``
  61
  62 ``write(content)``:
  63     Available in ``res.body_file.write(content)``.
  64
  65 ``flush()`` and ``tell()``:
  66     Not available.
  67
  68 There are also many extra methods and attributes on WebOb Response
  69 objects.
  70
  71 Django
  72 ======
  73
  74 This is a quick summary from reading `the Django documentation
  75 <http://www.djangoproject.com/documentation/request_response/>`_.
  76
  77 Request
  78 -------
  79
  80 ``encoding``:
  81     Is ``req.charset``
  82
  83 ``REQUEST``:
  84     Is ``req.params``
  85
  86 ``FILES``:
  87     File uploads are ``cgi.FieldStorage`` objects directly in
  88     ``res.POST``
  89
  90 ``META``:
  91     Is ``req.environ``
  92
  93 ``user``:
  94     No equivalent (too connected to application model for WebOb).
  95     There is ``req.remote_user``, which is only ever a string.
  96
  97 ``session``:
  98     No equivalent
  99
 100 ``raw_post_data``:
 101     Available with ``req.body``
 102
 103 ``__getitem__(key)``:
 104     You have to use ``req.params``
 105
 106 ``is_secure()``:
 107     No equivalent; you could use ``req.scheme == 'https'``.
 108
 109 QueryDict
 110 ---------
 111
 112 QueryDict is the way Django represents the multi-key dictionary-like
 113 objects that are request variables (query string and POST body
 114 variables).  The equivalent in WebOb is MultiDict.
 115
 116 Mutability:
 117     WebOb dictionaries are sometimes mutable (req.GET is,
 118     req.params is not)
 119
 120 Ordering:
 121     I believe Django does not order the keys fully; MultiDict is a
 122     full ordering.  Methods that iterate over the parameters iterate
 123     over keys in their order in the original request.
 124
 125 ``keys()``, ``items()``, ``values()`` (plus ``iter*``):
 126     These return all values in MultiDict, but only the last value for
 127     a QueryDict.  That is, given ``a=1&a=2`` with MultiDict
 128     ``d.items()`` returns ``[('a', '1'), ('a', '2')]``, but QueryDict
 129     returns ``[('a', '1')]``
 130
 131 ``getlist(key)``:
 132     Available as ``d.getall(key)``
 133
 134 ``setlist(key)``:
 135     No direct equivalent
 136
 137 ``appendlist(key, value)``:
 138     Available as ``d.add(key, value)``
 139
 140 ``setlistdefault(key, default_list)``:
 141     No direct equivalent
 142
 143 ``lists()``:
 144     Is ``d.dict_of_lists()``
 145
 146 The MultiDict object has a ``d.getone(key)`` method, that raises
 147 KeyError if there is not exactly one key.  There is a method
 148 ``d.mixed()`` which returns a version where values are lists *if*
 149 there are multiple values for a list.  This is similar to how many
 150 cgi-based request forms are represented.
 151
 152 Response
 153 --------
 154
 155 Constructor:
 156     Totally different.  The WebOb Response object should probably be
 157     subclassed for direct application use; in WebOb it does not
 158     *prefer* HTML or anything normal web application conventions
 159
 160 dictionary-like:
 161     The Django response object is somewhat dictionary-like, setting
 162     headers.  The equivalent dictionary-like object is
 163     ``res.headers``.  In WebOb this is a MultiDict.
 164
 165 ``has_header(header)``:
 166     Use ``header in res.headers``
 167
 168 ``write(content)``:
 169     As ``res.body_file.write(content)``
 170
 171 ``flush()``, ``tell()``:
 172     Not available
 173
 174 ``content``:
 175     Use ``res.body`` for the ``str`` value, ``res.unicode_body`` for
 176     the ``unicode`` value
 177
 178 Response Subclasses
 179 -------------------
 180
 181 These are generally like ``webob.exc`` objects.
 182 ``HttpResponseNotModified`` is ``HTTPNotModified``; this naming
 183 translation generally works.
 184
 185 CherryPy/TurboGears
 186 ===================
 187
 188 The `CherryPy request object
 189 <http://www.cherrypy.org/wiki/RequestObject>`_ is also used by
 190 TurboGears 1.x.
 191
 192 Request
 193 -------
 194
 195 ``app``:
 196     No equivalent
 197
 198 ``base``:
 199     ``req.application_url``
 200
 201 ``close()``:
 202     No equivalent
 203
 204 ``closed``:
 205     No equivalent
 206
 207 ``config``:
 208     No equivalent
 209
 210 ``cookie``:
 211     A ``SimpleCookie`` object in CherryPy; a dictionary in WebOb
 212     (``SimpleCookie`` can represent cookie parameters, but cookie
 213     parameters are only sent with responses not requests)
 214
 215 ``dispatch``:
 216     No equivalent (this is the object dispatcher in CherryPy).
 217
 218 ``error_page``, ``error_response``, ``handle_error``:
 219     No equivalent
 220
 221 ``get_resource()``:
 222     Similar to ``req.get_response(app)``
 223
 224 ``handler``:
 225     No equivalent
 226
 227 ``headers``, ``header_list``:
 228     The WSGI environment represents headers as a dictionary, available
 229     through ``req.headers`` (no list form is available in the request).
 230
 231 ``hooks``:
 232     No equivalent
 233
 234 ``local``:
 235     No equivalent
 236
 237 ``methods_with_bodies``:
 238     This represents methods where CherryPy will automatically try to
 239     read the request body.  WebOb lazily reads POST requests with the
 240     correct content type, and no other bodies.
 241
 242 ``namespaces``:
 243     No equivalent
 244
 245 ``protocol``:
 246     As ``req.environ['SERVER_PROTOCOL']``
 247
 248 ``query_string``:
 249     As ``req.query_string``
 250
 251 ``remote``:
 252     ``remote.ip`` is like ``req.remote_addr``.  ``remote.port`` is not
 253     available.  ``remote.name`` is in
 254     ``req.environ.get('REMOTE_HOST')``
 255
 256 ``request_line``:
 257     No equivalent
 258
 259 ``respond()``:
 260     A method that is somewhat similar to ``req.get_response()``.
 261
 262 ``rfile``:
 263     ``req.body_file``
 264
 265 ``run``:
 266     No equivalent
 267
 268 ``server_protocol``:
 269     As ``req.environ['SERVER_PROTOCOL']``
 270
 271 ``show_tracebacks``:
 272     No equivalent
 273
 274 ``throw_errors``:
 275     No equivalent
 276
 277 ``throws``:
 278     No equivalent
 279
 280 ``toolmaps``:
 281     No equivalent
 282
 283 ``wsgi_environ``:
 284     As ``req.environ``
 285
 286 Response
 287 --------
 288
 289 From information `from the wiki
 290 <http://www.cherrypy.org/wiki/ResponseObject>`_.
 291
 292 ``body``:
 293     This is an iterable in CherryPy, a string in WebOb;
 294     ``res.app_iter`` gives an iterable in WebOb.
 295
 296 ``check_timeout``:
 297     No equivalent
 298
 299 ``collapse_body()``:
 300     This turns a stream/iterator body into a single string.  Accessing
 301     ``res.body`` will do this automatically.
 302
 303 ``cookie``:
 304     Accessible through ``res.set_cookie(...)``, ``res.delete_cookie``,
 305     ``res.unset_cookie()``
 306
 307 ``finalize()``:
 308     No equivalent
 309
 310 ``header_list``:
 311     In ``res.headerlist``
 312
 313 ``stream``:
 314     This can make CherryPy stream the response body out directory.
 315     There is direct no equivalent; you can use a dynamically generated
 316     iterator to do something similar.
 317
 318 ``time``:
 319     No equivalent
 320
 321 ``timed_out``:
 322     No equivalent
 323
 324 Yaro
 325 ====
 326
 327 `Yaro <http://lukearno.com/projects/yaro/>`_ is a small wrapper around
 328 the WSGI environment, much like WebOb in scope.
 329
 330 The WebOb objects have many more methods and attributes.  The Yaro
 331 Response object is a much smaller subset of WebOb's Response.
 332
 333 Request
 334 -------
 335
 336 ``query``:
 337     As ``req.GET``
 338
 339 ``form``:
 340     As ``req.POST``
 341
 342 ``cookie``:
 343     A ``SimpleCookie`` object in Yaro; a dictionary in WebOb
 344     (``SimpleCookie`` can represent cookie parameters, but cookie
 345     parameters are only sent with responses not requests)
 346
 347 ``uri``:
 348     Returns a URI object, no equivalent (only string URIs available).
 349
 350 ``redirect``:
 351     Not available (response-related).  ``webob.exc.HTTPFound()`` can
 352     be useful here.
 353
 354 ``forward(yaroapp)``, ``wsgi_forward(wsgiapp)``:
 355     Available with ``req.get_response(app)`` and
 356     ``req.call_application(app)``.  In both cases it is a WSGI
 357     application in WebOb, there is no special kind of communication;
 358     ``req.call_application()`` just returns a ``webob.Response`` object.
 359
 360 ``res``:
 361     The request object in WebOb *may* have a ``req.response``
 362     attribute.
 363
 364 Werkzeug
 365 ========
 366
 367 Probably not that many people know about this library, which is a
 368 offshoot of `Pocoo <http://pocoo.org>`_, and used to go by another
 369 name (Columbrid?)  This library is based around WSGI, similar to Paste
 370 and Yaro.
 371
 372 This is take from the `wrapper documentation
 373 <http://werkzeug.pocoo.org/documentation/wrappers>`_.
 374
 375 Request
 376 -------
 377
 378 path:
 379     As ``req.path_info``
 380 args:
 381     As ``req.GET``
 382 form:
 383     As ``req.POST``
 384 values:
 385     As ``req.params``
 386 files:
 387     In ``req.POST`` (as FieldStorage objects)
 388 data:
 389     In ``req.body_file``
 390
 391 Response
 392 --------
 393
 394 response:
 395     In ``res.body`` (settable as ``res.body`` or ``res.app_iter``)
 396 status:
 397     In ``res.status_int``
 398 mimetype:
 399     In ``res.content_type``
 400 write(data):
 401     With ``res.body_file.write(data)``
 402
 403 Zope 3
 404 ======
 405
 406 From the Zope 3 interfaces for the `Request
 407 <http://apidoc.zope.org/++apidoc++/Interface/zope.publisher.interfaces.browser.IBrowserRequest/index.html>`_
 408 and `Response
 409 <http://apidoc.zope.org/++apidoc++/Interface/zope.publisher.interfaces.http.IHTTPResponse/index.html>`_.
 410
 411 Request
 412 -------
 413
 414 ``locale``, ``setupLocale()``:
 415     This is not fully calculated, but information is available in
 416     ``req.accept_languages``.
 417
 418 ``principal``, ``setPrincipal(principal)``:
 419     ``req.remote_user`` gives the username, but there is no standard
 420     place for a user *object*.
 421
 422 ``publication``, ``setPublication()``,
 423     These are associated with the object publishing system in Zope.
 424     This kind of publishing system is outside the scope of WebOb.
 425
 426 ``traverse(object)``, ``getTraversalStack()``, ``setTraversalStack()``:
 427     These all relate to traversal, which is part of the publishing
 428     system.
 429
 430 ``processInputs()``, ``setPathSuffix(steps)``:
 431     Also associated with traversal and preparing the request.
 432
 433 ``environment``:
 434     In ``req.environ``
 435
 436 ``bodyStream``:
 437     In ``req.body_file``
 438
 439 ``interaction``:
 440     This is the security context for the request; all the possible
 441     participants or principals in the request.  There's no
 442     equivalent.
 443
 444 ``annotations``:
 445     Extra information associated with the request.  This would
 446     generally go in custom keys of ``req.environ``, or if you set
 447     attributes those attributes are stored in
 448     ``req.environ['webob.adhoc_attrs']``.
 449
 450 ``debug``:
 451     There is no standard debug flag for WebOb.
 452
 453 ``__getitem__(key)``, ``get(key)``, etc:
 454     These treat the request like a dictionary, which WebOb does not
 455     do.  They seem to take values from the environment, not
 456     parameters.  Also on the Zope request object is ``items()``,
 457     ``__contains__(key)``, ``__iter__()``, ``keys()``, ``__len__()``,
 458     ``values()``.
 459
 460 ``getPositionalArguments()``:
 461     I'm not sure what the equivalent would be, as there are no
 462     positional arguments during instantiation (it doesn't fit into
 463     WSGI).  Maybe ``wsgiorg.urlvars``?
 464
 465 ``retry()``, ``supportsRetry()``:
 466     Creates a new request that can be used to retry a request.
 467     Similar to ``req.copy()``.
 468
 469 ``close()``, ``hold(obj)``:
 470     This closes resources associated with the request, including any
 471     "held" objects.  There's nothing similar.
 472
 473 Response
 474 --------
 475
 476 ``authUser``:
 477     Not sure what this is or does.
 478
 479 ``reset()``:
 480     No direct equivalent; you'd have to do ``res.headers = [];
 481     res.body = ''; res.status = 200``
 482
 483 ``setCookie(name, value, **kw)``:
 484     Is ``res.set_cookie(...)``.
 485
 486 ``getCookie(name)``:
 487     No equivalent.  Hm.
 488
 489 ``expireCookie(name)``:
 490     Is ``res.delete_cookie(name)``.
 491
 492 ``appendToCookie(name, value)``:
 493     This appends the value to any existing cookie (separating values
 494     with a colon).  WebOb does not do this.
 495
 496 ``setStatus(status)``:
 497     Availble by setting ``res.status`` (can be set to an integer or a
 498     string of "code reason").
 499
 500 ``getHeader(name, default=None)``:
 501     Is ``res.headers.get(name)``.
 502
 503 ``getStatus()``:
 504     Is ``res.status_int`` (or ``res.status`` to include reason)
 505
 506 ``addHeader(name, value)``:
 507     Is ``res.headers.add(name, value)`` (in Zope and WebOb, this does
 508     not clobber any previous value).
 509
 510 ``getHeaders()``:
 511     Is ``res.headerlist``.
 512
 513 ``setHeader(name, value)``:
 514     Is ``res.headers[name] = value``.
 515
 516 ``getStatusString()``:
 517     Is ``res.status``.
 518
 519 ``consumeBody()``:
 520     This consumes any non-string body to turn the body into a single
 521     string.  Any access to ``res.body`` will do this (e.g., when you
 522     have set the ``res.app_iter``).
 523
 524 ``internalError()``:
 525     This is available with ``webob.exc.HTTP*()``.
 526
 527 ``handleException(exc_info)``:
 528     This is provided with a tool like ``paste.exceptions``.
 529
 530 ``consumeBodyIter()``:
 531     This returns the iterable for the body, even if the body was a
 532     string.  Anytime you access ``res.app_iter`` you will get an
 533     iterable.  ``res.body`` and ``res.app_iter`` can be interchanged
 534     and accessed as many times as you want, unlike the Zope
 535     equivalents.
 536
 537 ``setResult(result)``:
 538     You can achieve the same thing through ``res.body = result``, or
 539     ``res.app_iter = result``.  ``res.body`` accepts None, a unicode
 540     string (*if* you have set a charset) or a normal string.
 541     ``res.app_iter`` only accepts None and an interable.  You can't
 542     update all of a response with one call.
 543
 544     Like in Zope, WebOb updates Content-Length.  Unlike Zope, it does
 545     not automatically calculate a charset.
 546
 547
 548 mod_python
 549 ==========
 550
 551 Some key attributes from the `mod_python
 552 <http://modpython.org/live/current/doc-html/pyapi-mprequest-mem.html>`_
 553 request object.
 554
 555 Request
 556 -------
 557
 558 ``req.uri``:
 559     In ``req.path``.
 560
 561 ``req.user``:
 562     In ``req.remote_user``.
 563
 564 ``req.get_remote_host()``:
 565     In ``req.environ['REMOTE_ADDR']`` or ``req.remote_addr``.
 566
 567 ``req.headers_in.get('referer')``:
 568     In ``req.headers.get('referer')`` or ``req.referer`` (same pattern
 569     for other request headers, presumably).
 570
 571 Response
 572 --------
 573
 574 ``util.redirect`` or ``req.status = apache.HTTP_MOVED_TEMPORARILY``:
 575
 576 .. code-block::
 577
 578     from webob.exc import HTTPMovedTemporarily()
 579     exc = HTTPMovedTemporarily(location=url)
 580     return exc(environ, start_response)
 581
 582 ``req.content_type = "application/x-csv"`` and
 583 ``req.headers_out.add('Content-Disposition', 'attachment;filename=somefile.csv'):
 584
 585 .. code-block::
 586
 587     res = req.ResponseClass()
 588     res.content_type = 'application/x-csv'
 589     res.headers.add('Content-Disposition', 'attachment;filename=somefile.csv')
 590     return res(environ, start_response)