Azure / Azure/azure-sdk-for-python
azure-ai-projects package: Add support for session file download to disk
- 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
Assessment
This issue has not been assessed yet.