Anonymous avatar Anonymous committed 483ffc1

sphinx-ify

Comments (0)

Files changed (12)

docs/comment-example.txt

 middleware also needs a location to store the comments; we'll put them
 all in a single directory.
 
-.. code-block::
+.. code-block:: python
 
     import os
     
 
 When you use this middleware, you'll use it like:
 
-.. code-block::
+.. code-block:: python
 
     app = ... make the application ...
     app = Commenter(app, storage_dir='./comments')
 Paste`` to install this).  The setup is all at the bottom of
 ``example.py``, and looks like this:
 
-.. code-block::
+.. code-block:: python
 
     if __name__ == '__main__':
         import optparse
 actually do anything.  Here's a kind of minimal version of the
 middleware (using WebOb):
 
-.. code-block::
+.. code-block:: python
 
     from webob import Request
 
 This doesn't modify the response it any way.  You could write it like
 this without WebOb:
 
-.. code-block::
+.. code-block:: python
 
     class Commenter(object):
         ...
 ``http://localhost:8080/index.html`` becomes
 ``http%3A%2F%2Flocalhost%3A8080%2Findex.html``).
 
-.. code-block::
+.. code-block:: python
 
     from cPickle import load, dump
 
 that were error responses (anything but ``200``), nor do we want to
 filter responses that aren't HTML.  So we get:
 
-.. code-block::
+.. code-block:: python
 
     class Commenter(object):
         ...
 We'll also need a simple method to add stuff to the page.  We'll use a
 regular expression to find the end of the page and put text in:
 
-.. code-block::
+.. code-block:: python
 
     import re
 
 
 And then we'll use it like:
 
-.. code-block::
+.. code-block:: python
 
     data = self.get_data(req.url)
     body = resp.body
 We get the body, update it, and put it back in the response.  This
 also updates ``Content-Length``.  Then we define:
 
-.. code-block::
+.. code-block:: python
 
     from webob import html_escape
 
 
 So here's what this all looks like:
 
-.. code-block::
+.. code-block:: python
 
     class Commenter(object):
         ...
 
 Here's what the form looks like:
 
-.. code-block::
+.. code-block:: python
 
     class Commenter(object):
         ...
 If you look at the method call, what we do is call the method then
 treat the result as a WSGI application:
 
-.. code-block::
+.. code-block:: python
 
     return self.process_comment(req)(environ, start_response)
 
 You could write this as:
 
-.. code-block::
+.. code-block:: python
 
     response = self.process_comment(req)
     return response(environ, start_response)
 A common pattern in WSGI middleware that *doesn't* use WebOb is to
 just do:
 
-.. code-block::
+.. code-block:: python
 
     return self.process_comment(environ, start_response)
 
 
 Here's the actual processing code:
 
-.. code-block::
+.. code-block:: python
 
     from webob import exc
     from webob import Response
+# -*- coding: utf-8 -*-
+#
+# Paste documentation build configuration file, created by
+# sphinx-quickstart on Tue Apr 22 22:08:49 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys
+
+# If your extensions are in another directory, add it here.
+#sys.path.append('some/directory')
+
+# General configuration
+# ---------------------
+
+# 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']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'WebOb'
+copyright = '2008, Ian Bicking'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '0.9'
+# The full version, including alpha/beta/rc tags.
+release = '0.9.2'
+
+# 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 documents that shouldn't be included in the build.
+unused_docs = ['jsonrpc-example-code/test_jsonrpc']
+
+# 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'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# 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
+
+# Content template for the index page.
+#html_index = ''
+
+# 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_use_modindex = True
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'WebObdoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# 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, document class [howto/manual]).
+#latex_documents = []
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True

docs/differences.txt

 
 ``util.redirect`` or ``req.status = apache.HTTP_MOVED_TEMPORARILY``:
 
-.. code-block::
+.. code-block:: python
 
     from webob.exc import HTTPTemporaryRedirect
     exc = HTTPTemporaryRedirect(location=url)
 ``req.content_type = "application/x-csv"`` and 
 ``req.headers_out.add('Content-Disposition', 'attachment;filename=somefile.csv')``:
 
