Back to index

python3.2  3.2.2
Public Member Functions | Public Attributes | Static Public Attributes | Private Member Functions | Private Attributes
cgi.FieldStorage Class Reference

List of all members.

Public Member Functions

def __init__
def __repr__
def __iter__
def __getattr__
def __getitem__
def getvalue
def getfirst
def getlist
def keys
def __contains__
def __len__
def __nonzero__
def read_urlencoded
def read_multi
def read_single
def read_binary
def read_lines
def read_lines_to_eof
def read_lines_to_outerboundary
def skip_lines
def make_file

Public Attributes

 keep_blank_values
 strict_parsing
 qs_on_post
 fp
 encoding
 errors
 headers
 outerboundary
 bytes_read
 limit
 disposition
 disposition_options
 name
 filename
 type
 type_options
 innerboundary
 length
 list
 file
 done

Static Public Attributes

 FieldStorageClass = None
int bufsize = 8

Private Member Functions

def __write

Private Attributes

 _binary_file
 __file

Detailed Description

Store a sequence of fields, reading multipart/form-data.

This class provides naming, typing, files stored on disk, and
more.  At the top level, it is accessible like a dictionary, whose
keys are the field names.  (Note: None can occur as a field name.)
The items are either a Python list (if there's multiple values) or
another FieldStorage or MiniFieldStorage object.  If it's a single
object, it has the following attributes:

name: the field name, if specified; otherwise None

filename: the filename, if specified; otherwise None; this is the
    client side filename, *not* the file name on which it is
    stored (that's a temporary file you don't deal with)

value: the value as a *string*; for file uploads, this
    transparently reads the file every time you request the value
    and returns *bytes*

file: the file(-like) object from which you can read the data *as
    bytes* ; None if the data is stored a simple string

type: the content-type, or None if not specified

type_options: dictionary of options specified on the content-type
    line

disposition: content-disposition, or None if not specified

disposition_options: dictionary of corresponding options

headers: a dictionary(-like) object (sometimes email.message.Message or a
    subclass thereof) containing *all* headers

The class is subclassable, mostly for the purpose of overriding
the make_file() method, which is called internally to come up with
a file open for reading and writing.  This makes it possible to
override the default choice of storing all files in a temporary
directory and unlinking them as soon as they have been opened.

Definition at line 351 of file cgi.py.


Constructor & Destructor Documentation

def cgi.FieldStorage.__init__ (   self,
  fp = None,
  headers = None,
  outerboundary = b'',
  environ = os.environ,
  keep_blank_values = 0,
  strict_parsing = 0,
  limit = None,
  encoding = 'utf-8',
  errors = 'replace' 
)
Constructor.  Read multipart/* until last part.

Arguments, all optional:

fp              : file pointer; default: sys.stdin.buffer
    (not used when the request method is GET)
    Can be :
    1. a TextIOWrapper object
    2. an object whose read() and readline() methods return bytes

headers         : header dictionary-like object; default:
    taken from environ as per CGI spec

outerboundary   : terminating multipart boundary
    (for internal use only)

environ         : environment dictionary; default: os.environ

keep_blank_values: flag indicating whether blank values in
    percent-encoded forms should be treated as blank strings.
    A true value indicates that blanks should be retained as
    blank strings.  The default false value indicates that
    blank values are to be ignored and treated as if they were
    not included.

strict_parsing: flag indicating what to do with parsing errors.
    If false (the default), errors are silently ignored.
    If true, errors raise a ValueError exception.

limit : used internally to read parts of multipart/form-data forms,
    to exit from the reading loop when reached. It is the difference
    between the form content-length and the number of bytes already
    read

encoding, errors : the encoding and error handler used to decode the
    binary stream to strings. Must be the same as the charset defined
    for the page sending the form (content-type : meta http-equiv or
    header)

Definition at line 396 of file cgi.py.

00396 
00397                  limit=None, encoding='utf-8', errors='replace'):
00398         """Constructor.  Read multipart/* until last part.
00399 
00400         Arguments, all optional:
00401 
00402         fp              : file pointer; default: sys.stdin.buffer
00403             (not used when the request method is GET)
00404             Can be :
00405             1. a TextIOWrapper object
00406             2. an object whose read() and readline() methods return bytes
00407 
00408         headers         : header dictionary-like object; default:
00409             taken from environ as per CGI spec
00410 
00411         outerboundary   : terminating multipart boundary
00412             (for internal use only)
00413 
00414         environ         : environment dictionary; default: os.environ
00415 
00416         keep_blank_values: flag indicating whether blank values in
00417             percent-encoded forms should be treated as blank strings.
00418             A true value indicates that blanks should be retained as
00419             blank strings.  The default false value indicates that
00420             blank values are to be ignored and treated as if they were
00421             not included.
00422 
00423         strict_parsing: flag indicating what to do with parsing errors.
00424             If false (the default), errors are silently ignored.
00425             If true, errors raise a ValueError exception.
00426 
00427         limit : used internally to read parts of multipart/form-data forms,
00428             to exit from the reading loop when reached. It is the difference
00429             between the form content-length and the number of bytes already
00430             read
00431 
00432         encoding, errors : the encoding and error handler used to decode the
00433             binary stream to strings. Must be the same as the charset defined
00434             for the page sending the form (content-type : meta http-equiv or
00435             header)
00436 
00437         """
00438         method = 'GET'
00439         self.keep_blank_values = keep_blank_values
00440         self.strict_parsing = strict_parsing
00441         if 'REQUEST_METHOD' in environ:
00442             method = environ['REQUEST_METHOD'].upper()
00443         self.qs_on_post = None
00444         if method == 'GET' or method == 'HEAD':
00445             if 'QUERY_STRING' in environ:
00446                 qs = environ['QUERY_STRING']
00447             elif sys.argv[1:]:
00448                 qs = sys.argv[1]
00449             else:
00450                 qs = ""
00451             qs = qs.encode(locale.getpreferredencoding(), 'surrogateescape')
00452             fp = BytesIO(qs)
00453             if headers is None:
00454                 headers = {'content-type':
00455                            "application/x-www-form-urlencoded"}
00456         if headers is None:
00457             headers = {}
00458             if method == 'POST':
00459                 # Set default content-type for POST to what's traditional
00460                 headers['content-type'] = "application/x-www-form-urlencoded"
00461             if 'CONTENT_TYPE' in environ:
00462                 headers['content-type'] = environ['CONTENT_TYPE']
00463             if 'QUERY_STRING' in environ:
00464                 self.qs_on_post = environ['QUERY_STRING']
00465             if 'CONTENT_LENGTH' in environ:
00466                 headers['content-length'] = environ['CONTENT_LENGTH']
00467         if fp is None:
00468             self.fp = sys.stdin.buffer
00469         # self.fp.read() must return bytes
00470         elif isinstance(fp, TextIOWrapper):
00471             self.fp = fp.buffer
00472         else:
00473             self.fp = fp
00474 
00475         self.encoding = encoding
00476         self.errors = errors
00477 
00478         self.headers = headers
00479         if not isinstance(outerboundary, bytes):
00480             raise TypeError('outerboundary must be bytes, not %s'
00481                             % type(outerboundary).__name__)
00482         self.outerboundary = outerboundary
00483 
00484         self.bytes_read = 0
00485         self.limit = limit
00486 
00487         # Process content-disposition header
00488         cdisp, pdict = "", {}
00489         if 'content-disposition' in self.headers:
00490             cdisp, pdict = parse_header(self.headers['content-disposition'])
00491         self.disposition = cdisp
00492         self.disposition_options = pdict
00493         self.name = None
00494         if 'name' in pdict:
00495             self.name = pdict['name']
00496         self.filename = None
00497         if 'filename' in pdict:
00498             self.filename = pdict['filename']
00499         self._binary_file = self.filename is not None
00500 
00501         # Process content-type header
00502         #
00503         # Honor any existing content-type header.  But if there is no
00504         # content-type header, use some sensible defaults.  Assume
00505         # outerboundary is "" at the outer level, but something non-false
00506         # inside a multi-part.  The default for an inner part is text/plain,
00507         # but for an outer part it should be urlencoded.  This should catch
00508         # bogus clients which erroneously forget to include a content-type
00509         # header.
00510         #
00511         # See below for what we do if there does exist a content-type header,
00512         # but it happens to be something we don't understand.
00513         if 'content-type' in self.headers:
00514             ctype, pdict = parse_header(self.headers['content-type'])
00515         elif self.outerboundary or method != 'POST':
00516             ctype, pdict = "text/plain", {}
00517         else:
00518             ctype, pdict = 'application/x-www-form-urlencoded', {}
00519         self.type = ctype
00520         self.type_options = pdict
00521         if 'boundary' in pdict:
00522             self.innerboundary = pdict['boundary'].encode(self.encoding)
00523         else:
00524             self.innerboundary = b""
00525 
00526         clen = -1
00527         if 'content-length' in self.headers:
00528             try:
00529                 clen = int(self.headers['content-length'])
00530             except ValueError:
00531                 pass
00532             if maxlen and clen > maxlen:
00533                 raise ValueError('Maximum content length exceeded')
00534         self.length = clen
00535         if self.limit is None and clen:
00536             self.limit = clen
00537 
00538         self.list = self.file = None
00539         self.done = 0
00540         if ctype == 'application/x-www-form-urlencoded':
00541             self.read_urlencoded()
00542         elif ctype[:10] == 'multipart/':
00543             self.read_multi(environ, keep_blank_values, strict_parsing)
00544         else:
00545             self.read_single()

Here is the caller graph for this function:


Member Function Documentation

def cgi.FieldStorage.__contains__ (   self,
  key 
)
Dictionary style __contains__ method.

Definition at line 620 of file cgi.py.

00620 
00621     def __contains__(self, key):
00622         """Dictionary style __contains__ method."""
00623         if self.list is None:
00624             raise TypeError("not indexable")
00625         return any(item.name == key for item in self.list)

Here is the call graph for this function:

def cgi.FieldStorage.__getattr__ (   self,
  name 
)

Definition at line 554 of file cgi.py.

00554 
00555     def __getattr__(self, name):
00556         if name != 'value':
00557             raise AttributeError(name)
00558         if self.file:
00559             self.file.seek(0)
00560             value = self.file.read()
00561             self.file.seek(0)
00562         elif self.list is not None:
00563             value = self.list
00564         else:
00565             value = None
00566         return value

def cgi.FieldStorage.__getitem__ (   self,
  key 
)
Dictionary style indexing.

Definition at line 567 of file cgi.py.

00567 
00568     def __getitem__(self, key):
00569         """Dictionary style indexing."""
00570         if self.list is None:
00571             raise TypeError("not indexable")
00572         found = []
00573         for item in self.list:
00574             if item.name == key: found.append(item)
00575         if not found:
00576             raise KeyError(key)
00577         if len(found) == 1:
00578             return found[0]
00579         else:
00580             return found

Here is the caller graph for this function:

def cgi.FieldStorage.__iter__ (   self)

Definition at line 551 of file cgi.py.

00551 
00552     def __iter__(self):
00553         return iter(self.keys())

Here is the call graph for this function:

def cgi.FieldStorage.__len__ (   self)
Dictionary style len(x) support.

Definition at line 626 of file cgi.py.

00626 
00627     def __len__(self):
00628         """Dictionary style len(x) support."""
00629         return len(self.keys())

Here is the call graph for this function:

Definition at line 630 of file cgi.py.

00630 
00631     def __nonzero__(self):
00632         return bool(self.list)

def cgi.FieldStorage.__repr__ (   self)
Return a printable representation.

Definition at line 546 of file cgi.py.

00546 
00547     def __repr__(self):
00548         """Return a printable representation."""
00549         return "FieldStorage(%r, %r, %r)" % (
00550                 self.name, self.filename, self.value)

def cgi.FieldStorage.__write (   self,
  line 
) [private]
line is always bytes, not string

Definition at line 736 of file cgi.py.

00736 
00737     def __write(self, line):
00738         """line is always bytes, not string"""
00739         if self.__file is not None:
00740             if self.__file.tell() + len(line) > 1000:
00741                 self.file = self.make_file()
00742                 data = self.__file.getvalue()
00743                 self.file.write(data)
00744                 self.__file = None
00745         if self._binary_file:
00746             # keep bytes
00747             self.file.write(line)
00748         else:
00749             # decode to string
00750             self.file.write(line.decode(self.encoding, self.errors))

Here is the call graph for this function:

Here is the caller graph for this function:

def cgi.FieldStorage.getfirst (   self,
  key,
  default = None 
)
Return the first value received.

Definition at line 592 of file cgi.py.

00592 
00593     def getfirst(self, key, default=None):
00594         """ Return the first value received."""
00595         if key in self:
00596             value = self[key]
00597             if isinstance(value, list):
00598                 return value[0].value
00599             else:
00600                 return value.value
00601         else:
00602             return default

def cgi.FieldStorage.getlist (   self,
  key 
)
Return list of received values.

Definition at line 603 of file cgi.py.

00603 
00604     def getlist(self, key):
00605         """ Return list of received values."""
00606         if key in self:
00607             value = self[key]
00608             if isinstance(value, list):
00609                 return [x.value for x in value]
00610             else:
00611                 return [value.value]
00612         else:
00613             return []

def cgi.FieldStorage.getvalue (   self,
  key,
  default = None 
)
Dictionary style get() method, including 'value' lookup.

Definition at line 581 of file cgi.py.

00581 
00582     def getvalue(self, key, default=None):
00583         """Dictionary style get() method, including 'value' lookup."""
00584         if key in self:
00585             value = self[key]
00586             if isinstance(value, list):
00587                 return [x.value for x in value]
00588             else:
00589                 return value.value
00590         else:
00591             return default

Here is the caller graph for this function:

def cgi.FieldStorage.keys (   self)
Dictionary style keys() method.

Definition at line 614 of file cgi.py.

00614 
00615     def keys(self):
00616         """Dictionary style keys() method."""
00617         if self.list is None:
00618             raise TypeError("not indexable")
00619         return list(set(item.name for item in self.list))

Here is the call graph for this function:

Here is the caller graph for this function:

Overridable: return a readable & writable file.

The file will be used as follows:
- data is written to it
- seek(0)
- data is read from it

The file is opened in binary mode for files, in text mode
for other fields

This version opens a temporary file for reading and writing,
and immediately deletes (unlinks) it.  The trick (on Unix!) is
that the file can still be used, but it can't be opened by
another process, and it will automatically be deleted when it
is closed or when the current process terminates.

If you want a more permanent file, you derive a class which
overrides this method.  If you want a visible temporary file
that is nevertheless automatically deleted when the script
terminates, try defining a __del__ method in a derived class
which unlinks the temporary files you have created.

Definition at line 823 of file cgi.py.

00823 
00824     def make_file(self):
00825         """Overridable: return a readable & writable file.
00826 
00827         The file will be used as follows:
00828         - data is written to it
00829         - seek(0)
00830         - data is read from it
00831 
00832         The file is opened in binary mode for files, in text mode
00833         for other fields
00834 
00835         This version opens a temporary file for reading and writing,
00836         and immediately deletes (unlinks) it.  The trick (on Unix!) is
00837         that the file can still be used, but it can't be opened by
00838         another process, and it will automatically be deleted when it
00839         is closed or when the current process terminates.
00840 
00841         If you want a more permanent file, you derive a class which
00842         overrides this method.  If you want a visible temporary file
00843         that is nevertheless automatically deleted when the script
00844         terminates, try defining a __del__ method in a derived class
00845         which unlinks the temporary files you have created.
00846 
00847         """
00848         if self._binary_file:
00849             return tempfile.TemporaryFile("wb+")
00850         else:
00851             return tempfile.TemporaryFile("w+",
00852                 encoding=self.encoding, newline = '\n')
00853 
00854 
00855 # Test/debug code
00856 # ===============

Here is the call graph for this function:

Here is the caller graph for this function:

Internal: read binary data.

Definition at line 708 of file cgi.py.

00708 
00709     def read_binary(self):
00710         """Internal: read binary data."""
00711         self.file = self.make_file()
00712         todo = self.length
00713         if todo >= 0:
00714             while todo > 0:
00715                 data = self.fp.read(min(todo, self.bufsize)) # bytes
00716                 if not isinstance(data, bytes):
00717                     raise ValueError("%s should return bytes, got %s"
00718                                      % (self.fp, type(data).__name__))
00719                 self.bytes_read += len(data)
00720                 if not data:
00721                     self.done = -1
00722                     break
00723                 self.file.write(data)
00724                 todo = todo - len(data)

Here is the call graph for this function:

Here is the caller graph for this function:

Internal: read lines until EOF or outerboundary.

Definition at line 725 of file cgi.py.

00725 
00726     def read_lines(self):
00727         """Internal: read lines until EOF or outerboundary."""
00728         if self._binary_file:
00729             self.file = self.__file = BytesIO() # store data as bytes for files
00730         else:
00731             self.file = self.__file = StringIO() # as strings for other fields
00732         if self.outerboundary:
00733             self.read_lines_to_outerboundary()
00734         else:
00735             self.read_lines_to_eof()

Here is the caller graph for this function:

Internal: read lines until EOF.

Definition at line 751 of file cgi.py.

00751 
00752     def read_lines_to_eof(self):
00753         """Internal: read lines until EOF."""
00754         while 1:
00755             line = self.fp.readline(1<<16) # bytes
00756             self.bytes_read += len(line)
00757             if not line:
00758                 self.done = -1
00759                 break
00760             self.__write(line)

Here is the call graph for this function:

Internal: read lines until outerboundary.
Data is read as bytes: boundaries and line ends must be converted
to bytes for comparisons.

Definition at line 761 of file cgi.py.

00761 
00762     def read_lines_to_outerboundary(self):
00763         """Internal: read lines until outerboundary.
00764         Data is read as bytes: boundaries and line ends must be converted
00765         to bytes for comparisons.
00766         """
00767         next_boundary = b"--" + self.outerboundary
00768         last_boundary = next_boundary + b"--"
00769         delim = b""
00770         last_line_lfend = True
00771         _read = 0
00772         while 1:
00773             if _read >= self.limit:
00774                 break
00775             line = self.fp.readline(1<<16) # bytes
00776             self.bytes_read += len(line)
00777             _read += len(line)
00778             if not line:
00779                 self.done = -1
00780                 break
00781             if line.startswith(b"--") and last_line_lfend:
00782                 strippedline = line.rstrip()
00783                 if strippedline == next_boundary:
00784                     break
00785                 if strippedline == last_boundary:
00786                     self.done = 1
00787                     break
00788             odelim = delim
00789             if line.endswith(b"\r\n"):
00790                 delim = b"\r\n"
00791                 line = line[:-2]
00792                 last_line_lfend = True
00793             elif line.endswith(b"\n"):
00794                 delim = b"\n"
00795                 line = line[:-1]
00796                 last_line_lfend = True
00797             else:
00798                 delim = b""
00799                 last_line_lfend = False
00800             self.__write(odelim + line)

Here is the call graph for this function:

def cgi.FieldStorage.read_multi (   self,
  environ,
  keep_blank_values,
  strict_parsing 
)
Internal: read a part that is itself multipart.

Definition at line 652 of file cgi.py.

00652 
00653     def read_multi(self, environ, keep_blank_values, strict_parsing):
00654         """Internal: read a part that is itself multipart."""
00655         ib = self.innerboundary
00656         if not valid_boundary(ib):
00657             raise ValueError('Invalid boundary in multipart form: %r' % (ib,))
00658         self.list = []
00659         if self.qs_on_post:
00660             query = urllib.parse.parse_qsl(
00661                 self.qs_on_post, self.keep_blank_values, self.strict_parsing,
00662                 encoding=self.encoding, errors=self.errors)
00663             for key, value in query:
00664                 self.list.append(MiniFieldStorage(key, value))
00665             FieldStorageClass = None
00666 
00667         klass = self.FieldStorageClass or self.__class__
00668         first_line = self.fp.readline() # bytes
00669         if not isinstance(first_line, bytes):
00670             raise ValueError("%s should return bytes, got %s" \
00671                              % (self.fp, type(first_line).__name__))
00672         self.bytes_read += len(first_line)
00673         # first line holds boundary ; ignore it, or check that
00674         # b"--" + ib == first_line.strip() ?
00675         while True:
00676             parser = FeedParser()
00677             hdr_text = b""
00678             while True:
00679                 data = self.fp.readline()
00680                 hdr_text += data
00681                 if not data.strip():
00682                     break
00683             if not hdr_text:
00684                 break
00685             # parser takes strings, not bytes
00686             self.bytes_read += len(hdr_text)
00687             parser.feed(hdr_text.decode(self.encoding, self.errors))
00688             headers = parser.close()
00689             part = klass(self.fp, headers, ib, environ, keep_blank_values,
00690                          strict_parsing,self.limit-self.bytes_read,
00691                          self.encoding, self.errors)
00692             self.bytes_read += part.bytes_read
00693             self.list.append(part)
00694             if self.bytes_read >= self.length:
00695                 break
00696         self.skip_lines()

Here is the call graph for this function:

Internal: read an atomic part.

Definition at line 697 of file cgi.py.

00697 
00698     def read_single(self):
00699         """Internal: read an atomic part."""
00700         if self.length >= 0:
00701             self.read_binary()
00702             self.skip_lines()
00703         else:
00704             self.read_lines()
00705         self.file.seek(0)

Here is the call graph for this function:

Internal: read data in query string format.

Definition at line 633 of file cgi.py.

00633 
00634     def read_urlencoded(self):
00635         """Internal: read data in query string format."""
00636         qs = self.fp.read(self.length)
00637         if not isinstance(qs, bytes):
00638             raise ValueError("%s should return bytes, got %s" \
00639                              % (self.fp, type(qs).__name__))
00640         qs = qs.decode(self.encoding, self.errors)
00641         if self.qs_on_post:
00642             qs += '&' + self.qs_on_post
00643         self.list = []
00644         query = urllib.parse.parse_qsl(
00645             qs, self.keep_blank_values, self.strict_parsing,
00646             encoding=self.encoding, errors=self.errors)
00647         for key, value in query:
00648             self.list.append(MiniFieldStorage(key, value))
00649         self.skip_lines()

Here is the call graph for this function:

Internal: skip lines until outer boundary if defined.

Definition at line 801 of file cgi.py.

00801 
00802     def skip_lines(self):
00803         """Internal: skip lines until outer boundary if defined."""
00804         if not self.outerboundary or self.done:
00805             return
00806         next_boundary = b"--" + self.outerboundary
00807         last_boundary = next_boundary + b"--"
00808         last_line_lfend = True
00809         while True:
00810             line = self.fp.readline(1<<16)
00811             self.bytes_read += len(line)
00812             if not line:
00813                 self.done = -1
00814                 break
00815             if line.endswith(b"--") and last_line_lfend:
00816                 strippedline = line.strip()
00817                 if strippedline == next_boundary:
00818                     break
00819                 if strippedline == last_boundary:
00820                     self.done = 1
00821                     break
00822             last_line_lfend = line.endswith(b'\n')

Here is the caller graph for this function:


Member Data Documentation

Definition at line 728 of file cgi.py.

Definition at line 498 of file cgi.py.

Definition at line 706 of file cgi.py.

Definition at line 483 of file cgi.py.

Definition at line 490 of file cgi.py.

Definition at line 491 of file cgi.py.

Definition at line 538 of file cgi.py.

Definition at line 474 of file cgi.py.

Definition at line 475 of file cgi.py.

Definition at line 650 of file cgi.py.

Definition at line 537 of file cgi.py.

Definition at line 495 of file cgi.py.

Definition at line 467 of file cgi.py.

Definition at line 477 of file cgi.py.

Definition at line 521 of file cgi.py.

Definition at line 438 of file cgi.py.

Definition at line 533 of file cgi.py.

Definition at line 484 of file cgi.py.

Definition at line 537 of file cgi.py.

Definition at line 492 of file cgi.py.

Definition at line 481 of file cgi.py.

Definition at line 442 of file cgi.py.

Definition at line 439 of file cgi.py.

Definition at line 518 of file cgi.py.

Definition at line 519 of file cgi.py.


The documentation for this class was generated from the following file: