Merge branch 'main' into gh-25949

smontanaro · web-flow · commit 8d5661b76643 · 2022-10-21T18:44:12.000-05:00
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
@@ -189,7 +189,8 @@ wider range of codecs when working with binary files:
 
    .. note::
 
-      Underlying encoded files are always opened in binary mode.
+      If *encoding* is not ``None``, then the
+      underlying encoded files are always opened in binary mode.
       No automatic conversion of ``'\n'`` is done on reading and writing.
       The *mode* argument may be any binary mode acceptable to the built-in
       :func:`open` function; the ``'b'`` is automatically added.
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
@@ -92,6 +92,11 @@ Module Contents
       the bitwise operators without losing their :class:`IntFlag` membership.
       :class:`IntFlag` members are also subclasses of :class:`int`. (`Notes`_)
 
+   :class:`ReprEnum`
+
+      Used by :class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag`
+      to keep the :class:`str() <str>` of the mixed-in type.
+
    :class:`EnumCheck`
 
       An enumeration with the values ``CONTINUOUS``, ``NAMED_FLAGS``, and
@@ -132,9 +137,20 @@ Module Contents
 
       Do not make ``obj`` a member.  Can be used as a decorator.
 
+   :func:`global_enum`
+
+      Modify the :class:`str() <str>` and :func:`repr` of an enum
+      to show its members as belonging to the module instead of its class.
+      Should only be used if the enum members will be exported to the
+      module global namespace.
+
+   :func:`show_flag_values`
+
+      Return a list of all power-of-two integers contained in a flag.
+
 
 .. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
-.. versionadded:: 3.11  ``StrEnum``, ``EnumCheck``, ``FlagBoundary``, ``property``, ``member``, ``nonmember``
+.. versionadded:: 3.11  ``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, ``member``, ``nonmember``, ``global_enum``, ``show_flag_values``
 
 ---------------
 
@@ -573,6 +589,20 @@ Data Types
       better support the *replacement of existing constants* use-case.
       :meth:`__format__` was already :func:`int.__format__` for that same reason.
 
+.. class:: ReprEnum
+
+   :class:`!ReprEum` uses the :meth:`repr() <Enum.__repr__>` of :class:`Enum`,
+   but the :class:`str() <str>` of the mixed-in data type:
+
+      * :meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag`
+      * :meth:`!str.__str__` for :class:`StrEnum`
+
+   Inherit from :class:`!ReprEnum` to keep the :class:`str() <str> / :func:`format`
+   of the mixed-in data type instead of using the
+   :class:`Enum`-default :meth:`str() <Enum.__str__>`.
+
+
+   .. versionadded:: 3.11
 
 .. class:: EnumCheck
 
@@ -808,6 +838,22 @@ Utilities and Decorators
 
    .. versionadded:: 3.11
 
+.. decorator:: global_enum
+
+   A decorator to change the :class:`str() <str>` and :func:`repr` of an enum
+   to show its members as belonging to the module instead of its class.
+   Should only be used when the enum members are exported
+   to the module global namespace (see :class:`re.RegexFlag` for an example).
+
+
+   .. versionadded:: 3.11
+
+.. function:: show_flag_values(value)
+
+   Return a list of all power-of-two integers contained in a flag *value*.
+
+   .. versionadded:: 3.11
+
 ---------------
 
 Notes
diff --git a/Doc/license.rst b/Doc/license.rst
@@ -987,3 +987,28 @@ https://www.w3.org/TR/xml-c14n2-testcases/ and is distributed under the
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Audioop
+-------
+The audioop module uses the code base in g771.c file of the SoX project::
+    Programming the AdLib/Sound Blaster
+    FM Music Chips
+    Version 2.0 (24 Feb 1992)
+    Copyright (c) 1991, 1992 by Jeffrey S. Lee
+    jlee@smylex.uucp
+    Warranty and Copyright Policy
+    This document is provided on an "as-is" basis, and its author makes
+    no warranty or representation, express or implied, with respect to
+    its quality performance or fitness for a particular purpose.  In no
+    event will the author of this document be liable for direct, indirect,
+    special, incidental, or consequential damages arising out of the use
+    or inability to use the information contained within.  Use of this
+    document is at your own risk.
+    This file may be used and copied freely so long as the applicable
+    copyright notices are retained, and no modifications are made to the
+    text of the document.  No money shall be charged for its distribution
+    beyond reasonable shipping, handling and duplication costs, nor shall
+    proprietary changes be made to this document so that it cannot be
+    distributed freely.  This document may not be included in published
+    material or commercial packages without the written consent of its
+    author.
diff --git a/Lib/codecs.py b/Lib/codecs.py
@@ -878,7 +878,8 @@ def open(filename, mode='r', encoding=None, errors='strict', buffering=-1):
         codecs. Output is also codec dependent and will usually be
         Unicode as well.
 
-        Underlying encoded files are always opened in binary mode.
+        If encoding is not None, then the
+        underlying encoded files are always opened in binary mode.
         The default file mode is 'r', meaning to open the file in read mode.
 
         encoding specifies the encoding which is to be used for the
diff --git a/Lib/test/test_codecs.py b/Lib/test/test_codecs.py
@@ -708,7 +708,8 @@ def test_decoder_state(self):
                                          "spamspam", self.spambe)
 
     def test_bug691291(self):
-        # Files are always opened in binary mode, even if no binary mode was
+        # If encoding is not None, then
+        # files are always opened in binary mode, even if no binary mode was
         # specified.  This means that no automatic conversion of '\n' is done
         # on reading and writing.
         s1 = 'Hello\r\nworld\r\n'
diff --git a/Modules/audioop.c b/Modules/audioop.c
@@ -1,3 +1,33 @@
+/* The audioop module uses the code base in g777.c file of the Sox project.
+ * Source: https://web.archive.org/web/19970716121258/http://www.spies.com/Sox/Archive/soxgamma.tar.gz
+ *                 Programming the AdLib/Sound Blaster
+ *                              FM Music Chips
+ *                          Version 2.0 (24 Feb 1992)
+ *
+ *                 Copyright (c) 1991, 1992 by Jeffrey S. Lee
+ *
+ *                               jlee@smylex.uucp
+ *
+ *
+ *
+ *                       Warranty and Copyright Policy
+ *
+ *     This document is provided on an "as-is" basis, and its author makes
+ *     no warranty or representation, express or implied, with respect to
+ *    its quality performance or fitness for a particular purpose.  In no
+ *    event will the author of this document be liable for direct, indirect,
+ *    special, incidental, or consequential damages arising out of the use
+ *    or inability to use the information contained within.  Use of this
+ *    document is at your own risk.
+ *
+ *    This file may be used and copied freely so long as the applicable
+ *    copyright notices are retained, and no modifications are made to the
+ *    text of the document.  No money shall be charged for its distribution
+ *    beyond reasonable shipping, handling and duplication costs, nor shall
+ *    proprietary changes be made to this document so that it cannot be
+ *    distributed freely.  This document may not be included in published
+ *    material or commercial packages without the written consent of its
+ *    author. */
 
 /* audioopmodule - Module to detect peak values in arrays */
 
@@ -28,20 +58,6 @@ fbound(double val, double minval, double maxval)
 }
 
 
-/* Code shamelessly stolen from sox, 12.17.7, g711.c
-** (c) Craig Reese, Joe Campbell and Jeff Poskanzer 1989 */
-
-/* From g711.c:
- *
- * December 30, 1994:
- * Functions linear2alaw, linear2ulaw have been updated to correctly
- * convert unquantized 16 bit values.
- * Tables for direct u- to A-law and A- to u-law conversions have been
- * corrected.
- * Borge Lindberg, Center for PersonKommunikation, Aalborg University.
- * bli@cpk.auc.dk
- *
- */
 #define BIAS 0x84   /* define the add-in bias for 16 bit samples */
 #define CLIP 32635
 #define SIGN_BIT        (0x80)          /* Sign bit for an A-law byte. */
