Merge pull request #506 from python/main

Sync Fork from Upstream Repo

Author: sthagen

Doc/c-api/import.rst

@@ -299,4 +299,8 @@ Importing Modules
    field; failure to provide the sentinel value can result in a memory fault.
    Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
    extend the internal table.  In the event of failure, no modules are added to the
-   internal table.  This should be called before :c:func:`Py_Initialize`.
+   internal table.  This must be called before :c:func:`Py_Initialize`.
+
+   If Python is initialized multiple times, :c:func:`PyImport_AppendInittab` or
+   :c:func:`PyImport_ExtendInittab` must be called before each Python
+   initialization.

Doc/c-api/init_config.rst

@@ -1193,7 +1193,10 @@ The caller is responsible to handle exceptions (error or exit) using
 
 If :c:func:`PyImport_FrozenModules`, :c:func:`PyImport_AppendInittab` or
 :c:func:`PyImport_ExtendInittab` are used, they must be set or called after
-Python preinitialization and before the Python initialization.
+Python preinitialization and before the Python initialization. If Python is
+initialized multiple times, :c:func:`PyImport_AppendInittab` or
+:c:func:`PyImport_ExtendInittab` must be called before each Python
+initialization.
 
 The current configuration (``PyConfig`` type) is stored in
 ``PyInterpreterState.config``.

Doc/c-api/veryhigh.rst

