Merge branch 'master' into die-idna-die

Author: asvetlov

.github/CODE_OF_CONDUCT.rst

@@ -0,0 +1,14 @@
+Code of Conduct
+===============
+
+Please note that all interactions on
+`Python Software Foundation <https://www.python.org/psf-landing/>`__-supported
+infrastructure is `covered
+<https://www.python.org/psf/records/board/minutes/2014-01-06/#management-of-the-psfs-web-properties>`__
+by the `PSF Code of Conduct <https://www.python.org/psf/codeofconduct/>`__,
+which includes all infrastructure used in the development of Python itself
+(e.g. mailing lists, issue trackers, GitHub, etc.).
+
+In general this means everyone is expected to be open, considerate, and
+respectful of others no matter what their position is within the project.
+

.travis.yml

@@ -91,6 +91,8 @@ script:
   - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then ./python Tools/scripts/patchcheck.py --travis $TRAVIS_PULL_REQUEST; fi
   # `-r -w` implicitly provided through `make buildbottest`.
   - make buildbottest TESTOPTS="-j4 -uall,-cpu"
+  # Check that all symbols exported by libpython start with "Py" or "_Py"
+  - make smelly
 
 notifications:
   email: false

Doc/c-api/init.rst

@@ -1246,7 +1246,7 @@ CPython interpreter.  This API uses a new type :c:type:`Py_tss_t` instead of
 
 .. c:macro:: Py_tss_NEEDS_INIT
 
-   This macro expands to the default value for :c:type:`Py_tss_t` variables.
+   This macro expands to the initializer for :c:type:`Py_tss_t` variables.
    Note that this macro won't be defined with :ref:`Py_LIMITED_API <stable>`.
 
 

Doc/c-api/memory.rst

