Module field_path (2.17.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