diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/api/exceptions.tex | 1 | ||||
| -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 | ||||
| -rw-r--r-- | Doc/ref/ref2.tex | 43 | ||||
| -rw-r--r-- | Doc/ref/ref3.tex | 12 | ||||
| -rw-r--r-- | Doc/tut/tut.tex | 54 | ||||
| -rw-r--r-- | Doc/whatsnew/whatsnew26.tex | 2 |
17 files changed, 146 insertions, 112 deletions
diff --git a/Doc/api/exceptions.tex b/Doc/api/exceptions.tex index 46ade49..01c0aaf 100644 --- a/Doc/api/exceptions.tex +++ b/Doc/api/exceptions.tex @@ -381,7 +381,6 @@ completeness, here are all the variables: \begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes} \lineiii{PyExc_BaseException\ttindex{PyExc_BaseException}}{\exception{BaseException}}{(1), (4)} \lineiii{PyExc_Exception\ttindex{PyExc_Exception}}{\exception{Exception}}{(1)} - \lineiii{PyExc_StandardError\ttindex{PyExc_StandardError}}{\exception{StandardError}}{(1)} \lineiii{PyExc_ArithmeticError\ttindex{PyExc_ArithmeticError}}{\exception{ArithmeticError}}{(1)} \lineiii{PyExc_LookupError\ttindex{PyExc_LookupError}}{\exception{LookupError}}{(1)} \lineiii{PyExc_AssertionError\ttindex{PyExc_AssertionError}}{\exception{AssertionError}}{} 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{, diff --git a/Doc/ref/ref2.tex b/Doc/ref/ref2.tex index 39b75a9..7b70676 100644 --- a/Doc/ref/ref2.tex +++ b/Doc/ref/ref2.tex @@ -565,6 +565,7 @@ number and an imaginary number). \index{floating point literal} \index{hexadecimal literal} \index{octal literal} +\index{binary literal} \index{decimal literal} \index{imaginary literal} \index{complex!literal} @@ -574,35 +575,32 @@ Note that numeric literals do not include a sign; a phrase like `\code{-}' and the literal \code{1}. -\subsection{Integer and long integer literals\label{integers}} +\subsection{Integer literals\label{integers}} -Integer and long integer literals are described by the following +Integer literals are described by the following lexical definitions: \begin{productionlist} - \production{longinteger} - {\token{integer} ("l" | "L")} \production{integer} {\token{decimalinteger} | \token{octinteger} | \token{hexinteger}} \production{decimalinteger} - {\token{nonzerodigit} \token{digit}* | "0"} + {\token{nonzerodigit} \token{digit}* | "0"+} \production{octinteger} - {"0" \token{octdigit}+} + {"0" ("o" | "O") \token{octdigit}+} \production{hexinteger} {"0" ("x" | "X") \token{hexdigit}+} + \production{bininteger} + {"0" ("b" | "B") \token{bindigit}+} \production{nonzerodigit} {"1"..."9"} \production{octdigit} {"0"..."7"} \production{hexdigit} {\token{digit} | "a"..."f" | "A"..."F"} + \production{bindigit} + {"0"..."1"} \end{productionlist} -Although both lower case \character{l} and upper case \character{L} are -allowed as suffix for long integers, it is strongly recommended to always -use \character{L}, since the letter \character{l} looks too much like the -digit \character{1}. - Plain integer literals that are above the largest representable plain integer (e.g., 2147483647 when using 32-bit arithmetic) are accepted as if they were long integers instead.\footnote{In versions of Python @@ -613,13 +611,16 @@ taken as the negative plain integer obtained by subtracting 4294967296 from their unsigned value.} There is no limit for long integer literals apart from what can be stored in available memory. -Some examples of plain integer literals (first row) and long integer -literals (second and third rows): +Note that leading zeros in a non-zero decimal number are not allowed. +This is for disambiguation with C-style octal literals, which Python +used before version 3.0. + +Some examples of integer literals: \begin{verbatim} -7 2147483647 0177 -3L 79228162514264337593543950336L 0377L 0x100000000L - 79228162514264337593543950336 0xdeadbeef +7 2147483647 0o177 0b100110111 +3 79228162514264337593543950336 0o377 0x100000000 + 79228162514264337593543950336 0xdeadbeef \end{verbatim} @@ -644,12 +645,10 @@ definitions: {("e" | "E") ["+" | "-"] \token{digit}+} \end{productionlist} -Note that the integer and exponent parts of floating point numbers -can look like octal integers, but are interpreted using radix 10. For -example, \samp{077e010} is legal, and denotes the same number -as \samp{77e10}. -The allowed range of floating point literals is -implementation-dependent. +Note that the integer and exponent parts are always interpreted using +radix 10. For example, \samp{077e010} is legal, and denotes the same +number as \samp{77e10}. +The allowed range of floating point literals is implementation-dependent. Some examples of floating point literals: \begin{verbatim} diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex index 66aa273..cced29e 100644 --- a/Doc/ref/ref3.tex +++ b/Doc/ref/ref3.tex @@ -2033,17 +2033,11 @@ and \function{float()}\bifuncindex{float}. Should return a value of the appropriate type. \end{methoddesc} -\begin{methoddesc}[numeric object]{__oct__}{self} -\methodline[numeric object]{__hex__}{self} -Called to implement the built-in functions -\function{oct()}\bifuncindex{oct} and -\function{hex()}\bifuncindex{hex}. Should return a string value. -\end{methoddesc} - \begin{methoddesc}[numeric object]{__index__}{self} Called to implement \function{operator.index()}. Also called whenever -Python needs an integer object (such as in slicing). Must return an -integer (int or long). +Python needs an integer object (such as in slicing, or in the built-in +\function{bin()}, \function{hex()} and \function{oct()} functions). +Must return an integer (int or long). \versionadded{2.5} \end{methoddesc} diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex index 4ed1b83..53a84a9 100644 --- a/Doc/tut/tut.tex +++ b/Doc/tut/tut.tex @@ -2689,7 +2689,7 @@ standard module \module{__builtin__}\refbimodindex{__builtin__}: 'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented', 'NotImplementedError', 'OSError', 'OverflowError', 'PendingDeprecationWarning', 'ReferenceError', 'RuntimeError', - 'RuntimeWarning', 'StandardError', 'StopIteration', 'SyntaxError', + 'RuntimeWarning', 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True', 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError', @@ -2734,9 +2734,9 @@ possible structure for your package (expressed in terms of a hierarchical filesystem): \begin{verbatim} -Sound/ Top-level package +sound/ Top-level package __init__.py Initialize the sound package - Formats/ Subpackage for file format conversions + formats/ Subpackage for file format conversions __init__.py wavread.py wavwrite.py @@ -2745,13 +2745,13 @@ Sound/ Top-level package auread.py auwrite.py ... - Effects/ Subpackage for sound effects + effects/ Subpackage for sound effects __init__.py echo.py surround.py reverse.py ... - Filters/ Subpackage for filters + filters/ Subpackage for filters __init__.py equalizer.py vocoder.py @@ -2774,20 +2774,20 @@ Users of the package can import individual modules from the package, for example: \begin{verbatim} -import Sound.Effects.echo +import sound.effects.echo \end{verbatim} -This loads the submodule \module{Sound.Effects.echo}. It must be referenced +This loads the submodule \module{sound.effects.echo}. It must be referenced with its full name. \begin{verbatim} -Sound.Effects.echo.echofilter(input, output, delay=0.7, atten=4) +sound.effects.echo.echofilter(input, output, delay=0.7, atten=4) \end{verbatim} An alternative way of importing the submodule is: \begin{verbatim} -from Sound.Effects import echo +from sound.effects import echo \end{verbatim} This also loads the submodule \module{echo}, and makes it available without @@ -2800,7 +2800,7 @@ echo.echofilter(input, output, delay=0.7, atten=4) Yet another variation is to import the desired function or variable directly: \begin{verbatim} -from Sound.Effects.echo import echofilter +from sound.effects.echo import echofilter \end{verbatim} Again, this loads the submodule \module{echo}, but this makes its function @@ -2827,7 +2827,7 @@ class or function or variable defined in the previous item. %The \code{__all__} Attribute \ttindex{__all__} -Now what happens when the user writes \code{from Sound.Effects import +Now what happens when the user writes \code{from sound.effects import *}? Ideally, one would hope that this somehow goes out to the filesystem, finds which submodules are present in the package, and imports them all. Unfortunately, this operation does not work very @@ -2849,19 +2849,19 @@ encountered. It is up to the package author to keep this list up-to-date when a new version of the package is released. Package authors may also decide not to support it, if they don't see a use for importing * from their package. For example, the file -\file{Sounds/Effects/__init__.py} could contain the following code: +\file{sounds/effects/__init__.py} could contain the following code: \begin{verbatim} __all__ = ["echo", "surround", "reverse"] \end{verbatim} -This would mean that \code{from Sound.Effects import *} would -import the three named submodules of the \module{Sound} package. +This would mean that \code{from sound.effects import *} would +import the three named submodules of the \module{sound} package. -If \code{__all__} is not defined, the statement \code{from Sound.Effects +If \code{__all__} is not defined, the statement \code{from sound.effects import *} does \emph{not} import all submodules from the package -\module{Sound.Effects} into the current namespace; it only ensures that the -package \module{Sound.Effects} has been imported (possibly running any +\module{sound.effects} into the current namespace; it only ensures that the +package \module{sound.effects} has been imported (possibly running any initialization code in \file{__init__.py}) and then imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by \file{__init__.py}. It also includes any @@ -2869,14 +2869,14 @@ submodules of the package that were explicitly loaded by previous import statements. Consider this code: \begin{verbatim} -import Sound.Effects.echo -import Sound.Effects.surround -from Sound.Effects import * +import sound.effects.echo +import sound.effects.surround +from sound.effects import * \end{verbatim} In this example, the echo and surround modules are imported in the current namespace because they are defined in the -\module{Sound.Effects} package when the \code{from...import} statement +\module{sound.effects} package when the \code{from...import} statement is executed. (This also works when \code{__all__} is defined.) Note that in general the practice of importing \code{*} from a module or @@ -2904,12 +2904,12 @@ which the current module is a submodule), the \keyword{import} statement looks for a top-level module with the given name. When packages are structured into subpackages (as with the -\module{Sound} package in the example), there's no shortcut to refer +\module{sound} package in the example), there's no shortcut to refer to submodules of sibling packages - the full name of the subpackage must be used. For example, if the module -\module{Sound.Filters.vocoder} needs to use the \module{echo} module -in the \module{Sound.Effects} package, it can use \code{from -Sound.Effects import echo}. +\module{sound.filters.vocoder} needs to use the \module{echo} module +in the \module{sound.effects} package, it can use \code{from +sound.effects import echo}. Starting with Python 2.5, in addition to the implicit relative imports described above, you can write explicit relative imports with the @@ -2920,8 +2920,8 @@ module for example, you might use: \begin{verbatim} from . import echo -from .. import Formats -from ..Filters import equalizer +from .. import formats +from ..filters import equalizer \end{verbatim} Note that both explicit and implicit relative imports are based on the diff --git a/Doc/whatsnew/whatsnew26.tex b/Doc/whatsnew/whatsnew26.tex index a40c100..5d2373f 100644 --- a/Doc/whatsnew/whatsnew26.tex +++ b/Doc/whatsnew/whatsnew26.tex @@ -53,7 +53,7 @@ \tableofcontents This article explains the new features in Python 2.6. No release date -for Python 2.6 has been set; it will probably be released in late 2007. +for Python 2.6 has been set; it will probably be released in mid 2008. % Compare with previous release in 2 - 3 sentences here. |