Skip to content

file_reference

numerous.collections.file_reference

Class for working with numerous files.

FileReference dataclass

Represents a file in a collection.

Source code in numerous/collections/file_reference.py 
 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
@dataclass
class FileReference:
    """Represents a file in a collection."""

    id: str
    key: str
    _client: Client

    @property
    def exists(self) -> bool:
        """
        Indicate whether the file exists.

        Returns:
            True if the file exists; False otherwise.

        """
        return self._client.file_exists(self.id)

    @property
    def tags(self) -> dict[str, str]:
        """
        Return the tags associated with the file.

        Returns:
            A dictionary of tag key-value pairs.

        """
        tags = self._client.file_tags(self.id)
        if tags is None:
            raise ValueError(NO_FILE_ERROR_MSG)
        return tags

    def read_text(self) -> str:
        """
        Read the file's content as text.

        Returns:
            The text content of the file.

        """
        return self._client.file_read_text(self.id)

    def read_bytes(self) -> bytes:
        """
        Read the file's content as bytes.

        Returns:
            The byte content of the file.

        """
        return self._client.file_read_bytes(self.id)

    def open(self) -> BinaryIO:
        """
        Open the file for reading in binary mode.

        Returns:
            A binary file-like object for reading the file.

        """
        return self._client.file_open(self.id)

    def save(self, data: bytes | str) -> None:
        """
        Upload and saves data to the file on the server.

        Args:
            data: The content to save to the file, either as bytes or string.

        """
        self._client.file_save(self.id, data)

    def save_file(self, data: TextIOWrapper) -> None:
        """
        Upload and saves a text file to the server.

        Args:
            data: A file-like object containing the text content to upload.

        """
        self._client.file_save(self.id, data.read())

    def delete(self) -> None:
        """Delete the file from the server."""
        self._client.file_delete(self.id)

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

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

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

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

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

        Raises:
            ValueError: If the file does not exist.

        """
        self._client.file_delete_tag(self.id, tag_key)

exists: bool property

Indicate whether the file exists.

Returns:

Type Description
bool

True if the file exists; False otherwise.

tags: dict[str, str] property

Return the tags associated with the file.

Returns:

Type Description
dict[str, str]

A dictionary of tag key-value pairs.

delete()

Delete the file from the server.

Source code in numerous/collections/file_reference.py 
102
103
104
def delete(self) -> None:
    """Delete the file from the server."""
    self._client.file_delete(self.id)

open()

Open the file for reading in binary mode.

Returns:

Type Description
BinaryIO

A binary file-like object for reading the file.
Source code in numerous/collections/file_reference.py 
72
73
74
75
76
77
78
79
80
def open(self) -> BinaryIO:
    """
    Open the file for reading in binary mode.

    Returns:
        A binary file-like object for reading the file.

    """
    return self._client.file_open(self.id)

read_bytes()

Read the file's content as bytes.

Returns:

Type Description
bytes

The byte content of the file.
Source code in numerous/collections/file_reference.py 
62
63
64
65
66
67
68
69
70
def read_bytes(self) -> bytes:
    """
    Read the file's content as bytes.

    Returns:
        The byte content of the file.

    """
    return self._client.file_read_bytes(self.id)

read_text()

Read the file's content as text.

Returns:

Type Description
str

The text content of the file.
Source code in numerous/collections/file_reference.py 
52
53
54
55
56
57
58
59
60
def read_text(self) -> str:
    """
    Read the file's content as text.

    Returns:
        The text content of the file.

    """
    return self._client.file_read_text(self.id)

save(data)

Upload and saves data to the file on the server.

Parameters:

Name Type Description Default
data bytes | str

The content to save to the file, either as bytes or string.

 required
Source code in numerous/collections/file_reference.py 
82
83
84
85
86
87
88
89
90
def save(self, data: bytes | str) -> None:
    """
    Upload and saves data to the file on the server.

    Args:
        data: The content to save to the file, either as bytes or string.

    """
    self._client.file_save(self.id, data)

save_file(data)

Upload and saves a text file to the server.

Parameters:

Name Type Description Default
data TextIOWrapper

A file-like object containing the text content to upload.

 required
Source code in numerous/collections/file_reference.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
def save_file(self, data: TextIOWrapper) -> None:
    """
    Upload and saves a text file to the server.

    Args:
        data: A file-like object containing the text content to upload.

    """
    self._client.file_save(self.id, data.read())

tag(key, value)

Add a tag to the file.

Parameters:

Name Type Description Default
key str

The tag key.

 required
value str

The tag value.

 required
Source code in numerous/collections/file_reference.py 
106
107
108
109
110
111
112
113
114
115
def tag(self, key: str, value: str) -> None:
    """
    Add a tag to the file.

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

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

tag_delete(tag_key)

Delete a tag from the file.

Parameters:

Name Type Description Default
tag_key str

The key of the tag to delete.

 required

Raises:

Type Description
ValueError

If the file does not exist.
Source code in numerous/collections/file_reference.py 
117
118
119
120
121
122
123
124
125
126
127
128
def tag_delete(self, tag_key: str) -> None:
    """
    Delete a tag from the file.

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

    Raises:
        ValueError: If the file does not exist.

    """
    self._client.file_delete_tag(self.id, tag_key)