On Thu, 2021-05-27 at 20:24 -0700, Ethan Furman wrote:

Greetings!

The Flag type in the enum module has had some improvements, but I find it necessary to move one of those improvements into a decorator instead, and I'm having a hard time thinking up a name.

What is the behavior? Well, a name in a flag type can be either canonical (it represents one thing), or aliased (it represents two or more things). To use Color as an example:

class Color(Flag): RED = 1 # 0001 GREEN = 2 # 0010 BLUE = 4 # 0100 PURPLE = RED | BLUE # 0101 WHITE = RED | GREEN | BLUE # 0111

The flags RED, GREEN, and BLUE are all canonical, while PURPLE and WHITE are aliases for certain flag combinations. But what if we have something like:

class Color(Flag): RED = 1 # 0001 BLUE = 4 # 0100 WHITE = 7 # 0111

As you see, WHITE is an "alias" for a value that does not exist in the Flag (0010, or 2). That seems like it's probably an error. But what about this?

class FlagWithMasks(IntFlag): DEFAULT = 0x0

FIRST_MASK = 0xF FIRST_ROUND = 0x0 FIRST_CEIL = 0x1 FIRST_TRUNC = 0x2

SECOND_MASK = 0xF0 SECOND_RECALC = 0x00 SECOND_NO_RECALC = 0x10

THIRD_MASK = 0xF00 THIRD_DISCARD = 0x000 THIRD_KEEP = 0x100

Here we have three flags (FIRST_MASK, SECOND_MASK, THIRD_MASK) that are aliasing values that don't exist, but it seems intentional and not an error.

So, like the enum.unique decorator that can be used when duplicate names should be an error, I'm adding a new decorator to verify that a Flag has no missing aliased values that can be used when the programmer thinks it's appropriate... but I have no idea what to call it.

Any nominations?

Maybe something like the following would be a good starting point: @bitmask_require_individual_bits -- Best regards, Michał Górny

On 5/28/2021 12:08 AM, Michał Górny wrote:

On Thu, 2021-05-27 at 20:24 -0700, Ethan Furman wrote:

...

Greetings!

The Flag type in the enum module has had some improvements, but I find it necessary to move one of those improvements into a decorator instead, and I'm having a hard time thinking up a name.

What is the behavior? Well, a name in a flag type can be either canonical (it represents one thing), or aliased (it represents two or more things). To use Color as an example:

class Color(Flag): RED = 1 # 0001 GREEN = 2 # 0010 BLUE = 4 # 0100 PURPLE = RED | BLUE # 0101 WHITE = RED | GREEN | BLUE # 0111

The flags RED, GREEN, and BLUE are all canonical, while PURPLE and WHITE are aliases for certain flag combinations. But what if we have something like:

class Color(Flag): RED = 1 # 0001 BLUE = 4 # 0100 WHITE = 7 # 0111

As you see, WHITE is an "alias" for a value that does not exist in the Flag (0010, or 2). That seems like it's probably an error. But what about this?

class FlagWithMasks(IntFlag): DEFAULT = 0x0

FIRST_MASK = 0xF FIRST_ROUND = 0x0 FIRST_CEIL = 0x1 FIRST_TRUNC = 0x2

SECOND_MASK = 0xF0 SECOND_RECALC = 0x00 SECOND_NO_RECALC = 0x10

THIRD_MASK = 0xF00 THIRD_DISCARD = 0x000 THIRD_KEEP = 0x100

Here we have three flags (FIRST_MASK, SECOND_MASK, THIRD_MASK) that are aliasing values that don't exist, but it seems intentional and not an error.

So, like the enum.unique decorator that can be used when duplicate names should be an error, I'm adding a new decorator to verify that a Flag has no missing aliased values that can be used when the programmer thinks it's appropriate... but I have no idea what to call it.

Any nominations?

Maybe something like the following would be a good starting point:

