Enumerations

The amaranth.lib.enum module is a drop-in replacement for the standard enum module that provides extended Enum, IntEnum, Flag, and IntFlag classes with the ability to specify a shape explicitly.

A shape can be specified for an enumeration with the shape= keyword argument:

from amaranth.lib import enum

class Funct(enum.Enum, shape=4):
    ADD = 0
    SUB = 1
    MUL = 2

>>> Shape.cast(Funct)
unsigned(4)

Any constant-castable expression can be used as the value of a member:

class Op(enum.Enum, shape=1):
    REG = 0
    IMM = 1

class Instr(enum.Enum, shape=5):
    ADD  = Cat(Funct.ADD, Op.REG)
    ADDI = Cat(Funct.ADD, Op.IMM)
    SUB  = Cat(Funct.SUB, Op.REG)
    SUBI = Cat(Funct.SUB, Op.IMM)
    ...

>>> Instr.SUBI
<Instr.SUBI: 17>

This module is a drop-in replacement for the standard enum module, and re-exports all of its members (not just the ones described below). In an Amaranth project, all import enum statements may be replaced with from amaranth.lib import enum.

Metaclass

class amaranth.lib.enum.EnumMeta

Subclass of the standard enum.EnumMeta that implements the ShapeCastable protocol.

This metaclass provides the as_shape() method, making its instances shape-castable, and accepts a shape= keyword argument to specify a shape explicitly. Other than this, it acts the same as the standard enum.EnumMeta class; if the shape= argument is not specified and as_shape() is never called, it places no restrictions on the enumeration class or the values of its members.

as_shape()

Cast this enumeration to a shape.

Returns:: Explicitly provided shape. If not provided, returns the result of shape-casting this class as a standard Python enumeration.
Return type:: Shape
Raises:: TypeError – If the enumeration has neither an explicitly provided shape nor any members.

Base classes

class amaranth.lib.enum.Enum: Subclass of the standard enum.Enum that has EnumMeta as its metaclass.

class amaranth.lib.enum.IntEnum: Subclass of the standard enum.IntEnum that has EnumMeta as its metaclass.

class amaranth.lib.enum.Flag: Subclass of the standard enum.Flag that has EnumMeta as its metaclass.

class amaranth.lib.enum.IntFlag: Subclass of the standard enum.IntFlag that has EnumMeta as its metaclass.