diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Makefile.deps | 1 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libitertools.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libos.tex | 65 | ||||
| -rw-r--r-- | Doc/lib/libpopen2.tex | 190 | ||||
| -rw-r--r-- | Doc/lib/libsubprocess.tex | 67 | ||||
| -rw-r--r-- | Doc/ref/ref3.tex | 5 | ||||
| -rw-r--r-- | Doc/ref/ref5.tex | 9 | ||||
| -rw-r--r-- | Doc/ref/ref7.tex | 38 | ||||
| -rw-r--r-- | Doc/tut/tut.tex | 10 |
10 files changed, 38 insertions, 350 deletions
diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps index 96800ac..49c05f4 100644 --- a/Doc/Makefile.deps +++ b/Doc/Makefile.deps @@ -270,7 +270,6 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \ lib/libimaplib.tex \ lib/libpoplib.tex \ lib/libcalendar.tex \ - lib/libpopen2.tex \ lib/libbisect.tex \ lib/libcollections.tex \ lib/libheapq.tex \ diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 05d84c3..c9cf38d 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -280,7 +280,6 @@ and how to embed it in other applications. \input{libsubprocess} \input{libsocket} \input{libsignal} -\input{libpopen2} \input{libasyncore} \input{libasynchat} diff --git a/Doc/lib/libitertools.tex b/Doc/lib/libitertools.tex index 681738d..9bf8ab0 100644 --- a/Doc/lib/libitertools.tex +++ b/Doc/lib/libitertools.tex @@ -459,7 +459,7 @@ Mark # is differencing with a range so that consecutive numbers all appear in # same group. >>> data = [ 1, 4,5,6, 10, 15,16,17,18, 22, 25,26,27,28] ->>> for k, g in groupby(enumerate(data), lambda (i,x):i-x): +>>> for k, g in groupby(enumerate(data), lambda t:t[0]-t[1]): ... print map(operator.itemgetter(1), g) ... [1] diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex index 2454e57..826e9fa 100644 --- a/Doc/lib/libos.tex +++ b/Doc/lib/libos.tex @@ -378,68 +378,6 @@ deleted once there are no file descriptors for the file. Availability: Macintosh, \UNIX, Windows. \end{funcdesc} -There are a number of different \function{popen*()} functions that -provide slightly different ways to create subprocesses. -\deprecated{2.6}{All of the \function{popen*()} functions are obsolete. - Use the \module{subprocess} module.} - -For each of the \function{popen*()} variants, if \var{bufsize} is -specified, it specifies the buffer size for the I/O pipes. -\var{mode}, if provided, should be the string \code{'b'} or -\code{'t'}; on Windows this is needed to determine whether the file -objects should be opened in binary or text mode. The default value -for \var{mode} is \code{'t'}. - -Also, for each of these variants, on \UNIX, \var{cmd} may be a sequence, in -which case arguments will be passed directly to the program without shell -intervention (as with \function{os.spawnv()}). If \var{cmd} is a string it will -be passed to the shell (as with \function{os.system()}). - -These methods do not make it possible to retrieve the exit status from -the child processes. The only way to control the input and output -streams and also retrieve the return codes is to use the -\refmodule{subprocess} module; these are only available on \UNIX. - -For a discussion of possible deadlock conditions related to the use -of these functions, see ``\ulink{Flow Control -Issues}{popen2-flow-control.html}'' -(section~\ref{popen2-flow-control}). - -\begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}} -Executes \var{cmd} as a sub-process. Returns the file objects -\code{(\var{child_stdin}, \var{child_stdout})}. -\deprecated{2.6}{All of the \function{popen*()} functions are obsolete. - Use the \module{subprocess} module.} -Availability: Macintosh, \UNIX, Windows. -\versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}} -Executes \var{cmd} as a sub-process. Returns the file objects -\code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}. -\deprecated{2.6}{All of the \function{popen*()} functions are obsolete. - Use the \module{subprocess} module.} -Availability: Macintosh, \UNIX, Windows. -\versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}} -Executes \var{cmd} as a sub-process. Returns the file objects -\code{(\var{child_stdin}, \var{child_stdout_and_stderr})}. -\deprecated{2.6}{All of the \function{popen*()} functions are obsolete. - Use the \module{subprocess} module.} -Availability: Macintosh, \UNIX, Windows. -\versionadded{2.0} -\end{funcdesc} - -(Note that \code{\var{child_stdin}, \var{child_stdout}, and -\var{child_stderr}} are named from the point of view of the child -process, so \var{child_stdin} is the child's standard input.) - -This functionality is also available in the \refmodule{popen2} module -using functions of the same names, but the return values of those -functions have a different order. - \subsection{File Descriptor Operations \label{os-fd-ops}} @@ -1575,9 +1513,6 @@ Availability: Macintosh, \UNIX. \end{funcdesc} \begin{funcdescni}{popen}{\unspecified} -\funclineni{popen2}{\unspecified} -\funclineni{popen3}{\unspecified} -\funclineni{popen4}{\unspecified} Run child processes, returning opened pipes for communications. These functions are described in section \ref{os-newstreams}. \end{funcdescni} diff --git a/Doc/lib/libpopen2.tex b/Doc/lib/libpopen2.tex deleted file mode 100644 index 5d40e1a..0000000 --- a/Doc/lib/libpopen2.tex +++ /dev/null @@ -1,190 +0,0 @@ -\section{\module{popen2} --- - Subprocesses with accessible I/O streams} - -\declaremodule{standard}{popen2} -\modulesynopsis{Subprocesses with accessible standard I/O streams.} -\sectionauthor{Drew Csillag}{drew_csillag@geocities.com} - -\deprecated{2.6}{This module is obsolete. Use the \module{subprocess} module.} - -This module allows you to spawn processes and connect to their -input/output/error pipes and obtain their return codes under -\UNIX{} and Windows. - -The \module{subprocess} module provides more powerful facilities for -spawning new processes and retrieving their results. Using the -\module{subprocess} module is preferable to using the \module{popen2} -module. - -The primary interface offered by this module is a trio of factory -functions. For each of these, if \var{bufsize} is specified, -it specifies the buffer size for the I/O pipes. \var{mode}, if -provided, should be the string \code{'b'} or \code{'t'}; on Windows -this is needed to determine whether the file objects should be opened -in binary or text mode. The default value for \var{mode} is -\code{'t'}. - -On \UNIX, \var{cmd} may be a sequence, in which case arguments will be passed -directly to the program without shell intervention (as with -\function{os.spawnv()}). If \var{cmd} is a string it will be passed to the -shell (as with \function{os.system()}). - -The only way to retrieve the return codes for the child processes is -by using the \method{poll()} or \method{wait()} methods on the -\class{Popen3} and \class{Popen4} classes; these are only available on -\UNIX. This information is not available when using the -\function{popen2()}, \function{popen3()}, and \function{popen4()} -functions, or the equivalent functions in the \refmodule{os} module. -(Note that the tuples returned by the \refmodule{os} module's functions -are in a different order from the ones returned by the \module{popen2} -module.) - -\begin{funcdesc}{popen2}{cmd\optional{, bufsize\optional{, mode}}} -Executes \var{cmd} as a sub-process. Returns the file objects -\code{(\var{child_stdout}, \var{child_stdin})}. -\end{funcdesc} - -\begin{funcdesc}{popen3}{cmd\optional{, bufsize\optional{, mode}}} -Executes \var{cmd} as a sub-process. Returns the file objects -\code{(\var{child_stdout}, \var{child_stdin}, \var{child_stderr})}. -\end{funcdesc} - -\begin{funcdesc}{popen4}{cmd\optional{, bufsize\optional{, mode}}} -Executes \var{cmd} as a sub-process. Returns the file objects -\code{(\var{child_stdout_and_stderr}, \var{child_stdin})}. -\versionadded{2.0} -\end{funcdesc} - - -On \UNIX, a class defining the objects returned by the factory -functions is also available. These are not used for the Windows -implementation, and are not available on that platform. - -\begin{classdesc}{Popen3}{cmd\optional{, capturestderr\optional{, bufsize}}} -This class represents a child process. Normally, \class{Popen3} -instances are created using the \function{popen2()} and -\function{popen3()} factory functions described above. - -If not using one of the helper functions to create \class{Popen3} -objects, the parameter \var{cmd} is the shell command to execute in a -sub-process. The \var{capturestderr} flag, if true, specifies that -the object should capture standard error output of the child process. -The default is false. If the \var{bufsize} parameter is specified, it -specifies the size of the I/O buffers to/from the child process. -\end{classdesc} - -\begin{classdesc}{Popen4}{cmd\optional{, bufsize}} -Similar to \class{Popen3}, but always captures standard error into the -same file object as standard output. These are typically created -using \function{popen4()}. -\versionadded{2.0} -\end{classdesc} - -\subsection{Popen3 and Popen4 Objects \label{popen3-objects}} - -Instances of the \class{Popen3} and \class{Popen4} classes have the -following methods: - -\begin{methoddesc}[Popen3]{poll}{} -Returns \code{-1} if child process hasn't completed yet, or its return -code otherwise. -\end{methoddesc} - -\begin{methoddesc}[Popen3]{wait}{} -Waits for and returns the status code of the child process. The -status code encodes both the return code of the process and -information about whether it exited using the \cfunction{exit()} -system call or died due to a signal. Functions to help interpret the -status code are defined in the \refmodule{os} module; see section -\ref{os-process} for the \function{W\var{*}()} family of functions. -\end{methoddesc} - - -The following attributes are also available: - -\begin{memberdesc}[Popen3]{fromchild} -A file object that provides output from the child process. For -\class{Popen4} instances, this will provide both the standard output -and standard error streams. -\end{memberdesc} - -\begin{memberdesc}[Popen3]{tochild} -A file object that provides input to the child process. -\end{memberdesc} - -\begin{memberdesc}[Popen3]{childerr} -A file object that provides error output from the child process, if -\var{capturestderr} was true for the constructor, otherwise -\code{None}. This will always be \code{None} for \class{Popen4} -instances. -\end{memberdesc} - -\begin{memberdesc}[Popen3]{pid} -The process ID of the child process. -\end{memberdesc} - - -\subsection{Flow Control Issues \label{popen2-flow-control}} - -Any time you are working with any form of inter-process communication, -control flow needs to be carefully thought out. This remains the case -with the file objects provided by this module (or the \refmodule{os} -module equivalents). - -% Example explanation and suggested work-arounds substantially stolen -% from Martin von Löwis: -% http://mail.python.org/pipermail/python-dev/2000-September/009460.html - -When reading output from a child process that writes a lot of data to -standard error while the parent is reading from the child's standard -output, a deadlock can occur. A similar situation can occur with other -combinations of reads and writes. The essential factors are that more -than \constant{_PC_PIPE_BUF} bytes are being written by one process in -a blocking fashion, while the other process is reading from the other -process, also in a blocking fashion. - -There are several ways to deal with this situation. - -The simplest application change, in many cases, will be to follow this -model in the parent process: - -\begin{verbatim} -import popen2 - -r, w, e = popen2.popen3('python slave.py') -e.readlines() -r.readlines() -r.close() -e.close() -w.close() -\end{verbatim} - -with code like this in the child: - -\begin{verbatim} -import os -import sys - -# note that each of these print statements -# writes a single long string - -print >>sys.stderr, 400 * 'this is a test\n' -os.close(sys.stderr.fileno()) -print >>sys.stdout, 400 * 'this is another test\n' -\end{verbatim} - -In particular, note that \code{sys.stderr} must be closed after -writing all data, or \method{readlines()} won't return. Also note -that \function{os.close()} must be used, as \code{sys.stderr.close()} -won't close \code{stderr} (otherwise assigning to \code{sys.stderr} -will silently close it, so no further errors can be printed). - -Applications which need to support a more general approach should -integrate I/O over pipes with their \function{select()} loops, or use -separate threads to read each of the individual files provided by -whichever \function{popen*()} function or \class{Popen*} class was -used. - -\begin{seealso} - \seemodule{subprocess}{Module for spawning and managing subprocesses.} -\end{seealso} diff --git a/Doc/lib/libsubprocess.tex b/Doc/lib/libsubprocess.tex index 4a57350..35ab4d0 100644 --- a/Doc/lib/libsubprocess.tex +++ b/Doc/lib/libsubprocess.tex @@ -15,8 +15,6 @@ and functions, such as: \begin{verbatim} os.system os.spawn* -os.popen* -popen2.* commands.* \end{verbatim} @@ -335,68 +333,3 @@ pipe = os.popen(cmd, mode='w', bufsize) ==> pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin \end{verbatim} - -\begin{verbatim} -(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize) -==> -p = Popen(cmd, shell=True, bufsize=bufsize, - stdin=PIPE, stdout=PIPE, close_fds=True) -(child_stdin, child_stdout) = (p.stdin, p.stdout) -\end{verbatim} - -\begin{verbatim} -(child_stdin, - child_stdout, - child_stderr) = os.popen3(cmd, mode, bufsize) -==> -p = Popen(cmd, shell=True, bufsize=bufsize, - stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True) -(child_stdin, - child_stdout, - child_stderr) = (p.stdin, p.stdout, p.stderr) -\end{verbatim} - -\begin{verbatim} -(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize) -==> -p = Popen(cmd, shell=True, bufsize=bufsize, - stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True) -(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout) -\end{verbatim} - -\subsubsection{Replacing popen2.*} - -\note{If the cmd argument to popen2 functions is a string, the command -is executed through /bin/sh. If it is a list, the command is directly -executed.} - -\begin{verbatim} -(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode) -==> -p = Popen(["somestring"], shell=True, bufsize=bufsize, - stdin=PIPE, stdout=PIPE, close_fds=True) -(child_stdout, child_stdin) = (p.stdout, p.stdin) -\end{verbatim} - -\begin{verbatim} -(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode) -==> -p = Popen(["mycmd", "myarg"], bufsize=bufsize, - stdin=PIPE, stdout=PIPE, close_fds=True) -(child_stdout, child_stdin) = (p.stdout, p.stdin) -\end{verbatim} - -The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen, -except that: - -\begin{itemize} -\item subprocess.Popen raises an exception if the execution fails - -\item the \var{capturestderr} argument is replaced with the \var{stderr} - argument. - -\item stdin=PIPE and stdout=PIPE must be specified. - -\item popen2 closes all file descriptors by default, but you have to - specify close_fds=True with subprocess.Popen. -\end{itemize} diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex index 3f82a8c..d8cf888 100644 --- a/Doc/ref/ref3.tex +++ b/Doc/ref/ref3.tex @@ -498,8 +498,9 @@ Special attributes: \lineiii{__closure__}{\code{None} or a tuple of cells that contain bindings for the function's free variables.}{Read-only} - \lineiii{__annotations__}{A dict containing annotations of parameters.} - {Writable} + \lineiii{__annotations__}{A dict containing annotations of parameters. + The keys of the dict are the parameter names, or \code{'return'} + for the return annotation, if provided.}{Writable} \lineiii{__kwdefaults__}{A dict containing defaults for keyword-only parameters.}{Writable} diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex index 9a4fe3a..2420f66 100644 --- a/Doc/ref/ref5.tex +++ b/Doc/ref/ref5.tex @@ -668,11 +668,7 @@ raised. Formal parameters using the syntax \samp{*identifier} or \samp{**identifier} cannot be used as positional argument slots or -as keyword argument names. Formal parameters using the syntax -\samp{(sublist)} cannot be used as keyword argument names; the -outermost sublist corresponds to a single unnamed argument slot, and -the argument value is assigned to the sublist using the usual tuple -assignment rules after all other parameter processing is done. +as keyword argument names. A call always returns some value, possibly \code{None}, unless it raises an exception. How this value is computed depends on the type @@ -1177,7 +1173,8 @@ def name(arguments): \end{verbatim} See section \ref{function} for the syntax of parameter lists. Note -that functions created with lambda forms cannot contain statements. +that functions created with lambda forms cannot contain statements +or annotations. \label{lambda} \section{Expression lists\label{exprlists}} diff --git a/Doc/ref/ref7.tex b/Doc/ref/ref7.tex index 02f96a4..9294557 100644 --- a/Doc/ref/ref7.tex +++ b/Doc/ref/ref7.tex @@ -381,6 +381,7 @@ section~\ref{types}): \begin{productionlist} \production{funcdef} {[\token{decorators}] "def" \token{funcname} "(" [\token{parameter_list}] ")" + ["->" \token{expression}]? ":" \token{suite}} \production{decorators} {\token{decorator}+} @@ -390,15 +391,14 @@ section~\ref{types}): {\token{identifier} ("." \token{identifier})*} \production{parameter_list} {(\token{defparameter} ",")*} - \productioncont{(~~"*" \token{identifier} [, "**" \token{identifier}]} - \productioncont{ | "**" \token{identifier}} + \productioncont{(~~"*" [\token{parameter}] ("," \token{defparameter})*} + \productioncont{ [, "**" \token{parameter}]} + \productioncont{ | "**" \token{parameter}} \productioncont{ | \token{defparameter} [","] )} + \production{parameter} + {\token{identifier} [":" \token{expression}]} \production{defparameter} {\token{parameter} ["=" \token{expression}]} - \production{sublist} - {\token{parameter} ("," \token{parameter})* [","]} - \production{parameter} - {\token{identifier} | "(" \token{sublist} ")"} \production{funcname} {\token{identifier}} \end{productionlist} @@ -435,14 +435,14 @@ def func(): pass func = f1(arg)(f2(func)) \end{verbatim} -When one or more top-level parameters have the form \var{parameter} +When one or more parameters have the form \var{parameter} \code{=} \var{expression}, the function is said to have ``default parameter values.'' For a parameter with a default value, the corresponding argument may be omitted from a call, in which case the parameter's default value is substituted. If a -parameter has a default value, all following parameters must also have -a default value --- this is a syntactic restriction that is not -expressed by the grammar. +parameter has a default value, all following parameters up until the +``\code{*}'' must also have a default value --- this is a syntactic +restriction that is not expressed by the grammar. \indexiii{default}{parameter}{value} \strong{Default parameter values are evaluated when the function @@ -473,7 +473,21 @@ is present, it is initialized to a tuple receiving any excess positional parameters, defaulting to the empty tuple. If the form ``\code{**identifier}'' is present, it is initialized to a new dictionary receiving any excess keyword arguments, defaulting to a -new empty dictionary. +new empty dictionary. Parameters after ``\code{*}'' or ``\code{*identifier}'' +are keyword-only parameters and may only be passed used keyword arguments. + +Parameters may have annotations of the form ``\code{: expression}'' +following the parameter name. Any parameter may have an annotation even +those of the form \code{*identifier} or \code{**identifier}. +Functions may have ``return'' annotation of the form ``\code{-> expression}'' +after the parameter list. These annotations can be any valid Python +expression and are evaluated when the function definition is executed. +Annotations may be evaluated in a different order than they appear in the +source code. The presence of annotations does not change the semantics of a +function. The annotation values are available as values of a dictionary +keyed by the parameters' names in the \member{__annotations__} +attribute of the function object. +\indexii{function}{annotations} It is also possible to create anonymous functions (functions not bound to a name), for immediate use in expressions. This uses lambda forms, @@ -482,7 +496,7 @@ merely a shorthand for a simplified function definition; a function defined in a ``\keyword{def}'' statement can be passed around or assigned to another name just like a function defined by a lambda form. The ``\keyword{def}'' form is actually more powerful since it -allows the execution of multiple statements. +allows the execution of multiple statements and annotations. \indexii{lambda}{form} \strong{Programmer's note:} Functions are first-class objects. A diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex index df6f351..6cd1bcc 100644 --- a/Doc/tut/tut.tex +++ b/Doc/tut/tut.tex @@ -184,12 +184,12 @@ your local Python guru or system administrator. (E.g., \file{/usr/local/python} is a popular alternative location.) On Windows machines, the Python installation is usually placed in -\file{C:\e Python26}, though you can change this when you're running +\file{C:\e Python30}, though you can change this when you're running the installer. To add this directory to your path, you can type the following command into the command prompt in a DOS box: \begin{verbatim} -set path=%path%;C:\python26 +set path=%path%;C:\python30 \end{verbatim} @@ -3539,7 +3539,7 @@ as desired. ... print 'x =', x ... print 'y =', y ... -<type 'exceptions.Exception'> +<type 'Exception'> ('spam', 'eggs') ('spam', 'eggs') x = spam @@ -4638,7 +4638,7 @@ operating system: >>> os.system('time 0:02') 0 >>> os.getcwd() # Return the current working directory -'C:\\Python26' +'C:\\Python30' >>> os.chdir('/server/accesslogs') \end{verbatim} @@ -5243,7 +5243,7 @@ applications include caching objects that are expensive to create: Traceback (most recent call last): File "<pyshell#108>", line 1, in -toplevel- d['primary'] # entry was automatically removed - File "C:/python26/lib/weakref.py", line 46, in __getitem__ + File "C:/python30/lib/weakref.py", line 46, in __getitem__ o = self.data[key]() KeyError: 'primary' \end{verbatim} |