Module field_path (2.18.0)

Utilities for managing / converting field paths to / from strings.

Classes

FieldPath

FieldPath(*parts)

Field Path object for client use.

A field path is a sequence of element keys, separated by periods. Each element key can be either a simple identifier, or a full unicode string.

In the string representation of a field path, non-identifier elements must be quoted using backticks, with internal backticks and backslashes escaped with a backslash.

Modules Functions

get_field_path

get_field_path(field_names: typing.Iterable[str])

Create a field path from a list of nested field names.

A field path is a .-delimited concatenation of the field names. It is used to represent a nested field. For example, in the data

data = {
   'aa': {
       'bb': {
           'cc': 10,
       },
   },
}

the field path 'aa.bb.cc' represents that data stored in data['aa']['bb']['cc'].

Parameter
Name	Description
`field_names`	`typing.Iterable[str]` The list of field names.

Returns
Type	Description
`str`	The `.`-delimited field path.

get_nested_value

get_nested_value(field_path: str, data: dict)

Get a (potentially nested) value from a dictionary.

If the data is nested, for example:

>>> data
{
    'top1': {
        'middle2': {
            'bottom3': 20,
            'bottom4': 22,
        },
        'middle5': True,
    },
    'top6': b' foo',
}

a field path can be used to access the nested data. For example:

>>> get_nested_value('top1', data)
{
    'middle2': {
        'bottom3': 20,
        'bottom4': 22,
    },
    'middle5': True,
}
>>> get_nested_value('top1.middle2', data)
{
    'bottom3': 20,
    'bottom4': 22,
}
>>> get_nested_value('top1.middle2.bottom3', data)
20

See xref_field_path for more information on field paths.

Parameters
Name	Description
`field_path`	`str` A field path (`.`-delimited list of field names).
`data`	`Dict[str, Any]` The (possibly nested) data.

Exceptions
Type	Description
`KeyError`	If the `field_path` does not match nested data.

Returns
Type	Description
`Any`	(A copy of) the value stored for the `field_path`.

parse_field_path

parse_field_path(api_repr: str)

Parse a field path from into a list of nested field names.

See field_path for more on field paths.

Parameter
Name	Description
`api_repr`	`str` The unique Firestore api representation which consists of either simple or UTF-8 field names. It cannot exceed 1500 bytes, and cannot be empty. Simple field names match `'^`_a-zA-Z][_a-zA-Z0-9]`*$'`. All other field names are escaped by surrounding them with backticks.

Returns
Type	Description
`List[str, ...]`	The list of field names in the field path.

render_field_path

render_field_path(field_names: typing.Iterable[str])

Create a field path from a list of nested field names.

A field path is a .-delimited concatenation of the field names. It is used to represent a nested field. For example, in the data

data = {
   'aa': {
       'bb': {
           'cc': 10,
       },
   },
}

the field path 'aa.bb.cc' represents that data stored in data['aa']['bb']['cc'].

Parameter
Name	Description
`field_names`	`typing.Iterable[str]` The list of field names.

Returns
Type	Description
`str`	The `.`-delimited field path.

split_field_path

split_field_path(path: str)

Split a field path into valid elements (without dots).

Parameter
Name	Description
`path`	`str` field path to be lexed.

Exceptions
Type	Description
`ValueError`	if the path does not match the elements-interspersed- with-dots pattern.

Returns
Type	Description
`List(str)`	tokens