Utils

Utility routines for django_enum.

django_enum.utils.choices(enum_cls: Type[Enum] | None, override: bool = False, aliases: bool = True) → List[Tuple[Any, str]]

Get the Django choices for an enumeration type. If the enum type has a choices attribute, it will be used. Otherwise, the choices will be derived from value, label pairs if the enumeration type has a label attribute, or the name attribute if it does not.

This is used for compat with enums that do not inherit from Django’s Choices type.

Parameters:

• enum_cls – The enumeration type

• override – Do not defer to choices attribute on the class if True

• aliases – Include first-class aliases in the result if True (default: True)

Returns:

A list of (value, label) pairs

django_enum.utils.decimal_params(enum: Type[Enum] | None, decimal_places: int | None = None, max_digits: int | None = None) → Dict[str, int]

Determine the maximum number of digits and decimal places required to represent all values of the enumeration class.

Parameters:

• enum – The enumeration class to determine the decimal parameters for

• decimal_places – Use this value for decimal_places rather than the computed value

• max_digits – Use this value for max_digits rather than the computed value

Returns:

A tuple of (max_digits, decimal_places)

django_enum.utils.decompose(flags: F | None) → List[F]

Get the activated flags in a Flag instance. For example:

class Permissions(IntFlag):

    READ    = 1 << 0
    WRITE   = 1 << 1
    EXECUTE = 1 << 2

assert decompose(Permissions.READ | Permissions.WRITE) == (
    [Permissions.READ, Permissions.Write]
)

Param:

flags: The flag instance to decompose

Returns:

A list of the Flag instances comprising the flag.

django_enum.utils.determine_primitive(enum: Type[Enum]) → Type | None

Determine the python type most appropriate to represent all values of the enumeration class. The primitive type determination algorithm is thus:

• Determine the types of all the values in the enumeration

• Determine the first supported primitive type in the enumeration class inheritance tree

• If there is only one value type, use its type as the primitive

• If there are multiple value types and they are all subclasses of the class primitive type, use the class primitive type. If there is no class primitive type use the first supported primitive type that all values are symmetrically coercible to. If there is no such type, return None

By definition all values of the enumeration with the exception of None may be coerced to the primitive type and vice-versa.

Parameters:

enum – The enumeration class to determine the primitive type for

Returns:

A python type or None if no primitive type could be determined

django_enum.utils.get_set_bits(flag: int | IntFlag | None) → List[int]

Return the indices of the bits set in the flag.

Parameters:

flag – The flag to get the set bits for, value must be an int.

Returns:

A list of indices of the set bits

django_enum.utils.get_set_values(flag: int | IntFlag | None) → List[int]

Return the integers corresponding to the flags set on the IntFlag or integer.

Parameters:

flag – The flag to get the set bits for, value must be an int.

Returns:

A list of flag integers

django_enum.utils.labels(enum_cls: Type[Enum] | None) → List[Any]

Return a list of labels to use for the enumeration type. See choices.

This is used for compat with enums that do not inherit from Django’s Choices type.

Parameters:

enum_cls – The enumeration type

Returns:

A list of labels

django_enum.utils.members(enum: Type[E], aliases: bool = True) → Generator[E, None, None]

Get the members of an enumeration class. This can be tricky to do in a python version agnostic way, so it is recommended to use this function.

Parameters:

• enum_cls – The enumeration class

• aliases – Include aliases in the result if True (default: True)

Returns:

A generator that yields the enumeration members

django_enum.utils.names(enum_cls: Type[Enum] | None, override: bool = False, aliases: bool = True) → List[Any]

Return a list of names to use for the enumeration type. This is used for compat with enums that do not inherit from Django’s Choices type.

Parameters:

• enum_cls – The enumeration type

• override – Do not defer to names attribute on the class if True

• aliases – Include first-class aliases in the result if True (default: True)

Returns:

A list of labels

django_enum.utils.values(enum_cls: Type[Enum] | None) → List[Any]

Return a list of the values of an enumeration type.

This is used for compat with enums that do not inherit from Django’s Choices type.

Parameters:

enum_cls – The enumeration type

Returns:

A list of values

django_enum.utils.with_typehint(baseclass: Type[T]) → Type[T]

Change inheritance to add Field type hints when type checking is running. This is just more simple than defining a Protocol - revisit if Django provides Field protocol - should also just be a way to create a Protocol from a class?

This is icky but it works - revisit in future.