a !feG@shdZddlZddlmZddlmZddlmZddl m Z Gddde Z Gd d d e Z d d ZdS) z0Create / interact with gcloud datastore queries.N)_ensure_tuple_or_list) query_pb2)helpers)Keyc@s$eZdZdZejjejjejjejj ejj dZ d(ddZ e ddZe d d Zejd d Ze d d Zejdd Ze ddZejddZejddZe ddZddZe ddZejddZddZd)ddZe dd Zejd!d Ze d"d#Zejd$d#Zd*d&d'ZdS)+QueryaA Query against the Cloud Datastore. This class serves as an abstraction for creating a query over data stored in the Cloud Datastore. :type client: :class:`gcloud.datastore.client.Client` :param client: The client used to connect to datastore. :type kind: string :param kind: The kind to query. :type project: string :param project: The project associated with the query. If not passed, uses the client's value. :type namespace: string or None :param namespace: The namespace to which to restrict results. If not passed, uses the client's value. :type ancestor: :class:`gcloud.datastore.key.Key` or None :param ancestor: key of the ancestor to which this query's results are restricted. :type filters: sequence of (property_name, operator, value) tuples :param filters: property filters applied by this query. :type projection: sequence of string :param projection: fields returned as part of query results. :type order: sequence of string :param order: field names used to order query results. Prepend '-' to a field name to sort it in descending order. :type distinct_on: sequence of string :param distinct_on: field names used to group query results. :raises: ValueError if ``project`` is not passed and no implicit default is set. )z<=z>=<>=Nc Csv||_||_|p|j|_|p |j|_||_g|_|D]\} } } || | | q4t d||_ t d||_ t d| |_ dS)N projectionorder distinct_on) _client_kindproject_project namespace _namespace _ancestor_filters add_filterr _projection_order _distinct_on) selfclientkindrrancestorfiltersr r r property_nameoperatorvaluer r W/var/www/html/python-backend/venv/lib/python3.9/site-packages/gcloud/datastore/query.py__init__Ks     zQuery.__init__cCs|jp |jjS)zjGet the project for this Query. :rtype: str :returns: The project for the query. )rrrrr r r"rcsz Query.projectcCs|jp |jjS)zvThis query's namespace :rtype: string or None :returns: the namespace assigned to this query )rrrr$r r r"rlszQuery.namespacecCst|tstd||_dS)zCUpdate the query's namespace. :type value: string zNamespace must be a stringN) isinstancestr ValueErrorrrr!r r r"rus cCs|jS)zeGet the Kind of the Query. :rtype: string :returns: The kind for the query. )rr$r r r"rsz Query.kindcCst|tstd||_dS)aUpdate the Kind of the Query. :type value: string :param value: updated kind for the query. .. note:: The protobuf specification allows for ``kind`` to be repeated, but the current implementation returns an error if more than one value is passed. If the back-end changes in the future to allow multiple values, this method will be updated to allow passing either a string or a sequence of strings. zKind must be a stringN)r%r& TypeErrorrr(r r r"rs cCs|jS)zsThe ancestor key for the query. :rtype: Key or None :returns: The ancestor for the query. rr$r r r"rszQuery.ancestorcCst|tstd||_dS)zlSet the ancestor for the query :type value: Key :param value: the new ancestor key zAncestor must be a KeyN)r%rr)rr(r r r"rs cCs d|_dS)z"Remove the ancestor for the query.Nr*r$r r r"rscCs|jddS)zFilters set on the query. :rtype: sequence of (property_name, operator, value) tuples. :returns: The filters set on the query. N)rr$r r r"rsz Query.filterscCs\|j|dur(d|f}d}t|||dkrFt|tsFtd||j|||fdS)aFilter the query based on a property name, operator and a value. Expressions take the form of:: .add_filter('', '', ) where property is a property stored on the entity in the datastore and operator is one of ``OPERATORS`` (ie, ``=``, ``<``, ``<=``, ``>``, ``>=``):: >>> from gcloud import datastore >>> client = datastore.Client() >>> query = client.query(kind='Person') >>> query.add_filter('name', '=', 'James') >>> query.add_filter('age', '>', 50) :type property_name: string :param property_name: A property name. :type operator: string :param operator: One of ``=``, ``<``, ``<=``, ``>``, ``>=``. :type value: :class:`int`, :class:`str`, :class:`bool`, :class:`float`, :class:`NoneType`, :class:`datetime.datetime`, :class:`gcloud.datastore.key.Key` :param value: The value to filter on. :raises: :class:`ValueError` if ``operation`` is not one of the specified values, or if a filter names ``'__key__'`` but passes an invalid value (a key is required). NzInvalid expression: "%s"z#Please use one of: =, <, <=, >, >=.__key__zInvalid key: "%s") OPERATORSgetr'r%rrappend)rrr r! error_messageZchoices_messager r r"rs!   zQuery.add_filtercCs|jddS)zFields names returned by the query. :rtype: sequence of string :returns: Names of fields in query results. Nrr$r r r"r szQuery.projectioncCs"t|tr|g}||jdd<dS)zSet the fields returned the query. :type projection: string or sequence of strings :param projection: Each value is a string giving the name of a property to be included in the projection query. N)r%r&r)rr r r r"r s cCsdg|jdd<dS)z(Set the projection to include only keys.r+Nr0r$r r r" keys_onlyszQuery.keys_onlyr cCs|d||dS)aFilter on a key. :type key: :class:`gcloud.datastore.key.Key` :param key: The key to filter on. :type operator: string :param operator: (Optional) One of ``=``, ``<``, ``<=``, ``>``, ``>=``. Defaults to ``=``. r+N)r)rkeyr r r r" key_filters zQuery.key_filtercCs|jddS)zNames of fields used to sort query results. :rtype: sequence of string :returns: The order(s) set on the query. N)rr$r r r"r sz Query.ordercCs"t|tr|g}||jdd<dS)aSet the fields used to sort query results. Sort fields will be applied in the order specified. :type value: string or sequence of strings :param value: Each value is a string giving the name of the property on which to sort, optionally preceded by a hyphen (-) to specify descending order. Omitting the hyphen implies ascending order. N)r%r&rr(r r r"r s cCs|jddS)zNames of fields used to group query results. :rtype: sequence of string :returns: The "distinct on" fields set on the query. N)rr$r r r"r &szQuery.distinct_oncCs"t|tr|g}||jdd<dS)zSet fields used to group query results. :type value: string or sequence of strings :param value: Each value is a string giving the name of a property to use to group results together. N)r%r&rr(r r r"r /s rcCs |dur|j}t||||||S)aExecute the Query; return an iterator for the matching entities. For example:: >>> from gcloud import datastore >>> client = datastore.Client() >>> query = client.query(kind='Person') >>> query.add_filter('name', '=', 'Sally') >>> list(query.fetch()) [, , ...] >>> list(query.fetch(1)) [] :type limit: integer or None :param limit: An optional limit passed through to the iterator. :type offset: integer :param offset: An optional offset passed through to the iterator. :type start_cursor: bytes :param start_cursor: An optional cursor passed through to the iterator. :type end_cursor: bytes :param end_cursor: An optional cursor passed through to the iterator. :type client: :class:`gcloud.datastore.client.Client` :param client: client used to connect to datastore. If not supplied, uses the query's value. :rtype: :class:`Iterator` :returns: The iterator for the query. :raises: ValueError if ``connection`` is not passed and no implicit default has been set. N)rIterator)rlimitoffset start_cursor end_cursorrr r r"fetch;s $ z Query.fetch)NNNNr r r r )r )NrNNN)__name__ __module__ __qualname____doc__ _query_pb2PropertyFilterZLESS_THAN_OR_EQUALZGREATER_THAN_OR_EQUALZ LESS_THANZ GREATER_THANEQUALr,r#propertyrrsetterrrdeleterrrr r1r3r r r9r r r r"rsh)           +       rc@sHeZdZdZejjZejjejj ejj fZ d ddZ ddZ ddZdS) r4aIRepresent the state of a given execution of a Query. :type query: :class:`gcloud.datastore.query.Query` :param query: Query object holding permanent configuration (i.e. things that don't change on with each page in a results set). :type client: :class:`gcloud.datastore.client.Client` :param client: The client used to make a request. :type limit: integer :param limit: (Optional) Limit the number of results returned. :type offset: integer :param offset: (Optional) Offset used to begin a query. :type start_cursor: bytes :param start_cursor: (Optional) Cursor to begin paging through query results. :type end_cursor: bytes :param end_cursor: (Optional) Cursor to end paging through query results. NcCs:||_||_||_||_||_||_d|_|_d|_dS)N) _queryr_limit_offset _start_cursor _end_cursor_page _more_results_skipped_results)rqueryrr5r6r7r8r r r"r#s zIterator.__init__c Cs t|j}|j}|dur$t||_|j}|dur>t||_|jdurR|j|j _ |j durd|j |_ |j j}|j jj||jj|jj|o|jd}|\}}}|_|dkrd|_n t||_d|_||jkrd|_n||jvrd|_ntddd|D|_|j|j|jfS) aFetch a single "page" of query results. Low-level API for fine control: the more convenient API is to iterate on the current Iterator. :rtype: tuple, (entities, more_results, cursor) :returns: The next page of results. N)Zquery_pbrrZtransaction_idTFz-Unexpected value returned for `more_results`.cSsg|]}t|qSr )rZentity_from_protobuf).0entityr r r" sz&Iterator.next_page..)_pb_from_queryrDrGbase64urlsafe_b64decoder7rHr8rEr5r!rFr6rZcurrent_transaction connectionZ run_queryrridrKurlsafe_b64encode _NOT_FINISHEDrJ _FINISHEDr'rI) rpbr7r8Z transactionZ query_resultsZ entity_pbsZcursor_as_bytesZmore_results_enumr r r" next_pagesD         zIterator.next_pageccsn||jD] }|Vq|js"qjt|j}|jdurD|j|8_|jdur|jdur|j|j8_qdS)zGenerator yielding all results matching our query. :rtype: sequence of :class:`gcloud.datastore.entity.Entity` N)rZrIrJlenrErFrK)rrOZ num_resultsr r r"__iter__s   zIterator.__iter__)NNNN)r:r;r<r=r>ZQueryResultBatchZ NOT_FINISHEDrWZNO_MORE_RESULTSZMORE_RESULTS_AFTER_LIMITZMORE_RESULTS_AFTER_CURSORrXr#rZr\r r r r"r4fs 6r4cCsft}|jD]}||jj_q|jr6|j|j_|jj}tj j |_ |j r|j }|jj}d|j_tjj|_ |jj||jD]^\}}}|j|} |jj} || j_| | _ |dkr| } | jj| qt| j|q|js|d|jD]F} |j} | dr4| dd| j_| j| _n| | j_| j| _q|jD]}||j_qN|S)aConvert a Query instance to the corresponding protobuf. :type query: :class:`Query` :param query: The source query. :rtype: :class:`gcloud.datastore._generated.query_pb2.Query` :returns: A protobuf that can be sent to the protobuf API. N.b. that it does not contain "in-flight" fields for ongoing query executions (cursors, offset, limit). r+filter-N) r>rr addrAnamerr]composite_filterZCompositeFilterANDoprZ to_protobufrproperty_filterr?Z HAS_ANCESTORr! key_valueZCopyFromr,r-rZ_set_protobuf_valueZ ClearFieldr startswithZ DESCENDING directionZ ASCENDINGr )rLrYZprojection_namerbZ ancestor_pbZancestor_filterrr r!Z pb_op_enumreZkey_pbpropZproperty_orderZdistinct_on_namer r r"rQsD               rQ)r=rRZgcloud._helpersrZgcloud.datastore._generatedrr>Zgcloud.datastorerZgcloud.datastore.keyrobjectrr4rQr r r r"s    Ow