Copied doc for reload() from trunk's function.rst to imp.rst
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 5b625ee..cb3a029 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -489,7 +489,7 @@
>>> Point._make(t)
Point(x=11, y=22)
-.. method:: somenamedtuple._asdict()
+.. method:: namedtuple._asdict()
Return a new dict which maps field names to their corresponding values:
@@ -498,7 +498,7 @@
>>> p._asdict()
{'x': 11, 'y': 22}
-.. method:: somenamedtuple._replace(kwargs)
+.. method:: namedtuple._replace(kwargs)
Return a new instance of the named tuple replacing specified fields with new values:
@@ -511,7 +511,7 @@
>>> for partnum, record in inventory.items():
... inventory[partnum] = record._replace(price=newprices[partnum], updated=time.now())
-.. attribute:: somenamedtuple._fields
+.. attribute:: namedtuple._fields
Tuple of strings listing the field names. This is useful for introspection
and for creating new named tuple types from existing named tuples.
@@ -541,15 +541,28 @@
Point(x=11, y=22)
Since a named tuple is a regular Python class, it is easy to add or change
-functionality. For example, the display format can be changed by overriding
-the :meth:`__repr__` method:
+functionality with a subclass. Here is how to add a calculated field and
+a fixed-width print format::
-::
+ >>> class Point(namedtuple('Point', 'x y')):
+ @property
+ def hypot(self):
+ return (self.x ** 2 + self.y ** 2) ** 0.5
+ def __repr__(self):
+ return 'Point(x=%.3f, y=%.3f, hypot=%.3f)' % (self.x, self.y, self.hypot)
- >>> Point = namedtuple('Point', 'x y')
- >>> Point.__repr__ = lambda self: 'Point(%.3f, %.3f)' % self
- >>> Point(x=11, y=22)
- Point(11.000, 22.000)
+ >>> print Point(3, 4),'\n', Point(2, 5), '\n', Point(9./7, 6)
+ Point(x=3.000, y=4.000, hypot=5.000)
+ Point(x=2.000, y=5.000, hypot=5.385)
+ Point(x=1.286, y=6.000, hypot=6.136)
+
+Another use for subclassing is to replace performance critcal methods with
+faster versions that bypass error-checking and localize variable access::
+
+ >>> class Point(namedtuple('Point', 'x y')):
+ _make = classmethod(tuple.__new__)
+ def _replace(self, _map=map, **kwds):
+ return self._make(_map(kwds.pop, ('x', 'y'), self))
Default values can be implemented by starting with a prototype instance
and customizing it with :meth:`_replace`:
diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst
index 35d91d2..8b8e326 100644
--- a/Doc/library/getopt.rst
+++ b/Doc/library/getopt.rst
@@ -11,7 +11,7 @@
It supports the same conventions as the Unix :cfunc:`getopt` function (including
the special meanings of arguments of the form '``-``' and '``--``'). Long
options similar to those supported by GNU software may be used as well via an
-optional third argument. This module provides a single function and an
+optional third argument. This module provides two functions and an
exception:
diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst
index 7b8133b..831d1a7 100644
--- a/Doc/library/imp.rst
+++ b/Doc/library/imp.rst
@@ -123,6 +123,68 @@
function does nothing.
+.. function:: reload(module)
+
+ Reload a previously imported *module*. The argument must be a module object, so
+ it must have been successfully imported before. This is useful if you have
+ edited the module source file using an external editor and want to try out the
+ new version without leaving the Python interpreter. The return value is the
+ module object (the same as the *module* argument).
+
+ When ``reload(module)`` is executed:
+
+ * Python modules' code is recompiled and the module-level code reexecuted,
+ defining a new set of objects which are bound to names in the module's
+ dictionary. The ``init`` function of extension modules is not called a second
+ time.
+
+ * As with all other objects in Python the old objects are only reclaimed after
+ their reference counts drop to zero.
+
+ * The names in the module namespace are updated to point to any new or changed
+ objects.
+
+ * Other references to the old objects (such as names external to the module) are
+ not rebound to refer to the new objects and must be updated in each namespace
+ where they occur if that is desired.
+
+ There are a number of other caveats:
+
+ If a module is syntactically correct but its initialization fails, the first
+ :keyword:`import` statement for it does not bind its name locally, but does
+ store a (partially initialized) module object in ``sys.modules``. To reload the
+ module you must first :keyword:`import` it again (this will bind the name to the
+ partially initialized module object) before you can :func:`reload` it.
+
+ When a module is reloaded, its dictionary (containing the module's global
+ variables) is retained. Redefinitions of names will override the old
+ definitions, so this is generally not a problem. If the new version of a module
+ does not define a name that was defined by the old version, the old definition
+ remains. This feature can be used to the module's advantage if it maintains a
+ global table or cache of objects --- with a :keyword:`try` statement it can test
+ for the table's presence and skip its initialization if desired::
+
+ try:
+ cache
+ except NameError:
+ cache = {}
+
+ It is legal though generally not very useful to reload built-in or dynamically
+ loaded modules, except for :mod:`sys`, :mod:`__main__` and :mod:`__builtin__`.
+ In many cases, however, extension modules are not designed to be initialized
+ more than once, and may fail in arbitrary ways when reloaded.
+
+ If a module imports objects from another module using :keyword:`from` ...
+ :keyword:`import` ..., calling :func:`reload` for the other module does not
+ redefine the objects imported from it --- one way around this is to re-execute
+ the :keyword:`from` statement, another is to use :keyword:`import` and qualified
+ names (*module*.*name*) instead.
+
+ If a module instantiates instances of a class, reloading the module that defines
+ the class does not affect the method definitions of the instances --- they
+ continue to use the old class definition. The same is true for derived classes.
+
+
The following constants with integer values, defined in this module, are used to
indicate the search result of :func:`find_module`.
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index a95e2b5..bf6ad71 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -688,7 +688,8 @@
Does basic configuration for the logging system by creating a
:class:`StreamHandler` with a default :class:`Formatter` and adding it to the
- root logger. The functions :func:`debug`, :func:`info`, :func:`warning`,
+ root logger. The function does nothing if any handlers have been defined for
+ the root logger. The functions :func:`debug`, :func:`info`, :func:`warning`,
:func:`error` and :func:`critical` will call :func:`basicConfig` automatically
if no handlers are defined for the root logger.
@@ -2384,24 +2385,24 @@
The output looks like this::
- 2005-03-23 23:47:11,663 - spam_application - INFO -
+ 2005-03-23 23:47:11,663 - spam_application - INFO -
creating an instance of auxiliary_module.Auxiliary
- 2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -
+ 2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -
creating an instance of Auxiliary
- 2005-03-23 23:47:11,665 - spam_application - INFO -
+ 2005-03-23 23:47:11,665 - spam_application - INFO -
created an instance of auxiliary_module.Auxiliary
- 2005-03-23 23:47:11,668 - spam_application - INFO -
+ 2005-03-23 23:47:11,668 - spam_application - INFO -
calling auxiliary_module.Auxiliary.do_something
- 2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -
+ 2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -
doing something
- 2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -
+ 2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -
done doing something
- 2005-03-23 23:47:11,670 - spam_application - INFO -
+ 2005-03-23 23:47:11,670 - spam_application - INFO -
finished auxiliary_module.Auxiliary.do_something
- 2005-03-23 23:47:11,671 - spam_application - INFO -
+ 2005-03-23 23:47:11,671 - spam_application - INFO -
calling auxiliary_module.some_function()
- 2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -
+ 2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -
received a call to "some_function"
- 2005-03-23 23:47:11,673 - spam_application - INFO -
+ 2005-03-23 23:47:11,673 - spam_application - INFO -
done with auxiliary_module.some_function()
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index cc16150..406c136 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -65,6 +65,27 @@
AF_NETLINK sockets are represented as pairs ``pid, groups``.
+
+Linux-only support for TIPC is also available using the :const:`AF_TIPC`
+address family. TIPC is an open, non-IP based networked protocol designed
+for use in clustered computer environments. Addresses are represented by a
+tuple, and the fields depend on the address type. The general tuple form is
+``(addr_type, v1, v2, v3 [, scope])``, where:
+
+ - *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
+ TIPC_ADDR_ID.
+ - *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
+ TIPC_NODE_SCOPE.
+ - If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is
+ the port identifier, and *v3* should be 0.
+
+ If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2*
+ is the lower port number, and *v3* is the upper port number.
+
+ If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
+ reference, and *v3* should be set to 0.
+
+
All errors raise exceptions. The normal exceptions for invalid argument types
and out-of-memory conditions can be raised; errors related to socket or address
semantics raise the error :exc:`socket.error`.
@@ -162,6 +183,12 @@
:meth:`ioctl` method of socket objects.
+.. data:: TIPC_*
+
+ TIPC related constants, matching the ones exported by the C socket API. See
+ the TIPC documentation for more information.
+
+
.. data:: has_ipv6
This constant contains a boolean value which indicates if IPv6 is supported on
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 7a4938c..4a1d566 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -389,9 +389,9 @@
| ``x & y`` | bitwise :dfn:`and` of *x* and | |
| | *y* | |
+------------+--------------------------------+----------+
-| ``x << n`` | *x* shifted left by *n* bits | (1), (2) |
+| ``x << n`` | *x* shifted left by *n* bits | (1)(2) |
+------------+--------------------------------+----------+
-| ``x >> n`` | *x* shifted right by *n* bits | (1), (3) |
+| ``x >> n`` | *x* shifted right by *n* bits | (1)(3) |
+------------+--------------------------------+----------+
| ``~x`` | the bits of *x* inverted | |
+------------+--------------------------------+----------+
@@ -436,7 +436,7 @@
support:
-.. method:: container.__iter__()
+.. method:: object.__iter__()
Return an iterator object. The object is required to support the iterator
protocol described below. If a container supports different types of
@@ -537,7 +537,7 @@
Most sequence types support the following operations. The ``in`` and ``not in``
operations have the same priorities as the comparison operations. The ``+`` and
``*`` operations have the same priority as the corresponding numeric operations.
-[#]_
+[#]_ Additional methods are provided for :ref:`typesseq-mutable`.
This table lists the sequence operations sorted in ascending priority
(operations in the same box have the same priority). In the table, *s* and *t*
@@ -560,9 +560,9 @@
+------------------+--------------------------------+----------+
| ``s[i]`` | *i*'th item of *s*, origin 0 | \(3) |
+------------------+--------------------------------+----------+
-| ``s[i:j]`` | slice of *s* from *i* to *j* | (3), (4) |
+| ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) |
+------------------+--------------------------------+----------+
-| ``s[i:j:k]`` | slice of *s* from *i* to *j* | (3), (5) |
+| ``s[i:j:k]`` | slice of *s* from *i* to *j* | (3)(5) |
| | with step *k* | |
+------------------+--------------------------------+----------+
| ``len(s)`` | length of *s* | |
diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst
index 5b05aed..3fedb56 100644
--- a/Doc/tutorial/controlflow.rst
+++ b/Doc/tutorial/controlflow.rst
@@ -595,10 +595,57 @@
No, really, it doesn't do anything.
+.. _tut-codingstyle:
+
+Intermezzo: Coding Style
+========================
+
+.. sectionauthor:: Georg Brandl <georg@python.org>
+.. index:: pair: coding; style
+
+Now that you are about to write longer, more complex pieces of Python, it is a
+good time to talk about *coding style*. Most languages can be written (or more
+concise, *formatted*) in different styles; some are more readable than others.
+Making it easy for others to read your code is always a good idea, and adopting
+a nice coding style helps tremendously for that.
+
+For Python, :pep:`8` has emerged as the style guide that most projects adher to;
+it promotes a very readable and eye-pleasing coding style. Every Python
+developer should read it at some point; here are the most important points
+extracted for you:
+
+* Use 4-space indentation, and no tabs.
+
+ 4 spaces are a good compromise between small indentation (allows greater
+ nesting depth) and large indentation (easier to read). Tabs introduce
+ confusion, and are best left out.
+
+* Wrap lines so that they don't exceed 79 characters.
+
+ This helps users with small displays and makes it possible to have several
+ code files side-by-side on larger displays.
+
+* Use blank lines to separate functions and classes, and larger blocks of
+ code inside functions.
+
+* When possible, put comments on a line of their own.
+
+* Use docstrings.
+
+* Use spaces around operators and after commas, but not directly inside
+ bracketing constructs: ``a = f(1, 2) + g(3, 4)``.
+
+* Name your classes and functions consistently; the convention is to use
+ ``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
+ and methods. Always use ``self`` as the name for the first method argument.
+
+* Don't use fancy encodings if your code is meant to be used in international
+ environments. Plain ASCII works best in any case.
+
.. rubric:: Footnotes
-.. [#] Actually, *call by object reference* would be a better description, since if a
- mutable object is passed, the caller will see any changes the callee makes to it
- (items inserted into a list).
+.. [#] Actually, *call by object reference* would be a better description,
+ since if a mutable object is passed, the caller will see any changes the
+ callee makes to it (items inserted into a list).
diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst
index a99e7d2..1189ce8 100644
--- a/Doc/tutorial/introduction.rst
+++ b/Doc/tutorial/introduction.rst
@@ -548,7 +548,7 @@
... # the sum of two elements defines the next
... a, b = 0, 1
>>> while b < 10:
- ... print(b)
+ ... print b
... a, b = b, a+b
...
1