@@ -185,42 +185,6 @@ the same library that the Python runtime is using.
       :c:func:`PyMem_RawRealloc`, instead of being allocated by
       :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`.
 
-
-.. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start)
-
-   This is a simplified interface to
-   :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set
-   to ``NULL`` and *flags* set to ``0``.
-
-
-.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
-
-   This is a simplified interface to
-   :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set
-   to ``NULL``.
-
-
-.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
-
-   Parse Python source code from *str* using the start token *start* according to
-   the *flags* argument.  The result can be used to create a code object which can
-   be evaluated efficiently. This is useful if a code fragment must be evaluated
-   many times. *filename* is decoded from the :term:`filesystem encoding and
-   error handler`.
-
-
-.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
-
-   This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below,
-   leaving *flags* set to ``0``.
-
-
-.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
-
-   Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python
-   source code is read from *fp* instead of an in-memory string.
-
-
 .. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
 
    This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving

Doc/data/refcounts.dat

@@ -1791,32 +1791,6 @@ PyObject_TypeCheck:int:::
 PyObject_TypeCheck:PyObject*:o:0:
 PyObject_TypeCheck:PyTypeObject*:type:0:
 
-PyParser_SimpleParseFile:struct _node*:::
-PyParser_SimpleParseFile:FILE*:fp::
-PyParser_SimpleParseFile:const char*:filename::
-PyParser_SimpleParseFile:int:start::
-
-PyParser_SimpleParseFileFlags:struct _node*:::
-PyParser_SimpleParseFileFlags:FILE*:fp::
-PyParser_SimpleParseFileFlags:const char*:filename::
-PyParser_SimpleParseFileFlags:int:start::
-PyParser_SimpleParseFileFlags:int:flags::
-
-PyParser_SimpleParseString:struct _node*:::
-PyParser_SimpleParseString:const char*:str::
-PyParser_SimpleParseString:int:start::
-
-PyParser_SimpleParseStringFlags:struct _node*:::
-PyParser_SimpleParseStringFlags:const char*:str::
-PyParser_SimpleParseStringFlags:int:start::
-PyParser_SimpleParseStringFlags:int:flags::
-
-PyParser_SimpleParseStringFlagsFilename:struct _node*:::
-PyParser_SimpleParseStringFlagsFilename:const char*:str::
-PyParser_SimpleParseStringFlagsFilename:const char*:filename::
-PyParser_SimpleParseStringFlagsFilename:int:start::
-PyParser_SimpleParseStringFlagsFilename:int:flags::
-
 PyRun_AnyFile:int:::
 PyRun_AnyFile:FILE*:fp::
 PyRun_AnyFile:const char*:filename::

Doc/faq/design.rst

@@ -708,6 +708,15 @@ bindings are resolved at run-time in Python, and the second version only needs
 to perform the resolution once.
 
 
+Why don't generators support the with statement?
+------------------------------------------------
+
+For technical reasons, a generator used directly as a context manager
+would not work correctly.  When, as is most common, a generator is used as
+an iterator run to completion, no closing is needed.  When it is, wrap
+it as "contextlib.closing(generator)" in the 'with' statment.
+
+
 Why are colons required for the if/while/def/class statements?
 --------------------------------------------------------------
 

Doc/faq/extending.rst

@@ -275,39 +275,8 @@ for more hints.
 
 However sometimes you have to run the embedded Python interpreter in the same
 thread as your rest application and you can't allow the
-:c:func:`PyRun_InteractiveLoop` to stop while waiting for user input.  The one
-solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error``
-equal to ``E_EOF``, which means the input is incomplete.  Here's a sample code
-fragment, untested, inspired by code from Alex Farber::
-
-   #define PY_SSIZE_T_CLEAN
-   #include <Python.h>
-   #include <node.h>
-   #include <errcode.h>
-   #include <grammar.h>
-   #include <parsetok.h>
-   #include <compile.h>
-
-   int testcomplete(char *code)
-     /* code should end in \n */
-     /* return -1 for error, 0 for incomplete, 1 for complete */
-   {
-     node *n;
-     perrdetail e;
-
-     n = PyParser_ParseString(code, &_PyParser_Grammar,
-                              Py_file_input, &e);
-     if (n == NULL) {
-       if (e.error == E_EOF)
-         return 0;
-       return -1;
-     }
-
-     PyNode_Free(n);
-     return 1;
-   }
-
-Another solution is trying to compile the received string with
+:c:func:`PyRun_InteractiveLoop` to stop while waiting for user input.
+A solution is trying to compile the received string with
 :c:func:`Py_CompileString`. If it compiles without errors, try to execute the
 returned code object by calling :c:func:`PyEval_EvalCode`. Otherwise save the
 input for later. If the compilation fails, find out if it's an error or just

Doc/library/atexit.rst

@@ -39,7 +39,7 @@ internal error is detected, or when :func:`os._exit` is called.
 
    If an exception is raised during execution of the exit handlers, a traceback is
    printed (unless :exc:`SystemExit` is raised) and the exception information is
-   saved.  After all exit handlers have had a chance to run the last exception to
+   saved.  After all exit handlers have had a chance to run, the last exception to
    be raised is re-raised.
 
    This function returns *func*, which makes it possible to use it as a
@@ -73,7 +73,7 @@ automatically when the program terminates without relying on the application
 making an explicit call into this module at termination. ::
 
    try:
-       with open("counterfile") as infile:
+       with open('counterfile') as infile:
            _count = int(infile.read())
    except FileNotFoundError:
        _count = 0
@@ -83,21 +83,22 @@ making an explicit call into this module at termination. ::
        _count = _count + n
 
    def savecounter():
-       with open("counterfile", "w") as outfile:
-           outfile.write("%d" % _count)
+       with open('counterfile', 'w') as outfile:
+           outfile.write('%d' % _count)
 
    import atexit
+
    atexit.register(savecounter)
 
 Positional and keyword arguments may also be passed to :func:`register` to be
 passed along to the registered function when it is called::
 
    def goodbye(name, adjective):
-       print('Goodbye, %s, it was %s to meet you.' % (name, adjective))
+       print('Goodbye %s, it was %s to meet you.' % (name, adjective))
 
    import atexit
-   atexit.register(goodbye, 'Donny', 'nice')
 
+   atexit.register(goodbye, 'Donny', 'nice')
    # or:
    atexit.register(goodbye, adjective='nice', name='Donny')
 
@@ -107,6 +108,6 @@ Usage as a :term:`decorator`::
 
    @atexit.register
    def goodbye():
-       print("You are now leaving the Python sector.")
+       print('You are now leaving the Python sector.')
 
 This only works with functions that can be called without arguments.

Doc/library/collections.rst

@@ -707,9 +707,9 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
 :class:`defaultdict` objects
 ----------------------------
 
-.. class:: defaultdict([default_factory[, ...]])
+.. class:: defaultdict(default_factory=None, /, [...])
 
-    Returns a new dictionary-like object.  :class:`defaultdict` is a subclass of the
+    Return a new dictionary-like object.  :class:`defaultdict` is a subclass of the
     built-in :class:`dict` class.  It overrides one method and adds one writable
     instance variable.  The remaining functionality is the same as for the
     :class:`dict` class and is not documented here.

Doc/library/faulthandler.rst

@@ -76,6 +76,10 @@ Fault handler state
    .. versionchanged:: 3.6
       On Windows, a handler for Windows exception is also installed.
 
+   .. versionchanged:: 3.10
+      The dump now mentions if a garbage collector collection is running
+      if *all_threads* is true.
+
 .. function:: disable()
 
    Disable the fault handler: uninstall the signal handlers installed by

Doc/library/inspect.rst

@@ -1450,10 +1450,6 @@ the following flags:
    The flag is set when the code object is a generator function, i.e.
    a generator object is returned when the code object is executed.
 
-.. data:: CO_NOFREE
-
-   The flag is set if there are no free or cell variables.
-
 .. data:: CO_COROUTINE
 
    The flag is set when the code object is a coroutine function.