@@ -150,7 +150,7 @@ The default raw memory block allocator uses the following functions:
 
    Frees the memory block pointed to by *p*, which must have been returned by a
    previous call to :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc` or
-   :c:func:`PyMem_RawCalloc`.  Otherwise, or if ``PyMem_Free(p)`` has been
+   :c:func:`PyMem_RawCalloc`.  Otherwise, or if ``PyMem_RawFree(p)`` has been
    called before, undefined behavior occurs.
 
    If *p* is *NULL*, no operation is performed.
@@ -263,6 +263,69 @@ versions and is therefore deprecated in extension modules.
 * ``PyMem_DEL(ptr)``
 
 
+Object allocators
+=================
+
+The following function sets, modeled after the ANSI C standard, but specifying
+behavior when requesting zero bytes, are available for allocating and releasing
+memory from the Python heap.
+
+By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`.
+
+.. warning::
+
+   The :term:`GIL <global interpreter lock>` must be held when using these
+   functions.
+
+.. c:function:: void* PyObject_Malloc(size_t n)
+
+   Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
+   allocated memory, or *NULL* if the request fails.
+
+   Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as
+   if ``PyObject_Malloc(1)`` had been called instead. The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a distinct
+   non-*NULL* pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called
+   instead.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: void* PyObject_Realloc(void *p, size_t n)
+
+   Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
+   unchanged to the minimum of the old and the new sizes.
+
+   If *p* is *NULL*, the call is equivalent to ``PyObject_Malloc(n)``; else if *n*
+   is equal to zero, the memory block is resized but is not freed, and the
+   returned pointer is non-*NULL*.
+
+   Unless *p* is *NULL*, it must have been returned by a previous call to
+   :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`.
+
+   If the request fails, :c:func:`PyObject_Realloc` returns *NULL* and *p* remains
+   a valid pointer to the previous memory area.
+
+
+.. c:function:: void PyObject_Free(void *p)
+
+   Frees the memory block pointed to by *p*, which must have been returned by a
+   previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or
+   :c:func:`PyObject_Calloc`.  Otherwise, or if ``PyObject_Free(p)`` has been called
+   before, undefined behavior occurs.
+
+   If *p* is *NULL*, no operation is performed.
+
+
 Customize Memory Allocators
 ===========================
 

Doc/c-api/typeobj.rst

@@ -623,6 +623,22 @@ type objects) *must* have the :attr:`ob_size` field.
    | :const:`Py_GE` | ``>=``     |
    +----------------+------------+
 
+   The following macro is defined to ease writing rich comparison functions:
+
+   .. c:function:: PyObject *Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op)
+
+      Return ``Py_True`` or ``Py_False`` from the function, depending on the
+      result of a comparison.
+      VAL_A and VAL_B must be orderable by C comparison operators (for example,
+      they may be C ints or floats). The third argument specifies the requested
+      operation, as for :c:func:`PyObject_RichCompare`.
+
+      The return value's reference count is properly incremented.
+
+      On error, sets an exception and returns NULL from the function.
+
+      .. versionadded:: 3.7
+
 
 .. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset
 

Doc/library/asyncio-eventloop.rst

@@ -341,9 +341,10 @@ Creating connections
 
 .. coroutinemethod:: AbstractEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)
 
-   Create datagram connection: socket family :py:data:`~socket.AF_INET` or
-   :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
-   socket type :py:data:`~socket.SOCK_DGRAM`. *protocol_factory* must be a
+   Create datagram connection: socket family :py:data:`~socket.AF_INET`,
+   :py:data:`~socket.AF_INET6` or :py:data:`~socket.AF_UNIX` depending on
+   *host* (or *family* if specified), socket type
+   :py:data:`~socket.SOCK_DGRAM`. *protocol_factory* must be a
    callable returning a :ref:`protocol <asyncio-protocol>` instance.
 
    This method is a :ref:`coroutine <coroutine>` which will try to
@@ -554,6 +555,21 @@ Low-level socket operations
 
    This method is a :ref:`coroutine <coroutine>`.
 
+.. coroutinemethod:: AbstractEventLoop.sock_recv_into(sock, buf)
+
+   Receive data from the socket.  Modeled after blocking
+   :meth:`socket.socket.recv_into` method.
+
+   The received data is written into *buf* (a writable buffer).
+   The return value is the number of bytes written.
+
+   With :class:`SelectorEventLoop` event loop, the socket *sock* must be
+   non-blocking.
+
+   This method is a :ref:`coroutine <coroutine>`.
+
+   .. versionadded:: 3.7
+
 .. coroutinemethod:: AbstractEventLoop.sock_sendall(sock, data)
 
    Send data to the socket.  Modeled after blocking

Doc/library/calendar.rst

@@ -19,11 +19,13 @@ the week to Sunday (6) or to any other weekday.  Parameters that specify dates
 are given as integers. For related
 functionality, see also the :mod:`datetime` and :mod:`time` modules.
 
-Most of these functions and classes rely on the :mod:`datetime` module which
-uses an idealized calendar, the current Gregorian calendar extended
+The functions and classes defined in this module
+use an idealized calendar, the current Gregorian calendar extended indefinitely
 in both directions.  This matches the definition of the "proleptic Gregorian"
 calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
-it's the base calendar for all computations.
+it's the base calendar for all computations.  Zero and negative years are
+interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
+2 BC, and so on.
 
 
 .. class:: Calendar(firstweekday=0)
@@ -53,17 +55,40 @@ it's the base calendar for all computations.
       month that are required to get a complete week.
 
 
+   .. method:: itermonthdays(year, month)
+
+      Return an iterator for the month *month* in the year *year* similar to
+      :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+      range. Days returned will simply be day of the month numbers.  For the
+      days outside of the specified month, the day number is ``0``.
+
+
    .. method:: itermonthdays2(year, month)
 
       Return an iterator for the month *month* in the year *year* similar to
-      :meth:`itermonthdates`. Days returned will be tuples consisting of a day
+      :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+      range. Days returned will be tuples consisting of a day of the month
       number and a week day number.
 
 
-   .. method:: itermonthdays(year, month)
+   .. method:: itermonthdays3(year, month)
+
+      Return an iterator for the month *month* in the year *year* similar to
+      :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+      range. Days returned will be tuples consisting of a year, a month and a day
+      of the month numbers.
+
+      .. versionadded:: 3.7
+
+
+   .. method:: itermonthdays4(year, month)
 
       Return an iterator for the month *month* in the year *year* similar to
-      :meth:`itermonthdates`. Days returned will simply be day numbers.
+      :meth:`itermonthdates`, but not restricted by the :class:`datetime.date`
+      range. Days returned will be tuples consisting of a year, a month, a day
+      of the month, and a day of the week numbers.
+
+      .. versionadded:: 3.7
 
 
    .. method:: monthdatescalendar(year, month)

Doc/library/configparser.rst

@@ -995,7 +995,8 @@ ConfigParser Objects
       Attempt to read and parse a list of filenames, returning a list of
       filenames which were successfully parsed.
 
-      If *filenames* is a string or :term:`path-like object`, it is treated as
+      If *filenames* is a string, a :class:`bytes` object or a
+      :term:`path-like object`, it is treated as
       a single filename.  If a file named in *filenames* cannot be opened, that
       file will be ignored.  This is designed so that you can specify a list of
       potential configuration file locations (for example, the current
@@ -1022,6 +1023,9 @@ ConfigParser Objects
       .. versionadded:: 3.6.1
          The *filenames* parameter accepts a :term:`path-like object`.
 
+      .. versionadded:: 3.7
+         The *filenames* parameter accepts a :class:`bytes` object.
+
 
    .. method:: read_file(f, source=None)
 

Doc/library/crypt.rst

@@ -41,17 +41,24 @@ are available on all platforms):
 .. data:: METHOD_SHA512
 
    A Modular Crypt Format method with 16 character salt and 86 character
-   hash.  This is the strongest method.
+   hash based on the SHA-512 hash function.  This is the strongest method.
 
 .. data:: METHOD_SHA256
 
    Another Modular Crypt Format method with 16 character salt and 43
-   character hash.
+   character hash based on the SHA-256 hash function.
+
+.. data:: METHOD_BLOWFISH
+
+   Another Modular Crypt Format method with 22 character salt and 31
+   character hash based on the Blowfish cipher.
+
+   .. versionadded:: 3.7
 
 .. data:: METHOD_MD5
 
    Another Modular Crypt Format method with 8 character salt and 22
-   character hash.
+   character hash based on the MD5 hash function.
 
 .. data:: METHOD_CRYPT
 
@@ -109,19 +116,25 @@ The :mod:`crypt` module defines the following functions:
       Accept ``crypt.METHOD_*`` values in addition to strings for *salt*.
 
 
-.. function:: mksalt(method=None)
+.. function:: mksalt(method=None, *, log_rounds=12)
 
    Return a randomly generated salt of the specified method.  If no
    *method* is given, the strongest method available as returned by
    :func:`methods` is used.
 
-   The return value is a string either of 2 characters in length for
-   ``crypt.METHOD_CRYPT``, or 19 characters starting with ``$digit$`` and
-   16 random characters from the set ``[./a-zA-Z0-9]``, suitable for
-   passing as the *salt* argument to :func:`crypt`.
+   The return value is a string suitable for passing as the *salt* argument
+   to :func:`crypt`.
+
+   *log_rounds* specifies the binary logarithm of the number of rounds
+   for ``crypt.METHOD_BLOWFISH``, and is ignored otherwise.  ``8`` specifies
+   ``256`` rounds.
 
    .. versionadded:: 3.3
 
+   .. versionchanged:: 3.7
+      Added the *log_rounds* parameter.
+
+
 Examples
 --------
 

Doc/library/csv.rst

@@ -172,7 +172,7 @@ The :mod:`csv` module defines the following classes:
    A short usage example::
 
        >>> import csv
-       >>> with open('names.csv') as csvfile:
+       >>> with open('names.csv', newline='') as csvfile:
        ...     reader = csv.DictReader(csvfile)
        ...     for row in reader:
        ...         print(row['first_name'], row['last_name'])
@@ -211,7 +211,7 @@ The :mod:`csv` module defines the following classes:
 
        import csv
 
-       with open('names.csv', 'w') as csvfile:
+       with open('names.csv', 'w', newline='') as csvfile:
            fieldnames = ['first_name', 'last_name']
            writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
 
@@ -270,7 +270,7 @@ The :mod:`csv` module defines the following classes:
 
 An example for :class:`Sniffer` use::
 
-   with open('example.csv') as csvfile:
+   with open('example.csv', newline='') as csvfile:
        dialect = csv.Sniffer().sniff(csvfile.read(1024))
        csvfile.seek(0)
        reader = csv.reader(csvfile, dialect)