[3.13] gh-140806: add docs for `enum.bin` function (#140807) (#143740)

(cherry picked from commit 7f50a5febd7af7259237a78dc533e9f9f274d51c)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>

diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index f559659ab6056ddfbc2ba1de1fd2bfed3ec88073..a3e0a57e09cebff1d63b23fa458dafc7f561995d 100644 (file)
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -153,6 +153,12 @@ Module Contents
 
       Return a list of all power-of-two integers contained in a flag.
 
+   :func:`enum.bin`
+
+      Like built-in :func:`bin`, except negative values are represented in
+      two's complement, and the leading bit always indicates sign
+      (``0`` implies positive, ``1`` implies negative).
+
 
 .. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
 .. versionadded:: 3.11  ``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, ``member``, ``nonmember``, ``global_enum``, ``show_flag_values``
@@ -1034,6 +1040,19 @@ Utilities and Decorators
 
    .. versionadded:: 3.11
 
+.. function:: bin(num, max_bits=None)
+
+   Like built-in :func:`bin`, except negative values are represented in
+   two's complement, and the leading bit always indicates sign
+   (``0`` implies positive, ``1`` implies negative).
+
+      >>> import enum
+      >>> enum.bin(10)
+      '0b0 1010'
+      >>> enum.bin(~10)   # ~10 is -11
+      '0b1 0101'
+
+   .. versionadded:: 3.10
 
 ---------------
 

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index e08d5d2a99541d56a4e283615b1f9f6a04722697..a1a5e333bf60b00e0f3312ef7e4d7a0ef09665f5 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -138,6 +138,8 @@ are always available.  They are listed here in alphabetical order.
       >>> f'{14:#b}', f'{14:b}'
       ('0b1110', '1110')
 
+   See also :func:`enum.bin` to represent negative values as twos-complement.
+
    See also :func:`format` for more information.
 
 

diff --git a/Lib/enum.py b/Lib/enum.py
index 51074404af324ce3e1046adae451628c7b4cfe9a..5e7b00654dd2bf5a8c79829ea9d885cdcebefb60 100644 (file)
--- a/Lib/enum.py
+++ b/Lib/enum.py
@@ -130,7 +130,7 @@ def show_flag_values(value):
 def bin(num, max_bits=None):
     """
     Like built-in bin(), except negative values are represented in
-    twos-compliment, and the leading bit always indicates sign
+    twos-complement, and the leading bit always indicates sign
     (0=positive, 1=negative).
 
     >>> bin(10)
@@ -139,6 +139,7 @@ def bin(num, max_bits=None):
     '0b1 0101'
     """
 
+    num = num.__index__()
     ceiling = 2 ** (num).bit_length()
     if num >= 0:
         s = bltns.bin(num + ceiling).replace('1', '0', 1)

diff --git a/Misc/NEWS.d/next/Documentation/2025-10-30-19-28-42.gh-issue-140806.RBT9YH.rst b/Misc/NEWS.d/next/Documentation/2025-10-30-19-28-42.gh-issue-140806.RBT9YH.rst
new file mode 100644 (file)
index 0000000..82bdf05
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2025-10-30-19-28-42.gh-issue-140806.RBT9YH.rst
@@ -0,0 +1 @@
+Add documentation for :func:`enum.bin`.