As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

Field Paths

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

class google.cloud.firestore_v1.field_path.FieldPath(*parts)

Bases: object

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.

Parameters

parts – (one or more strings) Indicating path of the key to be used.

__add__(other)

Adds other field path to end of this field path.

Parameters

other (FieldPath, str) – The field path to add to the end of this FieldPath.

static document_id()

A special FieldPath value to refer to the ID of a document. It can be used

in queries to sort or filter by the document ID.

Returns: A special sentinel value to refer to the ID of a document.

eq_or_parent(other)

Check whether other is an ancestor.

Returns

(bool) True IFF other is an ancestor or equal to self, else False.

classmethod from_api_repr(api_repr: str)

Factory: create a FieldPath from the string formatted per the API.

Parameters

• api_repr (str) – a string path, with non-identifier elements quoted

• characters (It cannot exceed 1500) –

• empty. (and cannot be) –

Returns

(FieldPath) An instance parsed from api_repr.

Raises

ValueError if the parsing fails –

classmethod from_string(path_string: str)

Factory: create a FieldPath from a unicode string representation.

This method splits on the character . and disallows the characters ~*/[]. To create a FieldPath whose components have those characters, call the constructor.

Parameters

• path_string (str) – A unicode string which cannot contain

• characters (~*/[]) –

• bytes (cannot exceed 1500) –

• empty. (and cannot be) –

Returns

(FieldPath) An instance parsed from path_string.

lineage()

Return field paths for all parents.

Returns: Set[FieldPath]

to_api_repr()

Render a quoted string representation of the FieldPath

Returns

(str) Quoted string representation of the path stored within this FieldPath.

google.cloud.firestore_v1.field_path.get_field_path(field_names: 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'].

Parameters

field_names – The list of field names.

Returns

The .-delimited field path.

Return type

str

google.cloud.firestore_v1.field_path.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 field_path() for more information on field paths.

Parameters

• field_path (str) – A field path (.-delimited list of field names).

• data (Dict[str, Any]) – The (possibly nested) data.

Returns

(A copy of) the value stored for the field_path.

Return type

Any

Raises

KeyError – If the field_path does not match nested data.

google.cloud.firestore_v1.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.

Parameters

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

The list of field names in the field path.

Return type

List[str, …]

google.cloud.firestore_v1.field_path.render_field_path(field_names: 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'].

Parameters

field_names – The list of field names.

Returns

The .-delimited field path.

Return type

str

google.cloud.firestore_v1.field_path.split_field_path(path: str)

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

Parameters

path (str) – field path to be lexed.

Returns

tokens

Return type

List(str)

Raises

ValueError – if the path does not match the elements-interspersed- with-dots pattern.