Fields Implementation

Field implementations extending attrs.field().

Enums

enum components.fields.FieldMetadata(value)

Bases: Enum

Enum containing keys for field metadata.

Valid values are as follows:

PARSER = <FieldMetadata.PARSER: 1>

FIELDTYPE = <FieldMetadata.FIELDTYPE: 2>

flag components.fields.FieldType(value)

Bases: Flag

Flag containing field metadata values for the field type.

Note that a field can only ever be one of these types. This is a flag for the sole reason of facilitating unions in lookups using get_fields().

Valid values are as follows:

INTERNAL = <FieldType.INTERNAL: 1>

CUSTOM_ID = <FieldType.CUSTOM_ID: 2>

SELECT = <FieldType.SELECT: 4>

MODAL = <FieldType.MODAL: 8>

The Flag and its members also have the following methods:

classmethod ALL()

Meta-value for all field types.

Mainly intended for use in get_fields().

Functions

components.fields.field(default=_Nothing.NOTHING, *, parser=None)

Define a custom ID field for the component.

The type annotation for this field is used to parse incoming custom ids.

This is a wrapper around attrs.field().

Note

In most cases, simply using a typehint will suffice to define a field. This function is generally only needed if you wish to supply a default value or custom parser.

Note

Fields created this way always have kw_only=True set.

Parameters:

• default (_T | Literal[NOTHING]) – The default value for this field. The type of the default should match that of the type annotation.

• parser (Optional[Parser[_T]]) – The parser to use for converting this field to and from a string. The type of the parser should match that of the type annotation.

Returns:

A new field with the provided default and/or parser.

Return type:

Field[T]

components.fields.get_field_type(field, default=None)

Get the FieldType of the field.

Parameters:

• field (Attribute[Any]) – The field of which to get the field type.

• default (Optional[FieldType]) – The default value to use if the field doesn’t have a FieldType set.

Returns:

The type of the provided field.

Return type:

FieldType

Raises:

TypeError – The provided field does not have a field type set, and no default was provided. The most common cause of this is using attrs.field() instead of components.field() to define a field.

components.fields.get_fields(cls, /, *, kind=FieldType.ALL())

Get the attributes of an attrs class.

This wraps attrs.fields() to be less strict typing-wise and has special handling for internal fields.

Parameters:

• cls (type) – The class of which to get the fields.

• kind (FieldType) – The kind(s) of fields to return. Can be any combination of FieldTypes.

components.fields.get_parser(field)

Get the user-provided parser of the provided field.

Parameters:

field (Attribute[Any]) – The field for which to get the components.api.Parser.

Returns:

• components.api.Parser – The user-provided parser of the provided field.

• None – The field’s parser was automatically inferred.

components.fields.internal(default, *, frozen=False)

Declare a field as internal.

This is used internally to differentiate component parameters from user-defined custom id parameters.

This is a wrapper around attrs.field().

Note

Fields created this way always have kw_only=True set.

Parameters:

• default (_T) – The default value for this field. The type of the default should match that of the type annotation.

• frozen (bool) – Whether or not the field should be marked frozen. A frozen field cannot be modified after the class has been created.

Returns:

A new field with the provided default and frozen status.

Return type:

Field[T]

components.fields.is_field_of_type(field, kind)

Check whether or not a field is marked as the provided FieldType.

Parameters:

• field (Attribute[Any]) – The field to check.

• kind (FieldType) – The FieldType to check for.

Returns:

Whether the provided field was of the provided FieldType.

Return type:

bool