diff -r 7d94034e1ddc Doc/glossary.rst --- a/Doc/glossary.rst Sun Oct 06 10:51:07 2013 +0200 +++ b/Doc/glossary.rst Tue Oct 08 11:29:07 2013 +0300 @@ -416,8 +416,9 @@ :func:`next`) return successive items in the stream. When no more data are available a :exc:`StopIteration` exception is raised instead. At this point, the iterator object is exhausted and any further calls to its - :meth:`__next__` method just raise :exc:`StopIteration` again. Iterators - are required to have an :meth:`__iter__` method that returns the iterator + :meth:`~iterator.__next__` method just raise :exc:`StopIteration` again. + Iterators are required to have an :meth:`~iterator.__iter__` method that + returns the iterator object itself so every iterator is also iterable and may be used in most places where other iterables are accepted. One notable exception is code which attempts multiple iteration passes. A container object (such as a @@ -554,9 +555,9 @@ dictionaries. There are the local, global and built-in namespaces as well as nested namespaces in objects (in methods). Namespaces support modularity by preventing naming conflicts. For instance, the functions - :func:`builtins.open` and :func:`os.open` are distinguished by their - namespaces. Namespaces also aid readability and maintainability by making - it clear which module implements a function. For instance, writing + :func:`builtins.open <.open>` and :func:`os.open` are distinguished by + their namespaces. Namespaces also aid readability and maintainability by + making it clear which module implements a function. For instance, writing :func:`random.seed` or :func:`itertools.islice` makes it clear that those functions are implemented by the :mod:`random` and :mod:`itertools` modules, respectively. @@ -579,8 +580,8 @@ new-style class Old name for the flavor of classes now used for all class objects. In earlier Python versions, only new-style classes could use Python's newer, - versatile features like :attr:`__slots__`, descriptors, properties, - :meth:`__getattribute__`, class methods, and static methods. + versatile features like :attr:`~object.__slots__`, descriptors, + properties, :meth:`__getattribute__`, class methods, and static methods. object Any data with state (attributes or value) and defined behavior @@ -795,7 +796,8 @@ type The type of a Python object determines what kind of object it is; every object has a type. An object's type is accessible as its - :attr:`__class__` attribute or can be retrieved with ``type(obj)``. + :attr:`~instance.__class__` attribute or can be retrieved with + ``type(obj)``. universal newlines A manner of interpreting text streams in which all of the following are 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 Tue Oct 08 11:29:07 2013 +0300 @@ -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 @@ -543,6 +543,7 @@ :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` if *format_spec* is not empty string. @@ -717,7 +718,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,8 +827,8 @@ .. 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) @@ -905,9 +906,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 +1116,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): @@ -1224,13 +1225,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 +1311,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 @@ -1375,7 +1377,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 + :attr:`object.__class__ `. The :func:`isinstance` built-in function is recommended for testing the type of an object, because it takes subclasses into account. @@ -1383,11 +1386,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 +1402,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 Tue Oct 08 11:29:07 2013 +0300 @@ -157,7 +157,7 @@ return a value from :meth:`__add__`, we'd miss the possibility that ``B`` defines a more intelligent :meth:`__radd__`, so the boilerplate should return :const:`NotImplemented` from - :meth:`__add__`. (Or ``A`` may not implement :meth:`__add__` at + :meth:`__add__`. (Or ``A`` may not implement :meth:`__add__` at all.) 3. Then ``B``'s :meth:`__radd__` gets a chance. If it accepts ``a``, all is well. 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 Tue Oct 08 11:29:07 2013 +0300 @@ -339,8 +339,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 "+" @@ -631,10 +631,10 @@ :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 +made available to Python as the :attr:`~sys.hash_info.modulus` attribute of :data:`sys.hash_info`. .. impl-detail:: @@ -1303,7 +1303,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`): @@ -1326,9 +1326,9 @@ Testing range objects for equality with ``==`` and ``!=`` compares them as sequences. That is, two range objects are considered equal if they represent the same sequence of values. (Note that two range -objects that compare equal might have different :attr:`start`, -:attr:`stop` and :attr:`step` attributes, for example ``range(0) == -range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.) +objects that compare equal might have different :attr:`~range.start`, +:attr:`~range.stop` and :attr:`~range.step` attributes, for example +``range(0) == range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.) .. versionchanged:: 3.2 Implement the Sequence ABC. @@ -1342,7 +1342,8 @@ object identity). .. versionadded:: 3.3 - The :attr:`start`, :attr:`stop` and :attr:`step` attributes. + The :attr:`~range.start`, :attr:`~range.stop` and :attr:`~range.step` + attributes. .. index:: @@ -2298,7 +2299,7 @@ (inclusive) as their first argument. -Each bytes and bytearray instance provides a :meth:`decode` convenience +Each bytes and bytearray instance provides a :meth:`~bytes.decode` convenience method that is the inverse of :meth:`str.encode`: .. method:: bytes.decode(encoding="utf-8", errors="strict") @@ -2809,11 +2810,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 @@ -3354,12 +3355,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 ```` is used, it treats the supplied expression as a subiterator. All values produced by that subiterator are passed directly to the caller of the current generator's methods. Any values passed in with -:meth:`send` and any exceptions passed in with :meth:`throw` are passed to -the underlying iterator if it has the appropriate methods. If this is not the -case, then :meth:`send` will raise :exc:`AttributeError` or :exc:`TypeError`, -while :meth:`throw` will just raise the passed in exception immediately. +:meth:`~generator.send` and any exceptions passed in with +:meth:`~generator.throw` are passed to the underlying iterator if it has the +appropriate methods. If this is not the case, then :meth:`~generator.send` +will raise :exc:`AttributeError` or :exc:`TypeError`, while +:meth:`~generator.throw` will just raise the passed in exception immediately. When the underlying iterator is complete, the :attr:`~StopIteration.value` attribute of the raised :exc:`StopIteration` instance becomes the value of @@ -388,6 +389,7 @@ is already executing raises a :exc:`ValueError` exception. .. index:: exception: StopIteration +.. class:: generator .. method:: generator.__next__() @@ -438,6 +440,7 @@ other exception, it is propagated to the caller. :meth:`close` does nothing if the generator has already exited due to an exception or normal exit. +.. class:: . .. index:: single: yield; examples @@ -630,10 +633,10 @@ containing the conversion of the slice items; otherwise, the conversion of the lone slice item is the key. The conversion of a slice item that is an expression is that expression. The conversion of a proper slice is a slice -object (see section :ref:`types`) whose :attr:`start`, :attr:`stop` and -:attr:`step` attributes are the values of the expressions given as lower bound, -upper bound and stride, respectively, substituting ``None`` for missing -expressions. +object (see section :ref:`types`) whose :attr:`~slice.start`, +:attr:`~slice.stop` and :attr:`~slice.step` attributes are the values of the +expressions given as lower bound, upper bound and stride, respectively, +substituting ``None`` for missing expressions. .. index::