feat(file-picker): add with_data support for web file content

[FeodorFitsner]

Summary

• add with_data argument to FilePicker.pick_files() in Python API
• return selected file content in FilePickerFile.bytes when with_data=True
• wire with_data through Flutter FilePickerService and include bytes in returned file payload
• add a new example: sdk/python/examples/services/file_picker/pick_and_save_text_content.py demonstrating:
  • picking text files and reading FilePickerFile.bytes
  • saving/downloading text content via save_file(src_bytes=...)

Motivation

This improves web file handling where a filesystem path is unavailable and callers need file contents directly.

Discussion reference: #3146

Validation

• dart analyze packages/flet/lib/src/services/file_picker.dart packages/flet/lib/src/utils/file_picker.dart
• uv run python -m compileall sdk/python/packages/flet/src/flet/controls/services/file_picker.py sdk/python/examples/services/file_picker/pick_and_save_text_content.py

Potentially related issues

• FilePicker Not Working Properly In Android and Web #4149 (web FilePicker path handling / inability to read selected file by path)
• picke_files can't get path property in web mode #326 (web path=None in picked files)

This PR does not change the web path behavior; it adds bytes opt-in as a supported alternative.

Summary by Sourcery

Add optional file content retrieval to the file picker API and demonstrate its usage with a new Python example.

New Features:

• Extend Python FilePicker.pick_files() with a with_data flag to request file contents for selected files.
• Expose file contents via a new bytes field on FilePickerFile objects in both Python and Flutter APIs when requested.
• Add a Python example demonstrating picking text files, reading their contents, and saving/downloading text content using FilePicker.

Enhancements:

• Propagate the with_data option through the Flutter FilePickerService and file mapping so web callers can receive file bytes instead of relying on paths.

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[cloudflare-workers-and-pages]

Deploying flet-docs with    Cloudflare Pages

Latest commit:	ef9bc87
Status:	✅  Deploy successful!
Preview URL:	https://7dc38c40.flet-docs.pages.dev
Branch Preview URL:	https://file-picker-client-upload.flet-docs.pages.dev

View logs

[Copilot]

Pull request overview

This PR adds optional file content retrieval to the FilePicker API, addressing web platform limitations where filesystem paths are unavailable.

Changes:

• Added with_data parameter to FilePicker.pick_files() method (defaults to False for backward compatibility)
• Added bytes field to FilePickerFile dataclass to store file contents when with_data=True
• Wired the feature through the Flutter FilePickerService with mutually exclusive withData/withReadStream logic
• Added example demonstrating picking and saving text files using the new bytes-based API

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
sdk/python/packages/flet/src/flet/controls/services/file_picker.py	Added with_data parameter to pick_files(), added bytes field to FilePickerFile dataclass, implemented _normalize_file() to convert byte arrays from Dart
sdk/python/examples/services/file_picker/pick_and_save_text_content.py	New example demonstrating picking text files with with_data=True and reading/saving content via bytes
packages/flet/lib/src/utils/file_picker.dart	Added bytes field to FilePickerFile class and included in serialization
packages/flet/lib/src/services/file_picker.dart	Added withData parameter extraction and made withData/withReadStream mutually exclusive, included bytes in returned file payload when withData=True

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[FeodorFitsner]

Addressed @ndonkoHenri review notes in ef9bc87:

• switched with_data parsing in Dart service to parseBool(...)
• updated example run instruction to uv run flet run --web pick_and_save_text_content.py
• added docs section in services/filepicker.md for the new with_data=True web use-case and linked the new example
• fixed Python docstring cross-references for pick_files()/bytes

Checks run:

• dart analyze packages/flet/lib/src/services/file_picker.dart packages/flet/lib/src/utils/file_picker.dart
• uv run python -m compileall sdk/python/packages/flet/src/flet/controls/services/file_picker.py sdk/python/examples/services/file_picker/pick_and_save_text_content.py
• local hooks passed on commit (ruff/format/typos/etc).

[cloudflare-workers-and-pages]

Deploying flet-examples with    Cloudflare Pages

Latest commit:	ef9bc87
Status:	✅  Deploy successful!
Preview URL:	https://0cec875e.flet-examples.pages.dev
Branch Preview URL:	https://file-picker-client-upload.flet-examples.pages.dev

View logs