VSfUTdZddlmZddlZddlmZddlmZddl m Z ddl m Z ddl mZdd l mZdd lmZdd lmZdd lmZmZmZmZmZmZmZmZmZmZmZm Z m!Z!e!rdd l"m#Z#ddl$m%Z%ddl&m'Z'ddl(m)Z)dZ*GddeeZ+ddZ,ddZ-y)zHClasses for representing collections for the Google Cloud Firestore API.) annotationsN)retry)_helpers)DistanceMeasure)DocumentReference)BaseAggregationQuery)BaseVectorQuery) QueryType)Vector) OptionalAnyAsyncGenerator Coroutine GeneratorGeneric AsyncIteratorIteratorIterableNoReturnTupleUnion TYPE_CHECKING)DocumentSnapshot) Transaction) FieldPath) VectorQuery>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789c eZdZdZd$dZdZedZedZd%dZ d&dZ d'dZ d(d)d Z d*d Z d+ d,d Z d+ d-d Z d+ d.dZ d+ d/dZd%dZd0dZ d+d d d1dZd2dZd3dZd4dZd5dZ d6dZ d6dZ d6dZ d6dZ d7 d8dZ d+ d9dZ d+ d:dZd;dZ d(d Z!d(dBaseCollectionReferencea 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. ctj|d||_|jdd|_|r t d|dy)NT) is_collectionclientzReceived unexpected argumentszOnly `client` is supported)r verify_path_pathpop_client TypeError)selfpathkwargss hC:\Users\user\Documents\project_loop\venv\Lib\site-packages\google/cloud/firestore_v1/base_collection.py__init__z BaseCollectionReference.__init__SsHT6 zz(D1 /9U  ct||jstS|j|jk(xr|j|jk(SN) isinstance __class__NotImplementedr$r&)r(others r+__eq__zBaseCollectionReference.__eq__\s;%0! !zzU[[(JT\\U]]-JJr-c |jdS)zfThe collection identifier. Returns: str: The last component of the path. )r$r(s r+idzBaseCollectionReference.idaszz"~r-ct|jdk(ry|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. Nr6)lenr$r&document)r( parent_paths r+parentzBaseCollectionReference.parentjs= tzz?a **Sb/K$t||$$k22r-ctr/NotImplementedErrorr7s r+_queryzBaseCollectionReference._queryy!!r-ctr/r@r7s r+_aggregation_queryz*BaseCollectionReference._aggregation_query|rCr-ctr/r@r7s r+ _vector_queryz%BaseCollectionReference._vector_queryrCr-Nc| t}|jdr|j|fzn|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. r)_auto_idr$r&r<)r( document_id child_paths r+r<z BaseCollectionReference.documentsH  "*K 59JJqMTZZ;.0 ~ $t||$$j11r-c|j}|6tjj|jj df}n |j }tjj||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. documents)r>rDOCUMENT_PATH_DELIMITERjoinr&_database_string_document_pathr8)r( parent_docr=expected_prefixs r+ _parent_infoz$BaseCollectionReference._parent_infosr[[  "::??.. <K%33K"::??dgg@VWO++r-cp| t}|j|}tj||}||fS)z+Shared setup for async / sync :method:`add`)rIr<rmake_retry_timeout_kwargs)r( document_datarJrtimeout document_refr*s r+ _prep_addz!BaseCollectionReference._prep_adds<  "*K}}[1 33E7CV##r-ctr/r@)r(rWrJrrXs r+addzBaseCollectionReference.adds "!r-c|j\}}||j|dddid}tj||}||fS)z6Shared setup for async / sync :method:`list_documents`T field_pathsN)r> collection_id page_size show_missingmask)rTr8rrV)r(r`rrXr>_requestr*s r+_prep_list_documentsz,BaseCollectionReference._prep_list_documentssU%%' !WW" #D)  33E7Cr-ctr/r@)r(r`rrXs r+list_documentsz&BaseCollectionReference.list_documents "!r-c>|jjSr/)rB recursiver7s r+rjz!BaseCollectionReference.recursives{{}&&((r-cD|j}|j|S)aCreate a "select" query with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.select` for more information on this method. Args: field_paths (Iterable[str, ...]): An iterable of field paths (``.``-delimited list of field names) to use as a projection of document fields in the query results. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A "projected" query. )rBselect)r(r^querys r+rlzBaseCollectionReference.selects  ||K((r-filterc|j}|ri|rg| td|dk(rB|dk(r=g}|D]4}t|tr|j |}|j |6|}|j |||S|j |S)aCreate a "where" query with this collection as parent. See :meth:`~google.cloud.firestore_v1.query.Query.where` for more information on this method. Args: field_path (str): A field path (``.``-delimited list of field names) for the field to filter on. Optional. op_string (str): A comparison operation in the form of a string. Acceptable values are ``<``, ``<=``, ``==``, ``>=``, ``>``, 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. zICan't pass in both the positional arguments and 'filter' at the same time__name__inrn)rB ValueErrorr0strr<appendwhere)r( field_path op_stringvaluerorm wrapped_namesnames r+rvzBaseCollectionReference.wheresB  )! _Z'I,= " !/D!$,#}}T2!((. / &;;z9e< <;;f;- -r-c H|j}|j|fi|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. )rBorder_by)r(rwr*rms r+r}z BaseCollectionReference.order_by2s%& u~~j3F33r-cD|j}|j|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. )rBlimitr(countrms r+rzBaseCollectionReference.limitHs& {{5!!r-cD|j}|j|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. )rB limit_to_lastrs r+rz%BaseCollectionReference.limit_to_last^s $ ""5))r-cD|j}|j|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. )rBoffset)r( num_to_skiprms r+rzBaseCollectionReference.offsetss ||K((r-cD|j}|j|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. )rBstart_atr(document_fieldsrms r+rz BaseCollectionReference.start_ats( ~~o..r-cD|j}|j|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. )rB start_afterrs r+rz#BaseCollectionReference.start_afters (   11r-cD|j}|j|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. )rB end_beforers r+rz"BaseCollectionReference.end_befores ( 00r-cD|j}|j|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. )rBend_atrs r+rzBaseCollectionReference.end_ats( ||O,,r-cV|j}tj||}||fS)z:Shared setup for async / sync :meth:`get` / :meth:`stream`)rBrrV)r(rrXrmr*s r+_prep_get_or_streamz+BaseCollectionReference._prep_get_or_streams+  33E7Cf}r-ctr/r@r( transactionrrXs r+getzBaseCollectionReference.getrhr-ctr/r@rs r+streamzBaseCollectionReference.streams "!r-ctr/r@)r(callbacks r+ on_snapshotz#BaseCollectionReference.on_snapshotrCr-cB|jj|S)z Adds a count over the nested query. :type alias: str :param alias: (Optional) The alias for the count alias)rEr)r(rs r+rzBaseCollectionReference.counts!&&(..U.;;r-cD|jj||S)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_. r)rEsumr( field_refrs r+rzBaseCollectionReference.sum s#&&(,,Ye,DDr-cD|jj||S)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_. r)rEavgrs r+rzBaseCollectionReference.avgs#&&(,,Ye,DDr-cF|jj||||S)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(Vector): 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. Returns: :class`~firestore_v1.vector_query.VectorQuery`: the vector query. )rG find_nearest)r( vector_field query_vectorrdistance_measures r+rz$BaseCollectionReference.find_nearest%s**!!#00 ,/?  r-)returnNone)rr )rr)rr r/)rJ Optional[str]rr)rzTuple[Any, str])NNN) rWdictrJrrOptional[retries.Retry]rXOptional[float]rzTuple[DocumentReference, dict]) rWrrJrrrrXrrzrBrErGr<rTrZr\rergrjrlrvr}rrrrrrrrrrrrrrrr-r+rr9s2K  3 3"""2,,2&*)-#' $$#$' $ ! $ ( $&&*)-#' ""#"' " ! " F "$()-#'  '!   0$()-#' " "'"! "   "))*%)#' 3.  3.!3.!3. 3.j4,",**)$/I/ /.2I2 2.1I1 1.-I- -2*.#' & !   .2)-#' "*"'"! "   ".2)-#' "*"'"! " L ""< E E     *    r-rcDdjdtdDS)zGenerate a "random" automatically generated ID. Returns: str: A 20 character string composed of digits, uppercase and lowercase and letters. c3NK|]}tjtywr/)randomchoice_AUTO_ID_CHARS).0rcs r+ z_auto_id..GsDQ6==0Ds#%)rOrangerr-r+rIrI?s 77D%)D DDr-c||jjtjd}|j |S)zConvert Document resource to document ref. Args: collection_reference (google.api_core.page_iterator.GRPCIterator): iterator response item (dict): document resource r6)r{splitrrNr<)collection_referenceitemrJs r+_item_to_document_refrJs2))//("B"BCBGK  ( ( 55r-)rrt)rr).r __future__rrgoogle.api_corerretriesgoogle.cloud.firestore_v1r+google.cloud.firestore_v1.base_vector_queryr"google.cloud.firestore_v1.documentr*google.cloud.firestore_v1.base_aggregationrr $google.cloud.firestore_v1.base_queryr google.cloud.firestore_v1.vectorr typingr r rrrrrrrrrrr'google.cloud.firestore_v1.base_documentr%google.cloud.firestore_v1.transactionr$google.cloud.firestore_v1.field_pathrfirestore_v1.vector_queryrrrrIrrr-r+rsrO" ,.G@KG:3"HA>5QC gi0C LE 6r-