github/sprockets.mixins.mediatype
1
0
Fork 0
mirror of https://github.com/sprockets/sprockets.mixins.mediatype.git synced 2024-12-27 11:17:30 +00:00
Code Issues Projects Releases Packages Wiki Activity

Improve documentation for FormUrlEncodedTranscoder.

Browse source
This commit is contained in:
Dave Shawley 2021-10-14 07:03:59 -04:00
parent ee66c5cadb
commit 2df3aade3c
No known key found for this signature in database
GPG key ID: F41A8A99298F8EED
1 changed files with 36 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

46
sprockets/mixins/mediatype/transcoders.py
View file

@ -274,19 +274,45 @@ class FormUrlEncodedTranscoder:
"""Opinionated transcoder for the venerable x-www-formurlencoded.
This transcoder implements transcoding according to the current
W3C documentation.
W3C documentation. The encoding interface takes mappings or
sequences of pairs and encodes both the name and value. The
following list describes how each supported type is encoded.
Any value type that is not on the list will result in a
:exc:`TypeError`.
* character strings are encoded as UTF-8 codepoints before
percent-encoding the resulting bytes
* the space character is represented as ``%20``
* :data:`False` is represented as ``false``
* :data:`True` is represented as ``true``
* :data:`None` is represented as the empty string
Some of the opinions can be changed by modifying ``self.options``.
+----------------------------+---------------------------------------+
| Value / Type | Encoding |
+============================+=======================================+
| character strings | UTF-8 codepoints before percent- |
| | encoding the resulting bytes |
+----------------------------+---------------------------------------+
| space character | ``%20`` or ``+`` |
+----------------------------+---------------------------------------+
| :data:`False` | ``false`` |
+----------------------------+---------------------------------------+
| :data:`True` | ``true`` |
+----------------------------+---------------------------------------+
| :data:`None` | the empty string |
+----------------------------+---------------------------------------+
| numbers | ``str(n)`` |
+----------------------------+---------------------------------------+
| byte sequences | percent-encoded bytes |
+----------------------------+---------------------------------------+
| :class:`uuid.UUID` | ``str(u)`` |
+----------------------------+---------------------------------------+
| :class:`datetime.datetime` | result of calling |
| | :meth:`~datetime.datetime.isoformat` |
+----------------------------+---------------------------------------+
https://url.spec.whatwg.org/#application/x-www-form-urlencoded
.. warning::
Types that are not explicitly mentioned above will result in
:meth:`to_bytes` raising a :exc:`TypeError`. This transcoder
differs slightly from others in that it does not include
support for encoding values that are nested collections.
.. attribute:: options
:type: FormUrlEncodingOptions
@ -423,4 +449,4 @@ class FormUrlEncodedTranscoder:
try:
return [(a, b) for a, b in value] # type: ignore
except (TypeError, ValueError):
raise TypeError
raise TypeError('Cannot convert value to sequence of tuples')