ѮhX4dZddlmZddlZddlmZmZmZmZm Z m Z m Z m Z m Z mZmZmZddlmZddlmZddlmZerDddlmZdd 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/Gdde eZ0ddZ1ddZ2y)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) 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- d0dZ d- d1dZd'dZd2dZ d-d d d3dZd4dZd5dZd6dZd7dZ d8dZ d8dZ d8dZ d8dZ d9 d:dZ d-d d d;dZ d-d d dd%Z$y )?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. ctj|d||_|jdd|_|r t d|dy)NT) is_collectionclientzReceived unexpected argumentszOnly `client` is supported)r verify_path_pathpop_client TypeError)selfpathkwargss {/home/www/academy-backend.kofcorporation.com/venv/lib/python3.12/site-packages/google/cloud/firestore_v1/base_collection.py__init__z BaseCollectionReference.__init__UsHT6 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.idcszz"~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. Nr8)lenr&r(document)r* parent_paths r-parentzBaseCollectionReference.parentls= tzz?a **Sb/K$t||$$k22r/ctr1NotImplementedErrorr9s r-_queryzBaseCollectionReference._query{!!r/ctr1rBr9s r-_aggregation_queryz*BaseCollectionReference._aggregation_query~rEr/ctr1rBr9s r- _vector_queryz%BaseCollectionReference._vector_queryrEr/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_pathr:)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`)rKr>rmake_retry_timeout_kwargs)r* document_datarLrtimeout document_refr,s r- _prep_addz!BaseCollectionReference._prep_adds<  "*K}}[1 33E7CV##r/ctr1rB)r*rYrLrrZs 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)rVr:rrX)r*rbrrZr@_requestr,s r-_prep_list_documentsz,BaseCollectionReference._prep_list_documentssU%%' !WW" #D)  33E7Cr/ctr1rB)r*rbrrZs r-list_documentsz&BaseCollectionReference.list_documents "!r/c>|jjSr1)rD recursiver9s r-rlz!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. )rDselect)r*r`querys r-rnzBaseCollectionReference.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__inrp)rD ValueErrorr2strr>appendwhere)r* field_path op_stringvaluerqro wrapped_namesnames r-rxzBaseCollectionReference.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. )rDorder_by)r*ryr,ros r-rz BaseCollectionReference.order_by4s%& 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. )rDlimitr*countros r-rzBaseCollectionReference.limitJs& {{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. )rD 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. )rDoffset)r* num_to_skipros r-rzBaseCollectionReference.offsetus ||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. )rDstart_atr*document_fieldsros 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. )rD 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. )rD 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. )rDend_atrs r-rzBaseCollectionReference.end_ats( ||O,,r/cV|j}tj||}||fS)z:Shared setup for async / sync :meth:`get` / :meth:`stream`)rDrrX)r*rrZror,s r-_prep_get_or_streamz+BaseCollectionReference._prep_get_or_streams+  33E7Cf}r/)explain_optionsctr1rBr* transactionrrZrs r-getzBaseCollectionReference.gets "!r/ctr1rBrs r-streamzBaseCollectionReference.streamrjr/ctr1rB)r*callbacks r- on_snapshotz#BaseCollectionReference.on_snapshotrEr/cB|jj|S)z Adds a count over the nested query. :type alias: str :param alias: (Optional) The alias for the count alias)rGr)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)rGsumr* field_refrs r-rzBaseCollectionReference.sums#&&(,,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)rGavgrs r-rzBaseCollectionReference.avgs#&&(,,Ye,DDr/distance_result_fielddistance_thresholdcL|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(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)rI find_nearest)r* vector_field query_vectorrdistance_measurerrs r-rz$BaseCollectionReference.find_nearest,s78!!#00    "71 1  r/)returnNone)rr)rr)rrr1)rL Optional[str]rr)rzTuple[Any, str])NNN) rYdictrLrr2retries.Retry | retries.AsyncRetry | object | NonerZOptional[float]rzTuple[DocumentReference, dict]) rYrrLrrrrZrrzrVr\r^rgrirlrnrxrrrrrrrrrrrrrrrrr/r-r!r!;s2K  3 3"""2,,2&*DH#' $$#$B $ ! $ ( $&&*DH#' ""#"B " ! " F "$(DH#'  B!   0$(DH#' " "B"! "   "))*%)#' 3.  3.!3.!3. 3.j4,",**)$/I/ /.2I2 2.1I1 1.-I- -2EI#' A !   .2DH#' " 59 "* "B "! " 2 " B ".2DH#' " 59 "*"B"! " 2 " M""< E E(04.2# # 5#  # * #  -# ,#  # r/r!cDdjdtdDS)zGenerate a "random" automatically generated ID. Returns: str: A 20 character string composed of digits, uppercase and lowercase and letters. c3NK|]}tjtywr1)randomchoice_AUTO_ID_CHARS).0res r- z_auto_id..ZsDQ6==0Ds#%)rQrangerr/r-rKrKRs 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 r8)r}splitrrPr>)collection_referenceitemrLs r-_item_to_document_refr]s2))//("B"BCBGK  ( ( 55r/)rrv)rr)3r __future__rrtypingrrrrrr r r r r rrgoogle.api_corerretriesgoogle.cloud.firestore_v1r$google.cloud.firestore_v1.base_queryr*google.cloud.firestore_v1.base_aggregationr'google.cloud.firestore_v1.base_documentr+google.cloud.firestore_v1.base_vector_queryrr"google.cloud.firestore_v1.documentr$google.cloud.firestore_v1.field_pathr'google.cloud.firestore_v1.query_profiler'google.cloud.firestore_v1.query_resultsr*google.cloud.firestore_v1.stream_generatorr%google.cloud.firestore_v1.transactionr google.cloud.firestore_v1.vectorr&google.cloud.firestore_v1.vector_queryrrr!rKrrr/r-rs}O"     -.:OHE>FHJA7BQT gi0T nE 6r/