From 135199e5ea0abca1e7438c7756c0d56d85a5e764 Mon Sep 17 00:00:00 2001 From: guoci Date: Thu, 30 Oct 2025 15:20:36 -0400 Subject: [PATCH 1/8] add docs for `enum.bin` function --- Doc/library/enum.rst | 20 ++++++++++++++++++++ Doc/library/functions.rst | 2 ++ Lib/enum.py | 3 ++- 3 files changed, 24 insertions(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index a8a7e671aadca2..06fabc3a55f580 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=positive, 1=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=positive, 1=negative). + + >>> from enum import enum + >>> enum.bin(10) + '0b0 1010' + >>> enum.bin(~10) # ~10 is -11 + '0b1 0101' + + .. versionadded:: 3.11 + --------------- 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) From 5a08f39cba87a0a20c5a0f244a27651097627239 Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Thu, 30 Oct 2025 19:28:47 +0000 Subject: [PATCH 2/8] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../Documentation/2025-10-30-19-28-42.gh-issue-140806.RBT9YH.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Documentation/2025-10-30-19-28-42.gh-issue-140806.RBT9YH.rst 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`. From b470926deab889f9c8ee61cd5d37ebde49b25ebe Mon Sep 17 00:00:00 2001 From: guoci Date: Thu, 30 Oct 2025 15:40:56 -0400 Subject: [PATCH 3/8] fix doctest --- Doc/library/enum.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 06fabc3a55f580..360c3f7860f589 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -1046,7 +1046,7 @@ Utilities and Decorators two's-complement, and the leading bit always indicates sign (0=positive, 1=negative). - >>> from enum import enum + >>> import enum >>> enum.bin(10) '0b0 1010' >>> enum.bin(~10) # ~10 is -11 From 9551c59f4951377e84333b964ee67a39a36d152d Mon Sep 17 00:00:00 2001 From: Guo Ci Date: Thu, 30 Oct 2025 16:16:57 -0400 Subject: [PATCH 4/8] Update Doc/library/enum.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/enum.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 360c3f7860f589..77e3d418150044 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -156,7 +156,7 @@ Module Contents :func:`enum.bin` Like built-in :func:`bin`, except negative values are represented in - two's-complement, and the leading bit always indicates sign + two's complement, and the leading bit always indicates sign (0=positive, 1=negative). From a9c136f7d26f3119e1fc667b75d1fba7c34c138d Mon Sep 17 00:00:00 2001 From: Guo Ci Date: Thu, 30 Oct 2025 16:17:07 -0400 Subject: [PATCH 5/8] Update Doc/library/enum.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/enum.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 77e3d418150044..e27ee81b62ce4b 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -157,7 +157,7 @@ Module Contents Like built-in :func:`bin`, except negative values are represented in two's complement, and the leading bit always indicates sign - (0=positive, 1=negative). + (``0`` implies positive, ``1`` implies negative). .. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto`` From ffed7d90f209693cc659f60ac28f6a4231ff7592 Mon Sep 17 00:00:00 2001 From: Guo Ci Date: Thu, 30 Oct 2025 16:17:23 -0400 Subject: [PATCH 6/8] Update Doc/library/enum.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/enum.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index e27ee81b62ce4b..7a4ad18f001b80 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -1044,7 +1044,7 @@ Utilities and Decorators Like built-in :func:`bin`, except negative values are represented in two's-complement, and the leading bit always indicates sign - (0=positive, 1=negative). + (``0`` implies positive, ``1`` implies negative). >>> import enum >>> enum.bin(10) From 8d91cef18e6895304ef8ef355a3275e985cbe4ce Mon Sep 17 00:00:00 2001 From: Guo Ci Date: Thu, 30 Oct 2025 16:17:31 -0400 Subject: [PATCH 7/8] Update Doc/library/enum.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/enum.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 7a4ad18f001b80..bc4beee64be162 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -1043,7 +1043,7 @@ Utilities and Decorators .. 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 + two's complement, and the leading bit always indicates sign (``0`` implies positive, ``1`` implies negative). >>> import enum From b72d7289d9c1cad787dbf236ff10040dd1b0b093 Mon Sep 17 00:00:00 2001 From: Guo Ci Date: Thu, 30 Oct 2025 16:18:56 -0400 Subject: [PATCH 8/8] Update Doc/library/enum.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/enum.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index bc4beee64be162..ec868b8e26484d 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -1052,7 +1052,7 @@ Utilities and Decorators >>> enum.bin(~10) # ~10 is -11 '0b1 0101' - .. versionadded:: 3.11 + .. versionadded:: 3.10 ---------------