# Enums

Configuration values are typed enums, never bare integers or strings — the
signature tells you the whole legal set, so a mistake fails at the call site
rather than as a firmware rejection later. Note what it fails *as*: passing a
bare `0` or `"330"` where a member is expected raises `AttributeError` (the SDK
reads `.name` or `.value` off the argument), and a mistyped member name raises
`AttributeError` too. A `TypeError` here means a mistyped *keyword*, which is a
different mistake.

Three flavours live side by side, and the difference is not cosmetic.

**Bound from C++, plain `enum.Enum`.** Most of them — every configuration
ladder (`SpiMode`, `UartBaudRate`, `I3cPushPullRate`, `I2cPullUp`, `I2cBus`,
`DeviceModel`, {py:obj}`~pycosmicsdk.StatusCode`, …). These are *not* `int`
subclasses: `SpiMode.MODE_0 == 0` is `False`. Pass the member, never a
literal.

**Bound from C++, arithmetic.** The eight `enum.IntEnum`s
({py:obj}`~pycosmicsdk.GpioPinNumber`,
{py:obj}`~pycosmicsdk.GpioFunctionality`,
{py:obj}`~pycosmicsdk.GpioLogicLevel`,
{py:obj}`~pycosmicsdk.I3cConnectorPort`,
{py:obj}`~pycosmicsdk.I3cConnectorEvent`,
{py:obj}`~pycosmicsdk.I3cConnectorType`,
{py:obj}`~pycosmicsdk.I3cTargetBusEventKind`,
{py:obj}`~pycosmicsdk.I3cTargetDcr`) plus the three `enum.IntFlag`s
({py:obj}`~pycosmicsdk.GpioTriggerType`, {py:obj}`~pycosmicsdk.I3cEvent`,
{py:obj}`~pycosmicsdk.I3cTransferFlags`). Nearly all of them are arithmetic
because their values turn up as raw `int` fields on notifications or are
bitwise-combinable flags, and being arithmetic is load-bearing there:
`n.pin_number == GpioPinNumber.PIN_3` holds only because of it. See the warning
on the [GPIO guide](../guides/gpio.md).
{py:obj}`~pycosmicsdk.GpioFunctionality` is the one member of this group that
is neither — it is only ever a `configure_pin` argument — and it is arithmetic
for consistency with the other GPIO enums rather than because anything compares
it against an `int`.

**Python-only.** Nine enums have no native counterpart. Seven are `StrEnum`s:
{py:obj}`~pycosmicsdk.DeviceState`, {py:obj}`~pycosmicsdk.ResetTarget`,
{py:obj}`~pycosmicsdk.ProtocolInterface`,
{py:obj}`~pycosmicsdk.SpiTransport`, {py:obj}`~pycosmicsdk.I3cTransport`,
{py:obj}`~pycosmicsdk.I2cTransport` and {py:obj}`~pycosmicsdk.BulkOperation`.
The three transport
enums are the ones easiest to mistake for bound enums, because they are
documented in their protocols' sections below alongside the C++-bound ladders —
but a transport value never crosses into the extension at all: `AUTO` is
resolved in Python and the result selects which call to make, so there is no
firmware number for a member to mirror and nothing to compare it against.
{py:obj}`~pycosmicsdk.BulkOperation` is Python-only for the same reason: support
is decided in Python from the integer triples the device's capability query
returns.

{py:obj}`~pycosmicsdk.I2cTargetBusEventKind` and
{py:obj}`~pycosmicsdk.SpiTargetBusEventKind` are the eighth and ninth, and they
are the exceptions to that rule: both are `enum.IntEnum` rather than `StrEnum`,
*because* their values **do** arrive from the device — as plain `int` fields on
{py:obj}`~pycosmicsdk.I2cTargetBusEventNotification` and
{py:obj}`~pycosmicsdk.SpiTargetBusEventNotification` — so a comparison against a
raw notification value has to succeed. That is the same rule the bound
device-ward enums follow; these two are Python-side only because firmware puts
no event-kind enum in its headers for I2C or SPI. Each notification's field is a
bare byte, and these name the values it currently takes: `WRITE_TRANSFER` and
`READ_TRANSFER` for I2C, and for SPI a single `TRANSACTION_COMPLETE`.

**{py:obj}`~pycosmicsdk.SpiTargetBusEventKind` having exactly one member** makes
the raw-`int` arm of {py:obj}`SpiTargetBusEvent.kind
<pycosmicsdk.SpiTargetBusEvent>` matter more there than anywhere else: it is the
only thing that will make a future second kind visible instead of dropping the
event.

The C++-bound enums carry no per-member prose — CosmicSDK's own enums have
none to bind — so their members below are listed as bare name/value pairs.

{py:obj}`~pycosmicsdk.StrEnum` itself is re-exported for Python 3.10, where
`enum.StrEnum` does not exist yet; on 3.11+ it *is* `enum.StrEnum`.

