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~
On Thu, May 27, 2021 at 11:34 PM Ethan Furman <ethan@stoneleaf.us> 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?
@prevent_missing_values? @check_all_values_exist? @sanity_check? Just some midnight thoughts from me.
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
On 28. 05. 21 5:24, 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?
Are you looking for a decorator for the whole Enum, or a way to mark individual *values* as masks?
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~
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 <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.
-- ~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 Fri, May 28, 2021 at 7:00 PM Joao S. O. Bueno <jsbueno@python.org.br> 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
On Fri, 28 May 2021 at 18:30, Ethan Furman <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.
-- ~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/
_______________________________________________ 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/WX7YCSRR... Code of Conduct: http://python.org/psf/codeofconduct/
-- Luciano Ramalho | Author of Fluent Python (O'Reilly, 2015) | http://shop.oreilly.com/product/0636920032519.do | Technical Principal at ThoughtWorks | Twitter: @ramalhoorg
On 5/31/2021 1:37 PM, Luciano Ramalho wrote:
On Fri, May 28, 2021 at 7:00 PM Joao S. O. Bueno <jsbueno@python.org.br> 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 Sat, 29 May 2021, 7:27 am Ethan Furman, <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"? Cheers, Nick.
-- ~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, <ethan@stoneleaf.us <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.
On Fri, May 28, 2021 at 10:26 PM Ethan Furman <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 all masked bits must be defined by individual values then it's a completely_masked enum? This is quite a bikeshed we're painting here! ;-)
Kind regards, Steve
Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/OM5M774M...
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
+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 <ja.py@farowl.co.uk> 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 Thu, May 27, 2021 at 8:30 PM Ethan Furman <ethan@stoneleaf.us> wrote:
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.
Are there use cases where you want to support gaps in the bits? If not, your decorator could accept which flags should be spanned. That seems useful, too. It would be a strictly stronger check. That would change the kind of name you want, though. Otherwise, some things that occur to me: factorable, factorizable, factorized, decomposable. The thinking here is that each named member should be capable of being decomposed / factored into individual values that themselves have names. --Chris
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 6/2/2021 7:59 PM, Ethan Furman wrote:
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?
Seems more forward-looking and extensible rather than a proliferation of decorators. I like that. And the EnumChecks provides a way to make a tradeoff between short names (although DECOMPOSABLE_ALIASES isn't particularly short, it could be made shorter given the explanations) and the explanations of them in the text value. However, for DECOMPOSABLE_ALIASES, not only is the name not short, the explanation isn't particularly clear either, and it doesn't sound like it would properly explain the case where you want to have a mask that is larger than the number of currently used individual "flags" (which maybe shouldn't be called "bits", but "flags"). That explanation confuses the terminology between "masks" calling them "flags" and "flags" calling them bits. But maybe my understanding of what you originally meant the term "flag" to mean in the Enum context is not clear... in any case, a terminology should be used consistently, and the terminology should differentiate between at least 3 cases: 1. single bit items (flag?) 2. multi-bit values that are not a superset of a group of related single bit items (group?) e.g. PURPLE = RED | BLUE (not including GREEN) 3. multi-bit values that are intended as a mask, to include all related single bit items as well as possibly reserving space for future, yet-undefined, related single bit items. (mask?) and maybe also 4. multi-bit fields containing a number, rather than a set of individual bits (field?)
On Wed, Jun 2, 2021 at 8:04 PM Ethan Furman <ethan@stoneleaf.us> 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 <ethan@stoneleaf.us> 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
participants (13)
-
Andrei Kulakov -
Barney Gale -
Chris Jerdonek -
Ethan Furman -
Glenn Linderman -
Jeff Allen -
Joao S. O. Bueno -
Jonathan Goble -
Luciano Ramalho -
Michał Górny -
Nick Coghlan -
Petr Viktorin -
Steve Holden