diff options
| -rw-r--r-- | CHANGES.txt | 3 | ||||
| -rw-r--r-- | TODO.txt | 2 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/latexindex.rst | 1 | ||||
| -rw-r--r-- | docs/narr/forms.rst | 126 | ||||
| -rw-r--r-- | docs/narr/views.rst | 121 |
6 files changed, 124 insertions, 130 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 5b228e77a..33949f29e 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -45,6 +45,9 @@ Documentation - Add (minimal) documentation about using I18N within Mako templates to "Internationalization and Localization" narrative chapter. +- Move content of "Forms" chapter back to "Views" chapter; I can't think of a + better place to put it. + Deprecations ------------- @@ -11,8 +11,6 @@ Must-Have (before 1.0) http://blog.abourget.net/2011/1/13/pyramid-and-mako:-how-to-do-i18n-the-pylons-way/, but I've asked Alexandre if we can include his text in the documentation. -- Figure out what to do with "Forms" chapter in narr docs. - - Actually explain ``{foo:<regex>}`` formatting and purpose in URL dispatch patterns within URL dispatch chapter. diff --git a/docs/index.rst b/docs/index.rst index 23596e5ce..8717542f1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -65,7 +65,6 @@ Narrative documentation in chapter form explaining how to use narr/router narr/threadlocals narr/zca - narr/forms Tutorials ========= diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 2426ec4b0..077283228 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -55,7 +55,6 @@ Narrative Documentation narr/startup narr/threadlocals narr/zca - narr/forms .. _tutorials: diff --git a/docs/narr/forms.rst b/docs/narr/forms.rst deleted file mode 100644 index 080f02159..000000000 --- a/docs/narr/forms.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. _forms_chapter: - -.. index:: - single: unicode, views, and forms - single: forms, views, and unicode - single: views, forms, and unicode - -Form Handling -============= - -Handling Form Submissions in View Callables (Unicode and Character Set Issues) ------------------------------------------------------------------------------- - -Most web applications need to accept form submissions from web browsers and -various other clients. In :app:`Pyramid`, form submission handling logic is -always part of a :term:`view`. For a general overview of how to handle form -submission data using the :term:`WebOb` API, see :ref:`webob_chapter` and -`"Query and POST variables" within the WebOb documentation -<http://pythonpaste.org/webob/reference.html#query-post-variables>`_. -:app:`Pyramid` defers to WebOb for its request and response implementations, -and handling form submission data is a property of the request -implementation. Understanding WebOb's request API is the key to -understanding how to process form submission data. - -There are some defaults that you need to be aware of when trying to handle -form submission data in a :app:`Pyramid` view. Having high-order (i.e., -non-ASCII) characters in data contained within form submissions is -exceedingly common, and the UTF-8 encoding is the most common encoding used -on the web for character data. Since Unicode values are much saner than -working with and storing bytestrings, :app:`Pyramid` configures the -:term:`WebOb` request machinery to attempt to decode form submission values -into Unicode from UTF-8 implicitly. This implicit decoding happens when view -code obtains form field values via the ``request.params``, ``request.GET``, -or ``request.POST`` APIs (see :ref:`request_module` for details about these -APIs). - -.. note:: - - Many people find the difference between Unicode and UTF-8 confusing. - Unicode is a standard for representing text that supports most of the - world's writing systems. However, there are many ways that Unicode data - can be encoded into bytes for transit and storage. UTF-8 is a specific - encoding for Unicode, that is backwards-compatible with ASCII. This makes - UTF-8 very convenient for encoding data where a large subset of that data - is ASCII characters, which is largely true on the web. UTF-8 is also the - standard character encoding for URLs. - -As an example, let's assume that the following form page is served up to a -browser client, and its ``action`` points at some :app:`Pyramid` view code: - -.. code-block:: xml - :linenos: - - <html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> - </head> - <form method="POST" action="myview"> - <div> - <input type="text" name="firstname"/> - </div> - <div> - <input type="text" name="lastname"/> - </div> - <input type="submit" value="Submit"/> - </form> - </html> - -The ``myview`` view code in the :app:`Pyramid` application *must* expect that -the values returned by ``request.params`` will be of type ``unicode``, as -opposed to type ``str``. The following will work to accept a form post from -the above form: - -.. code-block:: python - :linenos: - - def myview(request): - firstname = request.params['firstname'] - lastname = request.params['lastname'] - -But the following ``myview`` view code *may not* work, as it tries to decode -already-decoded (``unicode``) values obtained from ``request.params``: - -.. code-block:: python - :linenos: - - def myview(request): - # the .decode('utf-8') will break below if there are any high-order - # characters in the firstname or lastname - firstname = request.params['firstname'].decode('utf-8') - lastname = request.params['lastname'].decode('utf-8') - -For implicit decoding to work reliably, you should ensure that every form you -render that posts to a :app:`Pyramid` view explicitly defines a charset -encoding of UTF-8. This can be done via a response that has a -``;charset=UTF-8`` in its ``Content-Type`` header; or, as in the form above, -with a ``meta http-equiv`` tag that implies that the charset is UTF-8 within -the HTML ``head`` of the page containing the form. This must be done -explicitly because all known browser clients assume that they should encode -form data in the same character set implied by ``Content-Type`` value of the -response containing the form when subsequently submitting that form. There is -no other generally accepted way to tell browser clients which charset to use -to encode form data. If you do not specify an encoding explicitly, the -browser client will choose to encode form data in its default character set -before submitting it, which may not be UTF-8 as the server expects. If a -request containing form data encoded in a non-UTF8 charset is handled by your -view code, eventually the request code accessed within your view will throw -an error when it can't decode some high-order character encoded in another -character set within form data, e.g., when ``request.params['somename']`` is -accessed. - -If you are using the :class:`pyramid.response.Response` class to generate a -response, or if you use the ``render_template_*`` templating APIs, the UTF-8 -charset is set automatically as the default via the ``Content-Type`` header. -If you return a ``Content-Type`` header without an explicit charset, a -request will add a ``;charset=utf-8`` trailer to the ``Content-Type`` header -value for you, for response content types that are textual -(e.g. ``text/html``, ``application/xml``, etc) as it is rendered. If you are -using your own response object, you will need to ensure you do this yourself. - -.. note:: Only the *values* of request params obtained via - ``request.params``, ``request.GET`` or ``request.POST`` are decoded - to Unicode objects implicitly in the :app:`Pyramid` default - configuration. The keys are still (byte) strings. - - diff --git a/docs/narr/views.rst b/docs/narr/views.rst index e1eacfeae..16d9d964d 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -410,3 +410,124 @@ exception views which have a name will be ignored. Exception views can be configured with any view registration mechanism: ``@view_config`` decorator, ZCML, or imperative ``add_view`` styles. +.. index:: + single: unicode, views, and forms + single: forms, views, and unicode + single: views, forms, and unicode + +Handling Form Submissions in View Callables (Unicode and Character Set Issues) +------------------------------------------------------------------------------ + +Most web applications need to accept form submissions from web browsers and +various other clients. In :app:`Pyramid`, form submission handling logic is +always part of a :term:`view`. For a general overview of how to handle form +submission data using the :term:`WebOb` API, see :ref:`webob_chapter` and +`"Query and POST variables" within the WebOb documentation +<http://pythonpaste.org/webob/reference.html#query-post-variables>`_. +:app:`Pyramid` defers to WebOb for its request and response implementations, +and handling form submission data is a property of the request +implementation. Understanding WebOb's request API is the key to +understanding how to process form submission data. + +There are some defaults that you need to be aware of when trying to handle +form submission data in a :app:`Pyramid` view. Having high-order (i.e., +non-ASCII) characters in data contained within form submissions is +exceedingly common, and the UTF-8 encoding is the most common encoding used +on the web for character data. Since Unicode values are much saner than +working with and storing bytestrings, :app:`Pyramid` configures the +:term:`WebOb` request machinery to attempt to decode form submission values +into Unicode from UTF-8 implicitly. This implicit decoding happens when view +code obtains form field values via the ``request.params``, ``request.GET``, +or ``request.POST`` APIs (see :ref:`request_module` for details about these +APIs). + +.. note:: + + Many people find the difference between Unicode and UTF-8 confusing. + Unicode is a standard for representing text that supports most of the + world's writing systems. However, there are many ways that Unicode data + can be encoded into bytes for transit and storage. UTF-8 is a specific + encoding for Unicode, that is backwards-compatible with ASCII. This makes + UTF-8 very convenient for encoding data where a large subset of that data + is ASCII characters, which is largely true on the web. UTF-8 is also the + standard character encoding for URLs. + +As an example, let's assume that the following form page is served up to a +browser client, and its ``action`` points at some :app:`Pyramid` view code: + +.. code-block:: xml + :linenos: + + <html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> + </head> + <form method="POST" action="myview"> + <div> + <input type="text" name="firstname"/> + </div> + <div> + <input type="text" name="lastname"/> + </div> + <input type="submit" value="Submit"/> + </form> + </html> + +The ``myview`` view code in the :app:`Pyramid` application *must* expect that +the values returned by ``request.params`` will be of type ``unicode``, as +opposed to type ``str``. The following will work to accept a form post from +the above form: + +.. code-block:: python + :linenos: + + def myview(request): + firstname = request.params['firstname'] + lastname = request.params['lastname'] + +But the following ``myview`` view code *may not* work, as it tries to decode +already-decoded (``unicode``) values obtained from ``request.params``: + +.. code-block:: python + :linenos: + + def myview(request): + # the .decode('utf-8') will break below if there are any high-order + # characters in the firstname or lastname + firstname = request.params['firstname'].decode('utf-8') + lastname = request.params['lastname'].decode('utf-8') + +For implicit decoding to work reliably, you should ensure that every form you +render that posts to a :app:`Pyramid` view explicitly defines a charset +encoding of UTF-8. This can be done via a response that has a +``;charset=UTF-8`` in its ``Content-Type`` header; or, as in the form above, +with a ``meta http-equiv`` tag that implies that the charset is UTF-8 within +the HTML ``head`` of the page containing the form. This must be done +explicitly because all known browser clients assume that they should encode +form data in the same character set implied by ``Content-Type`` value of the +response containing the form when subsequently submitting that form. There is +no other generally accepted way to tell browser clients which charset to use +to encode form data. If you do not specify an encoding explicitly, the +browser client will choose to encode form data in its default character set +before submitting it, which may not be UTF-8 as the server expects. If a +request containing form data encoded in a non-UTF8 charset is handled by your +view code, eventually the request code accessed within your view will throw +an error when it can't decode some high-order character encoded in another +character set within form data, e.g., when ``request.params['somename']`` is +accessed. + +If you are using the :class:`pyramid.response.Response` class to generate a +response, or if you use the ``render_template_*`` templating APIs, the UTF-8 +charset is set automatically as the default via the ``Content-Type`` header. +If you return a ``Content-Type`` header without an explicit charset, a +request will add a ``;charset=utf-8`` trailer to the ``Content-Type`` header +value for you, for response content types that are textual +(e.g. ``text/html``, ``application/xml``, etc) as it is rendered. If you are +using your own response object, you will need to ensure you do this yourself. + +.. note:: Only the *values* of request params obtained via + ``request.params``, ``request.GET`` or ``request.POST`` are decoded + to Unicode objects implicitly in the :app:`Pyramid` default + configuration. The keys are still (byte) strings. + + |