U >iX@s:dZddlmZddlZddlmZmZmZmZm Z m Z m Z m Z m Z mZmZmZddlmZddlmZddlmZerddlmZdd lmZdd lmZmZdd lm Z dd l!m"Z"dd l#m$Z$ddl%m&Z&ddl'm(Z(ddl)m*Z*ddl+m,Z,ddl-m.Z.dZ/Gddde eZ0ddddZ1ddddZ2dS)zHClasses for representing collections for the Google Cloud Firestore API.) annotationsN) TYPE_CHECKINGAnyAsyncGenerator AsyncIterator Coroutine GeneratorGenericIterableSequenceTupleUnionOptional)retry)_helpers) QueryType)BaseAggregationQuery)DocumentSnapshot)BaseVectorQueryDistanceMeasure)DocumentReference) FieldPath)ExplainOptions)QueryResultsList)StreamGenerator) Transaction)Vector) VectorQueryZ>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789c @s>eZdZdZddddZddZedd Zed d Zd dd dZ ddddZ ddddZ dqdddddZ ddddZ drdddd d!d"d#d$Zdsdddd d%d"d&d'Zdtd(dd d)d*d+d,Zdud(dd d-d*d.d/Zd dd0d1Zd2d d3d4d5Zdvdd6ddd d7d8d9Zd:d d;dd d?d@dAZd>dBdCdDZd>d dEdFdGZdHd dIdJdKZdHd dIdLdMZdHd dIdNdOZdHd dIdPdQZdwdd dRdSdTdUZdxddVdWdd dXdYdZd[d\ZdyddVdWdd dXd]dZd^d_Zd`daZ dzdbdcZ!d{dddedfdgZ"d|dddedhdiZ#dddjd:dkd>dldd dmdndodpZ$dS)}BaseCollectionReferencea A reference to a collection in a Firestore database. The collection may already exist or this class can facilitate creation of documents within the collection. Args: path (Tuple[str, ...]): The components in the collection path. This is a series of strings representing each collection and sub-collection ID, as well as the document IDs for any documents that contain a sub-collection. kwargs (dict): The keyword arguments for the constructor. The only supported keyword is ``client`` and it must be a :class:`~google.cloud.firestore_v1.client.Client` if provided. It represents the client that created this collection reference. Raises: ValueError: if * the ``path`` is empty * there are an even number of elements * a collection ID in ``path`` is not a string * a document ID in ``path`` is not a string TypeError: If a keyword other than ``client`` is used. NonereturncOs6tj|dd||_|dd|_|r2td|ddS)NT)Z is_collectionclientzReceived unexpected argumentszOnly `client` is supported)rZ verify_path_pathpop_client TypeError)selfpathkwargsr*M/tmp/pip-unpacked-wheel-599y42ri/google/cloud/firestore_v1/base_collection.py__init__Usz BaseCollectionReference.__init__cCs(t||jstS|j|jko&|j|jkSN) isinstance __class__NotImplementedr#r%)r'otherr*r*r+__eq__^s zBaseCollectionReference.__eq__cCs |jdS)zfThe collection identifier. Returns: str: The last component of the path. )r#r'r*r*r+idcszBaseCollectionReference.idcCs,t|jdkrdS|jdd}|jj|S)aDocument that owns the current collection. Returns: Optional[:class:`~google.cloud.firestore_v1.document.DocumentReference`]: The parent document, if the current collection is not a top-level collection. Nr3)lenr#r%document)r' parent_pathr*r*r+parentls zBaseCollectionReference.parentrcCstdSr-NotImplementedErrorr4r*r*r+_query{szBaseCollectionReference._queryrcCstdSr-r;r4r*r*r+_aggregation_query~sz*BaseCollectionReference._aggregation_queryrcCstdSr-r;r4r*r*r+ _vector_querysz%BaseCollectionReference._vector_queryNz Optional[str]r) document_idr!cCs6|dkrt}|jdr$|j|fn|f}|jj|S)aCreate a sub-document underneath the current collection. Args: document_id (Optional[str]): The document identifier within the current collection. If not provided, will default to a random 20 character string composed of digits, uppercase and lowercase and letters. Returns: :class:`~google.cloud.firestore_v1.document.DocumentReference`: The child document. Nr)_auto_idr#r%r8)r'r@Z child_pathr*r*r+r8s z BaseCollectionReference.documentzTuple[Any, str]cCsD|j}|dkr$tj|jjdf}n|j}tj||jf}||fS)arGet fully-qualified parent path and prefix for this collection. Returns: Tuple[str, str]: Pair of * the fully-qualified (with database and project) path to the parent of this collection (will either be the database path or a document path). * the prefix to a document in this collection. NZ documents)r:rDOCUMENT_PATH_DELIMITERjoinr%Z_database_stringZ_document_pathr5)r'Z parent_docr9Zexpected_prefixr*r*r+ _parent_infos  z$BaseCollectionReference._parent_infodictz2retries.Retry | retries.AsyncRetry | object | NonezOptional[float]zTuple[DocumentReference, dict]) document_datar@rtimeoutr!cCs,|dkrt}||}t||}||fS)z+Shared setup for async / sync :method:`add`N)rAr8rmake_retry_timeout_kwargs)r'rFr@rrGZ document_refr)r*r*r+ _prep_adds   z!BaseCollectionReference._prep_addz=``, ``>``, and ``in``. Optional. value (Any): The value to compare the field against in the filter. If ``value`` is :data:`None` or a NaN, then ``==`` is the only allowed operation. If ``op_string`` is ``in``, ``value`` must be a sequence of values. Optional. filter (class:`~google.cloud.firestore_v1.base_query.BaseFilter`): an instance of a Filter. Either a FieldFilter or a CompositeFilter. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A filtered query. Raises: ValueError, if both the positional arguments (field_path, op_string, value) and the filter keyword argument are passed at the same time. NzICan't pass in both the positional arguments and 'filter' at the same time__name__inrU)r= ValueErrorr.strr8appendwhere)r'rWrXvaluerVrTZ wrapped_namesnamer*r*r+r^s!   zBaseCollectionReference.wherer\)rWr!cKs|}|j|f|S)aCreate an "order by" query with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.order_by` for more information on this method. Args: field_path (str): A field path (``.``-delimited list of field names) on which to order the query results. kwargs (Dict[str, Any]): The keyword arguments to pass along to the query. The only supported keyword is ``direction``, see :meth:`~google.cloud.firestore_v1.query.Query.order_by` for more information. Returns: :class:`~google.cloud.firestore_v1.query.Query`: An "order by" query. )r=order_by)r'rWr)rTr*r*r+ra4sz BaseCollectionReference.order_byint)countr!cCs|}||S)a-Create a limited query with this collection as parent. .. note:: `limit` and `limit_to_last` are mutually exclusive. Setting `limit` will drop previously set `limit_to_last`. See :meth:`~google.cloud.firestore_v1.query.Query.limit` for more information on this method. Args: count (int): Maximum number of documents to return that match the query. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A limited query. )r=limitr'rcrTr*r*r+rdJszBaseCollectionReference.limit)rccCs|}||S)aDCreate a limited to last query with this collection as parent. .. note:: `limit` and `limit_to_last` are mutually exclusive. Setting `limit_to_last` will drop previously set `limit`. See :meth:`~google.cloud.firestore_v1.query.Query.limit_to_last` for more information on this method. Args: count (int): Maximum number of documents to return that match the query. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A limited to last query. )r= limit_to_lastrer*r*r+rf`sz%BaseCollectionReference.limit_to_last) num_to_skipr!cCs|}||S)aSkip to an offset in a query with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.offset` for more information on this method. Args: num_to_skip (int): The number of results to skip at the beginning of query results. (Must be non-negative.) Returns: :class:`~google.cloud.firestore_v1.query.Query`: An offset query. )r=offset)r'rgrTr*r*r+rhuszBaseCollectionReference.offsetz*Union[DocumentSnapshot, dict, list, tuple])document_fieldsr!cCs|}||S)aStart query at a cursor with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.start_at` for more information on this method. Args: document_fields (Union[:class:`~google.cloud.firestore_v1. document.DocumentSnapshot`, dict, list, tuple]): A document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A query with cursor. )r=start_atr'rirTr*r*r+rjsz BaseCollectionReference.start_atcCs|}||S)aStart query after a cursor with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.start_after` for more information on this method. Args: document_fields (Union[:class:`~google.cloud.firestore_v1. document.DocumentSnapshot`, dict, list, tuple]): A document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A query with cursor. )r= start_afterrkr*r*r+rlsz#BaseCollectionReference.start_aftercCs|}||S)aEnd query before a cursor with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.end_before` for more information on this method. Args: document_fields (Union[:class:`~google.cloud.firestore_v1. document.DocumentSnapshot`, dict, list, tuple]): A document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A query with cursor. )r= end_beforerkr*r*r+rmsz"BaseCollectionReference.end_beforecCs|}||S)aEnd query at a cursor with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.end_at` for more information on this method. Args: document_fields (Union[:class:`~google.cloud.firestore_v1. document.DocumentSnapshot`, dict, list, tuple]): A document snapshot or a dictionary/list/tuple of fields representing a query results cursor. A cursor is a collection of values that represent a position in a query result set. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A query with cursor. )r=end_atrkr*r*r+rnszBaseCollectionReference.end_atzTuple[Any, dict])rrGr!cCs|}t||}||fS)z:Shared setup for async / sync :meth:`get` / :meth:`stream`)r=rrH)r'rrGrTr)r*r*r+_prep_get_or_streams z+BaseCollectionReference._prep_get_or_stream)explain_optionszOptional[Transaction]zOptional[ExplainOptions]z\QueryResultsList[DocumentSnapshot] | Coroutine[Any, Any, QueryResultsList[DocumentSnapshot]]) transactionrrGrpr!cCstdSr-r;r'rqrrGrpr*r*r+gets zBaseCollectionReference.getzCStreamGenerator[DocumentSnapshot] | AsyncIterator[DocumentSnapshot]cCstdSr-r;rrr*r*r+streamszBaseCollectionReference.streamcCstdSr-r;)r'callbackr*r*r+ on_snapshotsz#BaseCollectionReference.on_snapshotcCs|j|dS)z Adds a count over the nested query. :type alias: str :param alias: (Optional) The alias for the count alias)r>rc)r'rxr*r*r+rcszBaseCollectionReference.countzstr | FieldPath) field_refcCs|j||dS)a Adds a sum over the nested query. :type field_ref: Union[str, google.cloud.firestore_v1.field_path.FieldPath] :param field_ref: The field to aggregate across. :type alias: Optional[str] :param alias: Optional name of the field to store the result of the aggregation into. If not provided, Firestore will pick a default name following the format field_. rw)r>sumr'ryrxr*r*r+rzs zBaseCollectionReference.sumcCs|j||dS)a Adds an avg over the nested query. :type field_ref: Union[str, google.cloud.firestore_v1.field_path.FieldPath] :param field_ref: The field to aggregate across. :type alias: Optional[str] :param alias: Optional name of the field to store the result of the aggregation into. If not provided, Firestore will pick a default name following the format field_. rw)r>avgr{r*r*r+r|s zBaseCollectionReference.avgdistance_result_fielddistance_thresholdzUnion[Vector, Sequence[float]]rr) vector_field query_vectorrddistance_measurer~rr!cCs|j||||||dS)a Finds the closest vector embeddings to the given query vector. Args: vector_field (str): An indexed vector field to search upon. Only documents which contain vectors whose dimensionality match the query_vector can be returned. query_vector(Union[Vector, Sequence[float]]): The query vector that we are searching on. Must be a vector of no more than 2048 dimensions. limit (int): The number of nearest neighbors to return. Must be a positive integer of no more than 1000. distance_measure (:class:`DistanceMeasure`): The Distance Measure to use. distance_result_field (Optional[str]): Name of the field to output the result of the vector distance calculation distance_threshold (Optional[float]): A threshold for which no less similar documents will be returned. Returns: :class`~firestore_v1.vector_query.VectorQuery`: the vector query. r})r? find_nearest)r'rrrdrr~rr*r*r+r,sz$BaseCollectionReference.find_nearest)N)NNN)NNN)NNN)NNN)NNN)NN)NNN)NNN)N)N)N)%rY __module__ __qualname____doc__r,r2propertyr5r:r=r>r?r8rDrIrJrPrQrRrSr^rardrfrhrjrlrmrnrorsrtrvrcrzr|rr*r*r*r+r;s     5   rr\r cCsdddtdDS)zGenerate a "random" automatically generated ID. Returns: str: A 20 character string composed of digits, uppercase and lowercase and letters. css|]}ttVqdSr-)randomchoice_AUTO_ID_CHARS).0rNr*r*r+ Zsz_auto_id..)rCranger*r*r*r+rARsrArcCs|jtjd}||S)zConvert Document resource to document ref. Args: collection_reference (google.api_core.page_iterator.GRPCIterator): iterator response item (dict): document resource r3)r`splitrrBr8)Zcollection_referenceitemr@r*r*r+_item_to_document_ref]sr)3r __future__rrtypingrrrrrrr r r r r rZgoogle.api_corerretriesZgoogle.cloud.firestore_v1rZ$google.cloud.firestore_v1.base_queryrZ*google.cloud.firestore_v1.base_aggregationrZ'google.cloud.firestore_v1.base_documentrZ+google.cloud.firestore_v1.base_vector_queryrrZ"google.cloud.firestore_v1.documentrZ$google.cloud.firestore_v1.field_pathrZ'google.cloud.firestore_v1.query_profilerZ'google.cloud.firestore_v1.query_resultsrZ*google.cloud.firestore_v1.stream_generatorrZ%google.cloud.firestore_v1.transactionrZ google.cloud.firestore_v1.vectorrZ&google.cloud.firestore_v1.vector_queryrrrrArr*r*r*r+s4 8