Skip to content

collection_reference

numerous.collections.collection_reference

Class for working with Numerous collections.

CollectionReference dataclass

Source code in numerous/collections/collection_reference.py 
 17
 18
 19
 20
 21
 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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
@dataclass
class CollectionReference:
    id: str
    key: str
    _client: Client

    @property
    def tags(self) -> dict[str, str]:
        """Get the tags for the collection."""
        tags = self._client.collection_tags(self.id)
        return {tag.key: tag.value for tag in tags}

    def collection(self, collection_key: str) -> CollectionReference:
        """
        Get or create a child collection of this collection by key.

        Args:
            collection_key: Key of the nested collection. A key uniquely identifies a
                collection within the parent collection. Keys are case sensitive, and
                can be used as human-readable identifiers for collections

        Returns:
            NumerousCollection: The child collection identified by the given key.

        """
        ref = self._client.collection_reference(
            collection_key=collection_key, parent_collection_id=self.id
        )

        return CollectionReference(ref.id, ref.key, self._client)

    def document(self, key: str) -> DocumentReference:
        """
        Get or create a document by key.

        Args:
            key: Key of the document. A key uniquely identifies a document within its
                collection. Keys are case sensitive.

        Returns:
            The document in the collection with the given key.

        Raises:
            ParentCollectionNotFoundError: If the collection does not exist, for example
                if it was deleted.

        """
        doc_ref = self._client.document_reference(self.id, key)
        if doc_ref is None:
            return self._document_reference(doc_id=None, doc_key=key)
        return self._document_reference_from_identifier(doc_ref)

    def _document_reference_from_identifier(
        self, doc_ref: CollectionDocumentIdentifier
    ) -> DocumentReference:
        return self._document_reference(doc_ref.id, doc_ref.key)

    def _document_reference(
        self,
        doc_id: str | None,
        doc_key: str,
    ) -> DocumentReference:
        return DocumentReference(
            id=doc_id,
            key=doc_key,
            collection_id=self.id,
            collection_key=self.key,
            _client=self._client,
        )

    def file(self, key: str) -> FileReference:
        """
        Get or create a file by key.

        Args:
            key: The key of the file.

        """
        file_identifier = self._client.file_reference(self.id, key)
        if file_identifier is None:
            msg = "Failed to retrieve or create the file."
            raise ValueError(msg)

        return self._file_reference_from_identifier(file_identifier)

    def save_file(self, file_key: str, file_data: str) -> None:
        """
        Save data to a file in the collection.

        If the file with the specified key already exists,
        it will be overwritten with the new data.

        Args:
            file_key: The key of the file to save or update.
            file_data: The data to be written to the file.

        Raises:
            ValueError: If the file cannot be created or saved.

        """
        file = self.file(file_key)
        file.save(file_data)

    def files(
        self, tag_key: str | None = None, tag_value: str | None = None
    ) -> Generator[FileReference, None, None]:
        """
        Retrieve files from the collection, filtered by a tag key and value.

        Args:
            tag_key: The key of the tag used to filter files.
            tag_value: The value of the tag used to filter files.

        Yields:
            File references from the collection.

        """
        end_cursor = ""
        tag = None
        if tag_key is not None and tag_value is not None:
            tag = Tag(key=tag_key, value=tag_value)
        has_next_page = True
        while has_next_page:
            result = self._client.collection_files(self.id, end_cursor, tag)
            if result is None:
                break
            file_identifiers, has_next_page, end_cursor = result
            for file_identifier in file_identifiers:
                if file_identifier is None:
                    continue
                yield self._file_reference_from_identifier(file_identifier)

    def documents(
        self, tag_key: str | None = None, tag_value: str | None = None
    ) -> Generator[DocumentReference, None, None]:
        """
        Retrieve documents from the collection, filtered by a tag key and value.

        Args:
            tag_key: If this and `tag_value` is specified, filter documents with this
                tag.
            tag_value: If this and `tag_key` is specified, filter documents with this
                tag.

        Yields:
            Documents from the collection.

        """
        end_cursor = ""
        tag_input = None
        if tag_key is not None and tag_value is not None:
            tag_input = Tag(key=tag_key, value=tag_value)
        has_next_page = True
        while has_next_page:
            result = self._client.collection_documents(self.id, end_cursor, tag_input)
            doc_refs, has_next_page, end_cursor = result
            if doc_refs is None:
                break
            for doc_ref in doc_refs:
                if doc_ref is None:
                    continue
                yield self._document_reference_from_identifier(doc_ref)

    def collections(
        self, tag_key: str | None = None, tag_value: str | None = None
    ) -> Generator[CollectionReference, None, None]:
        """
        Retrieve collections from the collection, filtered by a tag key and value.

        Args:
            tag_key: If this and `tag_value` is specified, filter collections with this
                tag.
            tag_value: If this and `tag_key` is specified, filter collections with this
                tag.

        Yields:
            Nested collections of this collection.

        """
        end_cursor = ""
        tag = None
        if tag_key is not None and tag_value is not None:
            tag = Tag(key=tag_key, value=tag_value)
        has_next_page = True
        while has_next_page:
            result = self._client.collection_collections(self.id, end_cursor, tag)
            if result is None:
                break
            refs, has_next_page, end_cursor = result
            if refs is None:
                break
            for ref in refs:
                yield CollectionReference(ref.id, ref.key, self._client)

    def _file_reference_from_identifier(
        self, identifier: CollectionFileIdentifier
    ) -> FileReference:
        return FileReference(id=identifier.id, key=identifier.key, _client=self._client)

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

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

        """
        self._client.collection_tag_add(self.id, Tag(key=key, value=value))

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

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

        """
        self._client.collection_tag_delete(self.id, key)

