docs(examples): add code_execution_file_download example

[ayeshakhalid192007-dev]

Summary

Adds examples/code_execution_file_download.py, a runnable example demonstrating the correct way to extract file_id from a code execution response and download the generated file using client.beta.files.download().

Problem

Some documentation shows the following pattern for extracting file_id after code execution:

# INCORRECT — this never matches
if block.type == "tool_use" and block.name == "code_execution":
    for result_block in block.content:
        file_id = result_block.file_id

This condition is never satisfied because server-side tools (code_execution, web_search, etc.) produce a "server_tool_use" block for the invocation — not "tool_use". The generated file arrives in a separate block of type "bash_code_execution_tool_result". Users following this pattern waste API credits debugging a loop that never fires (ref #1360).

Changes

• examples/code_execution_file_download.py (new file, 79 lines)

The example:

1. Sends a messages.create() request with the code_execution_20250825 server tool
2. Prints all response block types for reference
3. Correctly iterates blocks checking for bash_code_execution_tool_result
4. Navigates the nested content path to reach file_id:

   block                           type = "bash_code_execution_tool_result"
     .content                      BashCodeExecutionResultBlock
       .content[i]                 BashCodeExecutionOutputBlock
         .type == "bash_code_execution_output"
         .file_id                  ← passed to client.beta.files.download()
   

5. Downloads the file and saves it to disk

Why this is safe

• Only examples/ is changed — a directory explicitly excluded from generator overwrites per CONTRIBUTING.md
• No SDK source, types, tests, or configuration files are modified
• The example uses only public, stable API surface (messages.create, beta.files.download)

Testing

Syntax check:

python3 -m py_compile examples/code_execution_file_download.py  →  OK

Lint (ruff, pyright, mypy):

./scripts/lint  →  0 errors, 0 warnings, 0 informations

Full test suite:

pytest  →  2235 passed, 297 skipped, 1 xfailed, 0 failed  (exit 0)

The 1 xfailed is a pre-existing @pytest.mark.xfail on test_runners.py::test_custom_message_handling unrelated to this change.

Files changed

File	Change
examples/code_execution_file_download.py	New file (79 lines)

Related issues

Closes #1360