pg.Field¶

Accessible via pg.Field, pg.typing.Field.

class Field(key_spec, value_spec, description=None, metadata=None)[source]¶

Bases: pg.Formattable, pg.JSONConvertible

Class that represents the definition of one or a group of attributes.

Field is held by a pg.Schema object for defining the name(s), the validation and transformation rules on its/their value(s) for a single symbolic attribute or a set of symbolic attributes.

A Field is defined by a tuple of 4 items:

(key specification, value specification, doc string, field metadata)

For example:

(pg.typing.StrKey('foo.*'),
 pg.typing.Int(),
 'Attributes with foo',
 {'user_data': 'bar'})

The key specification (or KeySpec, class pg.KeySpec) and value specification (or ValueSpec, class pg.ValueSpec) are required, while the doc string and the field metadata are optional. The KeySpec defines acceptable identifiers for this field, and the ValueSpec defines the attribute’s value type, its default value, validation rules and etc. The doc string serves as the description for the field, and the field metadata can be used for attribute-based code generation.

Field supports extension, which allows the subclass to add more restrictions to a field inherited from the base class, or override its default value. A field can be frozen if subclasses can no longer extend it.

See pg.KeySpec and pg.ValueSpec for details.

Attributes:

`annotation`	Type annotation for this field.
`default_value`	Returns the default value.
`description`	Description of this field.
`frozen`	Returns True if current field's value is frozen.
`key`	Key specification of this field.
`metadata`	Metadata of this field.
`value`	Value specification of this field.

Methods:

`apply`(value[, allow_partial, transform_fn, ...])	Apply current field to a value, which validate and complete the value.
`extend`(base_field)	Extend current field based on a base field.
`format`([compact, verbose, root_indent, markdown])	Format this field into a string.
`from_annotation`(annotation[, description, ...])	Creates a field from Python annotation.
`set_description`(description)	Sets the description for this field.
`to_json`(**kwargs)	Returns a plain Python value as a representation for this object.

property annotation: Any[source]¶: Type annotation for this field.

apply(value, allow_partial=False, transform_fn=None, root_path=None)[source]¶

Apply current field to a value, which validate and complete the value.

Return type:

Any

Parameters:

value – Value to validate against this spec.
allow_partial – Whether partial value is allowed. This is for dict or nested dict values.
transform_fn – Function to transform applied value into final value.
root_path – Key path for root.

Returns:

final value. When allow_partial is set to False (default), only fully qualified value is acceptable. When allow_partial is set to True, missing fields will be placeheld using MISSING_VALUE.

Raises:

KeyError – if additional key is found in value, or required key is missing and allow_partial is set to False.
TypeError – if type of value is not the same as spec required.
ValueError – if value is not acceptable, or value is MISSING_VALUE while allow_partial is set to False.

property default_value: Any[source]¶: Returns the default value.

property description: str | None[source]¶: Description of this field.

extend(base_field)[source]¶

Extend current field based on a base field.

Return type:: pg.Field

format(compact=False, verbose=True, root_indent=0, *, markdown=False, **kwargs)[source]¶

Format this field into a string.

Return type:: str

from_annotation(annotation, description=None, metadata=None, auto_typing=True)[source]¶

Creates a field from Python annotation.

Return type:: pg.Field

property frozen: bool[source]¶: Returns True if current field’s value is frozen.

property key: KeySpec[source]¶: Key specification of this field.

property metadata: Dict[str, Any][source]¶

Metadata of this field.

Metadata is defined as a dict type, so we can add multiple annotations to a field.

userdata = field.metadata.get(‘userdata’, None):

Returns:: Metadata of this field as a dict.

set_description(description)[source]¶

Sets the description for this field.

Return type:: None

to_json(**kwargs)[source]¶

Returns a plain Python value as a representation for this object.

A plain Python value are basic python types that can be serialized into JSON, e.g: bool, int, float, str, dict (with string keys), list, tuple where the container types should have plain Python values as their values.

Return type:: Dict[str, Any]
Parameters:: **kwargs – Keyword arguments as flags to control JSON conversion.
Returns:: A plain Python value.

property value: ValueSpec[source]¶: Value specification of this field.