#22613: minor other fixes in library docs (thanks Jacques Ducasse)

birkenfeld · birkenfeld · commit 8ed75cd8e931 · 2014-10-31T10:25:48.000+01:00
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
@@ -134,7 +134,7 @@ particular functionality, for example::
 
 Several of the ABCs are also useful as mixins that make it easier to develop
 classes supporting container APIs.  For example, to write a class supporting
-the full :class:`Set` API, it only necessary to supply the three underlying
+the full :class:`Set` API, it is only necessary to supply the three underlying
 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
 The ABC supplies the remaining methods such as :meth:`__and__` and
 :meth:`isdisjoint`::
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
@@ -908,7 +908,7 @@ customize a prototype instance:
     >>> janes_account = default_account._replace(owner='Jane')
 
 Enumerated constants can be implemented with named tuples, but it is simpler
-and more efficient to use a simple :class:`~enum.Enum` :
+and more efficient to use a simple :class:`~enum.Enum`:
 
     >>> Status = namedtuple('Status', 'open pending closed')._make(range(3))
     >>> Status.open, Status.pending, Status.closed
@@ -917,6 +917,9 @@ and more efficient to use a simple :class:`~enum.Enum` :
     >>> class Status(Enum):
     ...     open, pending, closed = range(3)
 
+
+.. seealso::
+
     * `Recipe for named tuple abstract base class with a metaclass mix-in
       <http://code.activestate.com/recipes/577629-namedtupleabc-abstract-base-class-mix-in-for-named/>`_
       by Jan Kaliszewski.  Besides providing an :term:`abstract base class` for
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
@@ -1833,7 +1833,7 @@ Utility functions
 .. function:: find_msvcrt()
    :module: ctypes.util
 
-   Windows only: return the filename of the VC runtype library used by Python,
+   Windows only: return the filename of the VC runtime library used by Python,
    and by the extension modules.  If the name of the library cannot be
    determined, ``None`` is returned.
 
@@ -2335,11 +2335,6 @@ other data types containing pointer type fields.
       and so on).  Later assignments to the :attr:`_fields_` class variable will
       raise an AttributeError.
 
-      Structure and union subclass constructors accept both positional and named
-      arguments.  Positional arguments are used to initialize the fields in the
-      same order as they appear in the :attr:`_fields_` definition, named
-      arguments are used to initialize the fields with the corresponding name.
-
       It is possible to defined sub-subclasses of structure types, they inherit
       the fields of the base class plus the :attr:`_fields_` defined in the
       sub-subclass, if any.
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
@@ -750,17 +750,20 @@ Classes and functions
    :func:`getargspec` or :func:`getfullargspec`.
 
    The first seven arguments are (``args``, ``varargs``, ``varkw``,
-   ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``). The
-   other five arguments are the corresponding optional formatting functions
-   that are called to turn names and values into strings. The last argument
-   is an optional function to format the sequence of arguments. For example::
+   ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``).
 
-    >>> from inspect import formatargspec, getfullargspec
-    >>> def f(a: int, b: float):
-    ...     pass
-    ...
-    >>> formatargspec(*getfullargspec(f))
-    '(a: int, b: float)'
+   The other six arguments are functions that are called to turn argument names,
+   ``*`` argument name, ``**`` argument name, default values, return annotation
+   and individual annotations into strings, respectively.
+
+   For example:
+
+   >>> from inspect import formatargspec, getfullargspec
+   >>> def f(a: int, b: float):
+   ...     pass
+   ...
+   >>> formatargspec(*getfullargspec(f))
+   '(a: int, b: float)'
 
 
 .. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])
diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst
@@ -20,6 +20,13 @@ The :mod:`pydoc` module automatically generates documentation from Python
 modules.  The documentation can be presented as pages of text on the console,
 served to a Web browser, or saved to HTML files.
 
