Merge branch 'python:main' into getdoc-fix

Author: lincolnj1

Doc/c-api/init_config.rst

@@ -505,6 +505,10 @@ Configuration Options
      - :c:member:`use_hash_seed <PyConfig.use_hash_seed>`
      - ``bool``
      - Read-only
+   * - ``"use_system_logger"``
+     - :c:member:`use_system_logger <PyConfig.use_system_logger>`
+     - ``bool``
+     - Read-only
    * - ``"user_site_directory"``
      - :c:member:`user_site_directory <PyConfig.user_site_directory>`
      - ``bool``
@@ -1927,9 +1931,10 @@ PyConfig
 
       Only available on macOS 10.12 and later, and on iOS.
 
-      Default: ``0`` (don't use system log).
+      Default: ``0`` (don't use the system log) on macOS; ``1`` on iOS (use the
+      system log).
 
-      .. versionadded:: 3.13.2
+      .. versionadded:: 3.14
 
    .. c:member:: int user_site_directory
 

Doc/data/stable_abi.dat

@@ -11,7 +11,6 @@ The following modules have a command-line interface.
 * :mod:`code`
 * :ref:`compileall <compileall-cli>`
 * :mod:`cProfile`: see :ref:`profile <profile-cli>`
-* :ref:`difflib <difflib-interface>`
 * :ref:`dis <dis-cli>`
 * :mod:`doctest`
 * :mod:`!encodings.rot_13`
@@ -24,7 +23,7 @@ The following modules have a command-line interface.
 * :mod:`!idlelib`
 * :ref:`inspect <inspect-module-cli>`
 * :ref:`json <json-commandline>`
-* :mod:`mimetypes`
+* :ref:`mimetypes <mimetypes-cli>`
 * :mod:`pdb`
 * :mod:`pickle`
 * :ref:`pickletools <pickletools-cli>`

Doc/library/cmdline.rst

@@ -40,11 +40,14 @@ Executor Objects
              future = executor.submit(pow, 323, 1235)
              print(future.result())
 
-   .. method:: map(fn, *iterables, timeout=None, chunksize=1)
+   .. method:: map(fn, *iterables, timeout=None, chunksize=1, buffersize=None)
 
       Similar to :func:`map(fn, *iterables) <map>` except:
 
-      * the *iterables* are collected immediately rather than lazily;
+      * The *iterables* are collected immediately rather than lazily, unless a
+        *buffersize* is specified to limit the number of submitted tasks whose
+        results have not yet been yielded. If the buffer is full, iteration over
+        the *iterables* pauses until a result is yielded from the buffer.
 
       * *fn* is executed asynchronously and several calls to
         *fn* may be made concurrently.
@@ -68,7 +71,10 @@ Executor Objects
       *chunksize* has no effect.
 
       .. versionchanged:: 3.5
-         Added the *chunksize* argument.
+         Added the *chunksize* parameter.
+
+      .. versionchanged:: next
+         Added the *buffersize* parameter.
 
    .. method:: shutdown(wait=True, *, cancel_futures=False)
 

Doc/library/concurrent.futures.rst

@@ -191,7 +191,7 @@ An example usage of the module::
 
 .. _mimetypes-objects:
 
-MimeTypes Objects
+MimeTypes objects
 -----------------
 
 The :class:`MimeTypes` class may be useful for applications which may want more
@@ -307,3 +307,97 @@ than one MIME-type database; it provides an interface similar to the one of the
 
       When *strict* is ``True`` (the default), the mapping will be added to the
       official MIME types, otherwise to the non-standard ones.
+
+
+.. _mimetypes-cli:
+
+Command-line usage
+------------------
+
+The :mod:`!mimetypes` module can be executed as a script from the command line.
+
+.. code-block:: sh
+
+   python -m mimetypes [-h] [-e] [-l] type [type ...]
+
+The following options are accepted:
+
+.. program:: mimetypes
+
+.. cmdoption:: -h
+               --help
+
+   Show the help message and exit.
+
+.. cmdoption:: -e
+               --extension
+
+   Guess extension instead of type.
+
+.. cmdoption:: -l
+               --lenient
+
+   Additionally search for some common, but non-standard types.
+
+By default the script converts MIME types to file extensions.
+However, if ``--extension`` is specified,
+it converts file extensions to MIME types.
+
+For each ``type`` entry, the script writes a line into the standard output
+stream. If an unknown type occurs, it writes an error message into the
+standard error stream and exits with the return code ``1``.
+
+
+.. mimetypes-cli-example:
+
+Command-line example
+--------------------
+
+Here are some examples of typical usage of the :mod:`!mimetypes` command-line
+interface:
+
+.. code-block:: console
+
+   $ # get a MIME type by a file name
+   $ python -m mimetypes filename.png
+   type: image/png encoding: None
+
+   $ # get a MIME type by a URL
+   $ python -m mimetypes https://example.com/filename.txt
+   type: text/plain encoding: None
+
+   $ # get a complex MIME type
+   $ python -m mimetypes filename.tar.gz
+   type: application/x-tar encoding: gzip
+
+   $ # get a MIME type for a rare file extension
+   $ python -m mimetypes filename.pict
+   error: unknown extension of filename.pict
+
+   $ # now look in the extended database built into Python
+   $ python -m mimetypes --lenient filename.pict
+   type: image/pict encoding: None
+
+   $ # get a file extension by a MIME type
+   $ python -m mimetypes --extension text/javascript
+   .js
+
+   $ # get a file extension by a rare MIME type
+   $ python -m mimetypes --extension text/xul
+   error: unknown type text/xul
+
+   $ # now look in the extended database again
+   $ python -m mimetypes --extension --lenient text/xul
+   .xul
+
+   $ # try to feed an unknown file extension
+   $ python -m mimetypes filename.sh filename.nc filename.xxx filename.txt
+   type: application/x-sh encoding: None
+   type: application/x-netcdf encoding: None
+   error: unknown extension of filename.xxx
+
+   $ # try to feed an unknown MIME type
+   $ python -m mimetypes --extension audio/aac audio/opus audio/future audio/x-wav
+   .aac
+   .opus
+   error: unknown type audio/future

Doc/library/mimetypes.rst

@@ -297,7 +297,7 @@ To add Python to an iOS Xcode project:
    * Writing bytecode (:c:member:`PyConfig.write_bytecode`) is *disabled*;
    * Signal handlers (:c:member:`PyConfig.install_signal_handlers`) are *enabled*;
    * System logging (:c:member:`PyConfig.use_system_logger`) is *enabled*
-     (optional, but strongly recommended);
+     (optional, but strongly recommended; this is enabled by default);
    * ``PYTHONHOME`` for the interpreter is configured to point at the
      ``python`` subfolder of your app's bundle; and
    * The ``PYTHONPATH`` for the interpreter includes:

Doc/using/ios.rst

@@ -465,6 +465,13 @@ contextvars
 * Support context manager protocol by :class:`contextvars.Token`.
   (Contributed by Andrew Svetlov in :gh:`129889`.)
 
+* Add the optional ``buffersize`` parameter to
+  :meth:`concurrent.futures.Executor.map` to limit the number of submitted
+  tasks whose results have not yet been yielded. If the buffer is full,
+  iteration over the *iterables* pauses until a result is yielded from the
+  buffer.
+  (Contributed by Enzo Bonnal and Josh Rosenberg in :gh:`74028`.)
+
 
 ctypes
 ------
@@ -645,6 +652,13 @@ json
 mimetypes
 ---------
 
+* Document the command-line for :mod:`mimetypes`.
+  It now exits with ``1`` on failure instead of ``0``
+  and ``2`` on incorrect command-line parameters instead of ``1``.
+  Also, errors are printed to stderr instead of stdout and their text is made
+  tighter.
+  (Contributed by Oleg Iarygin and Hugo van Kemenade in :gh:`93096`.)
+
 * Add MS and :rfc:`8081` MIME types for fonts:
 
   * Embedded OpenType: ``application/vnd.ms-fontobject``
@@ -1584,9 +1598,10 @@ Limited C API changes
   implementation details.
   (Contributed by Victor Stinner in :gh:`120600` and :gh:`124127`.)
 
-* Remove :c:func:`PySequence_Fast` from the limited C API, since this function
-  has to be used with :c:macro:`PySequence_Fast_GET_ITEM` which never worked
-  in the limited C API.
+* Remove the :c:macro:`PySequence_Fast_GET_SIZE`,
+  :c:macro:`PySequence_Fast_GET_ITEM` and :c:macro:`PySequence_Fast_ITEMS`
+  macros from the limited C API, since these macros never worked in the limited
+  C API. Keep :c:func:`PySequence_Fast` in the limited C API.
   (Contributed by Victor Stinner in :gh:`91417`.)
 
 

Doc/whatsnew/3.14.rst

@@ -726,6 +726,15 @@ PyAPI_FUNC(PyObject *) PySequence_Tuple(PyObject *o);
    This is equivalent to the Python expression: list(o) */
 PyAPI_FUNC(PyObject *) PySequence_List(PyObject *o);
 
+/* Return the sequence 'o' as a list, unless it's already a tuple or list.
+
+   Use PySequence_Fast_GET_ITEM to access the members of this list, and
+   PySequence_Fast_GET_SIZE to get its length.
+
+   Returns NULL on failure.  If the object does not support iteration, raises a
+   TypeError exception with 'm' as the message text. */
+PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
+
 /* Return the number of occurrences on value on 'o', that is, return
    the number of keys for which o[key] == value.
 

Include/abstract.h

@@ -86,15 +86,6 @@ PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
 #define PySequence_ITEM(o, i)\
     ( Py_TYPE(o)->tp_as_sequence->sq_item((o), (i)) )
 
-/* Return the sequence 'o' as a list, unless it's already a tuple or list.
-
-   Use PySequence_Fast_GET_ITEM to access the members of this list, and
-   PySequence_Fast_GET_SIZE to get its length.
-
-   Returns NULL on failure.  If the object does not support iteration, raises a
-   TypeError exception with 'm' as the message text. */
-PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
-
 /* Return the size of the sequence 'o', assuming that 'o' was returned by
    PySequence_Fast and is not NULL. */
 #define PySequence_Fast_GET_SIZE(o) \

Include/cpython/abstract.h

@@ -0,0 +1,39 @@
+#ifndef Py_INTERNAL_C_ARRAY_H
+#define Py_INTERNAL_C_ARRAY_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef Py_BUILD_CORE
+#  error "this header requires Py_BUILD_CORE define"
+#endif
+
+
+/* Utility for a number of growing arrays */
+
+typedef struct {
+    void *array;              /* pointer to the array */
+    int allocated_entries;    /* pointer to the capacity of the array */
+    size_t item_size;         /* size of each element */
+    int initial_num_entries;  /* initial allocation size */
+} _Py_c_array_t;
+
+
+int _Py_CArray_Init(_Py_c_array_t* array, int item_size, int initial_num_entries);
+void _Py_CArray_Fini(_Py_c_array_t* array);
+
+/* If idx is out of bounds:
+ * If arr->array is NULL, allocate arr->initial_num_entries slots.
+ * Otherwise, double its size.
+ *
+ * Return 0 if successful and -1 (with exception set) otherwise.
+ */
+int _Py_CArray_EnsureCapacity(_Py_c_array_t *c_array, int idx);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* !Py_INTERNAL_C_ARRAY_H */