tags: dict[str, str] property

Get the tags for the collection.

collection(collection_key)

Get or create a child collection of this collection by key.

Parameters:

Name Type Description Default
collection_key str

Key of the nested collection. A key uniquely identifies a collection within the parent collection. Keys are case sensitive, and can be used as human-readable identifiers for collections

 required

Returns:

Name Type Description
NumerousCollection CollectionReference

The child collection identified by the given key.
Source code in numerous/collections/collection_reference.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def collection(self, collection_key: str) -> CollectionReference:
    """
    Get or create a child collection of this collection by key.

    Args:
        collection_key: Key of the nested collection. A key uniquely identifies a
            collection within the parent collection. Keys are case sensitive, and
            can be used as human-readable identifiers for collections

    Returns:
        NumerousCollection: The child collection identified by the given key.

    """
    ref = self._client.collection_reference(
        collection_key=collection_key, parent_collection_id=self.id
    )

    return CollectionReference(ref.id, ref.key, self._client)

collections(tag_key=None, tag_value=None)

Retrieve collections from the collection, filtered by a tag key and value.

Parameters:

Name Type Description Default
tag_key str | None

If this and tag_value is specified, filter collections with this tag.

 None
tag_value str | None

If this and tag_key is specified, filter collections with this tag.

 None

Yields:

Type Description
CollectionReference

Nested collections of this collection.
Source code in numerous/collections/collection_reference.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
def collections(
    self, tag_key: str | None = None, tag_value: str | None = None
) -> Generator[CollectionReference, None, None]:
    """
    Retrieve collections from the collection, filtered by a tag key and value.

    Args:
        tag_key: If this and `tag_value` is specified, filter collections with this
            tag.
        tag_value: If this and `tag_key` is specified, filter collections with this
            tag.

    Yields:
        Nested collections of this collection.

    """
    end_cursor = ""
    tag = None
    if tag_key is not None and tag_value is not None:
        tag = Tag(key=tag_key, value=tag_value)
    has_next_page = True
    while has_next_page:
        result = self._client.collection_collections(self.id, end_cursor, tag)
        if result is None:
            break
        refs, has_next_page, end_cursor = result
        if refs is None:
            break
        for ref in refs:
            yield CollectionReference(ref.id, ref.key, self._client)

document(key)

Get or create a document by key.

Parameters:

Name Type Description Default
key str

Key of the document. A key uniquely identifies a document within its collection. Keys are case sensitive.

 required

Returns:

Type Description
DocumentReference

The document in the collection with the given key.

Raises:

Type Description
ParentCollectionNotFoundError

If the collection does not exist, for example if it was deleted.
Source code in numerous/collections/collection_reference.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def document(self, key: str) -> DocumentReference:
    """
    Get or create a document by key.

    Args:
        key: Key of the document. A key uniquely identifies a document within its
            collection. Keys are case sensitive.

    Returns:
        The document in the collection with the given key.

    Raises:
        ParentCollectionNotFoundError: If the collection does not exist, for example
            if it was deleted.

    """
    doc_ref = self._client.document_reference(self.id, key)
    if doc_ref is None:
        return self._document_reference(doc_id=None, doc_key=key)
    return self._document_reference_from_identifier(doc_ref)

documents(tag_key=None, tag_value=None)