@bitmask_require_individual_bits

@all_bits_defined or @unique_bits

I think a longer-named decorator, with a name that actually describes its behavior would be better than any smart short name in this case. "check_all_bits_defined" or something along it. On Fri, 28 May 2021 at 18:30, Ethan Furman wrote:

On 5/28/21 12:43 AM, Petr Viktorin wrote:

...

On 28. 05. 21 5:24, Ethan Furman wrote:

...

...

class FlagWithMasks(IntFlag): DEFAULT = 0x0

FIRST_MASK = 0xF FIRST_ROUND = 0x0 FIRST_CEIL = 0x1 FIRST_TRUNC = 0x2

SECOND_MASK = 0xF0 SECOND_RECALC = 0x00 SECOND_NO_RECALC = 0x10

THIRD_MASK = 0xF00 THIRD_DISCARD = 0x000 THIRD_KEEP = 0x100

Here we have three flags (FIRST_MASK, SECOND_MASK, THIRD_MASK) that

are aliasing values

...

that don't exist, but it seems intentional and not an error.

Are you looking for a decorator for the whole Enum, or a way to mark individual *values* as masks?

The decorator is for whole enum. The issue is not that some values are masks, but whether the absence of named bits covered by the mask is an error.

-- ~Ethan~ _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/OM5M774M... Code of Conduct: http://python.org/psf/codeofconduct/

On 5/29/2021 6:33 PM, Nick Coghlan wrote:

On Sat, 29 May 2021, 7:27 am Ethan Furman, mailto:ethan@stoneleaf.us> wrote:

On 5/28/21 12:43 AM, Petr Viktorin wrote:  > On 28. 05. 21 5:24, Ethan Furman wrote:

 >>      class FlagWithMasks(IntFlag):  >>          DEFAULT = 0x0  >>  >>          FIRST_MASK = 0xF  >>          FIRST_ROUND = 0x0  >>          FIRST_CEIL = 0x1  >>          FIRST_TRUNC = 0x2  >>  >>          SECOND_MASK = 0xF0  >>          SECOND_RECALC = 0x00  >>          SECOND_NO_RECALC = 0x10  >>  >>          THIRD_MASK = 0xF00  >>          THIRD_DISCARD = 0x000  >>          THIRD_KEEP = 0x100  >>  >> Here we have three flags (FIRST_MASK, SECOND_MASK, THIRD_MASK) that are aliasing values  >> that don't exist, but it seems intentional and not an error.  >  > Are you looking for a decorator for the whole Enum, or a way to mark individual *values* as masks?

The decorator is for whole enum.  The issue is not that some values are masks, but whether the absence of named bits covered by the mask is an error.

If you were prepared to incur a deprecation period, then you could make the decorator "@allow_masks" and flip the default behaviour to emit Deprecation Warning for masks, eventually upgrading it to Value Error.

Otherwise, maybe something like "@no_masks"?

"Mask" is one typical usage for combined flags, but not the only one.  I would not recommend using "mask" in the name of the decorator.

+1 on 'complete'. If 'enum.unique()' means 'every value has at most one name', then perhaps `enum.complete()` can mean 'every value has at least one name'? Or is that not accurate? Other suggestions: 'occupied', 'full', 'exhaustive'. Barney On Mon, 31 May 2021 at 00:02, Jeff Allen wrote:

On 28/05/2021 04:24, Ethan Furman wrote:

The flags RED, GREEN, and BLUE are all canonical, while PURPLE and WHITE are aliases for certain flag combinations. But what if we have something like:

class Color(Flag): RED = 1 # 0001 BLUE = 4 # 0100 WHITE = 7 # 0111

...

So, like the enum.unique decorator that can be used when duplicate names should be an error, I'm adding a new decorator to verify that a Flag has no missing aliased values that can be used when the programmer thinks it's appropriate... but I have no idea what to call it.

Any nominations?