:::{note}
A notification field that carries a raw firmware value stays an `int` rather
than being coerced into an enum, so a value this release does not name still
arrives instead of raising. Compare against the members you care about; do not
assume the set is closed, and do not call `SomeEnum(raw_value)` inside a
`where=` predicate.
:::

```{eval-rst}
.. autoclass:: pycosmicsdk.StrEnum
   :no-members:
```


## Device

```{eval-rst}
.. autoclass:: pycosmicsdk.DeviceModel
   :no-members:

.. autoclass:: pycosmicsdk.DeviceState
   :undoc-members:

.. autoclass:: pycosmicsdk.ResetTarget
   :undoc-members:

.. autoclass:: pycosmicsdk.ProtocolInterface
   :undoc-members:

```

## I2C

```{eval-rst}
.. autoclass:: pycosmicsdk.I2cBus
   :no-members:

.. autoclass:: pycosmicsdk.I2cPullUp
   :no-members:

.. autoclass:: pycosmicsdk.I2cOpenDrainRate
   :no-members:

.. autoclass:: pycosmicsdk.I2cTransport
   :no-members:

```

## I2C — target mode

```{eval-rst}
.. autoclass:: pycosmicsdk.I2cTargetModel
   :no-members:

.. autoclass:: pycosmicsdk.I2cTargetAddressMode
   :no-members:

.. autoclass:: pycosmicsdk.I2cTargetMemoryLayout
   :no-members:

.. autoclass:: pycosmicsdk.I2cTargetRegisterAccess
   :no-members:

.. autoclass:: pycosmicsdk.I2cTargetEraseScope
   :no-members:

.. autoclass:: pycosmicsdk.I2cTargetEepromBusyBehavior
   :no-members:

.. autoclass:: pycosmicsdk.I2cTargetBusEventKind
   :no-members:

```

## I3C — controller

```{eval-rst}
.. autoclass:: pycosmicsdk.I3cPushPullRate
   :no-members:

.. autoclass:: pycosmicsdk.I3cOpenDrainRate
   :no-members:

.. autoclass:: pycosmicsdk.I3cDriveStrength
   :no-members:

.. autoclass:: pycosmicsdk.I3cSdaPullUp
   :no-members:

.. autoclass:: pycosmicsdk.I3cTransferDirection
   :no-members:

.. autoclass:: pycosmicsdk.I3cTransferFlags
   :no-members:

.. autoclass:: pycosmicsdk.I3cEvent
   :no-members:

.. autoclass:: pycosmicsdk.I3cTransport
   :no-members:

```

## I3C — target mode

```{eval-rst}
.. autoclass:: pycosmicsdk.I3cTargetMemoryLayout
   :no-members:

.. autoclass:: pycosmicsdk.I3cTargetDcr
   :no-members:

.. autoclass:: pycosmicsdk.I3cTargetResetDefByte
   :no-members:

.. autoclass:: pycosmicsdk.I3cTargetBusEventKind
   :no-members:

```

## I3C — connector

```{eval-rst}
.. autoclass:: pycosmicsdk.I3cConnectorPort
   :no-members:

.. autoclass:: pycosmicsdk.I3cConnectorEvent
   :no-members:

.. autoclass:: pycosmicsdk.I3cConnectorType
   :no-members:

```

## UART

```{eval-rst}
.. autoclass:: pycosmicsdk.UartBaudRate
   :no-members:

.. autoclass:: pycosmicsdk.UartParity
   :no-members:

.. autoclass:: pycosmicsdk.UartDataSize
   :no-members:

.. autoclass:: pycosmicsdk.UartStopBit
   :no-members:

.. autoclass:: pycosmicsdk.UartHwHandshake
   :no-members:

```

## SPI

```{eval-rst}
.. autoclass:: pycosmicsdk.SpiMode
   :no-members:

.. autoclass:: pycosmicsdk.SpiBitOrder
   :no-members:

.. autoclass:: pycosmicsdk.SpiDataWidth
   :no-members:

.. autoclass:: pycosmicsdk.SpiChipSelect
   :no-members:

.. autoclass:: pycosmicsdk.SpiChipSelectPolarity
   :no-members:

.. autoclass:: pycosmicsdk.SpiTransport
   :no-members:

```

## SPI — target mode

```{eval-rst}
.. autoclass:: pycosmicsdk.SpiTargetModel
   :no-members:

.. autoclass:: pycosmicsdk.SpiTargetEngine
   :no-members:

.. autoclass:: pycosmicsdk.SpiTargetBusEventKind
   :no-members:

```

## GPIO

```{eval-rst}
.. autoclass:: pycosmicsdk.GpioPinNumber
   :no-members:

.. autoclass:: pycosmicsdk.GpioFunctionality
   :no-members:

.. autoclass:: pycosmicsdk.GpioLogicLevel
   :no-members:

.. autoclass:: pycosmicsdk.GpioTriggerType
   :no-members:

```

## The bulk transfer plane

```{eval-rst}
.. autoclass:: pycosmicsdk.BulkOperation
   :no-members:

```

## Status codes

```{eval-rst}
.. autoclass:: pycosmicsdk.StatusCode
   :no-members:

```