o ˷eD@sdZddlZddlmZddlmZddlmZddl m Z m Z m Z m Z mZmZmZmZmZmZddlmZddlmZdd lmZd ZGd d d eZd efddZd efddZdS)zHClasses for representing collections for the Google Cloud Firestore API.N)retry)_helpers)DocumentReference) AnyAsyncGenerator Coroutine Generator AsyncIteratorIteratorIterableNoReturnTupleUnion)DocumentSnapshot) BaseQuery) Transaction>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789c@seZdZdZdEddZddZedd Zed d Zde fd d Z dFde de fddZ deee ffddZ   dGdede dejdedee eff ddZ   dGdede dejdedeeeefeeeeeeffff ddZ   dGdedejdedeeeffddZ   dGdedejdedeee eefee efffddZdHd d!Zd"ee de fd#d$Z d%e d&e de fd'd(Z!d%e de fd)d*Z"d+ede fd,d-Z#d+efd.d/Z$d0ede fd1d2Z%d3ee&ee'e(fde fd4d5Z)d3ee&ee'e(fde fd6d7Z*d3ee&ee'e(fde fd8d9Z+d3ee&ee'e(fde fd:d;Z,  dIdejdedeeeffde.dejdedeee&eefee&efffd?d@Z/   dGd>e.dejdedee0e&e1e&ffdAdBZ2de3fdCdDZ4dS)JBaseCollectionReferencea 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. returnNcOs6tj|dd||_|dd|_|rtd|ddS)NT) is_collectionclientzReceived unexpected argumentszOnly `client` is supported)r verify_path_pathpop_client TypeError)selfpathkwargsr`/var/www/ideatree/venv/lib/python3.10/site-packages/google/cloud/firestore_v1/base_collection.py__init__Esz BaseCollectionReference.__init__cCs(t||jstS|j|jko|j|jkSN) isinstance __class__NotImplementedrr)rotherrrr __eq__Ns zBaseCollectionReference.__eq__cCs |jdS)zfThe collection identifier. Returns: str: The last component of the path. )rrrrr idSs 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. Nr()lenrrdocument)r parent_pathrrr parent\s  zBaseCollectionReference.parentcCtr"NotImplementedErrorr)rrr _querykzBaseCollectionReference._query document_idcCs6|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.document.DocumentReference`: The child document. Nr)_auto_idrrr-)rr5 child_pathrrr r-ns  z BaseCollectionReference.documentcCsD|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_prefixrrr _parent_infos  z$BaseCollectionReference._parent_info document_datartimeoutcCs,|durt}||}t||}||fS)z+Shared setup for async / sync :method:`add`N)r6r-rmake_retry_timeout_kwargs)rr@r5rrA document_refrrrr _prep_adds   z!BaseCollectionReference._prep_addcCr0r"r1)rr@r5rrArrr addszBaseCollectionReference.add page_sizecCs6|\}}||j|dddid}t||}||fS)z6Shared setup for async / sync :method:`list_documents`T field_pathsN)r/ collection_idrF show_missingmask)r?r*rrB)rrFrrAr/_requestrrrr _prep_list_documentss  z,BaseCollectionReference._prep_list_documentscCr0r"r1)rrFrrArrr list_documentsz&BaseCollectionReference.list_documentsrcCs |Sr")r3 recursiver)rrr rPs z!BaseCollectionReference.recursiverGcC|}||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. )r3select)rrGqueryrrr rRs zBaseCollectionReference.select field_path op_stringcCsV|dkr |dkr g}|D]}t|tr||}||q |}|}||||S)azCreate 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. op_string (str): A comparison operation in the form of a string. Acceptable values are ``<``, ``<=``, ``==``, ``>=``, ``>``, and ``in``. 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. Returns: :class:`~google.cloud.firestore_v1.query.Query`: A filtered query. __name__in)r#strr-appendr3where)rrTrUvalue wrapped_namesnamerSrrr rZs   zBaseCollectionReference.wherecKs|}|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. )r3order_by)rrTrrSrrr r^sz BaseCollectionReference.order_bycountcCrQ)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. )r3limitrr_rSrrr r`$s zBaseCollectionReference.limitcCrQ)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. )r3 limit_to_lastrarrr rb:s z%BaseCollectionReference.limit_to_last num_to_skipcCrQ)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. )r3offset)rrcrSrrr rdOs zBaseCollectionReference.offsetdocument_fieldscCrQ)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. )r3start_atrrerSrrr rfa z BaseCollectionReference.start_atcCrQ)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. )r3 start_afterrgrrr rixrhz#BaseCollectionReference.start_aftercCrQ)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. )r3 end_beforergrrr rjrhz"BaseCollectionReference.end_beforecCrQ)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. )r3end_atrgrrr rkrhzBaseCollectionReference.end_atcCs|}t||}||fS)z:Shared setup for async / sync :meth:`get` / :meth:`stream`)r3rrB)rrrArSrrrr _prep_get_or_streams z+BaseCollectionReference._prep_get_or_stream transactioncCr0r"r1rrmrrArrr getrOzBaseCollectionReference.getcCr0r"r1rnrrr streamszBaseCollectionReference.streamcCr0r"r1)rcallbackrrr on_snapshotr4z#BaseCollectionReference.on_snapshot)rNr")NNN)rr)NN)5rV __module__ __qualname____doc__r!r'propertyr*r/rr3rXrr-r rr?dictretriesRetryfloatrDrrrEintrMrrrNrPr rRrZr^r`rbrdrlisttuplerfrirjrkrlrror r rpr rrrrrr r+s      $     %          rrcCsdddtdDS)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).0rKrrr sz_auto_id..)r:rangerrrr r6sr6cCs|jtjd}||S)zConvert Document resource to document ref. Args: collection_reference (google.api_core.page_iterator.GRPCIterator): iterator response item (dict): document resource r()r]splitrr9r-)collection_referenceitemr5rrr _item_to_document_refs r) rurgoogle.api_corerrxgoogle.cloud.firestore_v1r"google.cloud.firestore_v1.documentrtypingrrrrr r r r r r'google.cloud.firestore_v1.base_documentr$google.cloud.firestore_v1.base_queryr%google.cloud.firestore_v1.transactionrrobjectrrXr6rrrrr s    0   6