o }l~iR]@sZdZddlmZddlZddlmZmZmZmZm Z m Z m Z m Z m Z mZmZmZddlmZddlmZddlmZddlmZerdd lmZdd lmZdd lmZmZdd l m!Z!dd l"m#Z#ddl$m%Z%ddl&m'Z'ddl(m)Z)ddl*m+Z+ddl,m-Z-ddl.m/Z/ddl0m1Z1ddl2m3Z3ddl4Z4dZ5Gddde eZ6dddZ7ddZ8dS) zHClasses for representing collections for the Google Cloud Firestore API.) annotationsN) TYPE_CHECKINGAnyAsyncGenerator AsyncIterator Coroutine GeneratorGenericIterableSequenceTupleUnionOptional)retry)_helpers)BaseDocumentReference) QueryType)BaseAggregationQuery)DocumentSnapshot)BaseVectorQueryDistanceMeasure)AsyncDocumentReference)DocumentReference) FieldPath)PipelineSource)ExplainOptions)QueryResultsList)StreamGenerator) Transaction)Vector) VectorQuery>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789c@seZdZdZd}ddZddZedd Zed d Zd~d dZ dddZ dddZ ddddZ dddZ   ddd$d%Z   ddd'd(Z    ddd.d/Z   ddd0dd2d3Zd~d4d5Zdd8d9Z   ddd:dd=d>Zdd@dAZddDdEZddFdGZddIdJZddMdNZddOdPZddQdRZddSdTZ  dddVdWZ   ddddXdd^d_Z   ddddXddadbZdcddZ ddedfZ!dddidjZ"dddkdlZ#dddmddwdxZ$dd{d|Z%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. returnNonecOs6tj|dd||_|dd|_|rtd|ddS)NT) is_collectionclientzReceived unexpected argumentszOnly `client` is supported)r verify_path_pathpop_client TypeError)selfpathkwargsr/p/var/www/newdalilibackend/backend/venv/lib/python3.10/site-packages/google/cloud/firestore_v1/base_collection.py__init__[sz BaseCollectionReference.__init__cCs(t||jstS|j|jko|j|jkSN) isinstance __class__NotImplementedr(r*)r,otherr/r/r0__eq__ds zBaseCollectionReference.__eq__cCs |jdS)zfThe collection identifier. Returns: str: The last component of the path. )r(r,r/r/r0idis zBaseCollectionReference.idcCs,t|jdkr dS|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_pathr/r/r0parentrs  zBaseCollectionReference.parentrcCtr2NotImplementedErrorr9r/r/r0_queryzBaseCollectionReference._queryrcCr@r2rAr9r/r/r0_aggregation_queryrDz*BaseCollectionReference._aggregation_queryrcCr@r2rAr9r/r/r0 _vector_queryrDz%BaseCollectionReference._vector_queryN document_id Optional[str]rcCs6|durt}|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.base_document.BaseDocumentReference`: The child document. Nr)_auto_idr(r*r=)r,rG child_pathr/r/r0r=s  z BaseCollectionReference.documentTuple[Any, str]cCsD|j}|durtj|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. N documents)r?rDOCUMENT_PATH_DELIMITERjoinr*_database_string_document_pathr:)r, parent_docr>expected_prefixr/r/r0 _parent_infos  z$BaseCollectionReference._parent_info document_datadictr2retries.Retry | retries.AsyncRetry | object | NonetimeoutOptional[float]cCs,|durt}||}t||}||fS)z+Shared setup for async / sync :method:`add`N)rIr=rmake_retry_timeout_kwargs)r,rTrGrrW document_refr.r/r/r0 _prep_adds   z!BaseCollectionReference._prep_add=``, ``>``, 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__inrq)rC ValueErrorr3strr=appendwhere)r,rsrtvaluerrrp wrapped_namesnamer/r/r0rz s!    zBaseCollectionReference.whererxcKs|}|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. )rCorder_by)r,rsr.rpr/r/r0r~@sz BaseCollectionReference.order_bycountintcCrn)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. )rClimitr,rrpr/r/r0rVs zBaseCollectionReference.limitcCrn)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. )rC limit_to_lastrr/r/r0rls z%BaseCollectionReference.limit_to_last num_to_skipcCrn)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. )rCoffset)r,rrpr/r/r0rs zBaseCollectionReference.offsetdocument_fields*Union[DocumentSnapshot, dict, list, tuple]cCrn)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. )rCstart_atr,rrpr/r/r0r z BaseCollectionReference.start_atcCrn)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. )rC start_afterrr/r/r0rrz#BaseCollectionReference.start_aftercCrn)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. )rC end_beforerr/r/r0rrz"BaseCollectionReference.end_beforecCrn)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. )rCend_atrr/r/r0rrzBaseCollectionReference.end_atTuple[Any, dict]cCs|}t||}||fS)z:Shared setup for async / sync :meth:`get` / :meth:`stream`)rCrrY)r,rrWrpr.r/r/r0_prep_get_or_streams z+BaseCollectionReference._prep_get_or_stream)explain_optionsr` transactionOptional[Transaction]rOptional[ExplainOptions]\QueryResultsList[DocumentSnapshot] | Coroutine[Any, Any, QueryResultsList[DocumentSnapshot]]cCr@r2rAr,rrrWrr`r/r/r0gets zBaseCollectionReference.getCStreamGenerator[DocumentSnapshot] | AsyncIterator[DocumentSnapshot]cCr@r2rArr/r/r0streams zBaseCollectionReference.streamcCr@r2rA)r,callbackr/r/r0 on_snapshotrDz#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)rEr)r,rr/r/r0rszBaseCollectionReference.count field_refstr | FieldPathcC|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_. r)rEsumr,rrr/r/r0rs zBaseCollectionReference.sumcCr)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)rEavgrr/r/r0r-s zBaseCollectionReference.avgdistance_result_fielddistance_threshold vector_field query_vectorUnion[Vector, Sequence[float]]rdistance_measurerrrr 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)rF find_nearest)r,rrrrrrr/r/r0r:sz$BaseCollectionReference.find_nearestsource'PipelineSource'cCs||S)a Convert this query into a Pipeline Queries containing a `cursor` or `limit_to_last` are not currently supported Args: source: the PipelineSource to build the pipeline off o Raises: - NotImplementedError: raised if the query contains a `cursor` or `limit_to_last` Returns: a Pipeline representing the query )rC_build_pipeline)r,rr/r/r0r_s z'BaseCollectionReference._build_pipeline)r#r$)r#r)r#r)r#rr2)rGrHr#r)r#rK)NNN)rTrUrGrHrrVrWrX) rTrUrGrHrrVrWrXr#r\)NNNN) r^r_rrVrWrXr`rar#rb) r^r_rrVrWrXr`rar#rj)rcrmr#r)rsrHrtrHr#r)rsrxr#r)rrr#r)rr)rrr#r)rrr#r)NN)rrVrWrXr#r) rrrrVrWrXrrr`rar#r) rrrrVrWrXrrr`rar#r)rr)rrxrrrrrrrrHrrXr#r )rr)&ru __module__ __qualname____doc__r1r7propertyr:r?rCrErFr=rSr[r]rirkrlrorzr~rrrrrrrrrrrrrrrrr/r/r/r0r"As               5           %r"r#rxcCsdddtdDS)zGenerate a "random" automatically generated ID. Returns: str: A 20 character string composed of digits, uppercase and lowercase and letters. css|]}ttVqdSr2)randomchoice_AUTO_ID_CHARS).0rgr/r/r0 wsz_auto_id..)rNranger/r/r/r0rIosrIcCs|jtjd}||S)aLConvert Document resource to document ref. Args: collection_reference (google.api_core.page_iterator.GRPCIterator): iterator response item (dict): document resource Returns: :class:`~google.cloud.firestore_v1.base_document.BaseDocumentReference`: The child document r8)r}splitrrMr=)collection_referenceitemrGr/r/r0_item_to_document_refzs r)r#rx)9r __future__rrtypingrrrrrrr r r r r rgoogle.api_corerretriesgoogle.cloud.firestore_v1r'google.cloud.firestore_v1.base_documentr$google.cloud.firestore_v1.base_queryr*google.cloud.firestore_v1.base_aggregationrr+google.cloud.firestore_v1.base_vector_queryrr(google.cloud.firestore_v1.async_documentr"google.cloud.firestore_v1.documentr$google.cloud.firestore_v1.field_pathr)google.cloud.firestore_v1.pipeline_sourcer'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_queryr datetimerr"rIrr/r/r/r0s> 8                 2