Retrieve documents from the collection, filtered by a tag key and value.

Parameters:

Name Type Description Default
tag_key str | None

If this and tag_value is specified, filter documents with this tag.

 None
tag_value str | None

If this and tag_key is specified, filter documents with this tag.

 None

Yields:

Type Description
DocumentReference

Documents from the collection.
Source code in numerous/collections/collection_reference.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
def documents(
    self, tag_key: str | None = None, tag_value: str | None = None
) -> Generator[DocumentReference, None, None]:
    """
    Retrieve documents from the collection, filtered by a tag key and value.

    Args:
        tag_key: If this and `tag_value` is specified, filter documents with this
            tag.
        tag_value: If this and `tag_key` is specified, filter documents with this
            tag.

    Yields:
        Documents from the collection.

    """
    end_cursor = ""
    tag_input = None
    if tag_key is not None and tag_value is not None:
        tag_input = Tag(key=tag_key, value=tag_value)
    has_next_page = True
    while has_next_page:
        result = self._client.collection_documents(self.id, end_cursor, tag_input)
        doc_refs, has_next_page, end_cursor = result
        if doc_refs is None:
            break
        for doc_ref in doc_refs:
            if doc_ref is None:
                continue
            yield self._document_reference_from_identifier(doc_ref)

file(key)

Get or create a file by key.

Parameters:

Name Type Description Default
key str

The key of the file.

 required
Source code in numerous/collections/collection_reference.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def file(self, key: str) -> FileReference:
    """
    Get or create a file by key.

    Args:
        key: The key of the file.

    """
    file_identifier = self._client.file_reference(self.id, key)
    if file_identifier is None:
        msg = "Failed to retrieve or create the file."
        raise ValueError(msg)

    return self._file_reference_from_identifier(file_identifier)

files(tag_key=None, tag_value=None)

Retrieve files from the collection, filtered by a tag key and value.

Parameters:

Name Type Description Default
tag_key str | None

The key of the tag used to filter files.

 None
tag_value str | None

The value of the tag used to filter files.

 None

Yields:

Type Description
FileReference

File references from the collection.
Source code in numerous/collections/collection_reference.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def files(
    self, tag_key: str | None = None, tag_value: str | None = None
) -> Generator[FileReference, None, None]:
    """
    Retrieve files from the collection, filtered by a tag key and value.

    Args:
        tag_key: The key of the tag used to filter files.
        tag_value: The value of the tag used to filter files.

    Yields:
        File references from the collection.

    """
    end_cursor = ""
    tag = None
    if tag_key is not None and tag_value is not None:
        tag = Tag(key=tag_key, value=tag_value)
    has_next_page = True
    while has_next_page:
        result = self._client.collection_files(self.id, end_cursor, tag)
        if result is None:
            break
        file_identifiers, has_next_page, end_cursor = result
        for file_identifier in file_identifiers:
            if file_identifier is None:
                continue
            yield self._file_reference_from_identifier(file_identifier)

save_file(file_key, file_data)

Save data to a file in the collection.

If the file with the specified key already exists, it will be overwritten with the new data.

Parameters:

Name Type Description Default
file_key str

The key of the file to save or update.

 required
file_data str

The data to be written to the file.

 required

Raises:

Type Description
ValueError

If the file cannot be created or saved.
Source code in numerous/collections/collection_reference.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def save_file(self, file_key: str, file_data: str) -> None:
    """
    Save data to a file in the collection.

    If the file with the specified key already exists,
    it will be overwritten with the new data.

    Args:
        file_key: The key of the file to save or update.
        file_data: The data to be written to the file.

    Raises:
        ValueError: If the file cannot be created or saved.

    """
    file = self.file(file_key)
    file.save(file_data)

tag(key, value)

Add a tag to the collection.

Parameters:

Name Type Description Default
key str

The tag key.

 required
value str

The tag value.

 required
Source code in numerous/collections/collection_reference.py 
216
217
218
219
220
221
222
223
224
225
def tag(self, key: str, value: str) -> None:
    """
    Add a tag to the collection.

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

    """
    self._client.collection_tag_add(self.id, Tag(key=key, value=value))

tag_delete(key)

Delete a tag from the collection.

Parameters:

Name Type Description Default
key str

The key of the tag to delete.

 required
Source code in numerous/collections/collection_reference.py 
227
228
229
230
231
232
233
234
235
def tag_delete(self, key: str) -> None:
    """
    Delete a tag from the collection.

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

    """
    self._client.collection_tag_delete(self.id, key)