Skip to content

# `nautobot.apps.choices`

Utilities for implementing choices.

## `nautobot.apps.choices.BannerClassChoices`

Bases: `ChoiceSet`

Styling choices for custom banners.

Source code in `nautobot/extras/choices.py`

    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    class BannerClassChoices(ChoiceSet):
        """Styling choices for custom banners."""

        CLASS_SUCCESS = "success"
        CLASS_INFO = "info"
        CLASS_WARNING = "warning"
        CLASS_DANGER = "danger"

        CHOICES = (
            (CLASS_SUCCESS, "Success"),
            (CLASS_INFO, "Info"),
            (CLASS_WARNING, "Warning"),
            (CLASS_DANGER, "Danger"),
        )

## `nautobot.apps.choices.ButtonActionColorChoices`

Bases: `ChoiceSet`

Map standard button actions to Bootstrap color classes.

Source code in `nautobot/core/choices.py`

    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    class ButtonActionColorChoices(ChoiceSet):
        """
        Map standard button actions to Bootstrap color classes.
        """

        ADD = "info"
        CANCEL = "default"
        CLONE = "success"
        CONFIGURE = "default"
        CONNECT = "success"
        DEFAULT = "default"
        DELETE = "danger"
        DISCONNECT = "info"
        EDIT = "warning"
        EXPORT = "success"
        IMPORT = "primary"
        INFO = "info"
        SUBMIT = "primary"
        SWAP = "primary"

        CHOICES = (
            (ADD, "Add"),
            (CANCEL, "Cancel"),
            (CLONE, "Clone"),
            (CONFIGURE, "Configure"),
            (CONNECT, "Connect"),
            (DEFAULT, "Default"),
            (DELETE, "Delete"),
            (DISCONNECT, "Disconnect"),
            (EDIT, "Edit"),
            (EXPORT, "Export"),
            (IMPORT, "Import"),
            (INFO, "Info"),
            (SUBMIT, "Submit"),
            (SWAP, "Swap"),
        )

## `nautobot.apps.choices.ButtonActionIconChoices`

Bases: `ChoiceSet`

Map standard button actions to Material Design Icons classes.

Source code in `nautobot/core/choices.py`

    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    class ButtonActionIconChoices(ChoiceSet):
        """
        Map standard button actions to Material Design Icons classes.
        """

        ADD = "mdi-plus-thick"
        ALERT = "mdi-alert"
        ARROW_DOWN = "mdi-arrow-down-bold"
        ARROW_UP = "mdi-arrow-up-bold"
        CONFIGURE = "mdi-cogs"
        CONNECT = "mdi-ethernet-cable"
        DELETE = "mdi-trash-can-outline"
        DISCONNECT = "mdi-ethernet-cable-off"
        EDIT = "mdi-pencil"
        EXPORT = "mdi-database-export-outline"
        HELP = "mdi-help-circle"
        INFO = "mdi-help-circle"
        IMPORT = "mdi-database-import-outline"
        LOCK = "mdi-lock"
        MAGNIFY = "mdi-magnify"
        NOTE = "mdi-note-text"
        SWAP = "mdi-swap-vertical"
        TRASH = "mdi-trash-can-outline"

        CHOICES = (
            (ADD, "Add"),
            (ALERT, "Alert"),
            (ARROW_DOWN, "Arrow Down"),
            (ARROW_UP, "Arrow Up"),
            (CONFIGURE, "Configure"),
            (CONNECT, "Connect"),
            (DELETE, "Delete"),
            (DISCONNECT, "Disconnect"),
            (EDIT, "Edit"),
            (EXPORT, "Export"),
            (HELP, "Help"),
            (INFO, "Info"),
            (IMPORT, "Import"),
            (LOCK, "Lock"),
            (MAGNIFY, "Magnify"),
            (NOTE, "Note"),
            (SWAP, "Swap"),
            (TRASH, "Trash"),
        )

## `nautobot.apps.choices.ChoiceSet`

Base class for defining choices for a model and/or menu.

Subclasses should define a CHOICES constant which consists of a list of tuples of the form `(value, display_str)`, or optionally as tuples of the form `(grouping, ((value, display_str), (value, display_str), ...))`.

Example

    class GreekCapitalLetterChoices(ChoiceSet):
        ALPHA = "A"
        BETA = "B"
        GAMMA = "Γ"

        CHOICES = (
            (ALPHA, "alpha"),
            (BETA, "beta"),
            (GAMMA, "gamma"),
        )

Source code in `nautobot/core/choices.py`

    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    class ChoiceSet(metaclass=ChoiceSetMeta):
        """
        Base class for defining choices for a model and/or menu.

        Subclasses should define a CHOICES constant which consists of a list of tuples of the form `(value, display_str)`,
        or optionally as tuples of the form `(grouping, ((value, display_str), (value, display_str), ...))`.

        Example:
            ```python
            class GreekCapitalLetterChoices(ChoiceSet):
                ALPHA = "A"
                BETA = "B"
                GAMMA = "Γ"

                CHOICES = (
                    (ALPHA, "alpha"),
                    (BETA, "beta"),
                    (GAMMA, "gamma"),
                )
            ```
        """

        CHOICES = []

        @classmethod
        def values(cls):
            """Get a flat list of all values defined in this ChoiceSet's `CHOICES`."""
            return [c[0] for c in unpack_grouped_choices(cls.CHOICES)]

        @classmethod
        def as_dict(cls):
            """Get a dictionary representation of this ChoiceSet's `CHOICES`."""
            # Unpack grouped choices before casting as a dict
            return dict(unpack_grouped_choices(cls.CHOICES))

