Mailing List Archive

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 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

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


_______________________________________________
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/PPPCZGMDH47UPGH6RKVXNQQX3IQ2AMCS/
Code of Conduct: http://python.org/psf/codeofconduct/

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?
_______________________________________________
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/NDQ55INDDQMGERVYUHUYNDZ572IPD4UY/
Code of Conduct: http://python.org/psf/codeofconduct/

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
_______________________________________________
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/NE5UYXEUZ6KKHVH3Z2OX45SSWCXYEYYO/
Code of Conduct: http://python.org/psf/codeofconduct/

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/OM5M774MP5QPLFXZ7OVGBPR7ZFB6X35A/
Code of Conduct: http://python.org/psf/codeofconduct/

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/OM5M774MP5QPLFXZ7OVGBPR7ZFB6X35A/
> Code of Conduct: http://python.org/psf/codeofconduct/
>

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/OM5M774MP5QPLFXZ7OVGBPR7ZFB6X35A/
> 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.

+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/7VN5Z5FSN3CH33KKQELX63L7JW6WEB2L/
> 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/OM5M774MP5QPLFXZ7OVGBPR7ZFB6X35A/
>> 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/WX7YCSRRDJWLVJUMLGBZL34OP7JW4MDQ/
> 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
_______________________________________________
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/3BBRVAW2AKDUXNJYLCIPK2V7BX4CWMGF/
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 <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.
_______________________________________________
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/U6B74BNJ76COD4WQE7UR4IQXHU4W5F6K/
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~
_______________________________________________
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/DVFOYTEPFNUDXWIYS763XGTCWJ6GFL5U/
Code of Conduct: http://python.org/psf/codeofconduct/

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?)

_______________________________________________
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/VPAMZXZFKJ5SVGUWSIV6DB5EBHXXLMCV/
Code of Conduct: http://python.org/psf/codeofconduct/

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 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/OM5M774MP5QPLFXZ7OVGBPR7ZFB6X35A/
>

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

?
> On 6 Jun 2021, at 16:58, Andrei Kulakov <andrei.avk@gmail.com> wrote:
>
>
> 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.

I’m not sure it’s a quite the same - it doesn’t require that the sets in the cover have cardinality 1, which I think Ethan does.
And the ‘exact’ requirement (that each bit is covered once) surely doesn’t apply.

It’s more like “full cover by singletons”.

On 6/6/21 9:14 AM, Irit Katriel via Python-Dev wrote:
> On 6 Jun 2021, at 16:58, Andrei Kulakov wrote:

>> 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.
>
> I’m not sure it’s a quite the same - it doesn’t require that the sets in the cover have cardinality 1, which I think
> Ethan does.

Well, I'm not sure what "cardinality 1" means, so I don't know if I do or not. :)

--
~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/BMCG6MA3HKYAQC4JARJFXZDOZGCSIPMM/
Code of Conduct: http://python.org/psf/codeofconduct/

On Mon, Jun 7, 2021 at 1:36 PM Ethan Furman <ethan@stoneleaf.us> wrote:

> On 6/6/21 9:14 AM, Irit Katriel via Python-Dev wrote:
> > On 6 Jun 2021, at 16:58, Andrei Kulakov wrote:
>
> >> 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.
> >
> > I’m not sure it’s a quite the same - it doesn’t require that the sets
> in the cover have cardinality 1, which I think
> > Ethan does.
>
> Well, I'm not sure what "cardinality 1" means, so I don't know if I do or
> not. :)
>
>
> It means each bit flag has only one bit set. In the 'exact cover'
definition, that's not a requirement (if it were, it would
make the problem too trivial to solve).

I also want to mention that 'exact cover' seems a very direct, easy to
remember name also for users who are not
familiar with the Math definition..

-andrei

Andrei is suggesting to look at each enum value as the set of "bits set to
1" in this value, and then apply a set-thoery term to the problem. A set of
"cardinality 1" in this context is an enum value with only one "1", what
you called canonical. The condition you defined is that any bit that is set
anywhere, is also in a canonical value. Anyway, I don't know whether this
kind of terminology is widely accessible.

Maybe you could use something like @composite. As in, every non-canonical
value in the enum is the composition of canonical values.


On Mon, Jun 7, 2021 at 6:36 PM Ethan Furman <ethan@stoneleaf.us> wrote:

> On 6/6/21 9:14 AM, Irit Katriel via Python-Dev wrote:
> > On 6 Jun 2021, at 16:58, Andrei Kulakov wrote:
>
> >> 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.
> >
> > I’m not sure it’s a quite the same - it doesn’t require that the sets
> in the cover have cardinality 1, which I think
> > Ethan does.
>
> Well, I'm not sure what "cardinality 1" means, so I don't know if I do or
> not. :)
>
> --
> ~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/BMCG6MA3HKYAQC4JARJFXZDOZGCSIPMM/
> Code of Conduct: http://python.org/psf/codeofconduct/
>

Irit Katriel via Python-Dev writes:

> Andrei is suggesting to look at each enum value as the set of "bits set to
> 1" in this value, and then apply a set-thoery term to the problem.
> [...] Anyway, I don't know whether this kind of terminology is
> widely accessible.

I think the everyday meaning of "cover" is close enough to the set
theory meaning that only set theorists can be confused. (Not a joke,
because I'm not sure exactly what Ethan intends.) I'm not sure
"exact_cover" or "complete_cover" or similar are good names, but
they're as good as any I've seen so far.

> Maybe you could use something like @composite. As in, every non-canonical
> value in the enum is the composition of canonical values.

-1 on "composite". "Compose" has other, more important meanings, and
isn't very suggestive of this kind of factorization, to me at least.

Steve

_______________________________________________
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/OZOEOD3OT76OSWJ5ZZ4Y4X4JSYWCG4ZS/
Code of Conduct: http://python.org/psf/codeofconduct/