Azure / Azure/azure-sdk-for-python

azure-ai-projects package: Add support for session file download to disk

Open
#46,477 0 comments 0 reactions 1 assignee Claimed by @dargilco View on GitHub
AI Projects feature-request
Dominant language
Python
Stars
5.6k
Forks
3.4k
Avg merge
1d 21h
Merged PRs (30d)
193

Description

We have a method called download_session_file that returns a byte stream. We need another one that can write the stream to disk as a file.

Here are the design options Copilot suggested:

## Option 1: Separate Methods (Recommended)

```python
# Keep existing method for streaming
def download_session_file(
self, agent_name: str, agent_session_id: str, *, path: str, **kwargs: Any
) -> Iterator[bytes]:

# Add new method for saving to disk
def download_session_file_to_path(
self, agent_name: str, agent_session_id: str, *, path: str, file_path: str, **kwargs: Any
) -> None:
```

**Pros:** Clear intent, no breaking changes, return types are unambiguous
**Cons:** Two methods to maintain

---

## Option 2: Single Method with Optional Parameter

```python
def download_session_file(
self, agent_name: str, agent_session_id: str, *, path: str,
file_path: Optional[str] = None, **kwargs: Any
) -> Optional[Iterator[bytes]]:
```

Returns `Iterator[bytes]` when `file_path` is None, returns `None` (or bytes written) when writing to disk.

**Pros:** Single entry point
**Cons:** Ambiguous return type, harder to document, may confuse static analysis

---

## Option 3: Rename + Add

```python
# Rename existing to be explicit about streaming
def get_session_file_content(
self, agent_name: str, agent_session_id: str, *, path: str, **kwargs: Any
) -> Iterator[bytes]:

# "download" implies saving to disk
def download_session_file(
self, agent_name: str, agent_session_id: str, *, path: str, file_path: str, **kwargs: Any
) -> None:
```

**Pros:** Semantically clearer ("download" = save to disk)
**Cons:** Breaking change to existing API

---

## My Recommendation

**Option 1** is the safest and follows Azure SDK patterns (e.g., `download_blob` vs other blob operations). The name `download_session_file_to_path` or `save_session_file_to_path` clearly indicates the destination is a local file path.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.