Flag and Bitwise Members

## What `enum.Flag` actually is `enum.Flag` is a base class in the standard library's `enum` module for enums whose members are meant to be *combined*. An ordinary `enum.Enum` member is a singleton standing for one choice out of several; a `Flag` member stands for one bit, and any subset of those bits is itself a valid value of the enum. That is the whole point: one variable can carry "read and write, but not execute" without a list, a set, or three booleans. ```python from enum import Flag, auto class Perm(Flag): READ = auto() WRITE = auto() EXEC = auto() ``` `auto()` inside a `Flag` subclass assigns successive powers of two — 1, 2, 4 — so the bits never collide. ## The operators `Flag` implements `__or__`, `__and__`, `__xor__` and `__invert__` over its members, and every one of them returns **another member of the same enum**, not a bare integer: ```python rw = Perm.READ | Perm.WRITE rw # <Perm.READ|WRITE: 3> rw & Perm.READ # <Perm.READ: 1> rw & Perm.EXEC # <Perm: 0> rw ^ Perm.READ # <Perm.WRITE: 2> ~Perm.READ # <Perm.WRITE|EXEC: 6> ``` A value that names more than one bit is called a *composite* member. It has a `name` (`'READ|WRITE'`) and a `value` (`3`) like any other member, and it is cached: evaluating `Perm.READ | Perm.WRITE` twice gives you the identical object back, so `is` works on composites too. Note what `~` does. It complements only within the bits the class names — `~Perm.READ` is `WRITE|EXEC`, not the infinite ones-complement of the integer 1. That is what makes `perms & ~Perm.WRITE` a safe way to clear a flag. ## Testing membership by masking The idiomatic presence test is a mask evaluated for truth: ```python if perms & Perm.WRITE: ... ``` This works because `Flag` defines truthiness by value: the only falsy member is the zero-valued one, which is what `&` returns when the bits do not overlap. `Perm(0)` is a real member — it prints as `<Perm: 0>`, iterating it yields nothing, and `bool()` of it is `False`. The mistake to avoid is equality: ```python perms = Perm.READ | Perm.WRITE perms == Perm.WRITE # False — perms carries an extra bit perms & Perm.WRITE # <Perm.WRITE: 2>, truthy ``` Equality asks "is this exactly this set of bits", which is almost never the question being asked. Masking (or the `in` operator, which reads as a subset test) asks "does this set contain that flag", which is. ## Setting and clearing Granting is `|=`, revoking is `&= ~`: ```python perms = Perm.READ perms |= Perm.WRITE # now READ|WRITE perms &= ~Perm.READ # now WRITE ``` Because members are immutable, `|=` rebinds the name to a different member rather than mutating anything — which is exactly what you want if the value is shared. ## `Flag` versus `IntFlag` `enum.Flag` members are **not** integers. Mixing one with a raw `int` is an error: ```python Perm.READ | 4 # TypeError: unsupported operand type(s) for |: 'Perm' and 'int' ``` That strictness is a feature: it stops a stray number from silently becoming a permission. `enum.IntFlag` is the variant that also subclasses `int`, so its members compare equal to their numbers, combine with plain ints, and serialize as ints — which is what you want when the value round-trips through a database column, a wire protocol or an OS-level bitmask, and what you do *not* want when the flags are purely internal. Reach for `Flag` by default and `IntFlag` only where an integer really has to cross a boundary. ## Practical notes All of this has been in `enum` since Python 3.6, but 3.11 reworked the surrounding behaviour: the `repr` of a composite became `<Perm.READ|WRITE: 3>`, composite members became iterable and sized, and the handling of bits no member covers was formalized with the `boundary=` class keyword. On 3.14 everything above holds as written. One last habit: keep the members single-bit. If you want a named combination, define it explicitly (`RW = READ | WRITE`); it becomes an alias for the composite, `Perm.RW is Perm.READ | Perm.WRITE` is `True`, and iterating the class still yields only the three canonical single-bit members. ## Why one flag value instead of three booleans Three separate boolean attributes model the same information, and interviewers sometimes ask why you would not just use them. A `Flag` value is one object to pass, one column or field to store, one thing to log, and it stays correct when a fourth permission is added — the signatures of every function that takes it are unchanged. It also makes the illegal states harder to build: there is no way to hand a function a permission it did not define, whereas three booleans can be passed in the wrong order without a murmur. The cost is indirection, so keep the enum small and named after the domain, not after the bits.