diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/bdb.rst | 5 | ||||
| -rw-r--r-- | Doc/library/ftplib.rst | 18 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 45 | ||||
| -rw-r--r-- | Doc/library/httplib.rst | 16 | ||||
| -rw-r--r-- | Doc/library/pdb.rst | 6 | ||||
| -rw-r--r-- | Doc/library/smtplib.rst | 30 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 10 | ||||
| -rw-r--r-- | Doc/library/socketserver.rst | 4 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 13 | ||||
| -rw-r--r-- | Doc/library/telnetlib.rst | 16 | ||||
| -rw-r--r-- | Doc/library/tempfile.rst | 5 | ||||
| -rw-r--r-- | Doc/library/textwrap.rst | 18 | ||||
| -rw-r--r-- | Doc/library/tk.rst | 3 | ||||
| -rw-r--r-- | Doc/library/urllib2.rst | 21 |
14 files changed, 138 insertions, 72 deletions
diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst index f04b671..fefb2ad 100644 --- a/Doc/library/bdb.rst +++ b/Doc/library/bdb.rst @@ -207,6 +207,11 @@ The :mod:`bdb` module also defines two classes: Stop when returning from the given frame. + .. method:: set_until(frame) + + Stop when the line with the line no greater than the current one is + reached or when returning from current frame + .. method:: set_trace([frame]) Start debugging from *frame*. If *frame* is not specified, debugging diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index 41bdcd8..99aae0d 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -40,11 +40,12 @@ The module defines the following items: .. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]]) Return a new instance of the :class:`FTP` class. When *host* is given, the - method call ``connect(host)`` is made. When *user* is given, additionally the - method call ``login(user, passwd, acct)`` is made (where *passwd* and *acct* - default to the empty string when not given). The optional *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). + method call ``connect(host)`` is made. When *user* is given, additionally + the method call ``login(user, passwd, acct)`` is made (where *passwd* and + *acct* default to the empty string when not given). The optional *timeout* + parameter specifies a timeout in seconds for blocking operations like the + connection attempt (if is not specified, or passed as None, the global + default timeout setting will be used). .. attribute:: all_errors @@ -122,9 +123,10 @@ followed by ``lines`` for the text version or ``binary`` for the binary version. made. The optional *timeout* parameter specifies a timeout in seconds for 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. + 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. .. method:: FTP.getwelcome() diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 129aa3c..9ccc59c 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -848,10 +848,15 @@ are always available. They are listed here in alphabetical order. use is to define a managed attribute x:: class C(object): - def __init__(self): self._x = None - def getx(self): return self._x - def setx(self, value): self._x = value - def delx(self): del self._x + def __init__(self): + self._x = None + + def getx(self): + return self._x + def setx(self, value): + self._x = value + def delx(self): + del self._x x = property(getx, setx, delx, "I'm the 'x' property.") If given, *doc* will be the docstring of the property attribute. Otherwise, the @@ -867,8 +872,36 @@ are always available. They are listed here in alphabetical order. """Get the current voltage.""" return self._voltage - turns the :meth:`voltage` method into a "getter" for a read-only attribute with - the same name. + turns the :meth:`voltage` method into a "getter" for a read-only attribute + with the same name. + + A property object has :attr:`getter`, :attr:`setter`, and :attr:`deleter` + methods usable as decorators that create a copy of the property with the + corresponding accessor function set to the decorated function. This is + best explained with an example:: + + class C(object): + def __init__(self): self._x = None + + @property + def x(self): + """I'm the 'x' property.""" + return self._x + + @x.setter + def x(self, value): + self._x = value + + @x.deleter + def x(self): + del self._x + + This code is exactly equivalent to the first example. Be sure to give the + additional functions the same name as the original property (``x`` in this + case.) + + The returned property also has the attributes ``fget``, ``fset``, and + ``fdel`` corresponding to the constructor arguments. .. XXX does accept objects with __index__ too diff --git a/Doc/library/httplib.rst b/Doc/library/httplib.rst index 03fe681..16b74ee 100644 --- a/Doc/library/httplib.rst +++ b/Doc/library/httplib.rst @@ -27,14 +27,14 @@ The module provides the following classes: .. class:: HTTPConnection(host[, port[, strict[, timeout]]]) An :class:`HTTPConnection` instance represents one transaction with an HTTP - server. It should be instantiated passing it a host and optional port number. - If no port number is passed, the port is extracted from the host string if it - has the form ``host:port``, else the default HTTP port (80) is used. When True, - the optional parameter *strict* causes ``BadStatusLine`` to be raised if the - status line can't be parsed as a valid HTTP/1.0 or 1.1 status line. If the - optional *timeout* parameter is given, connection attempts will timeout after - that many seconds (if it is not given or ``None``, the global default timeout - setting is used). + server. It should be instantiated passing it a host and optional port + number. If no port number is passed, the port is extracted from the host + string if it has the form ``host:port``, else the default HTTP port (80) is + used. When True, the optional parameter *strict* causes ``BadStatusLine`` to + be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1 + status line. If the optional *timeout* parameter is given, blocking + operations (like connection attempts) will timeout after that many seconds + (if it is not given or ``None``, the global default timeout setting is used). For example, the following calls all create instances that connect to the server at the same host and port:: diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst index df8cf6c..ba6c1b5 100644 --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -261,6 +261,12 @@ n(ext) inside a called function, while ``next`` executes called functions at (nearly) full speed, only stopping at the next line in the current function.) +unt(il) + Continue execution until the line with the the line number greater than the + current one is reached or when returning from current frame. + + .. versionadded:: 2.6 + r(eturn) Continue execution until the current function returns. diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index d4dd43f..602edb6 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -19,13 +19,14 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). .. class:: SMTP([host[, port[, local_hostname[, timeout]]]]) - A :class:`SMTP` instance encapsulates an SMTP connection. It has methods that - support a full repertoire of SMTP and ESMTP operations. If the optional host and - port parameters are given, the SMTP :meth:`connect` method is called with those - parameters during initialization. An :exc:`SMTPConnectError` is raised if the - specified host doesn't respond correctly. The optional *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). + A :class:`SMTP` instance encapsulates an SMTP connection. It has methods + that support a full repertoire of SMTP and ESMTP operations. If the optional + host and port parameters are given, the SMTP :meth:`connect` method is called + with those parameters during initialization. An :exc:`SMTPConnectError` is + raised if the specified host doesn't respond correctly. The optional + *timeout* parameter specifies a timeout in seconds for blocking operations + like the connection attempt (if not specified, or passed as None, the global + default timeout setting will be used). For normal use, you should only require the initialization/connect, :meth:`sendmail`, and :meth:`quit` methods. An example is included below. @@ -35,13 +36,14 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). A :class:`SMTP_SSL` instance behaves exactly the same as instances of :class:`SMTP`. :class:`SMTP_SSL` should be used for situations where SSL is - required from the beginning of the connection and using :meth:`starttls` is not - appropriate. If *host* is not specified, the local host is used. If *port* is - omitted, the standard SMTP-over-SSL port (465) is used. *keyfile* and *certfile* - are also optional, and can contain a PEM formatted private key and certificate - chain file for the SSL connection. The optional *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). + required from the beginning of the connection and using :meth:`starttls` is + not appropriate. If *host* is not specified, the local host is used. If + *port* is omitted, the standard SMTP-over-SSL port (465) is used. *keyfile* + and *certfile* are also optional, and can contain a PEM formatted private key + and certificate chain file for the SSL connection. The optional *timeout* + parameter specifies a timeout in seconds for blocking operations like the + connection attempt (if not specified, or passed as None, the global default + timeout setting will be used). .. class:: LMTP([host[, port[, local_hostname]]]) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index d7164da..8fefce6 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -213,9 +213,9 @@ The module :mod:`socket` exports the following constants and functions: service name (like ``'http'``), a numeric port number or ``None``. The rest of the arguments are optional and must be numeric if specified. For - *host* and *port*, by passing either an empty string or ``None``, you can pass - ``NULL`` to the C API. The :func:`getaddrinfo` function returns a list of - 5-tuples with the following structure: + *host* and *port*, by passing ``None``, you can pass ``NULL`` to the C API. + The :func:`getaddrinfo` function returns a list of 5-tuples with the following + structure: ``(family, socktype, proto, canonname, sockaddr)`` @@ -785,7 +785,7 @@ sends traffic to the first one connected successfully. :: import socket import sys - HOST = '' # Symbolic name meaning all available interfaces + HOST = None # Symbolic name meaning all available interfaces PORT = 50007 # Arbitrary non-privileged port s = None for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE): @@ -847,7 +847,7 @@ sends traffic to the first one connected successfully. :: The last example shows how to write a very simple network sniffer with raw -sockets on Windows. The example requires administrator priviliges to modify +sockets on Windows. The example requires administrator privileges to modify the interface:: import socket diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst index b7ce818..e24b429 100644 --- a/Doc/library/socketserver.rst +++ b/Doc/library/socketserver.rst @@ -155,7 +155,7 @@ Server Objects .. data:: address_family The family of protocols to which the server's socket belongs. - :const:`socket.AF_INET` and :const:`socket.AF_UNIX` are two possible values. + Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`. .. data:: RequestHandlerClass @@ -199,7 +199,7 @@ The server classes support the following class variables: .. data:: socket_type The type of socket used by the server; :const:`socket.SOCK_STREAM` and - :const:`socket.SOCK_DGRAM` are two possible values. + :const:`socket.SOCK_DGRAM` are two common values. .. data:: timeout diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index ce6aab3..09549ad 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1114,7 +1114,7 @@ The conversion flag characters are: +---------+---------------------------------------------------------------------+ A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it -is not necessary for Python. +is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``. The conversion types are: @@ -1125,13 +1125,13 @@ The conversion types are: +------------+-----------------------------------------------------+-------+ | ``'i'`` | Signed integer decimal. | | +------------+-----------------------------------------------------+-------+ -| ``'o'`` | Unsigned octal. | \(1) | +| ``'o'`` | Signed octal value. | \(1) | +------------+-----------------------------------------------------+-------+ -| ``'u'`` | Unsigned decimal. | | +| ``'u'`` | Obselete type -- it is identical to ``'d'``. | \(7) | +------------+-----------------------------------------------------+-------+ -| ``'x'`` | Unsigned hexadecimal (lowercase). | \(2) | +| ``'x'`` | Signed hexadecimal (lowercase). | \(2) | +------------+-----------------------------------------------------+-------+ -| ``'X'`` | Unsigned hexadecimal (uppercase). | \(2) | +| ``'X'`` | Signed hexadecimal (uppercase). | \(2) | +------------+-----------------------------------------------------+-------+ | ``'e'`` | Floating point exponential format (lowercase). | \(3) | +------------+-----------------------------------------------------+-------+ @@ -1193,6 +1193,9 @@ Notes: The precision determines the maximal number of characters used. +(7) + See :pep:`237`. + Since Python strings have an explicit length, ``%s`` conversions do not assume that ``'\0'`` is the end of the string. diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst index 4c8ce45..8c8ddbb 100644 --- a/Doc/library/telnetlib.rst +++ b/Doc/library/telnetlib.rst @@ -27,11 +27,12 @@ Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin). :class:`Telnet` represents a connection to a Telnet server. The instance is initially not connected by default; the :meth:`open` method must be used to - establish a connection. Alternatively, the host name and optional port number - can be passed to the constructor, to, in which case the connection to the server - will be established before the constructor returns. The optional *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). + establish a connection. Alternatively, the host name and optional port + number can be passed to the constructor, to, in which case the connection to + the server will be established before the constructor returns. The optional + *timeout* parameter specifies a timeout in seconds for blocking operations + like the connection attempt (if not specified, or passed as None, the global + default timeout setting will be used). Do not reopen an already connected instance. @@ -121,8 +122,9 @@ Telnet Objects Connect to a host. The optional second argument is the port number, which defaults to the standard Telnet port (23). The optional *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). + specifies a timeout in seconds for blocking operations like the 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. diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst index 25d5acb..69b05ce 100644 --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -156,11 +156,6 @@ The module defines the following user-callable functions: :func:`NamedTemporaryFile`, passing it the `delete=False` parameter:: >>> f = NamedTemporaryFile(delete=False) - >>> print f.name - >>> f.write("Hello World!\n") - >>> f.close() - >>> os.unlink(f.name) - >>> f = NamedTemporaryFile(delete=False) >>> f <open file '<fdopen>', mode 'w+b' at 0x384698> >>> f.name diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst index 243e43c..a18a801 100644 --- a/Doc/library/textwrap.rst +++ b/Doc/library/textwrap.rst @@ -39,6 +39,10 @@ instance and calling a single method on it. That instance is not reused, so for applications that wrap/fill many text strings, it will be more efficient for you to create your own :class:`TextWrapper` object. +Text is preferably wrapped on whitespaces and right after the hyphens in +hyphenated words; only then will long words be broken if necessary, unless +:attr:`TextWrapper.break_long_words` is set to false. + An additional utility function, :func:`dedent`, is provided to remove indentation from strings that have unwanted whitespace to the left of the text. @@ -167,10 +171,22 @@ indentation from strings that have unwanted whitespace to the left of the text. than :attr:`width`. (Long words will be put on a line by themselves, in order to minimize the amount by which :attr:`width` is exceeded.) + + .. attribute:: break_on_hyphens + + (default: ``True``) If true, wrapping will occur preferably on whitespaces + and right after hyphens in compound words, as it is customary in English. + If false, only whitespaces will be considered as potentially good places + for line breaks, but you need to set :attr:`break_long_words` to false if + you want truly insecable words. Default behaviour in previous versions + was to always allow breaking hyphenated words. + + .. versionadded:: 2.6 + + :class:`TextWrapper` also provides two public methods, analogous to the module-level convenience functions: - .. method:: wrap(text) Wraps the single paragraph in *text* (a string) so every line is at most diff --git a/Doc/library/tk.rst b/Doc/library/tk.rst index 3e2f100..8451f6d 100644 --- a/Doc/library/tk.rst +++ b/Doc/library/tk.rst @@ -23,7 +23,8 @@ mechanism which allows Python and Tcl to interact. :mod:`Tkinter`'s chief virtues are that it is fast, and that it usually comes bundled with Python. Although it has been used to create some very good -applications, including IDLE, it has weak documentation and an outdated look and +applications, including IDLE, its standard documentation is weak (but there +are some good books and tutorials), and it has an outdated look and feel. For more modern, better documented, and much more extensive GUI libraries, see the :ref:`other-gui-packages` section. diff --git a/Doc/library/urllib2.rst b/Doc/library/urllib2.rst index 7987007..143fe50 100644 --- a/Doc/library/urllib2.rst +++ b/Doc/library/urllib2.rst @@ -26,10 +26,10 @@ The :mod:`urllib2` module defines the following functions: :func:`urllib.urlencode` function takes a mapping or sequence of 2-tuples and returns a string in this format. - The optional *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. + The optional *timeout* parameter specifies a timeout in seconds for blocking + operations like the connection attempt (if not specified, or passed as + ``None``, the global default timeout setting will be used). This actually + only works for HTTP, HTTPS, FTP and FTPS connections. This function returns a file-like object with two additional methods: @@ -399,12 +399,13 @@ OpenerDirector Objects .. method:: OpenerDirector.open(url[, data][, timeout]) Open the given *url* (which can be a request object or a string), optionally - passing the given *data*. Arguments, return values and exceptions raised are the - same as those of :func:`urlopen` (which simply calls the :meth:`open` method on - the currently installed global :class:`OpenerDirector`). The optional *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). + passing the given *data*. Arguments, return values and exceptions raised are + the same as those of :func:`urlopen` (which simply calls the :meth:`open` + method on the currently installed global :class:`OpenerDirector`). The + optional *timeout* parameter specifies a timeout in seconds for blocking + operations like the connection attempt (if not specified, or passed as + ``None``, the global default timeout setting will be used; this actually only + works for HTTP, HTTPS, FTP and FTPS connections). .. method:: OpenerDirector.error(proto[, arg[, ...]]) |