### `as_dict()` `classmethod`

Get a dictionary representation of this ChoiceSet's `CHOICES`.

Source code in `nautobot/core/choices.py`

    44
    45
    46
    47
    48
    @classmethod
    def as_dict(cls):
        """Get a dictionary representation of this ChoiceSet's `CHOICES`."""
        # Unpack grouped choices before casting as a dict
        return dict(unpack_grouped_choices(cls.CHOICES))

### `values()` `classmethod`

Get a flat list of all values defined in this ChoiceSet's `CHOICES`.

Source code in `nautobot/core/choices.py`

    39
    40
    41
    42
    @classmethod
    def values(cls):
        """Get a flat list of all values defined in this ChoiceSet's `CHOICES`."""
        return [c[0] for c in unpack_grouped_choices(cls.CHOICES)]

## `nautobot.apps.choices.JobResultStatusChoices`

Bases: `ChoiceSet`

These status choices are using the same taxonomy as within Celery core. A Nautobot Job status is equivalent to a Celery task state.

Source code in `nautobot/extras/choices.py`

    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    class JobResultStatusChoices(ChoiceSet):
        """
        These status choices are using the same taxonomy as within Celery core. A Nautobot Job status
        is equivalent to a Celery task state.
        """

        STATUS_FAILURE = states.FAILURE
        STATUS_PENDING = states.PENDING
        STATUS_RECEIVED = states.RECEIVED
        STATUS_RETRY = states.RETRY
        STATUS_REVOKED = states.REVOKED
        STATUS_STARTED = states.STARTED
        STATUS_SUCCESS = states.SUCCESS

        CHOICES = sorted(zip(states.ALL_STATES, states.ALL_STATES))

        #: Set of all possible states.
        ALL_STATES = states.ALL_STATES
        #: Set of states meaning the task returned an exception.
        EXCEPTION_STATES = states.EXCEPTION_STATES
        #: State precedence.
        #: None represents the precedence of an unknown state.
        #: Lower index means higher precedence.
        PRECEDENCE = states.PRECEDENCE
        #: Set of exception states that should propagate exceptions to the user.
        PROPAGATE_STATES = states.PROPAGATE_STATES
        #: Set of states meaning the task result is ready (has been executed).
        READY_STATES = states.READY_STATES
        #: Set of states meaning the task result is not ready (hasn't been executed).
        UNREADY_STATES = states.UNREADY_STATES

        @staticmethod
        def precedence(state):
            """
            Get the precedence for a state. Lower index means higher precedence.

            Args:
                state (str): One of the status choices.

            Returns:
                (int): Precedence value.

            Examples:
                >>> JobResultStatusChoices.precedence(JobResultStatusChoices.STATUS_SUCCESS)
                0

            """
            return states.precedence(state)

### `precedence(state)` `staticmethod`

Get the precedence for a state. Lower index means higher precedence.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`state` | `str` | One of the status choices. | required

Returns:

Type | Description
--- | ---
`int` | Precedence value.

Examples:

    >>> JobResultStatusChoices.precedence(JobResultStatusChoices.STATUS_SUCCESS)
    0

Source code in `nautobot/extras/choices.py`

    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    @staticmethod
    def precedence(state):
        """
        Get the precedence for a state. Lower index means higher precedence.

        Args:
            state (str): One of the status choices.

        Returns:
            (int): Precedence value.

        Examples:
            >>> JobResultStatusChoices.precedence(JobResultStatusChoices.STATUS_SUCCESS)
            0

        """
        return states.precedence(state)

## `nautobot.apps.choices.unpack_grouped_choices(choices)`

Unpack a grouped choices hierarchy into a flat list of two-tuples. For example:

choices = ( ('Foo', ( (1, 'A'), (2, 'B') )), ('Bar', ( (3, 'C'), (4, 'D') )) )

becomes:

choices = ( (1, 'A'), (2, 'B'), (3, 'C'), (4, 'D') )

Source code in `nautobot/core/choices.py`

    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    def unpack_grouped_choices(choices):
        """
        Unpack a grouped choices hierarchy into a flat list of two-tuples. For example:

        choices = (
            ('Foo', (
                (1, 'A'),
                (2, 'B')
            )),
            ('Bar', (
                (3, 'C'),
                (4, 'D')
            ))
        )

        becomes:

        choices = (
            (1, 'A'),
            (2, 'B'),
            (3, 'C'),
            (4, 'D')
        )
        """
        unpacked_choices = []
        for key, value in choices:
            if isinstance(value, (list, tuple)):
                # Entered an optgroup
                for optgroup_key, optgroup_value in value:
                    unpacked_choices.append((optgroup_key, optgroup_value))
            else:
                unpacked_choices.append((key, value))
        return unpacked_choices