NDB: Query constructor (#7239)

* draft of Query class with notes

* remove bad comment

* Add docstring

* update docstring

Author: averikitsch

ndb/src/google/cloud/ndb/query.py

@@ -872,10 +872,120 @@ def resolve(self, bindings, used):
 
 
 class Query:
-    __slots__ = ()
+    """Query object.
 
-    def __init__(self, *args, **kwargs):
-        raise NotImplementedError
+    Args:
+        kind (str): The kind of entities to be queried.
+        ancestor (Key): Entities returned will be descendants of `ancestor`.
+        filters (Union[Node, tuple]): Node representing a filter expression
+            tree. Property filters applied by this query. The sequence
+            is ``(property_name, operator, value)``.
+        orders (Union[datastore_query.Order, list]): The field names used to
+            order query results. Renamed `order` in google.cloud.datastore.
+        app (str): The namespace to restrict results. If not passed, uses the
+            client's value. Renamed `project` in google.cloud.datastore.
+        namespace (str): The namespace to which to restrict results.
+            If not passed, uses the client's value.
+        default_options (QueryOptions): QueryOptions object.
+        projection (Union[list, tuple]): The fields returned as part of the
+            query results.
+        group_by (Union[list, tuple]): The field names used to group query
+            results. Renamed distinct_on in google.cloud.datastore.
+
+    Raises: TypeError if any of the arguments are invalid.
+    """
+
+    def __init__(self, kind=None, ancestor=None, filters=None, orders=None,
+                 app=None, namespace=None, default_options=None,
+                 projection=None, group_by=None):
+        if ancestor is not None:
+            if isinstance(ancestor, ParameterizedThing):
+                if isinstance(ancestor, ParameterizedFunction):
+                    if ancestor.func != 'key':
+                        raise TypeError("ancestor cannot be a GQL function"
+                                        "other than Key")
+            else:
+                if not isinstance(ancestor, model.Key):
+                    raise TypeError("ancestor must be a Key; "
+                                    F"received {ancestor}")
+                if not ancestor.id():
+                    raise ValueError("ancestor cannot be an incomplete key")
+                if app is not None:
+                    if app != ancestor.app():
+                        raise TypeError("ancestor/app id mismatch")
+                else:
+                    app = ancestor.app()
+                if namespace is not None:
+                    if namespace != ancestor.namespace():
+                        raise TypeError("ancestor/namespace mismatch")
+                else:
+                    namespace = ancestor.namespace()
+        if filters is not None:
+            if not isinstance(filters, Node):
+                raise TypeError("filters must be a query Node or None; "
+                                F"received {filters}")
+        if orders is not None:
+            if not isinstance(orders, (list,)):  # datastore_query.Order
+                raise TypeError("orders must be an Order instance or None; "
+                                F"received {orders}")
+        # if default_options is not None:  # Optional QueryOptions object.
+        #     if not isinstance(default_options, datastore_rpc.BaseConfiguration):
+        #         raise TypeError("default_options must be a Configuration or None; "
+        #                         F"received {default_options}")
+        #     if projection is not None:
+        #         if default_options.projection is not None:
+        #             raise TypeError("cannot use projection keyword argument and "
+        #                             "default_options.projection at the same time")
+        #         if default_options.keys_only is not None:
+        #             raise TypeError("cannot use projection keyword argument and "
+        #                             "default_options.keys_only at the same time")
+
+        self.kind = kind
+        self.ancestor = ancestor
+        self.filters = filters
+        self.orders = orders
+        self.app = app
+        self.namespace = namespace
+        self.default_options = default_options
+
+        self.projection = None
+        if projection is not None:
+          if not projection:
+            raise TypeError('projection argument cannot be empty')
+          if not isinstance(projection, (tuple, list)):
+            raise TypeError("projection must be a tuple, list or None; "
+                            F"received {projection}")
+          self._check_properties(self._to_property_names(projection))
+          self.projection = tuple(projection)
+
+        self.group_by = None
+        if group_by is not None:
+          if not group_by:
+            raise TypeError('group_by argument cannot be empty')
+          if not isinstance(group_by, (tuple, list)):
+            raise TypeError("group_by must be a tuple, list or None; "
+                            F"received {group_by}")
+          self._check_properties(self._to_property_names(group_by))
+          self.group_by = tuple(group_by)
+
+    def _to_property_names(self, properties):
+        if not isinstance(properties, (list, tuple)):
+          properties = [properties]
+        fixed = []
+        for prop in properties:
+          if isinstance(prop, str):
+            fixed.append(prop)
+          elif isinstance(prop, model.Property):
+            fixed.append(prop._name)
+          else:
+            raise TypeError(
+                F"Unexpected property {prop}; should be string or Property")
+        return fixed
+
+    def _check_properties(self, fixed, **kwargs):
+        modelclass = model.Model._kind_map.get(self.__kind)
+        if modelclass is not None:
+          modelclass._check_properties(fixed, **kwargs)
 
 
 def gql(*args, **kwargs):

ndb/tests/unit/test_query.py

@@ -881,8 +881,32 @@ def test_OR():
 class TestQuery:
     @staticmethod
     def test_constructor():
-        with pytest.raises(NotImplementedError):
-            query.Query()
+        q = query.Query(kind='Foo')
+        assert q.kind == 'Foo'
+        assert q.ancestor == None
+        assert q.filters == None
+        assert q.orders == None
+
+    @staticmethod
+    def test_query_errors():
+        # with pytest.raises(TypeError):
+        #     query.Query(ancestor=
+        #                 query.ParameterizedFunction('user', query.Parameter(1)))
+        with pytest.raises(TypeError):
+            query.Query(ancestor=42)
+        # with pytest.raises(ValueError):
+        #     query.Query(ancestor=model.Key('X', None))
+        # with pytest.raises(TypeError):
+        #     query.Query(ancestor=model.Key('X', 1), app='another')
+        # with pytest.raises(TypeError):
+        #     query.Query(ancestor=model.Key('X', 1), namespace='another')
+        with pytest.raises(TypeError):
+            query.Query(filters=42)
+        with pytest.raises(TypeError):
+            query.Query(orders=42)
+        # with pytest.raises(TypeError):
+        #     query.Query(default_options=42)
+
 
 
 def test_gql():