Skip to content

Files

files

Service class for handling file operations in Kaleidoscope.

This module provides methods for downloading files from the Kaleidoscope API.

Classes:

Name Description
FilesService

Service for downloading files by ID.
Example 
path = client.files.download_file(
    file_id="file-uuid",
    filename="original_filename.csv",
    destination="/tmp/downloads",
    activity_id="activity-uuid",
)

FilesService 

FilesService(client: KaleidoscopeClient)

Service class for file operations.

Provides methods to download files by ID from the Kaleidoscope API.

Methods:

Name Description
download_file

Download a file by ID and save it to a local path.
Source code in kalbio/files.py 
34
35
def __init__(self, client: "KaleidoscopeClient"):
    self._client = client

download_file 

download_file(file_id: str, filename: str | None = None, destination: str | Path | None = None, activity_id: str | None = None) -> str | None

Download a file by ID and save it to a local path.

When activity_id is provided, the download is scoped to that activity using /activities/{activity_id}/file/{file_id}. Otherwise falls back to /files/{file_id}.

Parameters:

Name Type Description Default
file_id str

The ID of the file to download.

 required
filename str

Name to save the file as. Defaults to the file_id if not provided. Typically the file_name from the webhook event payload.

 None
destination str | Path

Directory to save the file in. Defaults to the current working directory.

 None
activity_id str

The activity ID to scope the download to. When provided, uses the activity-scoped endpoint.

 None

Returns:

Type Description
str | None

The path to the downloaded file on success,
str | None

or None on failure.
Example 
# Download scoped to an activity
path = client.files.download_file(
    "file-uuid",
    filename="data.csv",
    activity_id="activity-uuid",
)

# Download by file ID only
path = client.files.download_file(
    "file-uuid",
    filename="data.csv",
    destination="/tmp/downloads",
)
Source code in kalbio/files.py 
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
def download_file(
    self,
    file_id: str,
    filename: Optional[str] = None,
    destination: Optional[str | Path] = None,
    activity_id: Optional[str] = None,
) -> str | None:
    """Download a file by ID and save it to a local path.

    When ``activity_id`` is provided, the download is scoped to that
    activity using ``/activities/{activity_id}/file/{file_id}``.
    Otherwise falls back to ``/files/{file_id}``.

    Args:
        file_id (str): The ID of the file to download.
        filename (str, optional): Name to save the file as. Defaults to
            the file_id if not provided. Typically the ``file_name``
            from the webhook event payload.
        destination (str | Path, optional): Directory to save the file in.
            Defaults to the current working directory.
        activity_id (str, optional): The activity ID to scope the
            download to. When provided, uses the activity-scoped
            endpoint.

    Returns:
        (str | None): The path to the downloaded file on success,
        or None on failure.

    Example:
        ```python
        # Download scoped to an activity
        path = client.files.download_file(
            "file-uuid",
            filename="data.csv",
            activity_id="activity-uuid",
        )

        # Download by file ID only
        path = client.files.download_file(
            "file-uuid",
            filename="data.csv",
            destination="/tmp/downloads",
        )
        ```
    """
    try:
        name = filename or file_id
        dest_dir = str(destination) if destination else "."
        download_path = f"{dest_dir}/{name}"

        if activity_id:
            url = f"/activities/{activity_id}/file/{file_id}"
        else:
            url = f"/files/{file_id}"

        return self._client._get_file(url, download_path)
    except Exception as e:
        _logger.error(f"Error downloading file {file_id}: {e}")
        return None