Package cherrypy :: Module _cpreqbody :: Class Entity
[hide private]
[frames] | no frames]

Class Entity

source code

object --+
         |
        Entity
Known Subclasses:

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 in :attr:`entity.parts<cherrypy._cpreqbody.Entity.parts>`.

Between the ``before_request_body`` and ``before_handler`` tools, CherryPy tries to process the request body (if any) by calling :func:`request.body.process<cherrypy._cpreqbody.RequestBody.process`. This uses the ``content_type`` of the Entity to look up a suitable processor in :attr:`Entity.processors<cherrypy._cpreqbody.Entity.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 the :func:`default_proc<cherrypy._cpreqbody.Entity.default_proc>` method 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 their ``Content-Disposition.name`` if given, otherwise in a generic "parts" argument. Each such part is either a string, or the :class:`Part<cherrypy._cpreqbody.Part>` itself if it's a file. (In this case it will have ``file`` and ``filename`` attributes, or possibly a ``value`` attribute). Each Part is itself a subclass of Entity, and has its own ``process`` method and ``processors`` dict.

There is a separate processor for the "multipart" major type which is more flexible, and simply stores all multipart parts in :attr:`request.body.parts<cherrypy._cpreqbody.Entity.parts>`. You can enable it with:

   cherrypy.request.body.processors['multipart'] = _cpreqbody.process_multipart

in an ``on_start_resource`` tool.

Nested Classes [hide private]
  part_class
The class used for multipart parts.
Instance Methods [hide private]
 
__init__(self, fp, headers, params=None, parts=None)
x.__init__(...) initializes x; see help(type(x)) for signature
source code
 
read(self, size=None, fp_out=None) source code
 
readline(self, size=None) source code
 
readlines(self, sizehint=None) source code
 
__iter__(self) source code
 
__next__(self) source code
 
next(self) source code
 
read_into_file(self, fp_out=None)
Read the request body into fp_out (or make_file() if None).
source code
 
make_file(self)
Return a file-like object into which the request body will be read.
source code
 
fullvalue(self)
Return this entity as a string, whether stored in a file or not.
source code
 
process(self)
Execute the best-match processor for the given media type.
source code
 
default_proc(self)
Called if a more-specific processor is not found for the ``Content-Type``.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables [hide private]
  attempt_charsets = ['utf-8']
A list of strings, each of which should be a known encoding.
  charset = None
The successful decoding; see "attempt_charsets" above.
  content_type = None
The value of the Content-Type request header.
  default_content_type = 'application/x-www-form-urlencoded'
This defines a default ``Content-Type`` to use if no Content-Type header is given.
  filename = None
The ``Content-Disposition.filename`` header, if available.
  fp = None
The readable socket file object.
  headers = None
A dict of request/multipart header names and values.
  length = None
The value of the ``Content-Length`` header, if provided.
  name = None
The "name" parameter of the ``Content-Disposition`` header, if any.
  params = None
If the request Content-Type is 'application/x-www-form-urlencoded' or multipart, this will be a dict of the params pulled from the entity body; that is, it will be the portion of request.params that come from the message body (sometimes called "POST params", although they can be sent with various HTTP method verbs).
  processors = {'application/x-www-form-urlencoded': process_url...
A dict of Content-Type names to processor methods.
  parts = None
A list of Part instances if ``Content-Type`` is of major type "multipart".
Properties [hide private]
  type
A deprecated alias for :attr:`content_type<cherrypy._cpreqbody.Entity.content_type>`.

Inherited from object: __class__

Method Details [hide private]

__init__(self, fp, headers, params=None, parts=None)
(Constructor)

source code 

x.__init__(...) initializes x; see help(type(x)) for signature

Overrides: object.__init__
(inherited documentation)

read_into_file(self, fp_out=None)

source code 

Read the request body into fp_out (or make_file() if None). Return fp_out.

make_file(self)

source code 

Return a file-like object into which the request body will be read.

By default, this will return a TemporaryFile. Override as needed. See also :attr:`cherrypy._cpreqbody.Part.maxrambytes`.


Class Variable Details [hide private]

attempt_charsets

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 as :attr:`entity.charset<cherrypy._cpreqbody.Entity.charset>`. This defaults to ``['utf-8']`` (plus 'ISO-8859-1' for "text/\*" types, as required by `HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7.1>`_), but ``['us-ascii', 'utf-8']`` for multipart parts.

Value:
['utf-8']

content_type

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.

Value:
None

default_content_type

This defines a default ``Content-Type`` to 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; a missing ``Content-Type`` header in the HTTP request entity is an error at best, and a security hole at worst. For multipart parts, however, the MIME spec declares that a part with no Content-Type defaults to "text/plain" (see :class:`Part<cherrypy._cpreqbody.Part>`).

Value:
'application/x-www-form-urlencoded'

headers

A dict of request/multipart header names and values.

This is a copy of the ``request.headers`` for the ``request.body``; for multipart parts, it is the set of headers for that part.

Value:
None

params

If the request Content-Type is 'application/x-www-form-urlencoded' or multipart, this will be a dict of the params pulled from the entity body; that is, it will be the portion of request.params that come from the message body (sometimes called "POST params", although they can be sent with various HTTP method verbs). This value is set between the 'before_request_body' and 'before_handler' hooks (assuming that process_request_body is True).

Value:
None

processors

A dict of Content-Type names to processor methods.

Value:
{'application/x-www-form-urlencoded': process_urlencoded, 'multipart/f\
orm-data': process_multipart_form_data, 'multipart': process_multipart\
,}

Property Details [hide private]

type

A deprecated alias for :attr:`content_type<cherrypy._cpreqbody.Entity.content_type>`.

Get Method:
unreachable(self)