diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index a8a7e671aadca2..ec868b8e26484d 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,20 @@ 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 + --------------- Notes diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 61799e303a1639..467e9b8afa88e0 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 ad782b8c41e160..2f26e78b77df8a 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`.