Skip to content

bagof.magic.fields

Classes

Field 

Field(*arg, **kwargs)

Bases: SlotsBase

A field in a Magic.

Parameters:

Name Type Description Default
name str

The name of the field.

 required
type type or type hint

The type of the field. This is used for type checking, validation, and conversion.

 required
default any

The default value for the field.

 required
factory Callable[[], any]

A factory function that generates a default value for the field.

 `Options().factory`
init bool

Whether to include this field in the generated __init__ method.

 `Options().init`
repr bool

Whether to include this field in the generated __repr__ method.

 `Options().repr`
hash bool

Whether to include this field in the generated __hash__ method.

 `Options().hash`
eq bool

Whether to include this field in the generated __eq__ method.

 `Options().eq`
order bool

Whether to include this field in the generated __lt__ methods.

 `Options().order`
metadata dict

User-defined metadata for this field.

 required
kw bool

Make this field a keyword argument in the generated __init__ method. To make the field keyword-only, set positional=False as well.

 `not Options().positional_only`
positional bool

Make this field a positional argument in the generated __init__ method. To make the field positional-only, set kw=False as well.

 `not Options().kw_only`
frozen bool

Whether to make this field immutable after initialization.

 `Options().frozen`
converter bool | Callable[[any], any]

A function that converts the input value for this field. If True, a converter will be generated based on the field type.

 `Options().convert`
validator bool | Callable[[any], any]

A function that validates the input value for this field. If should be pass-through when the value is valid, and raise an exception when it is not. If True, a validator will be generated based on the field type.

 `Options().validate`
var bool

Whether this field is a pseudo-field (InitVar or ClassVar). Pseudo-fields are not set by the generated __init__ method, but may one of its arguments (when init=True), or used in the generated __repr__ method (when init=False, repr=True). It is often more readable to use the InitVar and ClassVar annotations.

 False
doc str

A docstring for this field. The typing_extensions.Doc annotation can also be used to set this.

 required
key bool | str

Whether to include this field in the generated dict-like interface. If a string, it will be used as the key.

 `Options().mapping`
alias str

An alternative name for this field in the generated methods. This is useful when the field name is not a valid Python identifier, or when you want to use a different name in the generated methods for readability or consistency with an external API. By default, names that start with an underscore will have the underscore stripped in the alias.

 `name.lstrip("_")`

Other Parameters:

Name Type Description
compare bool

Alias for setting both eq and order at the same time.

Attributes

public_name property 
public_name: str

The public name of this field, used in generated methods.

public_key property 
public_key: str | None

The key to use for this field in the generated dict-like interface.

Methods:

Default 

Default(*values, **kwvalues)

Bases: AnnotatedField

Specify that a field has a default value.

Default(10)      ~> Field(default=10)
Default[int, 10] ~> Annotated[T, Field(default=10)]

Factory 

Factory(*values, **kwvalues)

Bases: AnnotatedField

Specify that a field has a default factory.

Factory()             ~> Field(factory=True)
Factory(list)         ~> Field(factory=list)
Factory[list]         ~> Annotated[T, Field(factory=True)]
Factory[list, mylist] ~> Annotated[T, Field(factory=mylist)]

ConvertTo 

ConvertTo(*values, **kwvalues)

Bases: AnnotatedField

Specify that a field has a converter.

ConvertTo()             ~> Field(converter=True)
ConvertTo(list)         ~> Field(converter=list)
ConvertTo[list]         ~> Annotated[T, Field(converter=True)]
ConvertTo[list, mylist] ~> Annotated[T, Field(converter=mylist)]

Validate 

Validate(*values, **kwvalues)

Bases: AnnotatedField

Specify that a field has a validator.

Validate()                  ~> Field(validator=True)
Validate(myvalidator)       ~> Field(validator=myvalidator)
Validate[list]              ~> Annotated[T, Field(validator=True)]
Validate[list, myvalidator] ~> Annotated[T, Field(validator=myvalidator)]

Init 

Init(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field should [not] be included in the generated __init__ method.

Init()      ~> Field(init=True)
NoInit()    ~> Field(init=False)
Init[int]   ~> Annotated[T, Field(init=True)]
NoInit[int] ~> Annotated[T, Field(init=False)]

Kw 

Kw(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field is [not] a keyword-only parameter.

Kw()        ~> Field(kw=True)
NotKw()     ~> Field(kw=False)
KwOnly()    ~> Field(kw=True, positional=False)
Kw[int]     ~> Annotated[T, Field(kw=True)]
NotKw[int]  ~> Annotated[T, Field(kw=False)]
KwOnly[int] ~> Annotated[T, Field(kw=True, positional=False)]

Positional 

Positional(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field is [not] a positional-only parameter.

Positional()        ~> Field(positional=True)
NotPositional()     ~> Field(positional=False)
PositionalOnly()    ~> Field(positional=True, kw=False)
Positional[int]     ~> Annotated[T, Field(positional=True)]
NotPositional[int]  ~> Annotated[T, Field(positional=False)]
PositionalOnly[int] ~> Annotated[T, Field(positional=True, kw=False)]

Frozen 

Frozen(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field is [not] frozen.

Frozen()       ~> Field(frozen=True)
NotFrozen()    ~> Field(frozen=False)
Frozen[int]    ~> Annotated[T, Field(frozen=True)]
NotFrozen[int] ~> Annotated[T, Field(frozen=False)]

Var 

Var(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field is a pseudo-field (InitVar or ClassVar).

Var()         ~> Field(var=True)
InitVar()     ~> Field(var=True, init=True)
ClassVar()    ~> Field(var=True, init=False)

Var[int]      ~> Annotated[T, Field(var=True)]
InitVar[int]  ~> Annotated[T, Field(var=True, init=True)]
ClassVar[int] ~> Annotated[T, Field(var=True, init=False)]

Repr 

Repr(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field should [not] be included in the generated __repr__ method.

Repr()       ~> Field(repr=True)
NoRepr()     ~> Field(repr=False)
Repr[int]    ~> Annotated[T, Field(repr=True)]
NoRepr[int]  ~> Annotated[T, Field(repr=False)]

Eq 

Eq(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field should [not] be included in the generated __eq__ method.

Eq()       ~> Field(eq=True)
NoEq()     ~> Field(eq=False)
Eq[int]    ~> Annotated[T, Field(eq=True)]
NoEq[int]  ~> Annotated[T, Field(eq=False)]

Order 

Order(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field should [not] be included in the generated __lt__ method.

Order()       ~> Field(order=True)
NoOrder()     ~> Field(order=False)
Order[int]    ~> Annotated[T, Field(order=True)]
NoOrder[int]  ~> Annotated[T, Field(order=False)]

Hash 

Hash(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field should [not] be included in the generated __hash__ method.

Hash()      ~> Field(hash=True)
NoHash()    ~> Field(hash=False)
Hash[int]   ~> Annotated[T, Field(hash=True)]
NoHash[int] ~> Annotated[T, Field(hash=False)]

Key 

Key(*values, **kwvalues)

Bases: BoolAnnotatedField

Specify that a field should [not] be included in the generated dict-like interface.

Key()       ~> Field(key=True)
NotKey()    ~> Field(key=False)
Key[int]    ~> Annotated[T, Field(key=True)]
NotKey[int] ~> Annotated[T, Field(key=False)]

Doc 

Doc(documentation: str)

Bases: AnnotatedField, Doc

Specify the docstring for a field.

Doc("This is a field")      ~> Field(doc="This is a field")
Doc[int, "This is a field"] ~> Annotated[T, Field(doc="This is a field")]