Skip to content

document_reference

numerous.collections.document_reference

Class for working with numerous documents.

DocumentReference dataclass

Source code in numerous/collections/document_reference.py 
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
@dataclass
class DocumentReference:
    id: str | None
    key: str
    collection_id: str
    collection_key: str
    _client: Client

    @property
    def exists(self) -> bool:
        """True if the document exists, False otherwise."""
        self._set_id_if_reference_exists()
        if self.id is None:
            return False

        return self._client.document_exists(self.id)

    def _set_id_if_reference_exists(self) -> None:
        if self.id is not None:
            return

        ref = self._client.document_reference(self.collection_id, self.key)
        if ref is not None:
            self.id = ref.id

    @property
    def tags(self) -> dict[str, str]:
        """Get the tags for the document."""
        self._set_id_if_reference_exists()
        if self.id is None:
            return {}

        return self._client.document_tags(self.id) or {}

    def set(self, data: dict[str, Any]) -> None:
        """
        Set the data for the document.

        Args:
            data: The data to set for the document.

        Raises:
            TypeError: If the data is not JSON serializable.

        """
        base64_data = dict_to_base64(data)
        self._client.document_set(self.collection_id, self.key, base64_data)

    def get(self) -> dict[str, Any] | None:
        """
        Get the data of the document.

        Returns:
            The data of the document if it is set.

        """
        self._set_id_if_reference_exists()
        if self.id is None:
            return None

        data = self._client.document_get(self.id)
        if data is None:
            return None

        return base64_to_dict(data)

    def delete(self) -> None:
        """Delete the referenced document."""
        self._set_id_if_reference_exists()
        if self.id is None:
            raise DocumentDoesNotExistError(
                collection_id=self.collection_id, key=self.key
            )

        self._client.document_delete(self.id)

    def tag(self, key: str, value: str) -> None:
        """
        Add a tag to the document.

        Args:
            key: The tag key.
            value: The tag value.

        """
        self._set_id_if_reference_exists()
        if self.id is None:
            raise DocumentDoesNotExistError(
                collection_id=self.collection_id, key=self.key
            )

        self._client.document_tag_add(self.id, Tag(key=key, value=value))

    def tag_delete(self, tag_key: str) -> None:
        """
        Delete a tag from the document.

        Args:
            tag_key: The key of the tag to delete.

        """
        self._set_id_if_reference_exists()
        if self.id is None:
            raise DocumentDoesNotExistError(
                collection_id=self.collection_id, key=self.key
            )

        self._client.document_tag_delete(self.id, tag_key)

exists: bool property

True if the document exists, False otherwise.

tags: dict[str, str] property

Get the tags for the document.

delete()

Delete the referenced document.

Source code in numerous/collections/document_reference.py 
88
89
90
91
92
93
94
95
96
def delete(self) -> None:
    """Delete the referenced document."""
    self._set_id_if_reference_exists()
    if self.id is None:
        raise DocumentDoesNotExistError(
            collection_id=self.collection_id, key=self.key
        )

    self._client.document_delete(self.id)

get()

Get the data of the document.

Returns:

Type Description
dict[str, Any] | None

The data of the document if it is set.
Source code in numerous/collections/document_reference.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def get(self) -> dict[str, Any] | None:
    """
    Get the data of the document.

    Returns:
        The data of the document if it is set.

    """
    self._set_id_if_reference_exists()
    if self.id is None:
        return None

    data = self._client.document_get(self.id)
    if data is None:
        return None

    return base64_to_dict(data)

set(data)

Set the data for the document.

Parameters:

Name Type Description Default
data dict[str, Any]

The data to set for the document.

 required

Raises:

Type Description
TypeError

If the data is not JSON serializable.
Source code in numerous/collections/document_reference.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
def set(self, data: dict[str, Any]) -> None:
    """
    Set the data for the document.

    Args:
        data: The data to set for the document.

    Raises:
        TypeError: If the data is not JSON serializable.

    """
    base64_data = dict_to_base64(data)
    self._client.document_set(self.collection_id, self.key, base64_data)

tag(key, value)

Add a tag to the document.

Parameters:

Name Type Description Default
key str

The tag key.

 required
value str

The tag value.

 required
Source code in numerous/collections/document_reference.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def tag(self, key: str, value: str) -> None:
    """
    Add a tag to the document.

    Args:
        key: The tag key.
        value: The tag value.

    """
    self._set_id_if_reference_exists()
    if self.id is None:
        raise DocumentDoesNotExistError(
            collection_id=self.collection_id, key=self.key
        )

    self._client.document_tag_add(self.id, Tag(key=key, value=value))

tag_delete(tag_key)

Delete a tag from the document.

Parameters:

Name Type Description Default
tag_key str

The key of the tag to delete.

 required
Source code in numerous/collections/document_reference.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def tag_delete(self, tag_key: str) -> None:
    """
    Delete a tag from the document.

    Args:
        tag_key: The key of the tag to delete.

    """
    self._set_id_if_reference_exists()
    if self.id is None:
        raise DocumentDoesNotExistError(
            collection_id=self.collection_id, key=self.key
        )

    self._client.document_tag_delete(self.id, tag_key)