+For modules, classes, functions and methods, the displayed documentation is
+derived from the docstring (i.e. the :attr:`__doc__` attribute) of the object,
+and recursively of its documentable members.  If there is no docstring,
+:mod:`pydoc` tries to obtain a description from the block of comment lines just
+above the definition of the class, function or method in the source file, or at
+the top of the module (see :func:`inspect.getcomments`).
+
 The built-in function :func:`help` invokes the online help system in the
 interactive interpreter, which uses :mod:`pydoc` to generate its documentation
 as text on the console.  The same text documentation can also be viewed from
diff --git a/Doc/library/reprlib.rst b/Doc/library/reprlib.rst
@@ -156,4 +156,3 @@ for file objects could be added::
 
    aRepr = MyRepr()
    print(aRepr.repr(sys.stdin))         # prints '<stdin>'
-
diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst
@@ -127,9 +127,6 @@ The :mod:`runpy` module provides two functions:
    supplied path, and ``__spec__``, ``__cached__``, ``__loader__`` and
    ``__package__`` will all be set to :const:`None`.
 
-   ``__spec__`` will be set to :const:`None` if the supplied path is a
-   direct path to a script (as source or as precompiled bytecode).
-
    If the supplied path is a reference to a valid sys.path entry, then
    ``__spec__`` will be set appropriately for the imported ``__main__``
    module (that is, ``__spec__.name`` will always be ``__main__``).
diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
@@ -192,7 +192,7 @@ The module defines the following user-callable items:
          >>> os.path.exists(f.name)
          False
 
-The module uses two global variables that tell it how to construct a
+The module uses a global variable that tell it how to construct a
 temporary name.  They are initialized at the first call to any of the
 functions above.  The caller may change them, but this is discouraged; use
 the appropriate function arguments, instead.
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
@@ -461,14 +461,19 @@ the `new_callable` argument to `patch`.
     .. attribute:: side_effect
 
         This can either be a function to be called when the mock is called,
-        or an exception (class or instance) to be raised.
+        an iterable or an exception (class or instance) to be raised.
 
         If you pass in a function it will be called with same arguments as the
         mock and unless the function returns the :data:`DEFAULT` singleton the
         call to the mock will then return whatever the function returns. If the
         function returns :data:`DEFAULT` then the mock will return its normal
         value (from the :attr:`return_value`).
 
+        If you pass in an iterable, it is used to retrieve an iterator which
+        must yield a value on every call.  This value can either be an exception
+        instance to be raised, or a value to be returned from the call to the
+        mock (:data:`DEFAULT` handling is identical to the function case).
+
         An example of a mock that raises an exception (to test exception
         handling of an API):
 
@@ -486,11 +491,7 @@ the `new_callable` argument to `patch`.
             >>> mock(), mock(), mock()
             (3, 2, 1)
 
-        The :attr:`side_effect` function is called with the same arguments as the
-        mock (so it is wise for it to take arbitrary args and keyword
-        arguments) and whatever it returns is used as the return value for
-        the call. The exception is if :attr:`side_effect` returns :data:`DEFAULT`,
-        in which case the normal :attr:`return_value` is used.
+        Using a callable:
 
             >>> mock = Mock(return_value=3)
             >>> def side_effect(*args, **kwargs):
@@ -1011,7 +1012,7 @@ patch
     used.
 
     A more powerful form of *spec* is *autospec*. If you set ``autospec=True``
-    then the mock with be created with a spec from the object being replaced.
+    then the mock will be created with a spec from the object being replaced.
     All attributes of the mock will also have the spec of the corresponding
     attribute of the object being replaced. Methods and functions being mocked
     will have their arguments checked and will raise a :exc:`TypeError` if they are

Original file line number	Diff line number	Diff line change
`@@ -156,4 +156,3 @@ for file objects could be added::`
`156`	`156`
`157`	`157`	`aRepr = MyRepr()`
`158`	`158`	`print(aRepr.repr(sys.stdin)) # prints '<stdin>'`
`159`		`-`