pg.KeySpec

Accessible via pg.KeySpec, pg.typing.KeySpec.

class KeySpec

Bases: pg.Formattable, pg.JSONConvertible

Interface for key specifications.

A key specification determines what keys are acceptable for a symbolic field (see pg.Field). Usually, symbolic attributes have an 1:1 relationship with symbolic fields. But in some cases (e.g. a dict with dynamic keys), a field can be used to describe a group of symbolic attributes:

# A dictionary that accepts key 'x' with float value
# or keys started with 'foo' with int values.
d = pg.Dict(value_spec=pg.Dict([
   ('x', pg.typing.Float(min_value=0.0)),
   (pg.typing.StrKey('foo.*'), pg.typing.Int())
]))

You may noticed that the code above pass a string ‘x’ for the key spec for a field definition. The string is automatically converted to pg.typing.ConstStrKey.

PyGlove’s Builtin key specifications are:

KeySpec type	Class
Fixed string identifier	pg.typing.ConstStrKey
Dynamic string identifier	pg.typing.StrKey
Key of a list	pg.typing.ListKey
Key of a tuple	pg.typing.TupleKey

In most scenarios, the user either use a string or a StrKey as the key spec, while other KeySpec subclasses (e.g. ListKey and TupleKey) are used internally to constrain list size and tuple items.

Methods:

extend(base)	Extend base key specification and returns self.
match(key)	Returns whether current key specification can match a key.

Classes:

from_str

alias of pg.typing.ConstStrKey

Attributes:

is_const

Returns whether current key is const.

abstract extend(base)

Extend base key specification and returns self.

NOTE(daiyip): When a Field extends a base Field (from a base schema), it calls extend on both its KeySpec and ValueSpec. KeySpec.extend is to determine whether the Field key is allowed to be extended, and ValueSpec.extend is to determine the final ValueSpec after extension.

Return type:

pg.KeySpec

Parameters:

base – A base KeySpec object.

Returns:

An KeySpec object derived from this key spec by extending the base.

from_str

alias of pg.typing.ConstStrKey

abstract property is_const: bool

Returns whether current key is const.

abstract match(key)

Returns whether current key specification can match a key.

Return type:

bool