* Enum: streamline repr() and str(); improve docs
- repr() is now ``enum_class.member_name``
- stdlib global enums are ``module_name.member_name``
- str() is now ``member_name``
- add HOW-TO section for ``Enum``
- change main documentation to be an API reference
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().
sre_compile does bit test (e.g. `flags & SRE_FLAG_IGNORECASE`) in loop.
`IntFlag.__and__` and `IntFlag.__new__` made it slower.
So this commit convert it to normal int before passing flags to `sre_compile()`.
Compiled regular expression objects with the re.LOCALE flag no longer
depend on the locale at compile time. Only the locale at matching
time affects the result of matching.
"issue28082: use IntFlag for re constants" by Ethan Furman.
The re module is not more used in the site module and so adding "import enum"
to re.py doesn't impact python_startup benchmark anymore.
Importing the enum module in the re module slows down Python startup by 34%
when Python is run from a virtual environment, or more generally when the re
module is imported at startup but not the enum module.
Ethan Furman
Ram Rachum
Serhiy Storchaka
INADA Naoki
Barry Warsaw
Victor Stinner
Raymond Hettinger
Benjamin Peterson
Antoine Pitrou
Georg Brandl
Christian Heimes
Ezio Melotti
Florent Xicluna