diff -r 7d94034e1ddc Doc/library/constants.rst --- a/Doc/library/constants.rst Sun Oct 06 10:51:07 2013 +0200 +++ b/Doc/library/constants.rst Mon Oct 07 23:39:13 2013 +0300 @@ -27,8 +27,8 @@ .. data:: NotImplemented Special value which can be returned by the "rich comparison" special methods - (:meth:`__eq__`, :meth:`__lt__`, and friends), to indicate that the comparison - is not implemented with respect to the other type. + (:meth:`~object.__eq__`, :meth:`~object.__lt__`, and friends), to indicate + that the comparison is not implemented with respect to the other type. .. data:: Ellipsis diff -r 7d94034e1ddc Doc/library/functions.rst --- a/Doc/library/functions.rst Sun Oct 06 10:51:07 2013 +0200 +++ b/Doc/library/functions.rst Mon Oct 07 23:39:13 2013 +0300 @@ -82,7 +82,7 @@ Convert an integer number to a binary string. The result is a valid Python expression. If *x* is not a Python :class:`int` object, it has to define an - :meth:`__index__` method that returns an integer. + :meth:`~object.__index__` method that returns an integer. .. function:: bool([x]) @@ -147,7 +147,7 @@ :const:`False` if not. If this returns true, it is still possible that a call fails, but if it is false, calling *object* will never succeed. Note that classes are callable (calling a class returns a new instance); - instances are callable if their class has a :meth:`__call__` method. + instances are callable if their class has a :meth:`~object.__call__` method. .. versionadded:: 3.2 This function was first removed in Python 3.0 and then brought back @@ -219,8 +219,8 @@ Future statements are specified by bits which can be bitwise ORed together to specify multiple statements. The bitfield required to specify a given feature - can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature` - instance in the :mod:`__future__` module. + can be found as the :attr:`~__future__._Feature.compiler_flag` attribute on + the :class:`~__future__._Feature` instance in the :mod:`__future__` module. The argument *optimize* specifies the optimization level of the compiler; the default value of ``-1`` selects the optimization level of the interpreter as @@ -290,15 +290,17 @@ Without arguments, return the list of names in the current local scope. With an argument, attempt to return a list of valid attributes for that object. - If the object has a method named :meth:`__dir__`, this method will be called and - must return the list of attributes. This allows objects that implement a custom - :func:`__getattr__` or :func:`__getattribute__` function to customize the way - :func:`dir` reports their attributes. + If the object has a method named :meth:`~object.__dir__`, this method will + be called and must return the list of attributes. This allows objects that + implement a custom :func:`~object.__getattr__` or + :func:`~object.__getattribute__` function to customize the way :func:`dir` + reports their attributes. - If the object does not provide :meth:`__dir__`, the function tries its best to - gather information from the object's :attr:`__dict__` attribute, if defined, and - from its type object. The resulting list is not necessarily complete, and may - be inaccurate when the object has a custom :func:`__getattr__`. + If the object does not provide :meth:`~object.__dir__`, the function tries + its best to gather information from the object's :attr:`~object.__dict__` + attribute, if defined, and from its type object. The resulting list is not + necessarily complete, and may be inaccurate when the object has a custom + :meth:`~object.__getattr__`. The default :func:`dir` mechanism behaves differently with different types of objects, as it attempts to produce the most relevant, rather than complete, @@ -539,9 +541,9 @@ A call to ``format(value, format_spec)`` is translated to ``type(value).__format__(format_spec)`` which bypasses the instance - dictionary when searching for the value's :meth:`__format__` method. A - :exc:`TypeError` exception is raised if the method is not found or if either - the *format_spec* or the return value are not strings. + dictionary when searching for the value's :meth:`~object.__format__` method. + A :exc:`TypeError` exception is raised if the method is not found or if + either the *format_spec* or the return value are not strings. .. versionadded:: 3.4 ``object().__format__(format_spec)`` raises :exc:`TypeError` @@ -594,9 +596,9 @@ .. note:: - For object's with custom :meth:`__hash__` methods, note that :func:`hash` - truncates the return value based on the bit width of the host machine. - See :meth:`__hash__` for details. + For object's with custom :meth:`~object.__hash__` methods, note that + :func:`hash` truncates the return value based on the bit width of the host + machine. See :meth:`~object.__hash__` for details. .. function:: help([object]) @@ -614,7 +616,7 @@ Convert an integer number to a hexadecimal string. The result is a valid Python expression. If *x* is not a Python :class:`int` object, it has to define an - :meth:`__index__` method that returns an integer. + :meth:`~object.__index__` method that returns an integer. .. note:: @@ -703,12 +705,12 @@ Return an :term:`iterator` object. The first argument is interpreted very differently depending on the presence of the second argument. Without a second argument, *object* must be a collection object which supports the - iteration protocol (the :meth:`__iter__` method), or it must support the - sequence protocol (the :meth:`__getitem__` method with integer arguments - starting at ``0``). If it does not support either of those protocols, - :exc:`TypeError` is raised. If the second argument, *sentinel*, is given, - then *object* must be a callable object. The iterator created in this case - will call *object* with no arguments for each call to its + iteration protocol (the :meth:`~object.__iter__` method), or it must support + the sequence protocol (the :meth:`~object.__getitem__` method with integer + arguments starting at ``0``). If it does not support either of those + protocols, :exc:`TypeError` is raised. If the second argument, *sentinel*, + is given, then *object* must be a callable object. The iterator created in + this case will call *object* with no arguments for each call to its :meth:`~iterator.__next__` method; if the value returned is equal to *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will be returned. @@ -717,7 +719,7 @@ One useful application of the second form of :func:`iter` is to read lines of a file until a certain line is reached. The following example reads a file - until the :meth:`readline` method returns an empty string:: + until the :meth:`~io.TextIOBase.readline` method returns an empty string:: with open('mydata.txt') as fp: for line in iter(fp.readline, ''): @@ -826,15 +828,15 @@ .. note:: - :class:`object` does *not* have a :attr:`__dict__`, so you can't assign - arbitrary attributes to an instance of the :class:`object` class. + :class:`object` does *not* have a :attr:`~object.__dict__`, so you can't + assign arbitrary attributes to an instance of the :class:`object` class. .. function:: oct(x) Convert an integer number to an octal string. The result is a valid Python expression. If *x* is not a Python :class:`int` object, it has to define an - :meth:`__index__` method that returns an integer. + :meth:`~object.__index__` method that returns an integer. .. index:: @@ -905,9 +907,9 @@ size" and falling back on :attr:`io.DEFAULT_BUFFER_SIZE`. On many systems, the buffer will typically be 4096 or 8192 bytes long. - * "Interactive" text files (files for which :meth:`isatty` returns True) use - line buffering. Other text files use the policy described above for binary - files. + * "Interactive" text files (files for which :meth:`~io.IOBase.isatty` + returns True) use line buffering. Other text files use the policy + described above for binary files. *encoding* is the name of the encoding used to decode or encode the file. This should only be used in text mode. The default encoding is platform @@ -1115,10 +1117,10 @@ 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:: + A property object has :attr:`~property.getter`, :attr:`~property.setter`, + and :attr:`~property.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: def __init__(self): @@ -1162,15 +1164,16 @@ representation is a string enclosed in angle brackets that contains the name of the type of the object together with additional information often including the name and address of the object. A class can control what this - function returns for its instances by defining a :meth:`__repr__` method. + function returns for its instances by defining a :meth:`~object.__repr__` + method. .. function:: reversed(seq) Return a reverse :term:`iterator`. *seq* must be an object which has - a :meth:`__reversed__` method or supports the sequence protocol (the - :meth:`__len__` method and the :meth:`__getitem__` method with integer - arguments starting at ``0``). + a :meth:`~object.__reversed__` method or supports the sequence protocol (the + :meth:`~object.__len__` method and the :meth:`~object.__getitem__` method + with integer arguments starting at ``0``). .. function:: round(number[, ndigits]) @@ -1224,13 +1227,13 @@ Return a :term:`slice` object representing the set of indices specified by ``range(start, stop, step)``. The *start* and *step* arguments default to - ``None``. Slice objects have read-only data attributes :attr:`start`, - :attr:`stop` and :attr:`step` which merely return the argument values (or their - default). They have no other explicit functionality; however they are used by - Numerical Python and other third party extensions. Slice objects are also - generated when extended indexing syntax is used. For example: - ``a[start:stop:step]`` or ``a[start:stop, i]``. See :func:`itertools.islice` - for an alternate version that returns an iterator. + ``None``. Slice objects have read-only data attributes :attr:`~slice.start`, + :attr:`~slice.stop` and :attr:`~slice.step` which merely return the argument + values (or their default). They have no other explicit functionality; + however they are used by Numerical Python and other third party extensions. + Slice objects are also generated when extended indexing syntax is used. For + example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See + :func:`itertools.islice` for an alternate version that returns an iterator. .. function:: sorted(iterable[, key][, reverse]) @@ -1310,9 +1313,10 @@ been overridden in a class. The search order is same as that used by :func:`getattr` except that the *type* itself is skipped. - The :attr:`__mro__` attribute of the *type* lists the method resolution - search order used by both :func:`getattr` and :func:`super`. The attribute - is dynamic and can change whenever the inheritance hierarchy is updated. + The :attr:`~class.__mro__` attribute of the *type* lists the method + resolution search order used by both :func:`getattr` and :func:`super`. The + attribute is dynamic and can change whenever the inheritance hierarchy is + updated. If the second argument is omitted, the super object returned is unbound. If the second argument is an object, ``isinstance(obj, type)`` must be true. If @@ -1343,10 +1347,10 @@ Note that :func:`super` is implemented as part of the binding process for explicit dotted attribute lookups such as ``super().__getitem__(name)``. - It does so by implementing its own :meth:`__getattribute__` method for searching - classes in a predictable order that supports cooperative multiple inheritance. - Accordingly, :func:`super` is undefined for implicit lookups using statements or - operators such as ``super()[name]``. + It does so by implementing its own :meth:`~object.__getattribute__` method + for searching classes in a predictable order that supports cooperative + multiple inheritance. Accordingly, :func:`super` is undefined for implicit + lookups using statements or operators such as ``super()[name]``. Also note that, aside from the zero argument form, :func:`super` is not limited to use inside methods. The two argument form specifies the @@ -1375,7 +1379,8 @@ With one argument, return the type of an *object*. The return value is a - type object and generally the same object as returned by ``object.__class__``. + type object and generally the same object as returned by + ``instance.__class__``. The :func:`isinstance` built-in function is recommended for testing the type of an object, because it takes subclasses into account. @@ -1383,11 +1388,11 @@ With three arguments, return a new type object. This is essentially a dynamic form of the :keyword:`class` statement. The *name* string is the - class name and becomes the :attr:`__name__` attribute; the *bases* tuple - itemizes the base classes and becomes the :attr:`__bases__` attribute; - and the *dict* dictionary is the namespace containing definitions for class - body and becomes the :attr:`__dict__` attribute. For example, the - following two statements create identical :class:`type` objects: + class name and becomes the :attr:`~class.__name__` attribute; the *bases* + tuple itemizes the base classes and becomes the :attr:`~class.__bases__` + attribute; and the *dict* dictionary is the namespace containing definitions + for class body and becomes the :attr:`~object.__dict__` attribute. For + example, the following two statements create identical :class:`type` objects: >>> class X: ... a = 1 @@ -1399,13 +1404,13 @@ .. function:: vars([object]) - Return the :attr:`__dict__` attribute for a module, class, instance, - or any other object with a :attr:`__dict__` attribute. + Return the :attr:`~object.__dict__` attribute for a module, class, instance, + or any other object with a :attr:`~object.__dict__` attribute. - Objects such as modules and instances have an updateable :attr:`__dict__` - attribute; however, other objects may have write restrictions on their - :attr:`__dict__` attributes (for example, classes use a - dictproxy to prevent direct dictionary updates). + Objects such as modules and instances have an updateable + :attr:`~object.__dict__` attribute; however, other objects may have write + restrictions on their :attr:`~object.__dict__` attributes (for example, + classes use a dictproxy to prevent direct dictionary updates). Without an argument, :func:`vars` acts like :func:`locals`. Note, the locals dictionary is only useful for reads since updates to the locals diff -r 7d94034e1ddc Doc/library/numbers.rst --- a/Doc/library/numbers.rst Sun Oct 06 10:51:07 2013 +0200 +++ b/Doc/library/numbers.rst Mon Oct 07 23:39:13 2013 +0300 @@ -117,7 +117,8 @@ operations either call an implementation whose author knew about the types of both arguments, or convert both to the nearest built in type and do the operation there. For subtypes of :class:`Integral`, this -means that :meth:`__add__` and :meth:`__radd__` should be defined as:: +means that :meth:`~object.__add__` and :meth:`~object.__radd__` should be +defined as:: class MyIntegral(Integral): @@ -151,15 +152,15 @@ of :class:`Complex` (``a : A <: Complex``), and ``b : B <: Complex``. I'll consider ``a + b``: - 1. If ``A`` defines an :meth:`__add__` which accepts ``b``, all is + 1. If ``A`` defines an :meth:`~object.__add__` which accepts ``b``, all is well. 2. If ``A`` falls back to the boilerplate code, and it were to - return a value from :meth:`__add__`, we'd miss the possibility - that ``B`` defines a more intelligent :meth:`__radd__`, so the + return a value from :meth:`~object.__add__`, we'd miss the possibility + that ``B`` defines a more intelligent :meth:`~object.__radd__`, so the boilerplate should return :const:`NotImplemented` from - :meth:`__add__`. (Or ``A`` may not implement :meth:`__add__` at - all.) - 3. Then ``B``'s :meth:`__radd__` gets a chance. If it accepts + :meth:`~object.__add__`. (Or ``A`` may not implement + :meth:`~object.__add__` at all.) + 3. Then ``B``'s :meth:`~object.__radd__` gets a chance. If it accepts ``a``, all is well. 4. If it falls back to the boilerplate, there are no more possible methods to try, so this is where the default implementation @@ -171,7 +172,7 @@ If ``A <: Complex`` and ``B <: Real`` without sharing any other knowledge, then the appropriate shared operation is the one involving the built -in :class:`complex`, and both :meth:`__radd__` s land there, so ``a+b +in :class:`complex`, and both :meth:`~object.__radd__` s land there, so ``a+b == b+a``. Because most of the operations on any given type will be very similar, diff -r 7d94034e1ddc Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst Sun Oct 06 10:51:07 2013 +0200 +++ b/Doc/library/stdtypes.rst Mon Oct 07 23:39:13 2013 +0300 @@ -56,9 +56,9 @@ * any empty mapping, for example, ``{}``. -* instances of user-defined classes, if the class defines a :meth:`__bool__` or - :meth:`__len__` method, when that method returns the integer zero or - :class:`bool` value ``False``. [1]_ +* instances of user-defined classes, if the class defines a + :meth:`~object.__bool__` or :meth:`~object.__len__` method, when that method + returns the integer zero or :class:`bool` value ``False``. [1]_ .. index:: single: true @@ -185,13 +185,14 @@ single: __ge__() (instance method) Non-identical instances of a class normally compare as non-equal unless the -class defines the :meth:`__eq__` method. +class defines the :meth:`~object.__eq__` method. Instances of a class cannot be ordered with respect to other instances of the same class, or other types of object, unless the class defines enough of the -methods :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` (in -general, :meth:`__lt__` and :meth:`__eq__` are sufficient, if you want the -conventional meanings of the comparison operators). +methods :meth:`~object.__lt__`, :meth:`~object.__le__`, :meth:`~object.__gt__`, +and :meth:`~object.__ge__` (in general, :meth:`~object.__lt__` and +:meth:`~object.__eq__` are sufficient, if you want the conventional meanings of +the comparison operators). The behavior of the :keyword:`is` and :keyword:`is not` operators cannot be customized; also they can be applied to any two objects and never raise an @@ -339,8 +340,8 @@ pair: C; language Conversion from floating point to integer may round or truncate - as in C; see functions :func:`floor` and :func:`ceil` in the :mod:`math` module - for well-defined conversions. + as in C; see functions :func:`~math.floor` and :func:`~math.ceil` in the + :mod:`math` module for well-defined conversions. (4) float also accepts the strings "nan" and "inf" with an optional prefix "+" @@ -625,13 +626,13 @@ ------------------------ For numbers ``x`` and ``y``, possibly of different types, it's a requirement -that ``hash(x) == hash(y)`` whenever ``x == y`` (see the :meth:`__hash__` +that ``hash(x) == hash(y)`` whenever ``x == y`` (see the :meth:`~object.__hash__` method documentation for more details). For ease of implementation and efficiency across a variety of numeric types (including :class:`int`, :class:`float`, :class:`decimal.Decimal` and :class:`fractions.Fraction`) Python's hash for numeric types is based on a single mathematical function that's defined for any rational number, and hence applies to all instances of -:class:`int` and :class:`fraction.Fraction`, and all finite instances of +:class:`int` and :class:`fractions.Fraction`, and all finite instances of :class:`float` and :class:`decimal.Decimal`. Essentially, this function is given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is made available to Python as the :attr:`modulus` attribute of @@ -789,10 +790,10 @@ --------------- Python's :term:`generator`\s provide a convenient way to implement the iterator -protocol. If a container object's :meth:`__iter__` method is implemented as a -generator, it will automatically return an iterator object (technically, a -generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__` -methods. +protocol. If a container object's :meth:`~object.__iter__` method is +implemented as a generator, it will automatically return an iterator object +(technically, a generator object) supplying the :meth:`~object.__iter__` and +:meth:`~generator.__next__` methods. More information about generators can be found in :ref:`the documentation for the yield expression `. @@ -1303,7 +1304,7 @@ only stores the ``start``, ``stop`` and ``step`` values, calculating individual items and subranges as needed). -Range objects implement the :class:`collections.Sequence` ABC, and provide +Range objects implement the :class:`collections.abc.Sequence` ABC, and provide features such as containment tests, element index lookup, slicing and support for negative indices (see :ref:`typesseq`): @@ -1477,8 +1478,8 @@ Casefolding is similar to lowercasing but more aggressive because it is intended to remove all case distinctions in a string. For example, the German lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already - lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` - converts it to ``"ss"``. + lowercase, :meth:`~str.lower` would do nothing to ``'ß'``; + :meth:`~str.casefold` converts it to ``"ss"``. The casefolding algorithm is described in section 3.13 of the Unicode Standard. @@ -1594,14 +1595,15 @@ .. method:: str.index(sub[, start[, end]]) - Like :meth:`find`, but raise :exc:`ValueError` when the substring is not found. + Like :meth:`~str.find`, but raise :exc:`ValueError` when the substring is + not found. .. method:: str.isalnum() Return true if all characters in the string are alphanumeric and there is at - least one character, false otherwise. A character ``c`` is alphanumeric if one - of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``, + least one character, false otherwise. A character ``c`` is alphanumeric if + one of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``, ``c.isdigit()``, or ``c.isnumeric()``. @@ -1763,7 +1765,7 @@ .. method:: str.rindex(sub[, start[, end]]) - Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not + Like :meth:`~str.rfind` but raises :exc:`ValueError` when the substring *sub* is not found. @@ -1787,8 +1789,8 @@ Return a list of the words in the string, using *sep* as the delimiter string. If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost* ones. If *sep* is not specified or ``None``, any whitespace string is a - separator. Except for splitting from the right, :meth:`rsplit` behaves like - :meth:`split` which is described in detail below. + separator. Except for splitting from the right, :meth:`~str.rsplit` behaves + like :meth:`~str.split` which is described in detail below. .. method:: str.rstrip([chars]) @@ -2809,11 +2811,11 @@ There are currently two built-in set types, :class:`set` and :class:`frozenset`. The :class:`set` type is mutable --- the contents can be changed using methods -like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value -and cannot be used as either a dictionary key or as an element of another set. -The :class:`frozenset` type is immutable and :term:`hashable` --- its contents cannot be -altered after it is created; it can therefore be used as a dictionary key or as -an element of another set. +like :meth:`~set.add` and :meth:`~set.remove`. Since it is mutable, it has no +hash value and cannot be used as either a dictionary key or as an element of +another set. The :class:`frozenset` type is immutable and :term:`hashable` --- +its contents cannot be altered after it is created; it can therefore be used as +a dictionary key or as an element of another set. Non-empty sets (not frozensets) can be created by placing a comma-separated list of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the @@ -2978,11 +2980,11 @@ :meth:`symmetric_difference_update` methods will accept any iterable as an argument. - Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and - :meth:`discard` methods may be a set. To support searching for an equivalent - frozenset, the *elem* set is temporarily mutated during the search and then - restored. During the search, the *elem* set should not be read or mutated - since it does not have a meaningful value. + Note, the *elem* argument to the :meth:`~object.__contains__`, + :meth:`remove`, and :meth:`discard` methods may be a set. To support + searching for an equivalent frozenset, the *elem* set is temporarily mutated + during the search and then restored. During the search, the *elem* set + should not be read or mutated since it does not have a meaningful value. .. _typesmapping: @@ -3066,13 +3068,14 @@ Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is not in the map. - If a subclass of dict defines a method :meth:`__missing__`, if the key *key* - is not present, the ``d[key]`` operation calls that method with the key *key* - as argument. The ``d[key]`` operation then returns or raises whatever is - returned or raised by the ``__missing__(key)`` call if the key is not - present. No other operations or methods invoke :meth:`__missing__`. If - :meth:`__missing__` is not defined, :exc:`KeyError` is raised. - :meth:`__missing__` must be a method; it cannot be an instance variable:: + If a subclass of dict defines a method :meth:`~dict.__missing__`, if the + key *key* is not present, the ``d[key]`` operation calls that method with + the key *key* as argument. The ``d[key]`` operation then returns or + raises whatever is returned or raised by the ``__missing__(key)`` call if + the key is not present. No other operations or methods invoke + :meth:`~dict.__missing__`. If :meth:`~dict.__missing__` is not defined, + :exc:`KeyError` is raised. :meth:`~dict.__missing__` must be a method; + it cannot be an instance variable:: >>> class Counter(dict): ... def __missing__(self, key): @@ -3311,7 +3314,7 @@ method should return a false value to indicate that the method completed successfully and does not want to suppress the raised exception. This allows context management code (such as ``contextlib.nested``) to easily detect whether - or not an :meth:`__exit__` method has actually failed. + or not an :meth:`~contextmanager.__exit__` method has actually failed. Python defines several context managers to support easy thread synchronisation, prompt closure of files or other objects, and simpler manipulation of the active @@ -3322,9 +3325,9 @@ Python's :term:`generator`\s and the :class:`contextlib.contextmanager` decorator provide a convenient way to implement these protocols. If a generator function is decorated with the :class:`contextlib.contextmanager` decorator, it will return a -context manager implementing the necessary :meth:`__enter__` and -:meth:`__exit__` methods, rather than the iterator produced by an undecorated -generator function. +context manager implementing the necessary :meth:`~contextmanager.__enter__` and +:meth:`~contextmanager.__exit__` methods, rather than the iterator produced by +an undecorated generator function. Note that there is no specific slot for any of these methods in the type structure for Python objects in the Python/C API. Extension types wanting to @@ -3354,12 +3357,13 @@ foo`` does not require a module object named *foo* to exist, rather it requires an (external) *definition* for a module named *foo* somewhere.) -A special attribute of every module is :attr:`__dict__`. This is the dictionary -containing the module's symbol table. Modifying this dictionary will actually -change the module's symbol table, but direct assignment to the :attr:`__dict__` -attribute is not possible (you can write ``m.__dict__['a'] = 1``, which defines -``m.a`` to be ``1``, but you can't write ``m.__dict__ = {}``). Modifying -:attr:`__dict__` directly is not recommended. +A special attribute of every module is :attr:`~object.__dict__`. This is the +dictionary containing the module's symbol table. Modifying this dictionary will +actually change the module's symbol table, but direct assignment to the +:attr:`~object.__dict__` attribute is not possible (you can write +``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write +``m.__dict__ = {}``). Modifying :attr:`~object.__dict__` directly is not +recommended. Modules built into the interpreter are written like this: ````. If loaded from a file, they are written as ```. + For objects that don't define :meth:`~object.__contains__`, the membership + test first tries iteration via :meth:`~object.__iter__`, then the old + sequence iteration protocol via :meth:`~object.__getitem__`, see :ref:`this + section in the language reference `. .. _numeric-types: @@ -2122,7 +2125,7 @@ (i.e., prevent it from being propagated), it should return a true value. Otherwise, the exception will be processed normally upon exit from this method. - Note that :meth:`__exit__` methods should not reraise the passed-in exception; + Note that :meth:`.__exit__` methods should not reraise the passed-in exception; this is the caller's responsibility. diff -r 7d94034e1ddc Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst Sun Oct 06 10:51:07 2013 +0200 +++ b/Doc/reference/expressions.rst Mon Oct 07 23:39:13 2013 +0300 @@ -1131,16 +1131,16 @@ For user-defined classes which define the :meth:`__contains__` method, ``x in y`` is true if and only if ``y.__contains__(x)`` is true. -For user-defined classes which do not define :meth:`__contains__` but do define -:meth:`__iter__`, ``x in y`` is true if some value ``z`` with ``x == z`` is -produced while iterating over ``y``. If an exception is raised during the -iteration, it is as if :keyword:`in` raised that exception. +For user-defined classes which do not define :meth:`~object.__contains__` but +do define :meth:`~object.__iter__`, ``x in y`` is true if some value ``z`` with +``x == z`` is produced while iterating over ``y``. If an exception is raised +during the iteration, it is as if :keyword:`in` raised that exception. Lastly, the old-style iteration protocol is tried: if a class defines -:meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative -integer index *i* such that ``x == y[i]``, and all lower integer indices do not -raise :exc:`IndexError` exception. (If any other exception is raised, it is as -if :keyword:`in` raised that exception). +:meth:`~object.__getitem__`, ``x in y`` is true if and only if there is a +non-negative integer index *i* such that ``x == y[i]``, and all lower integer +indices do not raise :exc:`IndexError` exception. (If any other exception is +raised, it is as if :keyword:`in` raised that exception). .. index:: operator: in