From 93efae61bf39a49d40f54f4c6d4e13b2dc16d67e Mon Sep 17 00:00:00 2001 From: Mike Koss Date: Thu, 8 Dec 2016 15:44:41 -0800 Subject: [PATCH 1/7] Add client methods collection() and doc(). --- firestore/google/cloud/firestore/client.py | 31 ++++++++++++++++++++++ firestore/unit_tests/test_client.py | 17 ++++++++++++ 2 files changed, 48 insertions(+) diff --git a/firestore/google/cloud/firestore/client.py b/firestore/google/cloud/firestore/client.py index d68b95c8aa3f..2b43040d68eb 100644 --- a/firestore/google/cloud/firestore/client.py +++ b/firestore/google/cloud/firestore/client.py @@ -22,6 +22,10 @@ from google.cloud.client import _ClientProjectMixin from google.cloud.credentials import get_credentials +from google.cloud.firestore.path import Path +from google.cloud.firestore.collection import CollectionRef +from google.cloud.firestore.document import DocumentRef + from google.cloud.gapic.firestore.v1alpha1 import datastore_api @@ -61,6 +65,33 @@ def __init__(self, project=None, credentials=None, emulator_host=None): self.database_id = None self._api = _make_firestore_api(self._connection, emulator_host) + def collection(self, collection_name): + """Get a reference to a top-level collection. + + :type collection_name: str + :param collection_name: The top-level collection name (kind). + + :rtype: :class:`~google.cloud.firebase.CollectionRef` + :returns: A reference to a top-level collection in the Firestore + database. + """ + return CollectionRef(self, Path(collection_name)) + + def doc(self, collection_name, document_id): + """Get a reference to a document in a top-level collection. + + :type collection_name: str + :param collection_name: The top-level collection name (kind). + + :type document_id: str or int + :param document_id: Unique document identifier within a top-level + collection. + + :rtype: :class:`~google.cloud.firestore.DocumentRef` + :returns: A reference to a document in a top-level collection. + """ + return DocumentRef(self, Path(collection_name, document_id)) + def _make_firestore_api(connection, emulator_host): """Create a Firestore gRPC helper library. diff --git a/firestore/unit_tests/test_client.py b/firestore/unit_tests/test_client.py index 4f11f9e9dc16..809e81c42d98 100644 --- a/firestore/unit_tests/test_client.py +++ b/firestore/unit_tests/test_client.py @@ -17,9 +17,16 @@ class TestClient(unittest.TestCase): + def setUp(self): + from google.cloud.firestore.path import Path + + self.collection_path = Path('my-collection') + self.doc_path = Path('my-collection', 'my-document') + @staticmethod def _get_target_class(): from google.cloud.firestore.client import Client + return Client def _make_one(self, *args, **kwargs): @@ -58,6 +65,16 @@ def test_credentialed_no_scopes_constructor(self): client = self._make_one('my-project-id', credentials=creds) self.assertIs(client._connection.credentials, creds) + def test_collection(self): + client = self._make_one('my-project-id') + col_ref = client.collection('my-collection') + self.assertEqual(col_ref._path, self.collection_path) + + def test_doc(self): + client = self._make_one('my-project-id') + col_ref = client.doc('my-collection', 'my-document') + self.assertEqual(col_ref._path, self.doc_path) + class MockCredentials(object): def __init__(self): From 780e397dc88c9aa07eba55cf78e146eae348885a Mon Sep 17 00:00:00 2001 From: Mike Koss Date: Thu, 8 Dec 2016 18:46:10 -0800 Subject: [PATCH 2/7] Add Query.order_by method. --- .../google/cloud/firestore/collection.py | 76 ++++++++++++++++++- firestore/unit_tests/test_collection.py | 14 ++++ 2 files changed, 88 insertions(+), 2 deletions(-) diff --git a/firestore/google/cloud/firestore/collection.py b/firestore/google/cloud/firestore/collection.py index 8dd4da6c1ae3..53abc070795d 100644 --- a/firestore/google/cloud/firestore/collection.py +++ b/firestore/google/cloud/firestore/collection.py @@ -19,11 +19,17 @@ from google.firestore.v1alpha1.query_pb2 import Filter from google.firestore.v1alpha1.query_pb2 import KindExpression from google.firestore.v1alpha1.query_pb2 import PropertyFilter +from google.firestore.v1alpha1.query_pb2 import PropertyOrder from google.firestore.v1alpha1.query_pb2 import PropertyReference from google.firestore.v1alpha1.query_pb2 import Query as PbQuery from google.protobuf.wrappers_pb2 import Int32Value +DIRECTIONS = { + 'asc': enums.Direction.ASCENDING, + 'desc': enums.Direction.DESCENDING +} + class Query(object): """Firestore Query. @@ -36,18 +42,48 @@ class Query(object): :type limit: int :param limit: (optional) Maximum number of results to return. + + :type field_orders: sequence of + :class:`~google.cloud.firestore.collection.FieldOrder` + :param field_orders: Sequence of fields to control order of results. """ def __init__(self, client, ref_path, - limit=None): + limit=None, + field_orders=None): if not ref_path.is_collection: raise ValueError('Invalid collection path: %s' % (ref_path,)) self._client = client self._path = ref_path self._limit = limit + self._field_orders = field_orders if field_orders else tuple() + + def order_by(self, field, direction=None): + """Modify the query to add an order clause on a specific field. + + Successive order_by calls will further refine the ordering of + return results. + + :type field: str + :param field: The name of a document field (property) on which to + order the query results. + + :type direction: str + :param direction: (optional) One of 'asc' (default) or 'desc' to + set the ordering direction to ascending or + descending, respectively. + + :rtype: :class:`~google.cloud.firestore.collection.Query` + :return: An ordered ``Query``. + """ + return Query( + self._client, + self._path, + limit=self._limit, + field_orders=self._field_orders + (FieldOrder(field, direction),)) def limit(self, count): """Limit a query to return a fixed number of results. @@ -80,7 +116,8 @@ def get(self): query = PbQuery( kind=[KindExpression(name=self._path.kind)], filter=complete_filter, - limit=Int32Value(value=self._limit) if self._limit else None) + limit=Int32Value(value=self._limit) if self._limit else None, + order=[order.to_proto() for order in self._field_orders]) response = self._client._api.run_query( self._client.project, self._client.database_id, @@ -148,3 +185,38 @@ def new_doc(self): :returns: A ``DocumentRef`` to the location of a new document. """ return self.doc(self._client.auto_id()) + + +class FieldOrder(object): + """Query order-by field. + + :type field_name: str + :param field_name : The name of a document field (property) on which to + order query results. + + :type direction: str + :param direction: (optional) One of 'asc' (default) or 'desc' to + set the ordering direction to ascending or + descending, respectively. + """ + + def __init__(self, field_name, direction): + if direction is None: + direction = 'asc' + if direction not in DIRECTIONS.keys(): + raise ValueError( + 'Invalid order_by direction (%s) - expect one of %s' % + (direction, DIRECTIONS.keys())) + self._field_name = field_name + self._direction = direction + + def to_proto(self): + """Convert FieldOrder to the corresponding gRPC PropertyReference for + use in a Query. + + :rtype: :class:`~google.firestore.v1alpha1.query_pb2.PropertyOrder` + :returns: A gRPC PropertyOrder. + """ + return PropertyOrder( + property=PropertyReference(name=self._field_name), + direction=DIRECTIONS[self._direction]) diff --git a/firestore/unit_tests/test_collection.py b/firestore/unit_tests/test_collection.py index 92331ea8bbfc..98cd7f5b4757 100644 --- a/firestore/unit_tests/test_collection.py +++ b/firestore/unit_tests/test_collection.py @@ -104,3 +104,17 @@ def test_get(self): docs = query.get() self.assertEqual(self.client._api.run_query.call_count, 1) self.assertIsInstance(docs, list) + query_pb = self.client._api.run_query.call_args[1]['query'] + self.assertEqual(len(query_pb.order), 0) + + def test_order_by(self): + query = self._make_one(self.collection_path) + query.order_by('my-property').get() + self.assertEqual(self.client._api.run_query.call_count, 1) + query_pb = self.client._api.run_query.call_args[1]['query'] + self.assertEqual(len(query_pb.order), 1) + + def test_invalid_order_by_dir(self): + query = self._make_one(self.collection_path) + with self.assertRaisesRegexp(ValueError, r'Invalid.*direction'): + query.order_by('my-property', 'descending') From 76597dc2d692bed784d2a81a4d193ddb0d7a4149 Mon Sep 17 00:00:00 2001 From: Mike Koss Date: Thu, 26 Jan 2017 11:21:54 -0800 Subject: [PATCH 3/7] Review comments and extended tests. --- .../google/cloud/firestore/collection.py | 47 ++++++++------ firestore/unit_tests/test_collection.py | 65 +++++++++++++++++-- 2 files changed, 85 insertions(+), 27 deletions(-) diff --git a/firestore/google/cloud/firestore/collection.py b/firestore/google/cloud/firestore/collection.py index 2be3aa8b9e6d..b2f641351fb9 100644 --- a/firestore/google/cloud/firestore/collection.py +++ b/firestore/google/cloud/firestore/collection.py @@ -20,10 +20,7 @@ from google.protobuf.wrappers_pb2 import Int32Value -DIRECTIONS = { - 'asc': enums.Direction.ASCENDING, - 'desc': enums.Direction.DESCENDING -} +_DEFAULT_DIRECTION = 'asc' class Query(object): @@ -40,7 +37,8 @@ class Query(object): :type field_orders: sequence of :class:`~google.cloud.firestore.collection.FieldOrder` - :param field_orders: Sequence of fields to control order of results. + :param field_orders: (Optional) Sequence of fields to control order of + results. :raises ValueError: Path must be a valid Collection path (not a Document path). @@ -50,16 +48,16 @@ def __init__(self, client, ref_path, limit=None, - field_orders=None): + field_orders=()): if not ref_path.is_collection: raise ValueError('Invalid collection path: %s' % (ref_path,)) self._client = client self._path = ref_path self._limit = limit - self._field_orders = field_orders if field_orders else tuple() + self._field_orders = field_orders - def order_by(self, field, direction=None): + def order_by(self, field, direction=_DEFAULT_DIRECTION): """Modify the query to add an order clause on a specific field. Successive order_by calls will further refine the ordering of @@ -198,25 +196,34 @@ class FieldOrder(object): :param direction: (optional) One of 'asc' (default) or 'desc' to set the ordering direction to ascending or descending, respectively. + + :raises ValueError: Direction must be valid or None. """ - def __init__(self, field_name, direction): - if direction is None: - direction = 'asc' - if direction not in DIRECTIONS.keys(): - raise ValueError( - 'Invalid order_by direction (%s) - expect one of %s' % - (direction, DIRECTIONS.keys())) + def __init__(self, field_name, direction=_DEFAULT_DIRECTION): self._field_name = field_name - self._direction = direction + self._direction_enum = _direction_to_enum(direction) def to_proto(self): - """Convert FieldOrder to the corresponding gRPC PropertyReference for - use in a Query. + """Convert FieldOrder to the corresponding protobuf PropertyReference + for use in a Query. :rtype: :class:`~google.firestore.v1alpha1.query_pb2.PropertyOrder` - :returns: A gRPC PropertyOrder. + :returns: A protobuf PropertyOrder. """ return query_pb2.PropertyOrder( property=query_pb2.PropertyReference(name=self._field_name), - direction=DIRECTIONS[self._direction]) + direction=self._direction_enum) + + +def _direction_to_enum(direction): + """Encode direction string into direction enum.""" + + if direction == 'asc': + return enums.Direction.ASCENDING + elif direction == 'desc': + return enums.Direction.DESCENDING + else: + raise ValueError('Invalid order_by direction (%s) - ' + 'expect one of \'asc\' or \'desc\'.' % + (direction,)) diff --git a/firestore/unit_tests/test_collection.py b/firestore/unit_tests/test_collection.py index 6b19ea5b018b..b3f75829c1ea 100644 --- a/firestore/unit_tests/test_collection.py +++ b/firestore/unit_tests/test_collection.py @@ -121,21 +121,72 @@ def test_get(self): docs = query.get() self.assertEqual(query._client._api.run_query.call_count, 1) self.assertIsInstance(docs, list) - query_pb = query._client._api.run_query.call_args[1]['query'] - self.assertEqual(len(query_pb.order), 0) + query_order = query._client._api.run_query.call_args[1]['query'].order + self.assertEqual(list(query_order), []) def test_order_by(self): from google.cloud.firestore._path import Path + from google.firestore.v1alpha1 import query_pb2 + from google.cloud.gapic.firestore.v1alpha1 import enums query = self._make_one(Path('my-collection')) query.order_by('my-property').get() self.assertEqual(query._client._api.run_query.call_count, 1) - query_pb = query._client._api.run_query.call_args[1]['query'] - self.assertEqual(len(query_pb.order), 1) - - def test_invalid_order_by_dir(self): + query_order = query._client._api.run_query.call_args[1]['query'].order + self.assertEqual(list(query_order), + [query_pb2.PropertyOrder( + property=query_pb2.PropertyReference( + name='my-property'), + direction=enums.Direction.ASCENDING)]) + + def test_order_by_chain(self): from google.cloud.firestore._path import Path + from google.firestore.v1alpha1 import query_pb2 + from google.cloud.gapic.firestore.v1alpha1 import enums query = self._make_one(Path('my-collection')) + query.order_by('my-property').order_by('another-prop', 'desc').get() + self.assertEqual(query._client._api.run_query.call_count, 1) + query_order = query._client._api.run_query.call_args[1]['query'].order + self.assertEqual(list(query_order), + [query_pb2.PropertyOrder( + property=query_pb2.PropertyReference( + name='my-property'), + direction=enums.Direction.ASCENDING), + query_pb2.PropertyOrder( + property=query_pb2.PropertyReference( + name='another-prop'), + direction=enums.Direction.DESCENDING)]) + + +class TestFieldOrder(unittest.TestCase): + @staticmethod + def _get_target_class(): + from google.cloud.firestore.collection import FieldOrder + + return FieldOrder + + def _make_one(self, *args, **kwargs): + return self._get_target_class()(*args, **kwargs) + + def test_constructor(self): + from google.cloud.gapic.firestore.v1alpha1 import enums + + order = self._make_one('my-property') + self.assertEqual(order._field_name, 'my-property') + self.assertEqual(order._direction_enum, enums.Direction.ASCENDING) + + def test_to_proto(self): + from google.cloud.gapic.firestore.v1alpha1 import enums + from google.firestore.v1alpha1 import query_pb2 + + order = self._make_one('my-property') + self.assertEqual(order.to_proto(), + query_pb2.PropertyOrder( + property=query_pb2.PropertyReference( + name='my-property'), + direction=enums.Direction.ASCENDING)) + + def test_invalid_dir(self): with self.assertRaisesRegexp(ValueError, r'Invalid.*direction'): - query.order_by('my-property', 'descending') + self._make_one('my-property', 'descending') From af13ca1e670231f8d69b6d9cd4c8dc38c75aa46e Mon Sep 17 00:00:00 2001 From: Danny Hermes Date: Thu, 26 Jan 2017 14:17:00 -0800 Subject: [PATCH 4/7] Review feedback for firestore unit tests for collection. --- firestore/unit_tests/test_collection.py | 142 +++++++++++++++++++----- 1 file changed, 113 insertions(+), 29 deletions(-) diff --git a/firestore/unit_tests/test_collection.py b/firestore/unit_tests/test_collection.py index b3f75829c1ea..9600f79b44b6 100644 --- a/firestore/unit_tests/test_collection.py +++ b/firestore/unit_tests/test_collection.py @@ -15,6 +15,21 @@ import unittest +def _make_credentials(): + import google.auth.credentials + import mock + + class _CredentialsWithScopes( + google.auth.credentials.Credentials, + google.auth.credentials.Scoped): + pass + + credentials = mock.Mock(spec=_CredentialsWithScopes) + # Return self when being scoped. + credentials.with_scopes.return_value = credentials + return credentials + + class TestCollectionRef(unittest.TestCase): @staticmethod @@ -78,6 +93,8 @@ def test_new_document(self): class TestQuery(unittest.TestCase): + PROJECT = 'project' + @staticmethod def _get_target_class(): from google.cloud.firestore.collection import Query @@ -90,8 +107,15 @@ def _make_one(self, *args, **kwargs): from google.cloud.gapic.firestore.v1alpha1.datastore_api import ( DatastoreApi) - client = Client() - client._api = mock.MagicMock(spec=DatastoreApi) + credentials = _make_credentials() + client = Client(project=self.PROJECT, credentials=credentials) + + # Mock the API to return an empty list of results. + client._api = mock.Mock(spec=['run_query']) + batch = mock.Mock(entity_results=[], spec=['entity_results']) + client._api.run_query.return_value = mock.Mock( + batch=batch, spec=['batch']) + return self._get_target_class()(client, *args, **kwargs) def test_constructor(self): @@ -114,49 +138,109 @@ def test_limit(self): self.assertEqual(query._limit, 123) + @staticmethod + def _make_query_pb(collection, **kwargs): + from google.cloud.gapic.firestore.v1alpha1 import enums + from google.firestore.v1alpha1.entity_pb2 import Value + from google.firestore.v1alpha1 import query_pb2 + from google.protobuf.struct_pb2 import NULL_VALUE + from google.protobuf.wrappers_pb2 import Int32Value + + return query_pb2.Query( + kind=[query_pb2.KindExpression(name=collection)], + filter=query_pb2.Filter( + property_filter=query_pb2.PropertyFilter( + property=query_pb2.PropertyReference(name='__key__'), + op=enums.Operator.HAS_PARENT, + value=Value(null_value=NULL_VALUE), + ), + ), + limit=Int32Value(value=None), + **kwargs + ) + def test_get(self): from google.cloud.firestore._path import Path - query = self._make_one(Path('my-collection')) + collection = 'my-collection' + query = self._make_one(Path(collection)) docs = query.get() - self.assertEqual(query._client._api.run_query.call_count, 1) - self.assertIsInstance(docs, list) - query_order = query._client._api.run_query.call_args[1]['query'].order - self.assertEqual(list(query_order), []) + self.assertEqual(docs, []) + + mock_query = query._client._api.run_query + expected = self._make_query_pb(collection) + mock_query.assert_called_once_with( + self.PROJECT, + None, + partition_id=None, + read_options=None, + query=expected, + gql_query=None, + property_mask=None, + ) def test_order_by(self): from google.cloud.firestore._path import Path from google.firestore.v1alpha1 import query_pb2 from google.cloud.gapic.firestore.v1alpha1 import enums - query = self._make_one(Path('my-collection')) - query.order_by('my-property').get() - self.assertEqual(query._client._api.run_query.call_count, 1) - query_order = query._client._api.run_query.call_args[1]['query'].order - self.assertEqual(list(query_order), - [query_pb2.PropertyOrder( - property=query_pb2.PropertyReference( - name='my-property'), - direction=enums.Direction.ASCENDING)]) + collection = 'my-collection' + query = self._make_one(Path(collection)) + prop_name = 'my-property' + new_query = query.order_by(prop_name) + docs = new_query.get() + self.assertEqual(docs, []) + + mock_query = query._client._api.run_query + order_pb = query_pb2.PropertyOrder( + property=query_pb2.PropertyReference(name=prop_name), + direction=enums.Direction.ASCENDING, + ) + expected = self._make_query_pb(collection, order=[order_pb]) + mock_query.assert_called_once_with( + self.PROJECT, + None, + partition_id=None, + read_options=None, + query=expected, + gql_query=None, + property_mask=None, + ) def test_order_by_chain(self): from google.cloud.firestore._path import Path from google.firestore.v1alpha1 import query_pb2 from google.cloud.gapic.firestore.v1alpha1 import enums - query = self._make_one(Path('my-collection')) - query.order_by('my-property').order_by('another-prop', 'desc').get() - self.assertEqual(query._client._api.run_query.call_count, 1) - query_order = query._client._api.run_query.call_args[1]['query'].order - self.assertEqual(list(query_order), - [query_pb2.PropertyOrder( - property=query_pb2.PropertyReference( - name='my-property'), - direction=enums.Direction.ASCENDING), - query_pb2.PropertyOrder( - property=query_pb2.PropertyReference( - name='another-prop'), - direction=enums.Direction.DESCENDING)]) + collection = 'my-collection' + query1 = self._make_one(Path(collection)) + prop_name1 = 'my-property' + query2 = query1.order_by(prop_name1) + prop_name2 = 'another-prop' + query3 = query2.order_by(prop_name2, 'desc') + docs = query3.get() + self.assertEqual(docs, []) + + mock_query = query1._client._api.run_query + order_pb1 = query_pb2.PropertyOrder( + property=query_pb2.PropertyReference(name=prop_name1), + direction=enums.Direction.ASCENDING, + ) + order_pb2 = query_pb2.PropertyOrder( + property=query_pb2.PropertyReference(name=prop_name2), + direction=enums.Direction.DESCENDING, + ) + expected = self._make_query_pb( + collection, order=[order_pb1, order_pb2]) + mock_query.assert_called_once_with( + self.PROJECT, + None, + partition_id=None, + read_options=None, + query=expected, + gql_query=None, + property_mask=None, + ) class TestFieldOrder(unittest.TestCase): From a69a4e7bbadb421b39cff10fdb9780d9651e4a1f Mon Sep 17 00:00:00 2001 From: Mike Koss Date: Thu, 26 Jan 2017 14:32:10 -0800 Subject: [PATCH 5/7] Fix lint error. --- firestore/unit_tests/test_collection.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/firestore/unit_tests/test_collection.py b/firestore/unit_tests/test_collection.py index 9600f79b44b6..cc52bad2e8c5 100644 --- a/firestore/unit_tests/test_collection.py +++ b/firestore/unit_tests/test_collection.py @@ -104,8 +104,6 @@ def _get_target_class(): def _make_one(self, *args, **kwargs): import mock from google.cloud.firestore.client import Client - from google.cloud.gapic.firestore.v1alpha1.datastore_api import ( - DatastoreApi) credentials = _make_credentials() client = Client(project=self.PROJECT, credentials=credentials) From dc98fbb5d683566b66ba92e9b7078b9f344ede7c Mon Sep 17 00:00:00 2001 From: Mike Koss Date: Thu, 26 Jan 2017 14:51:51 -0800 Subject: [PATCH 6/7] Docstring and format improvements. --- firestore/google/cloud/firestore/collection.py | 9 ++++++++- firestore/unit_tests/test_collection.py | 15 +++++++++------ 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/firestore/google/cloud/firestore/collection.py b/firestore/google/cloud/firestore/collection.py index b2f641351fb9..3d9ba2fbc476 100644 --- a/firestore/google/cloud/firestore/collection.py +++ b/firestore/google/cloud/firestore/collection.py @@ -217,8 +217,15 @@ def to_proto(self): def _direction_to_enum(direction): - """Encode direction string into direction enum.""" + """Encode direction string into direction enum. + :type direction: str + :param direction: One of 'asc' or 'desc' to set the ordering direction to + ascending or descending, respectively. + + :rtype: :class:`~enums.Direction` + :returns: A Query direction enum value. + """ if direction == 'asc': return enums.Direction.ASCENDING elif direction == 'desc': diff --git a/firestore/unit_tests/test_collection.py b/firestore/unit_tests/test_collection.py index cc52bad2e8c5..4187777ab7e6 100644 --- a/firestore/unit_tests/test_collection.py +++ b/firestore/unit_tests/test_collection.py @@ -263,12 +263,15 @@ def test_to_proto(self): from google.firestore.v1alpha1 import query_pb2 order = self._make_one('my-property') - self.assertEqual(order.to_proto(), - query_pb2.PropertyOrder( - property=query_pb2.PropertyReference( - name='my-property'), - direction=enums.Direction.ASCENDING)) + expected = query_pb2.PropertyOrder( + property=query_pb2.PropertyReference( + name='my-property' + ), + direction=enums.Direction.ASCENDING + ) + + self.assertEqual(order.to_proto(), expected) - def test_invalid_dir(self): + def test_invalid_direction(self): with self.assertRaisesRegexp(ValueError, r'Invalid.*direction'): self._make_one('my-property', 'descending') From 93220545b09118b6c369a614b9039be598f806b3 Mon Sep 17 00:00:00 2001 From: Mike Koss Date: Thu, 26 Jan 2017 14:56:03 -0800 Subject: [PATCH 7/7] Fix one-liner docstring. --- firestore/google/cloud/firestore/collection.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/firestore/google/cloud/firestore/collection.py b/firestore/google/cloud/firestore/collection.py index 3d9ba2fbc476..99e39e31d507 100644 --- a/firestore/google/cloud/firestore/collection.py +++ b/firestore/google/cloud/firestore/collection.py @@ -205,8 +205,9 @@ def __init__(self, field_name, direction=_DEFAULT_DIRECTION): self._direction_enum = _direction_to_enum(direction) def to_proto(self): - """Convert FieldOrder to the corresponding protobuf PropertyReference - for use in a Query. + """Convert FieldOrder to the protobuf PropertyReference. + + Intended to be used as a submessage in a Query protobuf. :rtype: :class:`~google.firestore.v1alpha1.query_pb2.PropertyOrder` :returns: A protobuf PropertyOrder.