|
10 | 10 | from warnings import warn
|
11 | 11 |
|
12 | 12 | from arangoasync.aql import AQL
|
13 |
| -from arangoasync.collection import StandardCollection |
| 13 | +from arangoasync.collection import Collection, StandardCollection |
14 | 14 | from arangoasync.connection import Connection
|
15 | 15 | from arangoasync.errno import HTTP_FORBIDDEN, HTTP_NOT_FOUND
|
16 | 16 | from arangoasync.exceptions import (
|
@@ -684,6 +684,351 @@ def response_handler(resp: Response) -> bool:
|
684 | 684 |
|
685 | 685 | return await self._executor.execute(request, response_handler)
|
686 | 686 |
|
| 687 | + async def has_document( |
| 688 | + self, |
| 689 | + document: str | Json, |
| 690 | + allow_dirty_read: bool = False, |
| 691 | + if_match: Optional[str] = None, |
| 692 | + if_none_match: Optional[str] = None, |
| 693 | + ) -> Result[bool]: |
| 694 | + """Check if a document exists. |
| 695 | +
|
| 696 | + Args: |
| 697 | + document (str | dict): Document ID, key or body. |
| 698 | + Document body must contain the "_id" field. |
| 699 | + allow_dirty_read (bool): Allow reads from followers in a cluster. |
| 700 | + if_match (str | None): The document is returned, if it has the same |
| 701 | + revision as the given ETag. |
| 702 | + if_none_match (str | None): The document is returned, if it has a |
| 703 | + different revision than the given ETag. |
| 704 | +
|
| 705 | + Returns: |
| 706 | + `True` if the document exists, `False` otherwise. |
| 707 | +
|
| 708 | + Raises: |
| 709 | + DocumentRevisionError: If the revision is incorrect. |
| 710 | + DocumentGetError: If retrieval fails. |
| 711 | +
|
| 712 | + References: |
| 713 | + - `get-a-document-header <https://docs.arangodb.com/stable/develop/http-api/documents/#get-a-document-header>`__ |
| 714 | + """ # noqa: E501 |
| 715 | + col = Collection.get_col_name(document) |
| 716 | + return await self.collection(col).has( |
| 717 | + document, |
| 718 | + allow_dirty_read=allow_dirty_read, |
| 719 | + if_match=if_match, |
| 720 | + if_none_match=if_none_match, |
| 721 | + ) |
| 722 | + |
| 723 | + async def document( |
| 724 | + self, |
| 725 | + document: str | Json, |
| 726 | + allow_dirty_read: bool = False, |
| 727 | + if_match: Optional[str] = None, |
| 728 | + if_none_match: Optional[str] = None, |
| 729 | + ) -> Result[Optional[Json]]: |
| 730 | + """Return a document. |
| 731 | +
|
| 732 | + Args: |
| 733 | + document (str | dict): Document ID, key or body. |
| 734 | + Document body must contain the "_id" field. |
| 735 | + allow_dirty_read (bool): Allow reads from followers in a cluster. |
| 736 | + if_match (str | None): The document is returned, if it has the same |
| 737 | + revision as the given ETag. |
| 738 | + if_none_match (str | None): The document is returned, if it has a |
| 739 | + different revision than the given ETag. |
| 740 | +
|
| 741 | + Returns: |
| 742 | + Document or `None` if not found. |
| 743 | +
|
| 744 | + Raises: |
| 745 | + DocumentRevisionError: If the revision is incorrect. |
| 746 | + DocumentGetError: If retrieval fails. |
| 747 | + DocumentParseError: If the document is malformed. |
| 748 | +
|
| 749 | + References: |
| 750 | + - `get-a-document <https://docs.arangodb.com/stable/develop/http-api/documents/#get-a-document>`__ |
| 751 | + """ # noqa: E501 |
| 752 | + col: StandardCollection[Json, Json, Jsons] = self.collection( |
| 753 | + Collection.get_col_name(document) |
| 754 | + ) |
| 755 | + return await col.get( |
| 756 | + document, |
| 757 | + allow_dirty_read=allow_dirty_read, |
| 758 | + if_match=if_match, |
| 759 | + if_none_match=if_none_match, |
| 760 | + ) |
| 761 | + |
| 762 | + async def insert_document( |
| 763 | + self, |
| 764 | + collection: str, |
| 765 | + document: Json, |
| 766 | + wait_for_sync: Optional[bool] = None, |
| 767 | + return_new: Optional[bool] = None, |
| 768 | + return_old: Optional[bool] = None, |
| 769 | + silent: Optional[bool] = None, |
| 770 | + overwrite: Optional[bool] = None, |
| 771 | + overwrite_mode: Optional[str] = None, |
| 772 | + keep_null: Optional[bool] = None, |
| 773 | + merge_objects: Optional[bool] = None, |
| 774 | + refill_index_caches: Optional[bool] = None, |
| 775 | + version_attribute: Optional[str] = None, |
| 776 | + ) -> Result[bool | Json]: |
| 777 | + """Insert a new document. |
| 778 | +
|
| 779 | + Args: |
| 780 | + collection (str): Collection name. |
| 781 | + document (dict): Document to insert. If it contains the "_key" or "_id" |
| 782 | + field, the value is used as the key of the new document (otherwise |
| 783 | + it is auto-generated). Any "_rev" field is ignored. |
| 784 | + wait_for_sync (bool | None): Wait until document has been synced to disk. |
| 785 | + return_new (bool | None): Additionally return the complete new document |
| 786 | + under the attribute `new` in the result. |
| 787 | + return_old (bool | None): Additionally return the complete old document |
| 788 | + under the attribute `old` in the result. Only available if the |
| 789 | + `overwrite` option is used. |
| 790 | + silent (bool | None): If set to `True`, no document metadata is returned. |
| 791 | + This can be used to save resources. |
| 792 | + overwrite (bool | None): If set to `True`, operation does not fail on |
| 793 | + duplicate key and existing document is overwritten (replace-insert). |
| 794 | + overwrite_mode (str | None): Overwrite mode. Supersedes **overwrite** |
| 795 | + option. May be one of "ignore", "replace", "update" or "conflict". |
| 796 | + keep_null (bool | None): If set to `True`, fields with value None are |
| 797 | + retained in the document. Otherwise, they are removed completely. |
| 798 | + Applies only when **overwrite_mode** is set to "update" |
| 799 | + (update-insert). |
| 800 | + merge_objects (bool | None): If set to `True`, sub-dictionaries are merged |
| 801 | + instead of the new one overwriting the old one. Applies only when |
| 802 | + **overwrite_mode** is set to "update" (update-insert). |
| 803 | + refill_index_caches (bool | None): Whether to add new entries to |
| 804 | + in-memory index caches if document insertions affect the edge index |
| 805 | + or cache-enabled persistent indexes. |
| 806 | + version_attribute (str | None): Support for simple external versioning to |
| 807 | + document operations. Only applicable if **overwrite** is set to `True` |
| 808 | + or **overwrite_mode** is set to "update" or "replace". |
| 809 | +
|
| 810 | + Returns: |
| 811 | + bool | dict: Document metadata (e.g. document id, key, revision) or `True` |
| 812 | + if **silent** is set to `True`. |
| 813 | +
|
| 814 | + Raises: |
| 815 | + DocumentInsertError: If insertion fails. |
| 816 | + DocumentParseError: If the document is malformed. |
| 817 | +
|
| 818 | + References: |
| 819 | + - `create-a-document <https://docs.arangodb.com/stable/develop/http-api/documents/#create-a-document>`__ |
| 820 | + """ # noqa: E501 |
| 821 | + col: StandardCollection[Json, Json, Jsons] = self.collection(collection) |
| 822 | + return await col.insert( |
| 823 | + document, |
| 824 | + wait_for_sync=wait_for_sync, |
| 825 | + return_new=return_new, |
| 826 | + return_old=return_old, |
| 827 | + silent=silent, |
| 828 | + overwrite=overwrite, |
| 829 | + overwrite_mode=overwrite_mode, |
| 830 | + keep_null=keep_null, |
| 831 | + merge_objects=merge_objects, |
| 832 | + refill_index_caches=refill_index_caches, |
| 833 | + version_attribute=version_attribute, |
| 834 | + ) |
| 835 | + |
| 836 | + async def update_document( |
| 837 | + self, |
| 838 | + document: Json, |
| 839 | + ignore_revs: Optional[bool] = None, |
| 840 | + wait_for_sync: Optional[bool] = None, |
| 841 | + return_new: Optional[bool] = None, |
| 842 | + return_old: Optional[bool] = None, |
| 843 | + silent: Optional[bool] = None, |
| 844 | + keep_null: Optional[bool] = None, |
| 845 | + merge_objects: Optional[bool] = None, |
| 846 | + refill_index_caches: Optional[bool] = None, |
| 847 | + version_attribute: Optional[str] = None, |
| 848 | + if_match: Optional[str] = None, |
| 849 | + ) -> Result[bool | Json]: |
| 850 | + """Update a document. |
| 851 | +
|
| 852 | + Args: |
| 853 | + document (dict): Partial or full document with the updated values. |
| 854 | + It must contain the "_key" or "_id" field. |
| 855 | + ignore_revs (bool | None): If set to `True`, the `_rev` attribute in the |
| 856 | + document is ignored. If this is set to `False`, then the `_rev` |
| 857 | + attribute given in the body document is taken as a precondition. |
| 858 | + The document is only updated if the current revision is the one |
| 859 | + specified. |
| 860 | + wait_for_sync (bool | None): Wait until document has been synced to disk. |
| 861 | + return_new (bool | None): Additionally return the complete new document |
| 862 | + under the attribute `new` in the result. |
| 863 | + return_old (bool | None): Additionally return the complete old document |
| 864 | + under the attribute `old` in the result. |
| 865 | + silent (bool | None): If set to `True`, no document metadata is returned. |
| 866 | + This can be used to save resources. |
| 867 | + keep_null (bool | None): If the intention is to delete existing attributes |
| 868 | + with the patch command, set this parameter to `False`. |
| 869 | + merge_objects (bool | None): Controls whether objects (not arrays) are |
| 870 | + merged if present in both the existing and the patch document. |
| 871 | + If set to `False`, the value in the patch document overwrites the |
| 872 | + existing document’s value. If set to `True`, objects are merged. |
| 873 | + refill_index_caches (bool | None): Whether to add new entries to |
| 874 | + in-memory index caches if document updates affect the edge index |
| 875 | + or cache-enabled persistent indexes. |
| 876 | + version_attribute (str | None): Support for simple external versioning to |
| 877 | + document operations. |
| 878 | + if_match (str | None): You can conditionally update a document based on a |
| 879 | + target revision id by using the "if-match" HTTP header. |
| 880 | +
|
| 881 | + Returns: |
| 882 | + bool | dict: Document metadata (e.g. document id, key, revision) or `True` |
| 883 | + if **silent** is set to `True`. |
| 884 | +
|
| 885 | + Raises: |
| 886 | + DocumentRevisionError: If precondition was violated. |
| 887 | + DocumentUpdateError: If update fails. |
| 888 | +
|
| 889 | + References: |
| 890 | + - `update-a-document <https://docs.arangodb.com/stable/develop/http-api/documents/#update-a-document>`__ |
| 891 | + """ # noqa: E501 |
| 892 | + col: StandardCollection[Json, Json, Jsons] = self.collection( |
| 893 | + Collection.get_col_name(document) |
| 894 | + ) |
| 895 | + return await col.update( |
| 896 | + document, |
| 897 | + ignore_revs=ignore_revs, |
| 898 | + wait_for_sync=wait_for_sync, |
| 899 | + return_new=return_new, |
| 900 | + return_old=return_old, |
| 901 | + silent=silent, |
| 902 | + keep_null=keep_null, |
| 903 | + merge_objects=merge_objects, |
| 904 | + refill_index_caches=refill_index_caches, |
| 905 | + version_attribute=version_attribute, |
| 906 | + if_match=if_match, |
| 907 | + ) |
| 908 | + |
| 909 | + async def replace_document( |
| 910 | + self, |
| 911 | + document: Json, |
| 912 | + ignore_revs: Optional[bool] = None, |
| 913 | + wait_for_sync: Optional[bool] = None, |
| 914 | + return_new: Optional[bool] = None, |
| 915 | + return_old: Optional[bool] = None, |
| 916 | + silent: Optional[bool] = None, |
| 917 | + refill_index_caches: Optional[bool] = None, |
| 918 | + version_attribute: Optional[str] = None, |
| 919 | + if_match: Optional[str] = None, |
| 920 | + ) -> Result[bool | Json]: |
| 921 | + """Replace a document. |
| 922 | +
|
| 923 | + Args: |
| 924 | + document (dict): New document. It must contain the "_key" or "_id" field. |
| 925 | + Edge document must also have "_from" and "_to" fields. |
| 926 | + ignore_revs (bool | None): If set to `True`, the `_rev` attribute in the |
| 927 | + document is ignored. If this is set to `False`, then the `_rev` |
| 928 | + attribute given in the body document is taken as a precondition. |
| 929 | + The document is only replaced if the current revision is the one |
| 930 | + specified. |
| 931 | + wait_for_sync (bool | None): Wait until document has been synced to disk. |
| 932 | + return_new (bool | None): Additionally return the complete new document |
| 933 | + under the attribute `new` in the result. |
| 934 | + return_old (bool | None): Additionally return the complete old document |
| 935 | + under the attribute `old` in the result. |
| 936 | + silent (bool | None): If set to `True`, no document metadata is returned. |
| 937 | + This can be used to save resources. |
| 938 | + refill_index_caches (bool | None): Whether to add new entries to |
| 939 | + in-memory index caches if document updates affect the edge index |
| 940 | + or cache-enabled persistent indexes. |
| 941 | + version_attribute (str | None): Support for simple external versioning to |
| 942 | + document operations. |
| 943 | + if_match (str | None): You can conditionally replace a document based on a |
| 944 | + target revision id by using the "if-match" HTTP header. |
| 945 | +
|
| 946 | + Returns: |
| 947 | + bool | dict: Document metadata (e.g. document id, key, revision) or `True` |
| 948 | + if **silent** is set to `True`. |
| 949 | +
|
| 950 | + Raises: |
| 951 | + DocumentRevisionError: If precondition was violated. |
| 952 | + DocumentReplaceError: If replace fails. |
| 953 | +
|
| 954 | + References: |
| 955 | + - `replace-a-document <https://docs.arangodb.com/stable/develop/http-api/documents/#replace-a-document>`__ |
| 956 | + """ # noqa: E501 |
| 957 | + col: StandardCollection[Json, Json, Jsons] = self.collection( |
| 958 | + Collection.get_col_name(document) |
| 959 | + ) |
| 960 | + return await col.replace( |
| 961 | + document, |
| 962 | + ignore_revs=ignore_revs, |
| 963 | + wait_for_sync=wait_for_sync, |
| 964 | + return_new=return_new, |
| 965 | + return_old=return_old, |
| 966 | + silent=silent, |
| 967 | + refill_index_caches=refill_index_caches, |
| 968 | + version_attribute=version_attribute, |
| 969 | + if_match=if_match, |
| 970 | + ) |
| 971 | + |
| 972 | + async def delete_document( |
| 973 | + self, |
| 974 | + document: str | Json, |
| 975 | + ignore_revs: Optional[bool] = None, |
| 976 | + ignore_missing: bool = False, |
| 977 | + wait_for_sync: Optional[bool] = None, |
| 978 | + return_old: Optional[bool] = None, |
| 979 | + silent: Optional[bool] = None, |
| 980 | + refill_index_caches: Optional[bool] = None, |
| 981 | + if_match: Optional[str] = None, |
| 982 | + ) -> Result[bool | Json]: |
| 983 | + """Delete a document. |
| 984 | +
|
| 985 | + Args: |
| 986 | + document (str | dict): Document ID, key or body. The body must contain the |
| 987 | + "_key" or "_id" field. |
| 988 | + ignore_revs (bool | None): If set to `True`, the `_rev` attribute in the |
| 989 | + document is ignored. If this is set to `False`, then the `_rev` |
| 990 | + attribute given in the body document is taken as a precondition. |
| 991 | + The document is only replaced if the current revision is the one |
| 992 | + specified. |
| 993 | + ignore_missing (bool): Do not raise an exception on missing document. |
| 994 | + This parameter has no effect in transactions where an exception is |
| 995 | + always raised on failures. |
| 996 | + wait_for_sync (bool | None): Wait until operation has been synced to disk. |
| 997 | + return_old (bool | None): Additionally return the complete old document |
| 998 | + under the attribute `old` in the result. |
| 999 | + silent (bool | None): If set to `True`, no document metadata is returned. |
| 1000 | + This can be used to save resources. |
| 1001 | + refill_index_caches (bool | None): Whether to add new entries to |
| 1002 | + in-memory index caches if document updates affect the edge index |
| 1003 | + or cache-enabled persistent indexes. |
| 1004 | + if_match (bool | None): You can conditionally remove a document based |
| 1005 | + on a target revision id by using the "if-match" HTTP header. |
| 1006 | +
|
| 1007 | + Returns: |
| 1008 | + bool | dict: Document metadata (e.g. document id, key, revision) or `True` |
| 1009 | + if **silent** is set to `True` and the document was found. |
| 1010 | +
|
| 1011 | + Raises: |
| 1012 | + DocumentRevisionError: If precondition was violated. |
| 1013 | + DocumentDeleteError: If deletion fails. |
| 1014 | +
|
| 1015 | + References: |
| 1016 | + - `remove-a-document <https://docs.arangodb.com/stable/develop/http-api/documents/#remove-a-document>`__ |
| 1017 | + """ # noqa: E501 |
| 1018 | + col: StandardCollection[Json, Json, Jsons] = self.collection( |
| 1019 | + Collection.get_col_name(document) |
| 1020 | + ) |
| 1021 | + return await col.delete( |
| 1022 | + document, |
| 1023 | + ignore_revs=ignore_revs, |
| 1024 | + ignore_missing=ignore_missing, |
| 1025 | + wait_for_sync=wait_for_sync, |
| 1026 | + return_old=return_old, |
| 1027 | + silent=silent, |
| 1028 | + refill_index_caches=refill_index_caches, |
| 1029 | + if_match=if_match, |
| 1030 | + ) |
| 1031 | + |
687 | 1032 | def graph(
|
688 | 1033 | self,
|
689 | 1034 | name: str,
|
|
0 commit comments