The propery you are looking for IIUC is that if a bit position is 1 in any member, then there is a member with only that bit set. I am seeing these members as sets of elements (bit positions) and therefore you want optionally to ensure that your enumeration has a name for every singleton set, into which any member could be analysed.

Words like "basis", "complete", "analytic", or "indicator" (as in indicator function) come to mind. I find "singletonian" attractive, but no-one will know what it means, and I just made it up.

Jeff _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/7VN5Z5FS... Code of Conduct: http://python.org/psf/codeofconduct/

On 5/31/2021 1:37 PM, Luciano Ramalho wrote:

On Fri, May 28, 2021 at 7:00 PM Joao S. O. Bueno wrote:

...

"check_all_bits_defined" or something along it. Best suggestion so far. Similar:

"ensure_all_bits_named"

I am all for brainstorming, as we've been doing for a few days. Maybe we need to brainstorm some more.

I just don't think the goal should be finding a one/two-word name for the decorator.

I see no need to find something shorter than a short sentence. After all, defining a new enum is not something we do all the time.

Cheers,

Luciano

In this vein, I suggest these variations     @name_all_used_flags     @require_individual_flag_names Clearly some flags may not be used, and need not be named, but this would require all the used flags to be (individually) named, without precluding combinations of same. And while I am guilty of using the word "bits" in prior suggestions, I realized today that the name of the Enum variety under discussion is "IntFlag" not "IntBits", so it seems more appropriate to use the word "flag" or "flags" rather than "bits", even though the implementation of a boolean flag is a single bit. So I withdraw my prior suggestions of  @all_bits_defined  and @unique_bits in favor of  @all_flags_defined and @unique_flags. Digression/Extensions: I'm also starting to wonder if Flag & IntFlag should be restricted to individual flags and combinations, and if another variety of Enum, that is very, very similar, should be called IntBitfields.  On the other hand, if there are a few flags and a small bitfield or two, that are sufficiently related, having them contained in a single Enum might be appropriate, and such has certainly been used on pre-existing APIs with plain int values manipulated with logical operators. Without having any clue as to how hard the implementation might be, or how it would conflict with other uses of decorators, and without any concern for the exact details of the implementation, if another syntax would be easier, I wonder if something along the lines of new syntax would be preferable to a decorator, when the possibility exists for both flags and bitfields to be defined in the same Enum: class SomeSpecificInt( IntBitfields ):    COLORS( 3 ): flags = {      RED = 1      GREEN = 2      BLUE = 4      PURPLE = RED | BLUE      },   OPACITY( 4 ): int,   DITHER( 4 ): values = {     CROSSHATCH = auto(),     SLANTED30DEGREES = auto(),     SLANTED45DEGREES = auto(),     SLANTED60DEGREES = auto(),     DOTS25PERCENT = auto(),     DOTS50PERCENT = auto(),     DOTS75PERCENT = auto(),     },   } The idea here would be that "flags" values would be unique bits that are in a 3-bit field, OPACITY would be an integer in a 4-bit field, and DITHER would be a set of unique values (only 4 defined so far, but allowing up to 15 values in a 4-bit field for future expansion). To require the COLORS to have uniquely named flags, a different keyword would be used instead of or in addition to "flags": COLORS( 3 ): individual flags   [or  COLORS( 3 ): individual_flags ] I realize this adds more complexity, and is far beyond the original proposal, but it also adds missing power to subdivided int values. The values for DITHER would be from 1-15 when extracted or cast, with the shifting done by the Enum implementation. Or maybe instead of the above proposal, the decorator approach could be taken for individual IntFlag classes, but a new "CombinedEnum" could be defined to join multiple Enum classes into a single "int" with bitfields.  In that case, the explicit bitfield sizes given in the above syntax would only be used for CombinedEnum, but the member Enum classes that are combined would have to meet the constraint of fitting their values into that many bits.

On 5/27/21 8:24 PM, Ethan Furman wrote:

