gmail attachments downloader updates

[dnoice]

Description

This PR adds a Gmail Attachment Downloader script that allows users to search their Gmail account and download attachments matching specific search criteria. The script has been enhanced with improved error handling, better user interface, custom download directory support, and comprehensive documentation.

Fixes #(issue_no)

Type of change

• New feature (non-breaking change which adds functionality)
• Documentation Update

Checklist:

• My code follows the style guidelines(Clean Code) of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have updated a helpful and easy to understand README.md
• My documentation follows [Template for README.md](https://github.com/avinashkranjan/Amazing-Python-Scripts/blob/master/Template%20for%20README.md)

Project Metadata

Category:

• Automation

Title: Gmail Attachment Downloader

Folder: Gmail_Attachment_Downloader

Requirements: requirements.txt (containing: ezgmail)

Script: attachment_downloader.py

Arguments: None (The script uses interactive prompts)

Contributor: dnoice

Description: A Python script that allows users to search their Gmail using query operators and download attachments matching the search criteria to a specified directory.

Summary by Sourcery

Provide a fully featured Gmail Attachment Downloader with an interactive command-line interface, custom download directory support, robust error handling, and comprehensive documentation

New Features:

• Add interactive Gmail Attachment Downloader script enabling search and download of attachments based on Gmail search queries
• Support specifying a custom download directory and automatically include attachment filters in searches

Enhancements:

• Implement progress tracking and improved error handling during attachment downloads
• Enhance CLI prompts to display email subjects, dates, and confirm actions before downloading

Documentation:

• Revise README with detailed features list, installation/authentication steps, usage examples, troubleshooting guidelines, advanced usage tips, and licensing

Chores:

• Remove obsolete attachment.py stub

[sourcery-ai]

Reviewer's Guide

This PR introduces a new interactive Gmail Attachment Downloader script leveraging the ezgmail API to search user mail threads by query operators, present formatted results, and download attachments to a specified directory with progress tracking and robust error handling; it also refines project documentation with a comprehensive README update and removes the legacy attachment.py script.

Sequence Diagram for Gmail Attachment Download Process

Loading

sequenceDiagram
    actor User
    participant Script as attachment_downloader.py
    participant EZGmail as ezgmail Library
    participant GmailAPI as Gmail API

    User->>Script: Executes script
    Script->>EZGmail: init()
    activate EZGmail
    EZGmail-->>Script: Authentication status (EMAIL_ADDRESS)
    deactivate EZGmail
    Script-->>User: Displays "Logged in as: ..."

    Script-->>User: Prompts "Enter search query:"
    User->>Script: Provides search query
    Script->>Script: query_with_attachments = query + " has:attachment"
    Script->>EZGmail: search(query_with_attachments)
    activate EZGmail
    EZGmail->>GmailAPI: Performs search operation
    activate GmailAPI
    GmailAPI-->>EZGmail: Search results (threads)
    deactivate GmailAPI
    EZGmail-->>Script: Returns GmailThread objects
    deactivate EZGmail

    alt No results found
        Script-->>User: "No results found..."
    else Results found
        Script-->>User: Displays formatted results (subject, date)
        Script-->>User: Prompts "Download attachments? (y/n):"
        User->>Script: Confirms 'y'
        Script-->>User: Prompts "Enter download directory:"
        User->>Script: Provides directory (or empty)

        Script->>Script: download_attachments(threads, dir)
        activate Script
        loop For each thread and message
            Script->>EZGmail: message.downloadAllAttachments()
            activate EZGmail
            EZGmail->>GmailAPI: Requests attachment data
            activate GmailAPI
            GmailAPI-->>EZGmail: Attachment data
            deactivate GmailAPI
            EZGmail-->>Script: Saves files to disk
            deactivate EZGmail
            Script-->>User: Shows progress/downloaded file names
        end
        deactivate Script
        Script-->>User: "Download complete! ... files saved to ..."
    end

    alt User cancels download
        User->>Script: Confirms 'n'
        Script-->>User: "Download canceled. Exiting..."
    end

File-Level Changes

Change	Details	Files
Implemented interactive Gmail attachment downloader script	Added ezgmail init and authentication checks with error feedback Prompted user for search query and appended attachment filter Displayed search results with formatted dates and subjects Created download_attachments function managing directory creation, per-thread/message loops, and progress output Wrapped operations in try/except/finally to handle errors and restore working directory	Attachment_Downloader/attachment_downloader.py
Overhauled README with detailed instructions and examples	Renamed project title and added Features and Requirements sections Expanded setup steps including Google API credential generation Outlined Usage with search operators, examples, and interactive prompts Added Troubleshooting, Advanced Usage, and License sections	Attachment_Downloader/README.md
Removed deprecated attachment.py script	Deleted legacy script to avoid confusion and redundancy	Attachment_Downloader/attachment.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @dnoice - I've reviewed your changes and they look great!

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion (code-quality): Replace if-expression with or (or-if-exp-identity)

Suggested change

	download_attachments(result_threads, custom_dir if custom_dir else None)
	download_attachments(result_threads, custom_dir or None)

Explanation

Here we find ourselves setting a value if it evaluates to True, and otherwise
using a default.

The 'After' case is a bit easier to read and avoids the duplication of
input_currency.

It works because the left-hand side is evaluated first. If it evaluates to
true then currency will be set to this and the right-hand side will not be
evaluated. If it evaluates to false the right-hand side will be evaluated and
currency will be set to DEFAULT_CURRENCY.

[github-actions]

Due to inactivity this pull request has been marked as stale.