feat: return FileItem from files.upload() (#118)

README.md

@@ -523,6 +523,25 @@ sync_client.files.upload(
 )
 ```
 
+`upload()` returns a `FileItem` describing the stored file:
+
+```python
+FileItem(
+    name="my-file.txt",
+    parent_path="some-relative-path",
+    bucket="my-bucket",
+    url="files/my-bucket/some-relative-path/my-file.txt",
+    node_type="ITEM",
+    resource_type="FILE",
+    content_length=12,
+    content_type="text/plain",
+    etag="9749fad13d6e7092a6337c4af9d83764",
+    created_at=1724836229736,
+    updated_at=1724836248936,
+    author="user@example.com",
+)
+```
+
 #### Downloading Files
 
 Use `download()` to download files from your storage bucket:
@@ -664,11 +683,12 @@ FileMetadata(
     resource_type="FILE",
     content_length=12,
     content_type="application/octet-stream",
+    etag="9749fad13d6e7092a6337c4af9d83764",
+    created_at=1724836229736,
+    updated_at=1724836248936,
+    author="user@example.com",
     next_token=None,
     items=None,
-    updatedAt=1724836248936,
-    etag="9749fad13d6e7092a6337c4af9d83764",
-    createdAt=1724836229736,
 )
 ```
 

aidial_client/resources/files.py

@@ -22,7 +22,7 @@
 from aidial_client.resources.base import AsyncResource, Resource
 from aidial_client.resources.metadata import AsyncMetadata, Metadata
 from aidial_client.types.file import FileDownloadResponse
-from aidial_client.types.metadata import FileMetadata
+from aidial_client.types.metadata import FileItem, FileMetadata
 
 
 def _files_error_processor(
@@ -49,9 +49,9 @@ def upload(
         file: FileTypes,
         etag_if_match: str | None = None,
         etag_if_none_match: Literal["*"] | None = None,
-    ) -> FileMetadata:
+    ) -> FileItem:
         return self.http_client.request(
-            cast_to=FileMetadata,
+            cast_to=FileItem,
             options=FinalRequestOptions(
                 method="PUT",
                 url=urljoin(API_PREFIX, self.get_api_path(str(url))),
@@ -163,9 +163,9 @@ async def upload(
         file: FileTypes,
         etag_if_match: str | None = None,
         etag_if_none_match: Literal["*"] | None = None,
-    ) -> FileMetadata:
+    ) -> FileItem:
         return await self.http_client.request(
-            cast_to=FileMetadata,
+            cast_to=FileItem,
             options=FinalRequestOptions(
                 method="PUT",
                 url=urljoin(API_PREFIX, self.get_api_path(str(url))),

aidial_client/types/metadata.py

@@ -30,7 +30,10 @@ class FileItem(BaseMetadata):
     resource_type: Literal["FILE"]
     content_length: int | None = None
     content_type: str | None = None
+    created_at: int | None = None
     updated_at: int | None = None
+    etag: str | None = None
+    author: str | None = None
 
 
 class FileMetadata(BaseMetadata):

tests/integration/test_async_files.py

@@ -4,7 +4,7 @@
 
 from aidial_client import AsyncDial, DialException
 from aidial_client._exception import EtagMismatchError
-from aidial_client.types.metadata import FileMetadata
+from aidial_client.types.metadata import FileItem
 from tests.integration.fixtures import *  # type: ignore # noqa
 
 current_file_path = os.path.abspath(__file__)
@@ -20,7 +20,7 @@ async def test_upload(async_client: AsyncDial):
         upload_result = await async_client.files.upload(
             url=await async_client.my_files_home() / file_path, file=file
         )
-    assert isinstance(upload_result, FileMetadata)
+    assert isinstance(upload_result, FileItem)
     assert upload_result.bucket == await async_client.my_bucket()
     assert upload_result.node_type == "ITEM"
     assert upload_result.name == file_name

tests/integration/test_sync_files.py

@@ -4,7 +4,7 @@
 
 from aidial_client import Dial, DialException
 from aidial_client._exception import EtagMismatchError
-from aidial_client.types.metadata import FileMetadata
+from aidial_client.types.metadata import FileItem
 from tests.integration.fixtures import *  # type: ignore # noqa
 
 current_file_path = os.path.abspath(__file__)
@@ -21,7 +21,7 @@ def test_upload(sync_client: Dial):
         upload_result = sync_client.files.upload(
             url=sync_client.my_files_home() / file_path, file=file
         )
-    assert isinstance(upload_result, FileMetadata)
+    assert isinstance(upload_result, FileItem)
     assert upload_result.bucket == sync_client.my_bucket()
     assert upload_result.node_type == "ITEM"
     assert upload_result.name == file_name

tests/resources/files/test_upload.py

@@ -4,7 +4,7 @@
 import pytest
 
 from aidial_client._exception import InvalidDialURLError
-from aidial_client.types.metadata import FileMetadata
+from aidial_client.types.metadata import FileItem
 from tests.client_mock import get_async_client_mock, get_client_mock
 
 UPLOAD_RESPONSE_MOCK = {
@@ -16,6 +16,10 @@
     "resourceType": "FILE",
     "contentLength": 128630,
     "contentType": "image/png",
+    "etag": "9749fad13d6e7092a6337c4af9d83764",
+    "createdAt": 1724836229736,
+    "updatedAt": 1724836248936,
+    "author": "user@example.com",
 }
 current_file_path = os.path.abspath(__file__)
 
@@ -35,10 +39,17 @@ def test_upload_file_object():
             file=file,
         )
         for r in [valid_response, valid_response_using_default_bucket]:
-            assert isinstance(r, FileMetadata)
+            assert isinstance(r, FileItem)
             assert r.bucket == "test-bucket"
             assert r.name == "file.png"
             assert r.parent_path == "folder1/folder2"
+            assert r.node_type == "ITEM"
+            assert r.content_length == 128630
+            assert r.content_type == "image/png"
+            assert r.etag == "9749fad13d6e7092a6337c4af9d83764"
+            assert r.created_at == 1724836229736
+            assert r.updated_at == 1724836248936
+            assert r.author == "user@example.com"
 
 
 @pytest.mark.asyncio
@@ -66,7 +77,14 @@ async def test_upload_file_object_async():
             file=file,
         )
         for r in [valid_response, valid_response_with_files_home]:
-            assert isinstance(r, FileMetadata)
+            assert isinstance(r, FileItem)
             assert r.bucket == "test-bucket"
             assert r.name == "file.png"
             assert r.parent_path == "folder1/folder2"
+            assert r.node_type == "ITEM"
+            assert r.content_length == 128630
+            assert r.content_type == "image/png"
+            assert r.etag == "9749fad13d6e7092a6337c4af9d83764"
+            assert r.created_at == 1724836229736
+            assert r.updated_at == 1724836248936
+            assert r.author == "user@example.com"