So, like the enum.unique decorator that can be used when duplicate names should be an error, I'm adding a new decorator to verify that a Flag has no missing aliased values that can be used when the programmer thinks it's appropriate... but I have no idea what to call it.

Any nominations?

Thank you everyone for your ideas! Instead of adding another single-purpose decorator, I'm toying with the idea of adding a general purpose decorator that accepts instructions. Something along the lines of: class EnumChecks(StrEnum): """ various conditions to check an enumeration for """ UNIQUE = "one name per value" CONTINUOUS = "no skipped values" DECOMPOSABLE_ALIASES = "flag aliases must have all bits named" def verify(enumeration, *checks): if UNIQUE in checks: # ensure no duplicates if CONTINUOUS in checks: # ensure no missing values if DECOMPOSABLE_ALIASES in checks: # ensure all multi-flag aliases are composed of named flags Thoughts? -- ~Ethan~

On Wed, Jun 2, 2021 at 8:04 PM Ethan Furman wrote:

Thank you everyone for your ideas! Instead of adding another single-purpose decorator, I'm toying with the idea of adding a general purpose decorator that accepts instructions. Something along the lines of: ... Thoughts?

I had a couple comments. First, are these checks going to run at import time? The reason I ask is that, in cases where the enums aren't generated dynamically, it seems like it could make sense for efficiency to have the option of running them instead during tests. The decorator would still be useful because it could tell the test harness what checks to run. My other comment is whether this design would permit checks that take arguments. For example, in the case of the "continuous" check, one might want to be able to say, "this Flag enum should span the first N bits" as opposed to using the highest occurring bit as the N. That way you can be sure you didn't leave off any flags at the end. --Chris

On Thu, May 27, 2021 at 11:31 PM Ethan Furman wrote:

Greetings!

The Flag type in the enum module has had some improvements, but I find it necessary to move one of those improvements into a decorator instead, and I'm having a hard time thinking up a name.

What is the behavior? Well, a name in a flag type can be either canonical (it represents one thing), or aliased (it represents two or more things). To use Color as an example:

class Color(Flag): RED = 1 # 0001 GREEN = 2 # 0010 BLUE = 4 # 0100 PURPLE = RED | BLUE # 0101 WHITE = RED | GREEN | BLUE # 0111

The flags RED, GREEN, and BLUE are all canonical, while PURPLE and WHITE are aliases for certain flag combinations. But what if we have something like:

class Color(Flag): RED = 1 # 0001 BLUE = 4 # 0100 WHITE = 7 # 0111

As you see, WHITE is an "alias" for a value that does not exist in the Flag (0010, or 2). That seems like it's probably an error. But what about this?

class FlagWithMasks(IntFlag): DEFAULT = 0x0

FIRST_MASK = 0xF FIRST_ROUND = 0x0 FIRST_CEIL = 0x1 FIRST_TRUNC = 0x2

SECOND_MASK = 0xF0 SECOND_RECALC = 0x00 SECOND_NO_RECALC = 0x10

THIRD_MASK = 0xF00 THIRD_DISCARD = 0x000 THIRD_KEEP = 0x100

Here we have three flags (FIRST_MASK, SECOND_MASK, THIRD_MASK) that are aliasing values that don't exist, but it seems intentional and not an error.

So, like the enum.unique decorator that can be used when duplicate names should be an error, I'm adding a new decorator to verify that a Flag has no missing aliased values that can be used when the programmer thinks it's appropriate... but I have no idea what to call it.

Any nominations?

-- ~Ethan~

In Math / CompSci there is a definition that almost exactly matches this: Exact Cover - https://en.wikipedia.org/wiki/Exact_cover The difference is that, IIRC, solving the problem is finding and removing all subsets that are unneeded to create an exact cover, so it's kind of arriving at it from a different direction, but 'exact cover' definition itself is a good match. -andrei