enum: Add Flags and IntFlags

[serhiy-storchaka]

BPO	23591
Nosy	@warsaw, @rhettinger, @ezio-melotti, @bitdancer, @ethanfurman, @serhiy-storchaka, @MojoVampire, @vedgar
Files	intflags.patch intflags_2.patch intflags_3.patch issue23591.stoneleaf.02.patch bit_length.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ethanfurman'
closed_at = <Date 2016-11-21.16:31:14.558>
created_at = <Date 2015-03-05.15:31:23.274>
labels = ['type-feature', 'library']
title = 'enum: Add Flags and IntFlags'
updated_at = <Date 2016-11-21.16:31:14.556>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2016-11-21.16:31:14.556>
actor = 'python-dev'
assignee = 'ethan.furman'
closed = True
closed_date = <Date 2016-11-21.16:31:14.558>
closer = 'python-dev'
components = ['Library (Lib)']
creation = <Date 2015-03-05.15:31:23.274>
creator = 'serhiy.storchaka'
dependencies = []
files = ['38344', '38387', '44114', '44278', '44319']
hgrepos = []
issue_num = 23591
keywords = ['patch']
message_count = 80.0
messages = ['237269', '237491', '237494', '237532', '247018', '247026', '247033', '247040', '269018', '269023', '269792', '269919', '270110', '272202', '272230', '272303', '272651', '272674', '272693', '272701', '272719', '272732', '272737', '272741', '272788', '272793', '272795', '272796', '272797', '272798', '272799', '272926', '272927', '272956', '272958', '273934', '273939', '273948', '273954', '273958', '274003', '274048', '274105', '274107', '274206', '274230', '274241', '274279', '274280', '274311', '274317', '274343', '274372', '274373', '274377', '274379', '274403', '274822', '274826', '274828', '274868', '274869', '274870', '274875', '274876', '274975', '274976', '274979', '275093', '275736', '275743', '275801', '275802', '276335', '276348', '276354', '276358', '276907', '277432', '281376']
nosy_count = 10.0
nosy_names = ['barry', 'rhettinger', 'ezio.melotti', 'r.david.murray', 'eli.bendersky', 'ethan.furman', 'python-dev', 'serhiy.storchaka', 'josh.r', 'veky']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23591'
versions = ['Python 3.6']

[serhiy-storchaka]

Here is preliminary implementation of IntFlags (no docs). This is an int subclass purposed to represent a set of integer flags. It supports named constants (as IntEnum), supports bitwise operations (&, |, ~) and has funny str and repr. See discussion on Python-Ideas [1].

The patch includes tests and few examples of using IntFlags in the stdlib.

[1] http://comments.gmane.org/gmane.comp.python.ideas/32267

[vadmium]

It would make more sense and be more consistent if the str() and repr() used one’s complement in all cases, i.e.:

self.assertEqual(str(Perm(~0)), "~0")

Also, the repr() seems to be doing a bad attempt at Python pseudo code. Instead of

<Perm.R|W: 3>

maybe it could be something like these:

<Perm.R|Perm.W: 3> # Mirroring str() -> "Perm.R|Perm.W"
<Perm R|W: 3>
<Perm: R|W = 3>

I wonder if the addition (+) operator should also be overridden; I haven’t looked, but I suspect some people may do FLAG1 + FLAG2 instead of FLAG1 | FLAG2.

[ethanfurman]

The current patch is more along the lines of a proof-of-concept.

The final IntFlag type (if there is one) would be quite a bit more extensive since part of the reason for its existence is to not lose type -- so pretty much every __op__ would have to be overridden.

Agreed about the repr() and str(), though.

[serhiy-storchaka]

I choose repr() so that for single flag it looks as for IntEnum instance. Other variants except <Perm.R|Perm.W: 3> have different format. <Perm.R|Perm.W: 3> is too verbose, it repeats the same class name multiple times.

But I don't like current repr.

Other operators are not overridden for purpose. IntFlags is int and can be used in all cases when int is used, but not in all cases the result should preserve the type. FLAG1 + FLAG2 works as if flags would be ints, but it should be rewritten to FLAG1 | FLAG2 to got the benefit from using IntFlags.

However I forgot to override the exclusive-or operator. It should be overridden.

Updated patch changes str and repr, override the exclusive-or operator and adds some documentation.

[serhiy-storchaka]

Why have you rejected this issue Ethan? I think this is useful feature and must be in Python, and other core developers agreed with this. Only minor implementation details are discussable.

[bitdancer]

I agree. Closing this does not follow our normal development workflow, since there has been a consensus in favor and none for rejection. If you think the API needs wider discussion a new thread can be started on python-ideas.

[bitdancer]

Ethan: to clarify...based on my years of watching this tracker, the way we normally handle an issue like this is to leave the issue open until it is resolved, sometimes with people proposing competing patches. (There might be reasons to change that tradition, but if so the forum for that discussion would be python-workflow.)

[ethanfurman]

My experience is that a module maintainer, or somebody claiming to speak for the module maintainer, can close any issue in their area at any time regardless of the number of core devs in favor of a change.

Whatever. I'll leave this open and write up a spec of what IntFlags should look like in case somebody wants to write the patch for it.

[serhiy-storchaka]

What should be done for landing this in 3.6?

[ethanfurman]

Just look briefly through your patches, and they look pretty good. I'll take a more in-depth look in the next couple weeks. (Feel free to ping again if you don't see any activity from me, and thanks for your patience.)