bpo-38250: [Enum] single-bit flags are canonical (GH-24215)

Flag members are now divided by one-bit verses multi-bit, with multi-bit being treated as aliases. Iterating over a flag only returns the contained single-bit flags.

Iterating, repr(), and str() show members in definition order.

When constructing combined-member flags, any extra integer values are either discarded (CONFORM), turned into ints (EJECT) or treated as errors (STRICT). Flag classes can specify which of those three behaviors is desired:

>>> class Test(Flag, boundary=CONFORM):
...     ONE = 1
...     TWO = 2
...
>>> Test(5)
<Test.ONE: 1>

Besides the three above behaviors, there is also KEEP, which should not be used unless necessary -- for example, _convert_ specifies KEEP as there are flag sets in the stdlib that are incomplete and/or inconsistent (e.g. ssl.Options). KEEP will, as the name suggests, keep all bits; however, iterating over a flag with extra bits will only return the canonical flags contained, not the extra bits.

Iteration is now in member definition order.  If member definition order
matches increasing value order, then a more efficient method of flag
decomposition is used; otherwise, sort() is called on the results of
that method to get definition order.


``re`` module:

repr() has been modified to support as closely as possible its previous
output; the big difference is that inverted flags cannot be output as
before because the inversion operation now always returns the comparable
positive result; i.e.

   re.A|re.I|re.M|re.S is ~(re.L|re.U|re.S|re.T|re.DEBUG)

in both of the above terms, the ``value`` is 282.

re's tests have been updated to reflect the modifications to repr().

2 files changed, 6 insertions, 0 deletions

diff --git a/Misc/ACKS b/Misc/ACKS
index 1362669..29ef986 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -141,6 +141,7 @@ Stefan Behnel
 Reimer Behrends
 Ben Bell
 Thomas Bellman
+John Belmonte
 Alexander “Саша” Belopolsky
 Eli Bendersky
 Nikhil Benesch
diff --git a/Misc/NEWS.d/next/Library/2021-01-14-15-07-16.bpo-38250.1fvhOk.rst b/Misc/NEWS.d/next/Library/2021-01-14-15-07-16.bpo-38250.1fvhOk.rst
new file mode 100644
index 0000000..e5a7246
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2021-01-14-15-07-16.bpo-38250.1fvhOk.rst
@@ -0,0 +1,5 @@
+[Enum] Flags consisting of a single bit are now considered canonical, and
+will be the only flags returned from listing and iterating over a Flag class
+or a Flag member.  Multi-bit flags are considered aliases; they will be
+returned from lookups and operations that result in their value.
+Iteration for both Flag and Flag members is in definition order.