Handle IMAP attachment filename collisions

[09Catho]

Summary

• add an overwrite_file option to ImapHook.download_mail_attachments, defaulting to the existing overwrite behavior
• preserve duplicate attachment filenames when overwrite_file=False by writing numeric suffixed copies such as report_1.csv
• add focused regression coverage for overwrite and non-overwrite behavior, including filenames without extensions and filenames with multiple extensions

Fixes #65870

Tests

• python -m ruff check providers\imap\src\airflow\providers\imap\hooks\imap.py providers\imap\tests\unit\imap\hooks\test_imap.py
• python -m ruff format --check providers\imap\src\airflow\providers\imap\hooks\imap.py providers\imap\tests\unit\imap\hooks\test_imap.py
• git diff --check
• standalone collision regression script for _create_file preserving duplicate filenames and overwriting existing files

I also attempted the focused pytest target with Airflow's managed environment:

• uv run python -m pytest providers\imap\tests\unit\imap\hooks\test_imap.py -q

That environment setup failed on Windows before running tests because apache-airflow[all] pulls apache-airflow-core[memray], and memray==1.19.3 reports memray does not support this platform (win32).

[boring-cyborg]

Congratulations on your first Pull Request and welcome to the Apache Airflow community! If you have any issues or are unsure about any anything please check our Contributors' Guide
Here are some useful points:

• Pay attention to the quality of your code (ruff, mypy and type annotations). Our prek-hooks will help you with that.
• In case of a new feature add useful documentation (in docstrings or in docs/ directory). Adding a new operator? Check this short guide Consider adding an example Dag that shows how users should use it.
• Consider using Breeze environment for testing locally, it's a heavy docker but it ships with a working Airflow and a lot of integrations.
• Be patient and persistent. It might take some time to get a review or get the final approval from Committers.
• Please follow ASF Code of Conduct for all communication including (but not limited to) comments on Pull Requests, Mailing list and Slack.
• Be sure to read the Airflow Coding style.
• Always keep your Pull Requests rebased, otherwise your build might fail due to changes not related to your commits.
  Apache Airflow is a community-driven project and together we are making it better 🚀.
  In case of doubts contact the developers at:
  Mailing List: dev@airflow.apache.org
  Slack: https://s.apache.org/airflow-slack

[Copilot]

Pull request overview

This PR updates the IMAP provider’s ImapHook.download_mail_attachments behavior to make attachment filename collision handling configurable, addressing data loss when multiple attachments share the same filename.

Changes:

• Adds an overwrite_file option to ImapHook.download_mail_attachments (defaulting to the current overwrite behavior).
• When overwrite_file=False, preserves all attachments by writing suffixed filenames (e.g. report_1.csv, archive.tar_1.gz) using an atomic create ("xb") loop.
• Adds unit regression coverage for both overwrite and non-overwrite modes, including filenames with no extension and multiple extensions.

Reviewed changes

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

File	Description
providers/imap/src/airflow/providers/imap/hooks/imap.py	Adds overwrite_file option and implements suffix-based collision handling when overwrite is disabled.
providers/imap/tests/unit/imap/hooks/test_imap.py	Adds regression tests validating collision behavior for both overwrite and non-overwrite modes.

[vincbeck]

Fixed in #68838