armi.utils.flags module

A Flag class, similar to enum.Flag.

This is an alternate implementation of the standard-library enum.Flag class. We use this to implement armi.reactor.flags.Flags. We used to use the standard-library implementation, but that became limiting when we wanted to make it possible for plugins to define their own flags; the standard implementation does not support extension. We also considered the aenum package, which permits extension of Enum classes, but unfortunately does not support extension of Flags. So, we had to make our own. This is a much simplified version of what comes with aenum, but still provides most of the safety and functionality.

class armi.utils.flags.auto

Bases: object

Empty class for requesting a lazily-evaluated automatic field value.

This can be used to automatically provision a value for a field, when the specific value does not matter.

In the future, it would be nice to support some arithmetic for these so that automatically-derived combinations of other automatically defined fields can be specified as well.

class armi.utils.flags.Flag(init=0)

Bases: object

A collection of bitwise flags.

This is intended to emulate enum.Flag, except with the possibility of extension after the class has been defined. Most docs for enum.Flag should be relevant here, but there are sure to be occasional differences.

Implementation: No two flags have equivalence. I_ARMI_FLAG_DEFINE

signature: Flag requirements: R_ARMI_FLAG_DEFINE

A bitwise flag class intended to emulate the standard library’s enum.Flag, with the added functionality that it allows for extension after the class has been defined. Each Flag is unique; no two Flags are equivalent. Note that while Python allows for arbitrary-width integers, exceeding the system-native integer size can lead to challenges in storing data, e.g. in an HDF5 file. In this case, the from_bytes() and to_bytes() methods are provided to represent a Flag’s values in smaller chunks so that writeability can be maintained.

Warning

Python features arbitrary-width integers, allowing one to represent an practically unlimited number of fields. However, including more flags than can be represented in the system-native integer types may lead to strange behavior when interfacing with non-pure Python code. For instance, exceeding 64 fields makes the underlying value not trivially-storable in an HDF5 file. In such circumstances, the from_bytes() and to_bytes() methods are available to represent a Flag’s values in smaller chunks.

classmethod width()

Return the number of bytes needed to store all of the flags on this class.

classmethod fields()

Return a dictionary containing a mapping from field name to integer value.

classmethod sortedFields()

Return a list of all field names, sorted by increasing integer value.

classmethod extend(fields: Dict[str, int | auto])

Extend the Flags object with new fields.

Warning

This alters the class that it is called upon! Existing instances should see the new data, since classes are mutable.

Implementation: Set of flags are extensible without loss of uniqueness. I_ARMI_FLAG_EXTEND0

signature: extend requirements: R_ARMI_FLAG_EXTEND

A class method to extend a Flag with a vector of provided additional fields, with field names as keys, without loss of uniqueness. Values for the additional fields can be explicitly specified, or an instance of auto can be supplied.

Parameters:

fields (dict) – A dictionary containing field names as keys, and their desired values, or an instance of auto as values.

Example

>>> class MyFlags(Flags):
...     FOO = auto()
...     BAR = 1
...     BAZ = auto()
>>> MyFlags.extend({
...     "SUPER": auto()
... })
>>> print(MyFlags.SUPER)
<MyFlags.SUPER: 8>

to_bytes(byteorder='little')

Return a byte stream representing the flag.

This is useful when storing Flags in a data type of limited size. Python ints can be of arbitrary size, while most other systems can only represent integers of 32 or 64 bits. For compatibility, this function allows to convert the flags to a sequence of single-byte elements.

Note that this uses snake_case to mimic the method on the Python-native int type.

classmethod from_bytes(bytes, byteorder='little')

Return a Flags instance given a byte stream.