Fix IMAP attachment filename collisions

[Abdeltoto]

Closes #65870

This PR adds an overwrite_file option to ImapHook.download_mail_attachments so callers can choose whether duplicate attachment filenames overwrite existing files or are preserved with incremental suffixes.

By default, overwrite_file=True keeps the current behavior. With overwrite_file=False, existing files are preserved using suffixes such as report_1.xlsx.

Tests cover:

• default overwrite behavior, including verifying the file content is replaced
• preserving duplicate filenames when overwrite_file=False
• filenames with a normal extension, no extension, and multiple extensions

Tested locally:

• python -m py_compile providers/imap/src/airflow/providers/imap/hooks/imap.py providers/imap/tests/unit/imap/hooks/test_imap.py
• git diff --check

I could not run the targeted pytest file locally from this sparse checkout because airflow is not installed in this environment.

---

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: GPT-5.5 following the Airflow pull request guidelines.

---

Important

🛠️ Maintainer triage note for @Abdeltoto · by @potiuk · 2026-06-17 14:51 UTC

Helpful heads-up from the maintainers — please address before this PR can be reviewed:

• Static / docs checks failing (CI image checks / Static checks). Run them locally with prek run --all-files (or pre-commit run --all-files) and push the fixes.
• See the Pull Request quality criteria.

The ball is in your court — you've been assigned to this PR. Fix the above, then mark it Ready for review.

_{Automated triage — may be imperfect; a maintainer takes the next look.}

[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

[potiuk]

@Abdeltoto A few things need addressing before review — see our Pull Request quality criteria.

• ❌ Pre-commit / static checks. See docs.

No rush.

Note: This comment was drafted by an AI-assisted triage tool and may contain mistakes. Once you have addressed the points above, an Apache Airflow maintainer — a real person — will take the next look at your PR. We use this two-stage triage process so that our maintainers' limited time is spent where it matters most: the conversation with you.

[potiuk]

Note

🗑️ Closing stale draft · by @potiuk · 2026-07-02 18:44 UTC

This draft has been inactive for ~14 days. Closing to keep the queue tidy — no judgment on the change itself. Please reopen (or open a fresh PR) whenever you pick it back up, and a maintainer will be glad to take a look.

_{Automated triage — may be imperfect.}