diff options
Diffstat (limited to 'Doc/lib')
| -rw-r--r-- | Doc/lib/lib.tex | 3 | ||||
| -rw-r--r-- | Doc/lib/libcodecs.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libfuncs.tex | 76 | ||||
| -rw-r--r-- | Doc/lib/libimp.tex | 5 | ||||
| -rw-r--r-- | Doc/lib/libitertools.tex | 8 | ||||
| -rw-r--r-- | Doc/lib/liblogging.tex | 7 | ||||
| -rw-r--r-- | Doc/lib/libmimewriter.tex | 80 | ||||
| -rw-r--r-- | Doc/lib/libmimify.tex | 94 | ||||
| -rw-r--r-- | Doc/lib/libpickle.tex | 6 | ||||
| -rw-r--r-- | Doc/lib/libposixfile.tex | 174 | ||||
| -rw-r--r-- | Doc/lib/libshlex.tex | 6 | ||||
| -rw-r--r-- | Doc/lib/libsubprocess.tex | 5 | ||||
| -rw-r--r-- | Doc/lib/libsys.tex | 36 | ||||
| -rw-r--r-- | Doc/lib/libtarfile.tex | 166 | ||||
| -rw-r--r-- | Doc/lib/libtypes.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libundoc.tex | 5 | ||||
| -rw-r--r-- | Doc/lib/libzipimport.tex | 5 |
17 files changed, 166 insertions, 514 deletions
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index cb82246..792b00b 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -146,8 +146,6 @@ and how to embed it in other applications. \input{libmhlib} \input{libmimetools} \input{libmimetypes} -\input{libmimewriter} -\input{libmimify} \input{libmultifile} \input{librfc822} @@ -265,7 +263,6 @@ and how to embed it in other applications. \input{libpty} \input{libfcntl} \input{libpipes} -\input{libposixfile} \input{libresource} \input{libnis} \input{libsyslog} diff --git a/Doc/lib/libcodecs.tex b/Doc/lib/libcodecs.tex index 78fa24d..a3399fb 100644 --- a/Doc/lib/libcodecs.tex +++ b/Doc/lib/libcodecs.tex @@ -237,7 +237,7 @@ any other keyword argument) is passed through to the incremental encoder. \begin{funcdesc}{iterdecode}{iterable, encoding\optional{, errors}} Uses an incremental decoder to iteratively decode the input provided by \var{iterable}. This function is a generator. \var{errors} (as well as -any other keyword argument) is passed through to the incremental encoder. +any other keyword argument) is passed through to the incremental decoder. \versionadded{2.5} \end{funcdesc} diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex index 5e6e2a0..4f49e33 100644 --- a/Doc/lib/libfuncs.tex +++ b/Doc/lib/libfuncs.tex @@ -890,82 +890,6 @@ class Parrot(object): \end{verbatim} \end{funcdesc} -\begin{funcdesc}{reload}{module} - Reload a previously imported \var{module}. The - argument must be a module object, so it must have been successfully - imported before. This is useful if you have edited the module - source file using an external editor and want to try out the new - version without leaving the Python interpreter. The return value is - the module object (the same as the \var{module} argument). - - When \code{reload(module)} is executed: - -\begin{itemize} - - \item Python modules' code is recompiled and the module-level code - reexecuted, defining a new set of objects which are bound to names in - the module's dictionary. The \code{init} function of extension - modules is not called a second time. - - \item As with all other objects in Python the old objects are only - reclaimed after their reference counts drop to zero. - - \item The names in the module namespace are updated to point to - any new or changed objects. - - \item Other references to the old objects (such as names external - to the module) are not rebound to refer to the new objects and - must be updated in each namespace where they occur if that is - desired. - -\end{itemize} - - There are a number of other caveats: - - If a module is syntactically correct but its initialization fails, - the first \keyword{import} statement for it does not bind its name - locally, but does store a (partially initialized) module object in - \code{sys.modules}. To reload the module you must first - \keyword{import} it again (this will bind the name to the partially - initialized module object) before you can \function{reload()} it. - - When a module is reloaded, its dictionary (containing the module's - global variables) is retained. Redefinitions of names will override - the old definitions, so this is generally not a problem. If the new - version of a module does not define a name that was defined by the - old version, the old definition remains. This feature can be used - to the module's advantage if it maintains a global table or cache of - objects --- with a \keyword{try} statement it can test for the - table's presence and skip its initialization if desired: - -\begin{verbatim} -try: - cache -except NameError: - cache = {} -\end{verbatim} - - - It is legal though generally not very useful to reload built-in or - dynamically loaded modules, except for \refmodule{sys}, - \refmodule[main]{__main__} and \refmodule[builtin]{__builtin__}. In - many cases, however, extension modules are not designed to be - initialized more than once, and may fail in arbitrary ways when - reloaded. - - If a module imports objects from another module using \keyword{from} - \ldots{} \keyword{import} \ldots{}, calling \function{reload()} for - the other module does not redefine the objects imported from it --- - one way around this is to re-execute the \keyword{from} statement, - another is to use \keyword{import} and qualified names - (\var{module}.\var{name}) instead. - - If a module instantiates instances of a class, reloading the module - that defines the class does not affect the method definitions of the - instances --- they continue to use the old class definition. The - same is true for derived classes. -\end{funcdesc} - \begin{funcdesc}{repr}{object} Return a string containing a printable representation of an object. This is the same value yielded by conversions (reverse quotes). diff --git a/Doc/lib/libimp.tex b/Doc/lib/libimp.tex index 5379309..6396605 100644 --- a/Doc/lib/libimp.tex +++ b/Doc/lib/libimp.tex @@ -69,8 +69,7 @@ this recipe recursively. Load a module that was previously found by \function{find_module()} (or by an otherwise conducted search yielding compatible results). This function does more than importing the module: if the module was -already imported, it is equivalent to a -\function{reload()}\bifuncindex{reload}! The \var{name} argument +already imported, it will reload the module! The \var{name} argument indicates the full module name (including the package name, if this is a submodule of a package). The \var{file} argument is an open file, and \var{filename} is the corresponding file name; these can be @@ -286,7 +285,7 @@ def __import__(name, globals=None, locals=None, fromlist=None): \end{verbatim} A more complete example that implements hierarchical module names and -includes a \function{reload()}\bifuncindex{reload} function can be +includes a \function{reload()} function can be found in the module \module{knee}\refmodindex{knee}. The \module{knee} module can be found in \file{Demo/imputil/} in the Python source distribution. diff --git a/Doc/lib/libitertools.tex b/Doc/lib/libitertools.tex index 9bf8ab0..19bc826 100644 --- a/Doc/lib/libitertools.tex +++ b/Doc/lib/libitertools.tex @@ -138,6 +138,13 @@ by functions or loops that truncate the stream. identity function and returns the element unchanged. Generally, the iterable needs to already be sorted on the same key function. + The operation of \function{groupby()} is similar to the \code{uniq} filter + in \UNIX{}. It generates a break or new group every time the value + of the key function changes (which is why it is usually necessary + to have sorted the data using the same key function). That behavior + differs from SQL's GROUP BY which aggregates common elements regardless + of their input order. + The returned group is itself an iterator that shares the underlying iterable with \function{groupby()}. Because the source is shared, when the \function{groupby} object is advanced, the previous group is no @@ -147,6 +154,7 @@ by functions or loops that truncate the stream. \begin{verbatim} groups = [] uniquekeys = [] + data = sorted(data, key=keyfunc) for k, g in groupby(data, keyfunc): groups.append(list(g)) # Store group iterator as a list uniquekeys.append(k) diff --git a/Doc/lib/liblogging.tex b/Doc/lib/liblogging.tex index 5783cbf..c5c3e4e 100644 --- a/Doc/lib/liblogging.tex +++ b/Doc/lib/liblogging.tex @@ -1208,8 +1208,11 @@ Returns a new instance of the \class{SysLogHandler} class intended to communicate with a remote \UNIX{} machine whose address is given by \var{address} in the form of a \code{(\var{host}, \var{port})} tuple. If \var{address} is not specified, \code{('localhost', 514)} is -used. The address is used to open a UDP socket. If \var{facility} is -not specified, \constant{LOG_USER} is used. +used. The address is used to open a UDP socket. An alternative to providing +a \code{(\var{host}, \var{port})} tuple is providing an address as a string, +for example "/dev/log". In this case, a Unix domain socket is used to send +the message to the syslog. If \var{facility} is not specified, +\constant{LOG_USER} is used. \end{classdesc} \begin{methoddesc}{close}{} diff --git a/Doc/lib/libmimewriter.tex b/Doc/lib/libmimewriter.tex deleted file mode 100644 index 74bd9bb..0000000 --- a/Doc/lib/libmimewriter.tex +++ /dev/null @@ -1,80 +0,0 @@ -\section{\module{MimeWriter} --- - Generic MIME file writer} - -\declaremodule{standard}{MimeWriter} - -\modulesynopsis{Generic MIME file writer.} -\sectionauthor{Christopher G. Petrilli}{petrilli@amber.org} - -\deprecated{2.3}{The \refmodule{email} package should be used in - preference to the \module{MimeWriter} module. This - module is present only to maintain backward - compatibility.} - -This module defines the class \class{MimeWriter}. The -\class{MimeWriter} class implements a basic formatter for creating -MIME multi-part files. It doesn't seek around the output file nor -does it use large amounts of buffer space. You must write the parts -out in the order that they should occur in the final -file. \class{MimeWriter} does buffer the headers you add, allowing you -to rearrange their order. - -\begin{classdesc}{MimeWriter}{fp} -Return a new instance of the \class{MimeWriter} class. The only -argument passed, \var{fp}, is a file object to be used for -writing. Note that a \class{StringIO} object could also be used. -\end{classdesc} - - -\subsection{MimeWriter Objects \label{MimeWriter-objects}} - - -\class{MimeWriter} instances have the following methods: - -\begin{methoddesc}[MimeWriter]{addheader}{key, value\optional{, prefix}} -Add a header line to the MIME message. The \var{key} is the name of -the header, where the \var{value} obviously provides the value of the -header. The optional argument \var{prefix} determines where the header -is inserted; \samp{0} means append at the end, \samp{1} is insert at -the start. The default is to append. -\end{methoddesc} - -\begin{methoddesc}[MimeWriter]{flushheaders}{} -Causes all headers accumulated so far to be written out (and -forgotten). This is useful if you don't need a body part at all, -e.g.\ for a subpart of type \mimetype{message/rfc822} that's (mis)used -to store some header-like information. -\end{methoddesc} - -\begin{methoddesc}[MimeWriter]{startbody}{ctype\optional{, plist\optional{, prefix}}} -Returns a file-like object which can be used to write to the -body of the message. The content-type is set to the provided -\var{ctype}, and the optional parameter \var{plist} provides -additional parameters for the content-type declaration. \var{prefix} -functions as in \method{addheader()} except that the default is to -insert at the start. -\end{methoddesc} - -\begin{methoddesc}[MimeWriter]{startmultipartbody}{subtype\optional{, - boundary\optional{, plist\optional{, prefix}}}} -Returns a file-like object which can be used to write to the -body of the message. Additionally, this method initializes the -multi-part code, where \var{subtype} provides the multipart subtype, -\var{boundary} may provide a user-defined boundary specification, and -\var{plist} provides optional parameters for the subtype. -\var{prefix} functions as in \method{startbody()}. Subparts should be -created using \method{nextpart()}. -\end{methoddesc} - -\begin{methoddesc}[MimeWriter]{nextpart}{} -Returns a new instance of \class{MimeWriter} which represents an -individual part in a multipart message. This may be used to write the -part as well as used for creating recursively complex multipart -messages. The message must first be initialized with -\method{startmultipartbody()} before using \method{nextpart()}. -\end{methoddesc} - -\begin{methoddesc}[MimeWriter]{lastpart}{} -This is used to designate the last part of a multipart message, and -should \emph{always} be used when writing multipart messages. -\end{methoddesc} diff --git a/Doc/lib/libmimify.tex b/Doc/lib/libmimify.tex deleted file mode 100644 index d99567a..0000000 --- a/Doc/lib/libmimify.tex +++ /dev/null @@ -1,94 +0,0 @@ -\section{\module{mimify} --- - MIME processing of mail messages} - -\declaremodule{standard}{mimify} -\modulesynopsis{Mimification and unmimification of mail messages.} - -\deprecated{2.3}{The \refmodule{email} package should be used in - preference to the \module{mimify} module. This - module is present only to maintain backward - compatibility.} - -The \module{mimify} module defines two functions to convert mail messages to -and from MIME format. The mail message can be either a simple message -or a so-called multipart message. Each part is treated separately. -Mimifying (a part of) a message entails encoding the message as -quoted-printable if it contains any characters that cannot be -represented using 7-bit \ASCII. Unmimifying (a part of) a message -entails undoing the quoted-printable encoding. Mimify and unmimify -are especially useful when a message has to be edited before being -sent. Typical use would be: - -\begin{verbatim} -unmimify message -edit message -mimify message -send message -\end{verbatim} - -The modules defines the following user-callable functions and -user-settable variables: - -\begin{funcdesc}{mimify}{infile, outfile} -Copy the message in \var{infile} to \var{outfile}, converting parts to -quoted-printable and adding MIME mail headers when necessary. -\var{infile} and \var{outfile} can be file objects (actually, any -object that has a \method{readline()} method (for \var{infile}) or a -\method{write()} method (for \var{outfile})) or strings naming the files. -If \var{infile} and \var{outfile} are both strings, they may have the -same value. -\end{funcdesc} - -\begin{funcdesc}{unmimify}{infile, outfile\optional{, decode_base64}} -Copy the message in \var{infile} to \var{outfile}, decoding all -quoted-printable parts. \var{infile} and \var{outfile} can be file -objects (actually, any object that has a \method{readline()} method (for -\var{infile}) or a \method{write()} method (for \var{outfile})) or strings -naming the files. If \var{infile} and \var{outfile} are both strings, -they may have the same value. -If the \var{decode_base64} argument is provided and tests true, any -parts that are coded in the base64 encoding are decoded as well. -\end{funcdesc} - -\begin{funcdesc}{mime_decode_header}{line} -Return a decoded version of the encoded header line in \var{line}. -This only supports the ISO 8859-1 charset (Latin-1). -\end{funcdesc} - -\begin{funcdesc}{mime_encode_header}{line} -Return a MIME-encoded version of the header line in \var{line}. -\end{funcdesc} - -\begin{datadesc}{MAXLEN} -By default, a part will be encoded as quoted-printable when it -contains any non-\ASCII{} characters (characters with the 8th bit -set), or if there are any lines longer than \constant{MAXLEN} characters -(default value 200). -\end{datadesc} - -\begin{datadesc}{CHARSET} -When not specified in the mail headers, a character set must be filled -in. The string used is stored in \constant{CHARSET}, and the default -value is ISO-8859-1 (also known as Latin1 (latin-one)). -\end{datadesc} - -This module can also be used from the command line. Usage is as -follows: -\begin{verbatim} -mimify.py -e [-l length] [infile [outfile]] -mimify.py -d [-b] [infile [outfile]] -\end{verbatim} -to encode (mimify) and decode (unmimify) respectively. \var{infile} -defaults to standard input, \var{outfile} defaults to standard output. -The same file can be specified for input and output. - -If the \strong{-l} option is given when encoding, if there are any lines -longer than the specified \var{length}, the containing part will be -encoded. - -If the \strong{-b} option is given when decoding, any base64 parts will -be decoded as well. - -\begin{seealso} - \seemodule{quopri}{Encode and decode MIME quoted-printable files.} -\end{seealso} diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex index 3290641..0c4cd98 100644 --- a/Doc/lib/libpickle.tex +++ b/Doc/lib/libpickle.tex @@ -799,7 +799,7 @@ class TextReader: del odict['fh'] # remove filehandle entry return odict - def __setstate__(self,dict): + def __setstate__(self, dict): fh = open(dict['file']) # reopen file count = dict['lineno'] # read from file... while count: # until line count is restored @@ -820,7 +820,7 @@ A sample usage might be something like this: ... obj.readline() '7: class TextReader:' >>> import pickle ->>> pickle.dump(obj,open('save.p','w')) +>>> pickle.dump(obj,open('save.p', 'wb')) \end{verbatim} If you want to see that \refmodule{pickle} works across Python @@ -829,7 +829,7 @@ follows can happen from either the same process or a new process. \begin{verbatim} >>> import pickle ->>> reader = pickle.load(open('save.p')) +>>> reader = pickle.load(open('save.p', 'rb')) >>> reader.readline() '8: "Print and number lines in a text file."' \end{verbatim} diff --git a/Doc/lib/libposixfile.tex b/Doc/lib/libposixfile.tex deleted file mode 100644 index 5c86f3e..0000000 --- a/Doc/lib/libposixfile.tex +++ /dev/null @@ -1,174 +0,0 @@ -% Manual text and implementation by Jaap Vermeulen -\section{\module{posixfile} --- - File-like objects with locking support} - -\declaremodule{builtin}{posixfile} - \platform{Unix} -\modulesynopsis{A file-like object with support for locking.} -\moduleauthor{Jaap Vermeulen}{} -\sectionauthor{Jaap Vermeulen}{} - - -\indexii{\POSIX}{file object} - -\deprecated{1.5}{The locking operation that this module provides is -done better and more portably by the -\function{\refmodule{fcntl}.lockf()} call. -\withsubitem{(in module fcntl)}{\ttindex{lockf()}}} - -This module implements some additional functionality over the built-in -file objects. In particular, it implements file locking, control over -the file flags, and an easy interface to duplicate the file object. -The module defines a new file object, the posixfile object. It -has all the standard file object methods and adds the methods -described below. This module only works for certain flavors of -\UNIX, since it uses \function{fcntl.fcntl()} for file locking.% -\withsubitem{(in module fcntl)}{\ttindex{fcntl()}} - -To instantiate a posixfile object, use the \function{open()} function -in the \module{posixfile} module. The resulting object looks and -feels roughly the same as a standard file object. - -The \module{posixfile} module defines the following constants: - - -\begin{datadesc}{SEEK_SET} -Offset is calculated from the start of the file. -\end{datadesc} - -\begin{datadesc}{SEEK_CUR} -Offset is calculated from the current position in the file. -\end{datadesc} - -\begin{datadesc}{SEEK_END} -Offset is calculated from the end of the file. -\end{datadesc} - -The \module{posixfile} module defines the following functions: - - -\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}} - Create a new posixfile object with the given filename and mode. The - \var{filename}, \var{mode} and \var{bufsize} arguments are - interpreted the same way as by the built-in \function{open()} - function. -\end{funcdesc} - -\begin{funcdesc}{fileopen}{fileobject} - Create a new posixfile object with the given standard file object. - The resulting object has the same filename and mode as the original - file object. -\end{funcdesc} - -The posixfile object defines the following additional methods: - -\begin{methoddesc}[posixfile]{lock}{fmt, \optional{len\optional{, start\optional{, whence}}}} - Lock the specified section of the file that the file object is - referring to. The format is explained - below in a table. The \var{len} argument specifies the length of the - section that should be locked. The default is \code{0}. \var{start} - specifies the starting offset of the section, where the default is - \code{0}. The \var{whence} argument specifies where the offset is - relative to. It accepts one of the constants \constant{SEEK_SET}, - \constant{SEEK_CUR} or \constant{SEEK_END}. The default is - \constant{SEEK_SET}. For more information about the arguments refer - to the \manpage{fcntl}{2} manual page on your system. -\end{methoddesc} - -\begin{methoddesc}[posixfile]{flags}{\optional{flags}} - Set the specified flags for the file that the file object is referring - to. The new flags are ORed with the old flags, unless specified - otherwise. The format is explained below in a table. Without - the \var{flags} argument - a string indicating the current flags is returned (this is - the same as the \samp{?} modifier). For more information about the - flags refer to the \manpage{fcntl}{2} manual page on your system. -\end{methoddesc} - -\begin{methoddesc}[posixfile]{dup}{} - Duplicate the file object and the underlying file pointer and file - descriptor. The resulting object behaves as if it were newly - opened. -\end{methoddesc} - -\begin{methoddesc}[posixfile]{dup2}{fd} - Duplicate the file object and the underlying file pointer and file - descriptor. The new object will have the given file descriptor. - Otherwise the resulting object behaves as if it were newly opened. -\end{methoddesc} - -\begin{methoddesc}[posixfile]{file}{} - Return the standard file object that the posixfile object is based - on. This is sometimes necessary for functions that insist on a - standard file object. -\end{methoddesc} - -All methods raise \exception{IOError} when the request fails. - -Format characters for the \method{lock()} method have the following -meaning: - -\begin{tableii}{c|l}{samp}{Format}{Meaning} - \lineii{u}{unlock the specified region} - \lineii{r}{request a read lock for the specified section} - \lineii{w}{request a write lock for the specified section} -\end{tableii} - -In addition the following modifiers can be added to the format: - -\begin{tableiii}{c|l|c}{samp}{Modifier}{Meaning}{Notes} - \lineiii{|}{wait until the lock has been granted}{} - \lineiii{?}{return the first lock conflicting with the requested lock, or - \code{None} if there is no conflict.}{(1)} -\end{tableiii} - -\noindent -Note: - -\begin{description} -\item[(1)] The lock returned is in the format \code{(\var{mode}, \var{len}, -\var{start}, \var{whence}, \var{pid})} where \var{mode} is a character -representing the type of lock ('r' or 'w'). This modifier prevents a -request from being granted; it is for query purposes only. -\end{description} - -Format characters for the \method{flags()} method have the following -meanings: - -\begin{tableii}{c|l}{samp}{Format}{Meaning} - \lineii{a}{append only flag} - \lineii{c}{close on exec flag} - \lineii{n}{no delay flag (also called non-blocking flag)} - \lineii{s}{synchronization flag} -\end{tableii} - -In addition the following modifiers can be added to the format: - -\begin{tableiii}{c|l|c}{samp}{Modifier}{Meaning}{Notes} - \lineiii{!}{turn the specified flags 'off', instead of the default 'on'}{(1)} - \lineiii{=}{replace the flags, instead of the default 'OR' operation}{(1)} - \lineiii{?}{return a string in which the characters represent the flags that - are set.}{(2)} -\end{tableiii} - -\noindent -Notes: - -\begin{description} -\item[(1)] The \samp{!} and \samp{=} modifiers are mutually exclusive. - -\item[(2)] This string represents the flags after they may have been altered -by the same call. -\end{description} - -Examples: - -\begin{verbatim} -import posixfile - -file = posixfile.open('/tmp/test', 'w') -file.lock('w|') -... -file.lock('u') -file.close() -\end{verbatim} diff --git a/Doc/lib/libshlex.tex b/Doc/lib/libshlex.tex index 451615f..23babd3 100644 --- a/Doc/lib/libshlex.tex +++ b/Doc/lib/libshlex.tex @@ -19,13 +19,15 @@ files for Python applications) or for parsing quoted strings. The \module{shlex} module defines the following functions: -\begin{funcdesc}{split}{s\optional{, comments}} +\begin{funcdesc}{split}{s\optional{, comments\optional{, posix}}} Split the string \var{s} using shell-like syntax. If \var{comments} is \constant{False} (the default), the parsing of comments in the given string will be disabled (setting the \member{commenters} member of the \class{shlex} instance to the empty string). This function operates -in \POSIX{} mode. +in \POSIX{} mode by default, but uses non-\POSIX{} mode if the +\var{posix} argument is false. \versionadded{2.3} +\versionchanged[Added the \var{posix} parameter]{2.6} \end{funcdesc} The \module{shlex} module defines the following class: diff --git a/Doc/lib/libsubprocess.tex b/Doc/lib/libsubprocess.tex index 35ab4d0..dc386bf 100644 --- a/Doc/lib/libsubprocess.tex +++ b/Doc/lib/libsubprocess.tex @@ -87,7 +87,10 @@ called in the child process just before the child is executed. If \var{close_fds} is true, all file descriptors except \constant{0}, \constant{1} and \constant{2} will be closed before the child process is -executed. (\UNIX{} only) +executed. (\UNIX{} only). Or, on Windows, if \var{close_fds} is true +then no handles will be inherited by the child process. Note that on +Windows, you cannot set \var{close_fds} to true and also redirect the +standard handles by setting \var{stdin}, \var{stdout} or \var{stderr}. If \var{shell} is \constant{True}, the specified command will be executed through the shell. diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex index 1284668..4ab3247 100644 --- a/Doc/lib/libsys.tex +++ b/Doc/lib/libsys.tex @@ -132,11 +132,6 @@ It is always available. encapsulates the call stack at the point where the exception originally occurred. \obindex{traceback} - If \function{exc_clear()} is called, this function will return three - \code{None} values until either another exception is raised in the - current thread or the execution stack returns to a frame where - another exception is being handled. - \warning{Assigning the \var{traceback} return value to a local variable in a function that is handling an exception will cause a circular reference. This will prevent anything referenced @@ -153,32 +148,6 @@ It is always available. efficient to avoid creating cycles.} \end{funcdesc} -\begin{funcdesc}{exc_clear}{} - This function clears all information relating to the current or last - exception that occurred in the current thread. After calling this - function, \function{exc_info()} will return three \code{None} values until - another exception is raised in the current thread or the execution stack - returns to a frame where another exception is being handled. - - This function is only needed in only a few obscure situations. These - include logging and error handling systems that report information on the - last or current exception. This function can also be used to try to free - resources and trigger object finalization, though no guarantee is made as - to what objects will be freed, if any. -\versionadded{2.3} -\end{funcdesc} - -\begin{datadesc}{exc_type} -\dataline{exc_value} -\dataline{exc_traceback} -\deprecated {1.5} - {Use \function{exc_info()} instead.} - Since they are global variables, they are not specific to the - current thread, so their use is not safe in a multi-threaded - program. When no exception is being handled, \code{exc_type} is set - to \code{None} and the other two are undefined. -\end{datadesc} - \begin{datadesc}{exec_prefix} A string giving the site-specific directory prefix where the platform-dependent Python files are installed; by default, this is @@ -377,10 +346,7 @@ else: \begin{datadesc}{modules} This is a dictionary that maps module names to modules which have already been loaded. This can be manipulated to force reloading of - modules and other tricks. Note that removing a module from this - dictionary is \emph{not} the same as calling - \function{reload()}\bifuncindex{reload} on the corresponding module - object. + modules and other tricks. \end{datadesc} \begin{datadesc}{path} diff --git a/Doc/lib/libtarfile.tex b/Doc/lib/libtarfile.tex index 73c35ed..54683a7 100644 --- a/Doc/lib/libtarfile.tex +++ b/Doc/lib/libtarfile.tex @@ -133,24 +133,20 @@ Some facts and figures: \versionadded{2.6} \end{excdesc} +Each of the following constants defines a tar archive format that the +\module{tarfile} module is able to create. See section \ref{tar-formats} for +details. + \begin{datadesc}{USTAR_FORMAT} - \POSIX{}.1-1988 (ustar) format. It supports filenames up to a length of - at best 256 characters and linknames up to 100 characters. The maximum - file size is 8 gigabytes. This is an old and limited but widely - supported format. + \POSIX{}.1-1988 (ustar) format. \end{datadesc} \begin{datadesc}{GNU_FORMAT} - GNU tar format. It supports arbitrarily long filenames and linknames and - files bigger than 8 gigabytes. It is the defacto standard on GNU/Linux - systems. + GNU tar format. \end{datadesc} \begin{datadesc}{PAX_FORMAT} - \POSIX{}.1-2001 (pax) format. It is the most flexible format with - virtually no limits. It supports long filenames and linknames, large files - and stores pathnames in a portable way. However, not all tar - implementations today are able to handle pax archives properly. + \POSIX{}.1-2001 (pax) format. \end{datadesc} \begin{datadesc}{DEFAULT_FORMAT} @@ -175,15 +171,15 @@ Some facts and figures: The \class{TarFile} object provides an interface to a tar archive. A tar archive is a sequence of blocks. An archive member (a stored file) is made up -of a header block followed by data blocks. It is possible, to store a file in a +of a header block followed by data blocks. It is possible to store a file in a tar archive several times. Each archive member is represented by a \class{TarInfo} object, see \citetitle{TarInfo Objects} (section \ref{tarinfo-objects}) for details. \begin{classdesc}{TarFile}{name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, - ignore_zeros=False, encoding=None, pax_headers=None, debug=0, - errorlevel=0} + ignore_zeros=False, encoding=None, errors=None, pax_headers=None, + debug=0, errorlevel=0} All following arguments are optional and can be accessed as instance attributes as well. @@ -231,18 +227,14 @@ tar archive several times. Each archive member is represented by a If \code{2}, all \emph{non-fatal} errors are raised as \exception{TarError} exceptions as well. - The \var{encoding} argument defines the local character encoding. It - defaults to the value from \function{sys.getfilesystemencoding()} or if - that is \code{None} to \code{"ascii"}. \var{encoding} is used only in - connection with the pax format which stores text data in \emph{UTF-8}. If - it is not set correctly, character conversion will fail with a - \exception{UnicodeError}. + The \var{encoding} and \var{errors} arguments control the way strings are + converted to unicode objects and vice versa. The default settings will work + for most users. See section \ref{tar-unicode} for in-depth information. \versionadded{2.6} - The \var{pax_headers} argument must be a dictionary whose elements are - either unicode objects, numbers or strings that can be decoded to unicode - using \var{encoding}. This information will be added to the archive as a - pax global header. + The \var{pax_headers} argument is an optional dictionary of unicode strings + which will be added as a pax global header if \var{format} is + \constant{PAX_FORMAT}. \versionadded{2.6} \end{classdesc} @@ -287,7 +279,7 @@ tar archive several times. Each archive member is represented by a Extract all members from the archive to the current working directory or directory \var{path}. If optional \var{members} is given, it must be a subset of the list returned by \method{getmembers()}. - Directory informations like owner, modification time and permissions are + Directory information like owner, modification time and permissions are set after all members have been extracted. This is done to work around two problems: A directory's modification time is reset each time a file is created in it. And, if a directory's permissions do not allow writing, @@ -365,6 +357,11 @@ tar archive several times. Each archive member is represented by a \deprecated{2.6}{Use the \member{format} attribute instead.} \end{memberdesc} +\begin{memberdesc}{pax_headers} + A dictionary containing key-value pairs of pax global headers. + \versionadded{2.6} +\end{memberdesc} + %----------------- % TarInfo Objects %----------------- @@ -384,8 +381,8 @@ the file's data itself. Create a \class{TarInfo} object. \end{classdesc} -\begin{methoddesc}{frombuf}{} - Create and return a \class{TarInfo} object from a string buffer. +\begin{methoddesc}{frombuf}{buf} + Create and return a \class{TarInfo} object from string buffer \var{buf}. \versionadded[Raises \exception{HeaderError} if the buffer is invalid.]{2.6} \end{methoddesc} @@ -396,10 +393,11 @@ the file's data itself. \versionadded{2.6} \end{methoddesc} -\begin{methoddesc}{tobuf}{\optional{format}} - Create a string buffer from a \class{TarInfo} object. See - \class{TarFile}'s \member{format} argument for information. - \versionchanged[The \var{format} parameter]{2.6} +\begin{methoddesc}{tobuf}{\optional{format\optional{, encoding + \optional{, errors}}}} + Create a string buffer from a \class{TarInfo} object. For information + on the arguments see the constructor of the \class{TarFile} class. + \versionchanged[The arguments were added]{2.6} \end{methoddesc} A \code{TarInfo} object has the following public data attributes: @@ -452,6 +450,12 @@ A \code{TarInfo} object has the following public data attributes: Group name. \end{memberdesc} +\begin{memberdesc}{pax_headers} + A dictionary containing key-value pairs of an associated pax + extended header. + \versionadded{2.6} +\end{memberdesc} + A \class{TarInfo} object also provides some convenient query methods: \begin{methoddesc}{isfile}{} @@ -554,3 +558,103 @@ for tarinfo in tar: tar.extract(tarinfo) tar.close() \end{verbatim} + +%------------ +% Tar format +%------------ + +\subsection{Supported tar formats \label{tar-formats}} + +There are three tar formats that can be created with the \module{tarfile} +module: + +\begin{itemize} + +\item +The \POSIX{}.1-1988 ustar format (\constant{USTAR_FORMAT}). It supports +filenames up to a length of at best 256 characters and linknames up to 100 +characters. The maximum file size is 8 gigabytes. This is an old and limited +but widely supported format. + +\item +The GNU tar format (\constant{GNU_FORMAT}). It supports long filenames and +linknames, files bigger than 8 gigabytes and sparse files. It is the de facto +standard on GNU/Linux systems. \module{tarfile} fully supports the GNU tar +extensions for long names, sparse file support is read-only. + +\item +The \POSIX{}.1-2001 pax format (\constant{PAX_FORMAT}). It is the most +flexible format with virtually no limits. It supports long filenames and +linknames, large files and stores pathnames in a portable way. However, not +all tar implementations today are able to handle pax archives properly. + +The \emph{pax} format is an extension to the existing \emph{ustar} format. It +uses extra headers for information that cannot be stored otherwise. There are +two flavours of pax headers: Extended headers only affect the subsequent file +header, global headers are valid for the complete archive and affect all +following files. All the data in a pax header is encoded in \emph{UTF-8} for +portability reasons. + +\end{itemize} + +There are some more variants of the tar format which can be read, but not +created: + +\begin{itemize} + +\item +The ancient V7 format. This is the first tar format from \UNIX{} Seventh +Edition, storing only regular files and directories. Names must not be longer +than 100 characters, there is no user/group name information. Some archives +have miscalculated header checksums in case of fields with non-\ASCII{} +characters. + +\item +The SunOS tar extended format. This format is a variant of the \POSIX{}.1-2001 +pax format, but is not compatible. + +\end{itemize} + +%---------------- +% Unicode issues +%---------------- + +\subsection{Unicode issues \label{tar-unicode}} + +The tar format was originally conceived to make backups on tape drives with the +main focus on preserving file system information. Nowadays tar archives are +commonly used for file distribution and exchanging archives over networks. One +problem of the original format (that all other formats are merely variants of) +is that there is no concept of supporting different character encodings. +For example, an ordinary tar archive created on a \emph{UTF-8} system cannot be +read correctly on a \emph{Latin-1} system if it contains non-\ASCII{} +characters. Names (i.e. filenames, linknames, user/group names) containing +these characters will appear damaged. Unfortunately, there is no way to +autodetect the encoding of an archive. + +The pax format was designed to solve this problem. It stores non-\ASCII{} names +using the universal character encoding \emph{UTF-8}. When a pax archive is +read, these \emph{UTF-8} names are converted to the encoding of the local +file system. + +The details of unicode conversion are controlled by the \var{encoding} and +\var{errors} keyword arguments of the \class{TarFile} class. + +The default value for \var{encoding} is the local character encoding. It is +deduced from \function{sys.getfilesystemencoding()} and +\function{sys.getdefaultencoding()}. In read mode, \var{encoding} is used +exclusively to convert unicode names from a pax archive to strings in the local +character encoding. In write mode, the use of \var{encoding} depends on the +chosen archive format. In case of \constant{PAX_FORMAT}, input names that +contain non-\ASCII{} characters need to be decoded before being stored as +\emph{UTF-8} strings. The other formats do not make use of \var{encoding} +unless unicode objects are used as input names. These are converted to +8-bit character strings before they are added to the archive. + +The \var{errors} argument defines how characters are treated that cannot be +converted to or from \var{encoding}. Possible values are listed in section +\ref{codec-base-classes}. In read mode, there is an additional scheme +\code{'utf-8'} which means that bad characters are replaced by their +\emph{UTF-8} representation. This is the default scheme. In write mode the +default value for \var{errors} is \code{'strict'} to ensure that name +information is not altered unnoticed. diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex index 4554305..2b143b9 100644 --- a/Doc/lib/libtypes.tex +++ b/Doc/lib/libtypes.tex @@ -163,7 +163,7 @@ The type of \code{Ellipsis}. \begin{datadesc}{TracebackType} The type of traceback objects such as found in -\code{sys.exc_traceback}. +\code{sys.exc_info()[2]}. \end{datadesc} \begin{datadesc}{FrameType} diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex index 041e3dd..146ba7f 100644 --- a/Doc/lib/libundoc.tex +++ b/Doc/lib/libundoc.tex @@ -88,7 +88,6 @@ installing the shared object if using dynamically-loaded extensions. % XXX need Windows instructions! \begin{description} -\item[\module{timing}] ---- Measure time intervals to high resolution (use \function{time.clock()} - instead). +\item +--- This section should be empty for Python 3.0. \end{description} diff --git a/Doc/lib/libzipimport.tex b/Doc/lib/libzipimport.tex index 098e788..8ebe3c5 100644 --- a/Doc/lib/libzipimport.tex +++ b/Doc/lib/libzipimport.tex @@ -29,11 +29,6 @@ by adding the corresponding \file{.pyc} or \file{.pyo} file, meaning that if a ZIP archive doesn't contain \file{.pyc} files, importing may be rather slow. -Using the built-in \function{reload()} function will -fail if called on a module loaded from a ZIP archive; it is unlikely that -\function{reload()} would be needed, since this would imply that the ZIP -has been altered during runtime. - The available attributes of this module are: \begin{excdesc}{ZipImportError} |