-.. code-block::
+.. code-block:: python
 
     res = req.ResponseClass()
     res.content_type = 'application/x-csv'

docs/do-it-yourself.txt

 
 A very simple application looks like this:
 
-.. code-block::
+.. code-block:: python
 
     >>> def application(environ, start_response):
     ...     start_response('200 OK', [('Content-Type', 'text/html')])
 
 We won't focus much on the server, but we will use WebOb to handle the application.  WebOb in a way has a simple server interface.  To use it you create a new request with ``req = webob.Request('http://localhost/test')``, and then call the application with ``resp = req.get_response(app)``.  For example:
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob import Request
     >>> req = Request.blank('http://localhost/test')
 
 WebOb is a library to create a request and response object.  It's centered around the WSGI model.  Requests are wrappers around the environment.  For example:
 
-.. code-block::
+.. code-block:: python
 
     >>> req = Request.blank('http://localhost/test')
     >>> req.environ['HTTP_HOST']
 
 Responses are objects that represent the... well, response.  The status, headers, and body:
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob import Response
     >>> resp = Response(body='Hello World!')
 
 While we can test the application using WebOb, you might want to serve the application.  Here's the basic recipe, using the `Paste <http://pythonpaste.org>`_ HTTP server:
 
-.. code-block::
+.. code-block:: python
 
     if __name__ == '__main__':
         from paste import httpserver
 
 you could also use `wsgiref <http://python.org/doc/current/lib/module-wsgiref.simpleserver.html>`_ from the standard library, but this is mostly appropriate for testing as it is single-threaded:
 
-.. code-block::
+.. code-block:: python
 
     if __name__ == '__main__':
         from wsgiref.simple_server import make_server
 
 So here's what a route would look like:
 
-.. code-block::
+.. code-block:: python
 
     app = Router()
     app.add_route('/', controller='controllers:index')
 
 To do the matching, we'll compile those templates to regular expressions.  
 
-.. code-block::
+.. code-block:: python
 
     >>> import re
     >>> var_regex = re.compile(r'''
 
 To test it we can try some translations.  You could put these directly in the docstring of the ``template_to_regex`` function and use `doctest <http://python.org/doc/current/lib/module-doctest.html>`_ to test that.  But I'm using doctest to test *this* document, so I can't put a docstring doctest inside the doctest itself.  Anyway, here's what a test looks like:
 
-.. code-block::
+.. code-block:: python
 
     >>> print template_to_regex('/a/static/path')
     ^\/a\/static\/path$
 
 Also, some people don't know how exactly the string method ``split`` works.  It takes two arguments -- the first is the character to split on, and the second is the maximum number of splits to do.  We want to split on just the first ``:`` character, so we'll use a maximum number of splits of 1.
 
-.. code-block::
+.. code-block:: python
 
     >>> import sys
     >>> def load_controller(string):
 
 Now, the ``Router`` class.  The class has the ``add_route`` method, and also a ``__call__`` method.  That ``__call__`` method makes the Router object itself a WSGI application.  So when a request comes in, it looks at ``PATH_INFO`` (also known as ``req.path_info``) and hands off the request to the controller that matches that path.
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob import Request
     >>> from webob import exc
 
 To do that we'll write a `decorator <http://www.ddj.com/web-development/184406073>`_.  A decorator is a function that wraps another function.  After decoration the function will be a WSGI application, but it will be decorating a function with a signature like ``controller_func(req, **urlvars)``.  The controller function will return a response object (which, remember, is a WSGI application on its own).
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob import Request, Response
     >>> from webob import exc
 
 You use this controller like:
 
-.. code-block::
+.. code-block:: python
 
     >>> @controller
     ... def index(req):
 
 Now we'll show a basic application.  Just a hello world application for now.  Note that this document is the module ``__main__``.
 
-.. code-block::
+.. code-block:: python
 
     >>> @controller
     ... def hello(req):
 
 Now let's test that application:
 
-.. code-block::
+.. code-block:: python
 
     >>> req = Request.blank('/')
     >>> resp = req.get_response(hello_world)
 
 We'll allow an extra ``action`` variable, which will define the method (actually ``action_method``, where ``_method`` is the request method).  If no action is given, we'll use just the method (i.e., ``get``, ``post``, etc).
 
-.. code-block::
+.. code-block:: python
 
     >>> def rest_controller(cls):
     ...     def replacement(environ, start_response):
 
 Here's the hello world:
 
-.. code-block::
+.. code-block:: python
 
     >>> class Hello(object):
     ...     def __init__(self, req):
 
 We'll run the same test as before:
 
-.. code-block::
+.. code-block:: python
 
     >>> hello_world = Router()
     >>> hello_world.add_route('/', controller=hello)
 
 Here's the basic structure for the local:
 
-.. code-block::
+.. code-block:: python
 
     >>> import threading
     >>> class Localized(object):
 
 This registration middleware looks like:
 
-.. code-block::
+.. code-block:: python
 
     >>> class RegisterRequest(object):
     ...     def __init__(self, app):
 
 then the request will be registered each time.  Now, lets create a URL generation function:
 
-.. code-block::
+.. code-block:: python
 
     >>> import urllib
     >>> def url(*segments, **vars):
 
 Now, to test:
 
-.. code-block::
+.. code-block:: python
 
     >>> get_request.register(Request.blank('http://localhost/'))
     >>> url('article', 1)
 
 We'll use `Tempita <http://pythonpaste.org/tempita/>`_ for templating, mostly because it's very simplistic about how it does loading.  The basic form is:
 
-.. code-block::
+.. code-block:: python
 
     import tempita
     template = tempita.HTMLTemplate.from_filename('some-file.html')
 
 We'll also let you pass an instantiated template in instead of a template name, which will be useful in places like a doctest where there aren't other files easily accessible.
 
-.. code-block::
+.. code-block:: python
 
     >>> import os
     >>> import tempita

docs/file-example.txt

 First we'll setup a really simple shim around our application, which
 we can use as we improve our application:
 
-.. code-block::
+.. code-block:: python
 
    >>> from webob import Request, Response
    >>> import os
 Now we can make different definitions of ``make_response``.  The
 simplest version:
 
-.. code-block::
+.. code-block:: python
 
    >>> def make_response(filename):
    ...     res = Response(content_type=get_mimetype(filename))
 Let's give it a go.  We'll test it out with a file ``test-file.txt``
 in the WebOb doc directory:
 
-.. code-block::
+.. code-block:: python
 
    >>> fn = os.path.join(doc_dir, 'test-file.txt')
    >>> open(fn).read()
 Well, that worked.  But it's not a very fancy object.  First, it reads
 everything into memory, and that's bad.  We'll create an iterator instead:
 
-.. code-block::
+.. code-block:: python
 
    >>> class FileIterable(object):
    ...     def __init__(self, filename):
 
 And testing:
 
-.. code-block::
+.. code-block:: python
 
    >>> req = Request.blank('/')
    >>> print req.get_response(app)
 different because we know we changed some code.  Now to add some basic
 metadata to the response:
 
-.. code-block::
+.. code-block:: python
 
    >>> def make_response(filename):
    ...     res = Response(content_type=get_mimetype(filename),
 Now, with ``conditional_response`` on, and with ``last_modified`` and
 ``etag`` set, we can do conditional requests:
 
-.. code-block::
+.. code-block:: python
 
    >>> req = Request.blank('/')
    >>> res = req.get_response(app)
 So we'll add an extra method, ``app_iter_range``, that ``Response``
 looks for:
 
-.. code-block::
+.. code-block:: python
 
    >>> class FileIterable(object):
    ...     def __init__(self, filename, start=None, stop=None):
 
 Now we'll test it out:
 
-.. code-block::
+.. code-block:: python
 
    >>> req = Request.blank('/')
    >>> res = req.get_response(app)
 WebOb
 +++++
 
-Other documents:
+.. toctree::
 
-* `Reference <reference.html>`_
-
-* Extracted documentation for the `request
-  <class-webob.Request.html>`_ and `response
-  <class-webob.Response.html>`_.
-
-* `Differences between the WebOb API and other framework/libraries
-  <differences.html>`_
-
-* `File-serving example <file-example.html>`_
-
-* `Comment middleware example <comment-example.html>`_
-
-* `JSON-RPC server and client example <jsonrpc-example.html>`_
-
-* `A Do-It-Yourself Framework <do-it-yourself.html>`_
+   reference
+   modules/webob
+   differences
+   file-example
+   wiki-example
+   comment-example
+   jsonrpc-example
+   do-it-yourself
+   news
+   license
 
 .. contents::
 
 Generally any attribute of the response can be passed in as a keyword
 argument to the class; e.g.:
 
-.. code-block::
+.. code-block:: python
 
   response = Response(body='hello world!', content_type='text/plain')
 
 ``Response``, so you can manipulate the instances in the same way.  A
 typical example is:
 
-.. code-block::
+.. code-block:: python
 
     response = HTTPNotFound('There is no such resource')
     # or:
 Python 2.5.  To get an exception object use ``response.exception``.
 You can use this like:
 
-.. code-block::
+.. code-block:: python
 
     try:
         ... stuff ...
 =======
 
 I haven't figured out the example I want to use here.  The
-`file-serving example`_ shows how to do more advanced HTTP techniques,
-while the `comment middleware example`_ shows middleware.  For
-applications it's more reasonable to use WebOb in the context of a
-larger framework.  `Pylons <http://pylonshq.com>`_ uses WebOb
-optionally in 0.9.7+.
+`file-serving example <file-example.html>`_ shows how to do more
+advanced HTTP techniques, while the `comment middleware example
+<comment-example.html>`_ shows middleware.  For applications it's more
+reasonable to use WebOb in the context of a larger framework.  `Pylons
+<http://pylonshq.com>`_ uses WebOb optionally in 0.9.7+.
 
 

docs/jsonrpc-example.txt

 and serve up our application (note that *creating* the application is
 left out to start with):
 
-.. code-block::
+.. code-block:: python
 
     import sys
 
 up the object and wrap it in our WSGI/WebOb wrapper.  We'll be calling
 that wrapper ``JSONRPC(obj)``, so here's how it'll go:
 
-.. code-block::
+.. code-block:: python
 
     def make_app(expr):
         module, expression = expr.split(':', 1)
 
 The instantiation of the server is already figured out:
 
-.. code-block::
+.. code-block:: python
 
     class JsonRpcApp(object):
 
 We'll start with a simple outline of the WSGI interface, using a kind
 of standard WebOb setup:
 
-.. code-block::
+.. code-block:: python
 
     from webob import Request, Response
     from webob import exc
 happens.  We'll start with just the most minimal implementation, with
 no error checking or handling:
 
-.. code-block::
+.. code-block:: python
 
     from simplejson import loads, dumps
 
 reasonable expectation.  There's a whole bunch of things that can go
 wrong.  For instance, it has to be a POST method:
 
-.. code-block::
+.. code-block:: python
 
     if not req.method == 'POST':
         raise exc.HTTPMethodNotAllowed(
 
 And maybe the request body doesn't contain valid JSON:
 
-.. code-block::
+.. code-block:: python
 
     try:
         json = loads(req.body)
 
 And maybe all the keys aren't in the dictionary:
 
-.. code-block::
+.. code-block:: python
 
     try:
         method = json['method']
 exception object (as opposed to the ``web.Response`` based object,
 though on Python 2.5+ these are the same objects):
 
-.. code-block::
+.. code-block:: python
 
     if method.startswith('_'):
         raise exc.HTTPForbidden(
 
 And maybe ``json['params']`` isn't a list:
 
-.. code-block::
+.. code-block:: python
 
     if not isinstance(params, list):
         raise ValueError(
 
 And maybe the method doesn't exist:
 
-.. code-block::
+.. code-block:: python
 
     try:
         method = getattr(self.obj, method)
 The last case is the error we actually can expect: that the method
 raises some exception.
 
-.. code-block::
+.. code-block:: python
 
     try:
         result = method(*params)
 Since we showed all the error handling in pieces, here's the complete
 code:
 
-.. code-block::
+.. code-block:: python
 
     from webob import Request, Response
     from webob import exc
 
 The basic idea is that you can create a blank Request:
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob import Request
     >>> req = Request.blank('http://python.org')
 
 Then you can send that request to an application:
 
-.. code-block::
+.. code-block:: python
 
     >>> from wsgiproxy.exactproxy import proxy_exact_request
     >>> resp = req.get_response(proxy_exact_request)
 This particular application (``proxy_exact_request``) sends the
 request over HTTP:
 
-.. code-block::
+.. code-block:: python
 
     >>> resp.content_type
     'text/html'
 you pass in a proxy application, in case you want to do local requests
 (e.g., to do direct tests against a ``JsonRpcApp`` instance):
 
-.. code-block::
+.. code-block:: python
 
     class ServerProxy(object):
 
 create a helper object that is callable, and our ``__getattr__`` will
 just return that:
 
-.. code-block::
+.. code-block:: python
 
     class ServerProxy(object):
         ...
 
 Here's the code to do the call:
 
-.. code-block::
+.. code-block:: python
 
     class _Method(object):
         ...
 interesting.  Note that you can make exception have any methods or
 signature you want, which we'll do:
 
-.. code-block::
+.. code-block:: python
 
     class ProxyError(Exception):
         """
 <http://svn.pythonpaste.org/Paste/WebOb/trunk/docs/json-example-code/test_jsonrpc.py>`_,
 which looks like:
 
-.. code-block::
+.. code-block:: python
 
     if __name__ == '__main__':
         import doctest
 As you can see, it's just a stub to run the doctest.  We'll need a
 simple object to expose.  We'll make it real simple:
 
-.. code-block::
+.. code-block:: python
 
     >>> class Divider(object):
     ...     def divide(self, a, b):
 
 Then we'll get the app setup:
 
-.. code-block::
+.. code-block:: python
 
     >>> from jsonrpc import *
     >>> app = JsonRpcApp(Divider())
 
 And attach the client *directly* to it:
 
-.. code-block::
+.. code-block:: python
 
     >>> proxy = ServerProxy('http://localhost:8080', proxy=app)
 
 
 So, now we have a proxy, lets use it:
 
-.. code-block::
+.. code-block:: python
 
     >>> proxy.divide(10, 4)
     2
 
 Lastly, we'll test a couple error conditions.  First a method error:
 
-.. code-block::
+.. code-block:: python
 
     >>> proxy.divide(10, 0) # doctest: +ELLIPSIS
     Traceback (most recent call last):
 
 The other exception can be:
 
-.. code-block::
+.. code-block:: python
 
     >>> proxy.add(1, 1)
     Traceback (most recent call last):

docs/modules/webob.txt

+:mod:`webob` -- Request/Response objects
+========================================
+
+.. automodule:: webob
+
+Request
+-------
+
+.. autoclass:: Request
+
+.. automodule:: webob.acceptparse
+.. autoclass:: Accept
+.. autoclass:: MIMEAccept
+
+.. automodule:: webob.byterange
+.. autoclass:: Range
+
+.. automodule:: webob.cachecontrol
+.. autoclass:: CacheControl
+
+.. automodule:: webob.datastruct
+.. autoclass:: EnvironHeaders
+
+.. automodule:: webob.etag
+.. autoclass:: ETagMatcher
+.. autoclass:: IfRange
+
+
+Response
+--------
+
+.. autoclass:: webob.Response
+
+.. autoclass:: webob.byterange.ContentRange
+
+.. autoclass:: webob.cachecontrol.CacheControl
+
+.. automodule:: webob.headerdict
+.. autoclass:: HeaderDict
+
+
+Misc Functions
+--------------
+
+.. autofunction:: webob.html_escape
+
+.. comment:
+   not sure what to do with these constants; not autoclass
+
+.. autoclass:: webob.day
+.. autoclass:: webob.week
+.. autoclass:: webob.hour
+.. autoclass:: webob.minute
+.. autoclass:: webob.second
+.. autoclass:: webob.month
+.. autoclass:: webob.year
+
+.. autoclass:: webob.AppIterRange
+
+.. automodule:: webob.multidict
+.. autoclass:: MultiDict
+.. autoclass:: UnicodeMultiDict
+.. autoclass:: NestedMultiDict
+.. autoclass:: NoVars
+
+.. automodule:: webob.updatedict
+.. autoclass:: webob.updatedict.UpdateDict
+
+
+Descriptors
+-----------
+
+.. autoclass:: webob.environ_getter
+.. autoclass:: webob.header_getter
+.. autoclass:: webob.converter
+.. autoclass:: webob.deprecated_property

docs/reference.txt

 
 The basic way you create a request object is simple enough:
 
-.. code-block::
+.. code-block:: python
 
    >>> from webob import Request
    >>> environ = {}
 easier to test and play around with, the ``Request`` class has a
 constructor that will fill in a minimal environment:
 
-.. code-block::
+.. code-block:: python
 
    >>> req = Request.blank('/article?id=1')
    >>> from pprint import pprint
 file-like object.  You can read the entire body with
 ``req.body``.
 
-.. code-block:: 
+.. code-block:: python 
 
     >>> req.body_file
     <cStringIO.StringI object at ...>
 All the normal parts of a request are also accessible through the
 request object:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.method
     'GET'
 
 You can make new URLs:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.relative_url('archive')
     'http://localhost/blog/archive'
 For parsing the URLs, it is often useful to deal with just the next
 path segment on PATH_INFO:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.path_info_peek() # Doesn't change request
     'article'
 All request headers are available through a dictionary-like object
 ``req.headers``.  Keys are case-insensitive.
 
-.. code-block::
+.. code-block:: python
 
     >>> req.headers['content-type'] = 'application/x-www-urlencoded'
     >>> req.headers
 
 Some examples:
 
-.. code-block::
+.. code-block:: python
 
     >>> req = Request.blank('/test?check=a&check=b&name=Bob')
     >>> req.GET
 We'll have to create a request body and change the method to get
 POST.  Until we do that, the variables are boring:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.POST
     <NoVars: Not a POST request>
 important.)  There is a dictionary called ``req.params`` that
 contains variables from both sources:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.params
     NestedMultiDict([('check', 'a'), ('check', 'b'), ('name', 'Bob'), ('name', 'Joe'), ('email', 'joe@example.com')])
 different character set).  You can force a charset, which will effect
 all the variables:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.charset = 'utf8'
     >>> req.GET
 Cookies are presented in a simple dictionary.  Like other variables,
 they will be decoded into Unicode strings if you set the charset.
 
-.. code-block::
+.. code-block:: python
 
     >>> req.headers['Cookie'] = 'test=value'
     >>> req.cookies
 The objects returned support containment to test for acceptability.
 E.g.:
 
-.. code-block::
+.. code-block:: python
 
     >>> 'text/html' in req.accept
     True
 example means that ``text/html`` is okay, but
 ``application/xhtml+xml`` is preferred):
 
-.. code-block::
+.. code-block:: python
 
     >>> req.accept = 'text/html;q=0.5, application/xhtml+xml;q=1'
     >>> req.accept
 First, when you trust the server's preference over the client (a good
 idea for Accept):
 
-.. code-block::
+.. code-block:: python
 
     >>> req.accept.first_match(['text/html', 'application/xhtml+xml'])
     'text/html'
 returned, even if the client says it prefers
 ``application/xhtml+xml``.  If we trust the client more:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.accept.best_match(['text/html', 'application/xhtml+xml'])
     'application/xhtml+xml'
 If we just want to know everything the client prefers, in the order it
 is preferred:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.accept.best_matches()
     ['application/xhtml+xml', 'text/html']
 nothing better then use ``en-US`` (and if ``en-US`` is okay, ignore
 any less preferrable languages):
 
-.. code-block::
+.. code-block:: python
 
     >>> req.accept_language = 'es, pt-BR'
     >>> req.accept_language.best_matches('en-US')
 server-side filenames based on other variables).  To test if a 304
 response is appropriate, you can use:
 
-.. code-block::
+.. code-block:: python
 
     >>> server_token = 'opaque-token'
     >>> server_token in req.if_none_match # You shouldn't return 304
 
 For date-based comparisons If-Modified-Since is used:
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob import UTC
     >>> from datetime import datetime
 the If-Range header fails to match then the full response (not a
 range) should be returned:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.if_range
     <Empty If-Range>
 
 You can also pass in a response object with:
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob import Response
     >>> res = Response(etag='opaque-etag')
 If-Unmodified-Since means "do this if the resource has remained
 unchanged".
 
-.. code-block::
+.. code-block:: python
 
     >>> server_token in req.if_match # No If-Match means everything is ok
     True
 There's two forms of the subrequest.  The more primitive form is
 this:
 
-.. code-block::
+.. code-block:: python
 
     >>> req = Request.blank('/')
     >>> def wsgi_app(environ, start_response):
 
 A handier response can be had with:
 
-.. code-block::
+.. code-block:: python
 
     >>> res = req.get_response(wsgi_app)
     >>> res
 environment.  This can be used to make a single global request object
 dynamic.  An example:
 
-.. code-block::
+.. code-block:: python
 
     >>> import threading
     >>> import webob
 You can assign attributes to your request objects.  They will all go
 in ``environ['webob.adhoc_attrs']`` (a dictionary).  
 
-.. code-block::
+.. code-block:: python
 
     >>> req = Request.blank('/')
     >>> req.some_attr = 'blah blah blah'
 
 The core attributes are unsurprising:
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob import Response
     >>> res = Response()
 
 You can set any of these attributes, e.g.:
 
-.. code-block::
+.. code-block:: python
 
     >>> res.status = 404
     >>> res.status
 In addition to ``res.headerlist``, there is dictionary-like view on
 the list in ``res.headers``:
 
-.. code-block::
+.. code-block:: python
 
     >>> res.headers
     HeaderDict([('content-type', 'text/html; charset=utf8'), ('Content-Length', '4')])
 There is also a file-like object you can access, which will update the
 app_iter in-place (turning the app_iter into a list if necessary):
 
-.. code-block::
+.. code-block:: python
 
     >>> res = Response(content_type='text/plain')
     >>> f = res.body_file
 Content-Type is a special case, as the type and the charset are
 handled through two separate properties:
 
-.. code-block::
+.. code-block:: python
 
     >>> res = Response()
     >>> res.content_type = 'text/html'
 
 Other headers:
 
-.. code-block::
+.. code-block:: python
 
     >>> # Used with a redirect:
     >>> res.location = 'http://localhost/foo'
 
 After setting all these headers, here's the result:
 
-.. code-block::
+.. code-block:: python
 
     >>> for name, value in res.headerlist:
     ...     print '%s: %s' % (name, value)
 You can also set Cache-Control related attributes with
 ``req.cache_expires(seconds, **attrs)``, like:
 
-.. code-block::
+.. code-block:: python
 
     >>> res = Response()
     >>> res.cache_expires(10)
 <http://python.org/doc/current/lib/datetime-timedelta.html>`_
 constants defined, e.g.:
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob import *
     >>> res = Response()
 Cookies (and the Set-Cookie header) are handled with a couple
 methods.  Most importantly:
 
-.. code-block::
+.. code-block:: python
 
     >>> res.set_cookie('key', 'value', max_age=360, path='/',
     ...                domain='example.org', secure=True)
 The only other real method of note (note that this does *not* delete
 the cookie from clients, only from the response object):
 
-.. code-block::
+.. code-block:: python
 
     >>> res.unset_cookie('key')
     >>> res.unset_cookie('bad_cookie')
 
 A response is a WSGI application, in that you can do:
 
-.. code-block::
+.. code-block:: python
 
     >>> req = Request.blank('/')
     >>> status, headers, app_iter = req.call_application(res)
 
 A possible pattern for your application might be:
 
-.. code-block::
+.. code-block:: python
 
     >>> def my_app(environ, start_response):
     ...     req = Request(environ)
 These provide a simple way to provide these non-200 response.  A very
 simple body is provided.
 
-.. code-block::
+.. code-block:: python
 
     >>> from webob.exc import *
     >>> exc = HTTPTemporaryRedirect(location='foo')
 Note that only if there's an ``Accept: text/html`` header in the
 request will an HTML response be given:
 
-.. code-block::
+.. code-block:: python
 
     >>> req.accept += 'text/html'
     >>> print str(req.get_response(exc)).strip()
 To enable this you must create the response like
 ``Response(conditional_request=True)``, or make a subclass like:
 
-.. code-block::
+.. code-block:: python
 
     >>> class AppResponse(Response):
     ...     default_content_type = 'text/html'

docs/test-file.txt

-This is a test.  Hello test people!

docs/wiki-example.txt

 class which is instantiated with the configuration.  For our
 application we'll be storing the pages under a directory.
 
-.. code-block::
+.. code-block:: python
 
     class WikiApp(object):
 
 start_response)``.  *Instances* of `WikiApp` are WSGI applications, so
 we'll implement a ``__call__`` method:
 
-.. code-block::
+.. code-block:: python
 
     class WikiApp(object):
         ...
 To make the script runnable we'll create a simple command-line
 interface:
 
-.. code-block::
+.. code-block:: python
 
     if __name__ == '__main__':
         import optparse
 application.  Here's kind of the hello world of WSGI applications
 using these objects:
 
-.. code-block::
+.. code-block:: python
 
     from webob import Request, Response
 
 
 All this together makes:
 
-.. code-block::
+.. code-block:: python
 
     from webob import Request, Response
     from webob import exc
 
 Here's the method to figure out the filename:
 
-.. code-block::
+.. code-block:: python
 
     import os
 
 
 Here's the actual domain object:
 
-.. code-block::
+.. code-block:: python
 
     class Page(object):
         def __init__(self, filename):
 defaults to ``view``.  So a simple page view will be
 ``action_view_GET``.  Let's implement that:
 
-.. code-block::
+.. code-block:: python
 
     class WikiApp(object):
         ...
 
 The template actually looks like this:
 
-.. code-block::
+.. code-block:: python
 
     from tempita import HTMLTemplate
 
 
 So let's look at the ``action_view_GET`` method again:
 
-.. code-block::
+.. code-block:: python
 
         def action_view_GET(self, req, page):
             if not page.exists:
 The edit screen will be implemented in the method
 ``action_edit_GET``.  There's a template and a very simple method:
 
-.. code-block::
+.. code-block:: python
 
     EDIT_TEMPLATE = HTMLTemplate("""\
     <html>
 The form submits to ``action_view_POST`` (``view`` is the default
 action).  So we have to implement that method:
 
-.. code-block::
+.. code-block:: python
 
     class WikiApp(object):
         ...
 display it in the page view.  To set it on save, we add a little to
 ``action_view_POST``:
 
-.. code-block::
+.. code-block:: python
 
     def action_view_POST(self, req, page):
         ...
 
 And then in ``action_view_GET``:
 
-.. code-block::
+.. code-block:: python
 
 
     VIEW_TEMPLATE = HTMLTemplate("""\
+#!/bin/sh
+
+mkdir -p docs/_static docs/_build
+sphinx-build -E -b html docs/ docs/_build || exit 1
+if [ "$1" = "publish" ] ; then
+  cd docs/
+  echo "Uploading files..."
+  scp -r _build/* ianb@webwareforpython.org:/home/paste/htdocs/webob/
+fi
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.