diff options
Diffstat (limited to 'Doc/lib')
| -rwxr-xr-x | Doc/lib/libctypes.tex | 4 | ||||
| -rw-r--r-- | Doc/lib/libdecimal.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libexcs.tex | 20 | ||||
| -rw-r--r-- | Doc/lib/libftplib.tex | 3 | ||||
| -rw-r--r-- | Doc/lib/libfuncs.tex | 23 | ||||
| -rw-r--r-- | Doc/lib/libhttplib.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libpoplib.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libsmtplib.tex | 4 | ||||
| -rw-r--r-- | Doc/lib/libsocket.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libtelnetlib.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libthreading.tex | 64 | ||||
| -rw-r--r-- | Doc/lib/liburllib2.tex | 19 |
12 files changed, 94 insertions, 52 deletions
diff --git a/Doc/lib/libctypes.tex b/Doc/lib/libctypes.tex index f19507a..346863d 100755 --- a/Doc/lib/libctypes.tex +++ b/Doc/lib/libctypes.tex @@ -437,8 +437,8 @@ You should be careful, however, not to pass them to functions expecting pointers to mutable memory. If you need mutable memory blocks, ctypes has a \code{create{\_}string{\_}buffer} function which creates these in various ways. The current memory block contents can be -accessed (or changed) with the \code{raw} property, if you want to access -it as NUL terminated string, use the \code{string} property: +accessed (or changed) with the \code{raw} property; if you want to access +it as NUL terminated string, use the \code{value} property: \begin{verbatim} >>> from ctypes import * >>> p = create_string_buffer(3) # create a 3 byte buffer, initialized to NUL bytes diff --git a/Doc/lib/libdecimal.tex b/Doc/lib/libdecimal.tex index a0a257e..8c665da 100644 --- a/Doc/lib/libdecimal.tex +++ b/Doc/lib/libdecimal.tex @@ -845,7 +845,7 @@ exception is raised upon encountering the condition. The following table summarizes the hierarchy of signals: \begin{verbatim} - exceptions.ArithmeticError(exceptions.StandardError) + exceptions.ArithmeticError(exceptions.Exception) DecimalException Clamped DivisionByZero(DecimalException, exceptions.ZeroDivisionError) diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex index 631c798..298f04d 100644 --- a/Doc/lib/libexcs.tex +++ b/Doc/lib/libexcs.tex @@ -64,13 +64,6 @@ from this class. \versionchanged[Changed to inherit from \exception{BaseException}]{2.5} \end{excdesc} -\begin{excdesc}{StandardError} -The base class for all built-in exceptions except -\exception{StopIteration}, \exception{GeneratorExit}, -\exception{KeyboardInterrupt} and \exception{SystemExit}. -\exception{StandardError} itself is derived from \exception{Exception}. -\end{excdesc} - \begin{excdesc}{ArithmeticError} The base class for those built-in exceptions that are raised for various arithmetic errors: \exception{OverflowError}, @@ -143,9 +136,9 @@ Raised when an \keyword{assert} statement fails. \begin{excdesc}{GeneratorExit} Raise when a generator's \method{close()} method is called. - It directly inherits from \exception{Exception} instead of - \exception{StandardError} since it is technically not an error. \versionadded{2.5} + \versionchanged[Changed to inherit from Exception instead of + StandardError]{3.0} \end{excdesc} \begin{excdesc}{IOError} @@ -257,10 +250,9 @@ Raised when an \keyword{assert} statement fails. \begin{excdesc}{StopIteration} Raised by builtin \function{next()} and an iterator's \method{__next__()} method to signal that there are no further values. - This is derived from \exception{Exception} rather than - \exception{StandardError}, since this is not considered an error in - its normal application. \versionadded{2.2} + \versionchanged[Changed to inherit from Exception instead of + StandardError]{3.0} \end{excdesc} @@ -304,7 +296,7 @@ Raised when an \keyword{assert} statement fails. Instances have an attribute \member{code} which is set to the proposed exit status or error message (defaulting to \code{None}). Also, this exception derives directly from \exception{BaseException} and - not \exception{StandardError}, since it is not technically an error. + not \exception{Exception}, since it is not technically an error. A call to \function{sys.exit()} is translated into an exception so that clean-up handlers (\keyword{finally} clauses of \keyword{try} statements) @@ -315,7 +307,7 @@ Raised when an \keyword{assert} statement fails. \function{fork()}). The exception inherits from \exception{BaseException} instead of - \exception{StandardError} or \exception{Exception} so that it is not + \exception{Exception} so that it is not accidentally caught by code that catches \exception{Exception}. This allows the exception to properly propagate up and cause the interpreter to exit. \versionchanged[Changed to inherit from \exception{BaseException}]{2.5} diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex index 98d7e80..1ce5f9b 100644 --- a/Doc/lib/libftplib.tex +++ b/Doc/lib/libftplib.tex @@ -46,6 +46,7 @@ made. When \var{user} is given, additionally the method call The optional \var{timeout} parameter specifies a timeout in seconds for the connection attempt (if is not specified, or passed as None, the global default timeout setting will be used). +\versionchanged[\var{timeout} was added]{2.6} \end{classdesc} \begin{datadesc}{all_errors} @@ -117,6 +118,8 @@ the connection attempt. If is not specified, or passed as None, the object timeout is used (the timeout that you passed when instantiating the class); if the object timeout is also None, the global default timeout setting will be used. + +\versionchanged[\var{timeout} was added]{2.6} \end{methoddesc} \begin{methoddesc}[FTP]{getwelcome}{} diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex index 4f49e33..3cc06c8 100644 --- a/Doc/lib/libfuncs.tex +++ b/Doc/lib/libfuncs.tex @@ -104,6 +104,14 @@ def my_import(name): \versionadded{2.3} \end{funcdesc} +\begin{funcdesc}{bin}{x} + Convert an integer number to a binary string. + The result is a valid Python expression. If \var{x} is not a Python + \class{int} object, it has to define an \method{__index__} method + that returns an integer. + \versionadded{3.0} +\end{funcdesc} + \begin{funcdesc}{bool}{\optional{x}} Convert a value to a Boolean, using the standard truth testing procedure. If \var{x} is false or omitted, this returns @@ -540,8 +548,10 @@ class C: \end{funcdesc} \begin{funcdesc}{hex}{x} - Convert an integer number (of any size) to a hexadecimal string. - The result is a valid Python expression. + Convert an integer number to a hexadecimal string. + The result is a valid Python expression. If \var{x} is not a Python + \class{int} object, it has to define an \method{__index__} method + that returns an integer. \versionchanged[Formerly only returned an unsigned literal]{2.4} \end{funcdesc} @@ -559,8 +569,7 @@ class C: representable as a Python integer, possibly embedded in whitespace. The \var{radix} parameter gives the base for the conversion and may be any integer in the range [2, 36], or zero. If - \var{radix} is zero, the proper radix is guessed based on the - contents of string; the interpretation is the same as for integer + \var{radix} is zero, the interpretation is the same as for integer literals. If \var{radix} is specified and \var{x} is not a string, \exception{TypeError} is raised. Otherwise, the argument may be a plain or @@ -707,8 +716,10 @@ class C: \end{funcdesc} \begin{funcdesc}{oct}{x} - Convert an integer number (of any size) to an octal string. The - result is a valid Python expression. + Convert an integer number to an octal string. The + result is a valid Python expression. If \var{x} is not a Python + \class{int} object, it has to define an \method{__index__} method + that returns an integer. \versionchanged[Formerly only returned an unsigned literal]{2.4} \end{funcdesc} diff --git a/Doc/lib/libhttplib.tex b/Doc/lib/libhttplib.tex index 7c9449d..37a442d 100644 --- a/Doc/lib/libhttplib.tex +++ b/Doc/lib/libhttplib.tex @@ -49,6 +49,7 @@ the server at the same host and port: >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10) \end{verbatim} \versionadded{2.0} +\versionchanged[\var{timeout} was added]{2.6} \end{classdesc} \begin{classdesc}{HTTPSConnection}{host\optional{, port\optional{, @@ -63,6 +64,7 @@ key. \var{cert_file} is a PEM formatted certificate chain file. \warning{This does not do any certificate verification!} \versionadded{2.0} +\versionchanged[\var{timeout} was added]{2.6} \end{classdesc} \begin{classdesc}{HTTPResponse}{sock\optional{, debuglevel=0}\optional{, strict=0}} diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex index 7b2c4a1..9ca5bbd 100644 --- a/Doc/lib/libpoplib.tex +++ b/Doc/lib/libpoplib.tex @@ -35,6 +35,8 @@ If \var{port} is omitted, the standard POP3 port (110) is used. The optional \var{timeout} parameter specifies a timeout in seconds for the connection attempt (if not specified, or passed as None, the global default timeout setting will be used). + +\versionchanged[\var{timeout} was added]{2.6} \end{classdesc} \begin{classdesc}{POP3_SSL}{host\optional{, port\optional{, keyfile\optional{, certfile}}}} diff --git a/Doc/lib/libsmtplib.tex b/Doc/lib/libsmtplib.tex index 26293d6..1c034e7 100644 --- a/Doc/lib/libsmtplib.tex +++ b/Doc/lib/libsmtplib.tex @@ -29,6 +29,8 @@ default timeout setting will be used). For normal use, you should only require the initialization/connect, \method{sendmail()}, and \method{quit()} methods. An example is included below. + +\versionchanged[\var{timeout} was added]{2.6} \end{classdesc} \begin{classdesc}{SMTP_SSL}{\optional{host\optional{, port\optional{, @@ -45,6 +47,8 @@ certificate chain file for the SSL connection. The optional \var{timeout} parameter specifies a timeout in seconds for the connection attempt (if not specified, or passed as None, the global default timeout setting will be used). + +\versionchanged[\var{timeout} was added]{2.6} \end{classdesc} \begin{classdesc}{LMTP}{\optional{host\optional{, port\optional{, diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex index ff0fb87..e3fce23 100644 --- a/Doc/lib/libsocket.tex +++ b/Doc/lib/libsocket.tex @@ -177,6 +177,7 @@ higher-level protocols, it is not normally used directly from application-level code. Passing the optional \var{timeout} parameter will set the timeout on the socket instance (if it is not given or \code{None}, the global default timeout setting is used). +\versionadded{2.6} \end{funcdesc} \begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{, diff --git a/Doc/lib/libtelnetlib.tex b/Doc/lib/libtelnetlib.tex index 269ee9b..853788f 100644 --- a/Doc/lib/libtelnetlib.tex +++ b/Doc/lib/libtelnetlib.tex @@ -40,6 +40,7 @@ This class has many \method{read_*()} methods. Note that some of them raise \exception{EOFError} when the end of the connection is read, because they can return an empty string for other reasons. See the individual descriptions below. +\versionchanged[\var{timeout} was added]{2.6} \end{classdesc} @@ -123,6 +124,7 @@ connection attempt (if not specified, or passed as None, the global default timeout setting will be used). Do not try to reopen an already connected instance. +\versionchanged[\var{timeout} was added]{2.6} \end{methoddesc} \begin{methoddesc}[Telnet]{msg}{msg\optional{, *args}} diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex index 522ea2f..19c496e 100644 --- a/Doc/lib/libthreading.tex +++ b/Doc/lib/libthreading.tex @@ -174,11 +174,14 @@ until a call to \method{release()} in another thread changes it to unlocked, then the \method{acquire()} call resets it to locked and returns. The \method{release()} method should only be called in the locked state; it changes the state to unlocked and returns -immediately. When more than one thread is blocked in -\method{acquire()} waiting for the state to turn to unlocked, only one -thread proceeds when a \method{release()} call resets the state to -unlocked; which one of the waiting threads proceeds is not defined, -and may vary across implementations. +immediately. If an attempt is made to release an unlocked lock, a +\exception{RuntimeError} will be raised. + +When more than one thread is blocked in \method{acquire()} waiting for +the state to turn to unlocked, only one thread proceeds when a +\method{release()} call resets the state to unlocked; which one of the +waiting threads proceeds is not defined, and may vary across +implementations. All methods are executed atomically. @@ -257,8 +260,9 @@ become unlocked, allow exactly one of them to proceed. If after the decrement the recursion level is still nonzero, the lock remains locked and owned by the calling thread. -Only call this method when the calling thread owns the lock. -Do not call this method when the lock is unlocked. +Only call this method when the calling thread owns the lock. A +\exception{RuntimeError} is raised if this method is called when the +lock is unlocked. There is no return value. \end{methoddesc} @@ -275,7 +279,8 @@ A condition variable has \method{acquire()} and \method{release()} methods that call the corresponding methods of the associated lock. It also has a \method{wait()} method, and \method{notify()} and \method{notifyAll()} methods. These three must only be called when -the calling thread has acquired the lock. +the calling thread has acquired the lock, otherwise a +\exception{RuntimeError} is raised. The \method{wait()} method releases the lock, and then blocks until it is awakened by a \method{notify()} or \method{notifyAll()} call for @@ -343,9 +348,9 @@ lock; there is no return value. \end{methoddesc} \begin{methoddesc}{wait}{\optional{timeout}} -Wait until notified or until a timeout occurs. -This must only be called when the calling thread has acquired the -lock. +Wait until notified or until a timeout occurs. If the calling thread +has not acquired the lock when this method is called, a +\exception{RuntimeError} is raised. This method releases the underlying lock, and then blocks until it is awakened by a \method{notify()} or \method{notifyAll()} call for the @@ -367,9 +372,10 @@ when the lock is reacquired. \end{methoddesc} \begin{methoddesc}{notify}{} -Wake up a thread waiting on this condition, if any. -This must only be called when the calling thread has acquired the -lock. +Wake up a thread waiting on this condition, if any. Wait until +notified or until a timeout occurs. If the calling thread has not +acquired the lock when this method is called, a +\exception{RuntimeError} is raised. This method wakes up one of the threads waiting for the condition variable, if any are waiting; it is a no-op if no threads are waiting. @@ -386,7 +392,9 @@ Note: the awakened thread does not actually return from its \begin{methoddesc}{notifyAll}{} Wake up all threads waiting on this condition. This method acts like -\method{notify()}, but wakes up all waiting threads instead of one. +\method{notify()}, but wakes up all waiting threads instead of one. If +the calling thread has not acquired the lock when this method is +called, a \exception{RuntimeError} is raised. \end{methoddesc} @@ -404,8 +412,9 @@ finds that it is zero, it blocks, waiting until some other thread calls \method{release()}. \begin{classdesc}{Semaphore}{\optional{value}} -The optional argument gives the initial value for the internal -counter; it defaults to \code{1}. +The optional argument gives the initial \var{value} for the internal +counter; it defaults to \code{1}. If the \var{value} given is less +than 0, \exception{ValueError} is raised. \end{classdesc} \begin{methoddesc}{acquire}{\optional{blocking}} @@ -586,9 +595,12 @@ before doing anything else to the thread. \begin{methoddesc}{start}{} Start the thread's activity. -This must be called at most once per thread object. It -arranges for the object's \method{run()} method to be invoked in a -separate thread of control. +It must be called at most once per thread object. It arranges for the +object's \method{run()} method to be invoked in a separate thread of +control. + +This method will raise a \exception{RuntimeException} if called more +than once on the same thread object. \end{methoddesc} \begin{methoddesc}{run}{} @@ -618,11 +630,10 @@ operation will block until the thread terminates. A thread can be \method{join()}ed many times. -A thread cannot join itself because this would cause a -deadlock. - -It is an error to attempt to \method{join()} a thread before it has -been started. +\method{join()} may throw a \exception{RuntimeError}, if an attempt is +made to join the current thread as that would cause a deadlock. It is +also an error to \method{join()} a thread before it has been started +and attempts to do so raises same exception. \end{methoddesc} \begin{methoddesc}{getName}{} @@ -651,7 +662,8 @@ Return the thread's daemon flag. \begin{methoddesc}{setDaemon}{daemonic} Set the thread's daemon flag to the Boolean value \var{daemonic}. -This must be called before \method{start()} is called. +This must be called before \method{start()} is called, otherwise +\exception{RuntimeError} is raised. The initial value is inherited from the creating thread. diff --git a/Doc/lib/liburllib2.tex b/Doc/lib/liburllib2.tex index 0df7385..9d2c382 100644 --- a/Doc/lib/liburllib2.tex +++ b/Doc/lib/liburllib2.tex @@ -14,7 +14,7 @@ authentication, redirections, cookies and more. The \module{urllib2} module defines the following functions: -\begin{funcdesc}{urlopen}{url\optional{, data}} +\begin{funcdesc}{urlopen}{url\optional{, data}\optional{, timeout}} Open the URL \var{url}, which can be either a string or a \class{Request} object. @@ -27,6 +27,11 @@ parameter is provided. \var{data} should be a buffer in the standard \function{urllib.urlencode()} function takes a mapping or sequence of 2-tuples and returns a string in this format. +The optional \var{timeout} parameter specifies a timeout in seconds for the +connection attempt (if not specified, or passed as None, the global default +timeout setting will be used). This actually only work for HTTP, HTTPS, FTP +and FTPS connections. + This function returns a file-like object with two additional methods: \begin{itemize} @@ -40,6 +45,8 @@ Raises \exception{URLError} on errors. Note that \code{None} may be returned if no handler handles the request (though the default installed global \class{OpenerDirector} uses \class{UnknownHandler} to ensure this never happens). + +\versionchanged[\var{timeout} was added]{2.6} \end{funcdesc} \begin{funcdesc}{install_opener}{opener} @@ -351,12 +358,18 @@ that HTTP errors are a special case). \end{itemize} \end{methoddesc} -\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}} +\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}{\optional{, timeout}}} Open the given \var{url} (which can be a request object or a string), optionally passing the given \var{data}. Arguments, return values and exceptions raised are the same as those of \function{urlopen()} (which simply calls the \method{open()} method -on the currently installed global \class{OpenerDirector}). +on the currently installed global \class{OpenerDirector}). The optional +\var{timeout} parameter specifies a timeout in seconds for the connection +attempt (if not specified, or passed as None, the global default timeout +setting will be used; this actually only work for HTTP, HTTPS, FTP +and FTPS connections). + +\versionchanged[\var{timeout} was added]{2.6} \end{methoddesc} \begin{methoddesc}[OpenerDirector]{error}{proto\optional{, |