From 7699d1be182fcf9365721f944505848f0ebfe990 Mon Sep 17 00:00:00 2001
From: Guo Ci <zguoci@gmail.com>
Date: Mon, 12 Jan 2026 06:34:18 -0500
Subject: [PATCH] gh-140806: add docs for `enum.bin` function (#140807)

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>
(cherry picked from commit 7f50a5febd7af7259237a78dc533e9f9f274d51c)
---
 Doc/library/enum.rst                          | 19 +++++++++++++++++++
 Doc/library/functions.rst                     |  2 ++
 Lib/enum.py                                   |  3 ++-
 ...-10-30-19-28-42.gh-issue-140806.RBT9YH.rst |  1 +
 4 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2025-10-30-19-28-42.gh-issue-140806.RBT9YH.rst

diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index f559659ab6056d..a3e0a57e09cebf 100644
--- 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 e08d5d2a99541d..a1a5e333bf60b0 100644
--- 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 51074404af324c..5e7b00654dd2bf 100644
--- 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
index 00000000000000..82bdf05d7300fa
--- /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`.