[ Pobierz całość w formacie PDF ]

and that class is a subclass ofEntity.
When an HTTP request includes an entity body, it is often desirable to provide that information to applications in a
form other than the raw bytes. Different content types demand different approaches. Examples:
" For a GIF file, we want the raw bytes in a stream.
" An HTML form is better parsed into its component fields, and each text field decoded from bytes to unicode.
" A JSON body should be deserialized into a Python dict or list.
When the request contains a Content-Type header, the media type is used as a key to look up a value in the
request.body.processorsdict. If the full media type is not found, then the major type is tried; for exam-
ple, if no processor is found for the  image/jpeg type, then we look for a processor for the  image types altogether. If
neither the full type nor the major type has a matching processor, then a default processor is used (default_proc).
For most types, this means no processing is done, and the body is left unread as a raw byte stream. Processors are
configurable in an  on_start_resource hook.
Some processors, especially those for the  text types, attempt to decode bytes to unicode. If the Content-Type request
header includes a  charset parameter, this is used to decode the entity. Otherwise, one or more default charsets may
be attempted, although this decision is up to each processor. If a processor successfully decodes an Entity or Part, it
should set thecharsetattribute on the Entity or Part to the name of the successful charset, so that applications can
easily re-encode or transcode the value if they wish.
If the Content-Type of the request entity is of major type  multipart , then the above parsing process, and possibly a
decoding process, is performed for each part.
For both the full entity and multipart parts, a Content-Disposition header may be used to fillnameandfilename
attributes on the request.body or the Part.
7.6.1 Custom Processors
You can add your own processors for any specific or major MIME type. Simply add it to theprocessorsdict in a
hook/tool that runs aton_start_resourceorbefore_request_body. Here s the built-in JSON tool for an
example:
def json_in(force=True, debug=False):
request = cherrypy.serving.request
def json_processor(entity):
"""Read application/json data into request.json."""
if not entity.headers.get("Content-Length", ""):
raise cherrypy.HTTPError(411)
body = entity.fp.read()
try:
request.json = json_decode(body)
except ValueError:
102 Chapter 7. Reference Manual
CherryPy Documentation, Release 3.2.4
raise cherrypy.HTTPError(400,  Invalid JSON document )
if force:
request.body.processors.clear()
request.body.default_proc = cherrypy.HTTPError(
415,  Expected an application/json content type )
request.body.processors[ application/json ] = json_processor
We begin by defining a newjson_processorfunction to stick in theprocessorsdictionary. All processor
functions take a single argument, theEntityinstance they are to process. It will be called whenever a request is
received (for those URI s where the tool is turned on) which has aContent-Typeof  application/json .
First, it checks for a validContent-Length(raising 411 if not valid), then reads the remaining bytes on the socket.
Thefpobject knows its own length, so it won t hang waiting for data that never arrives. It will return when all data
has been read. Then, we decode those bytes using Python s built-injsonmodule, and stick the decoded result onto
request.json. If it cannot be decoded, we raise 400.
If the  force argument is True (the default), the Tool clears the processors dict so that request enti-
ties of otherContent-Typesaren t parsed at all. Since there s no entry for those invalid MIME types, the
default_procmethod ofcherrypy.request.bodyis called. But this does nothing by default (usually
to provide the page handler an opportunity to handle it.) But in our case, we want to raise 415, so we replace
request.body.default_procwith the error (HTTPErrorinstances, when called, raise themselves).
If we were defining a custom processor, we can do so without making aTool. Just add the config entry:
request.body.processors = { application/json : json_processor}
Note that you can only replace theprocessorsdict wholesale this way, not update the existing one.
7.6.2 Classes
classcherrypy._cpreqbody.Entity(fp, headers, params=None, parts=None)
An HTTP request body, or MIME multipart body.
This class collects information about the HTTP request entity. When a given entity is of MIME type  multipart ,
each part is parsed into its own Entity instance, and the set of parts stored inentity.parts.
Between thebefore_request_bodyandbefore_handlertools, CherryPy tries to process the request
body (if any) by callingrequest.body.process. This uses thecontent_typeof the Entity to look
up a suitable processor inEntity.processors, a dict. If a matching processor cannot be found for the
complete Content-Type, it tries again using the major type. For example, if a request with an entity of type
 image/jpeg arrives, but no processor can be found for that complete type, then one is sought for the major type
 image . If a processor is still not found, then thedefault_procmethod of the Entity is called (which does
nothing by default; you can override this too).
CherryPy includes processors for the  application/x-www-form-urlencoded type, the  multipart/form-data
type, and the  multipart major type. CherryPy 3.2 processes these types almost exactly as older versions. Parts
are passed as arguments to the page handler using theirContent-Disposition.nameif given, otherwise
in a generic  parts argument. Each such part is either a string, or thePartitself if it s a file. (In this case it will
havefileandfilenameattributes, or possibly avalueattribute). Each Part is itself a subclass of Entity,
and has its ownprocessmethod andprocessorsdict.
There is a separate processor for the  multipart major type which is more flexible, and simply stores all multi-
part parts inrequest.body.parts. You can enable it with:
cherrypy.request.body.processors[ multipart ] = _cpreqbody.process_multipart
in anon_start_resourcetool.
7.6. cherrypy._cpreqbody 103
CherryPy Documentation, Release 3.2.4
attempt_charsets= [ utf-8 ]
A list of strings, each of which should be a known encoding.
When the Content-Type of the request body warrants it, each of the given encodings will be tried in order.
The first one to successfully decode the entity without raising an error is stored asentity.charset.
This defaults to[ utf-8 ](plus  ISO-8859-1 for  text/* types, as required by HTTP/1.1), but
[ us-ascii ,  utf-8 ]for multipart parts.
charset= None
The successful decoding; see  attempt_charsets above.
content_type= None
The value of the Content-Type request header.
If the Entity is part of a multipart payload, this will be the Content-Type given in the MIME headers for
this part.
default_content_type=  application/x-www-form-urlencoded
This defines a defaultContent-Typeto use if no Content-Type header is given. The empty string is
used for RequestBody, which results in the request body not being read or parsed at all. This is by design; [ Pobierz całość w formacie PDF ]