| Name | gmail-attachment-dl JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Gmail attachment downloader with regex filtering support |
| upload_time | 2025-08-12 06:23:54 |
| maintainer | None |
| docs_url | None |
| author | kakehashi |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2024 [Your Name]
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
gmail
attachment
download
email
automation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Gmail Attachment Downloader
Automatically download Gmail attachments (PDFs) based on regex filters. Supports multiple accounts and works with both personal Gmail and Google Workspace accounts.
## Features
- **Multi-account support** - Process multiple Gmail/Google Workspace accounts
- **Regex filtering** - Filter emails by From, To, Subject, and Body using regex patterns
- **Wildcard attachment filtering** - Filter attachments by filename patterns
- **Secure credential storage** - OAuth2 tokens are encrypted and stored securely
- **Cross-platform** - Works on Windows, macOS, and Linux
- **Batch processing** - Perfect for scheduled/cron jobs
- **Date range search** - Configurable search period
## Installation
### Quick Install from PyPI
Once published to PyPI, you can install and run easily:
```bash
# Install with uv (recommended)
uvx gmail-attachment-dl # Run directly without installation
# Or install globally
uv tool install gmail-attachment-dl
# Or install with pip
pip install gmail-attachment-dl
```
### Install from Source
#### Prerequisites
Create and activate a virtual environment:
```bash
python -m venv venv
# On Windows
.\venv\Scripts\Activate.ps1
# On Linux/macOS
source venv/bin/activate
```
### Basic Installation
Install the project in editable mode:
#### For Production Use
```bash
pip install -e "."
```
#### For Development
Install with development tools included:
```bash
pip install -e ".[dev]"
```
### Dependencies
**Core dependencies** (automatically installed):
- `google-auth>=2.0.0` - Google authentication library
- `google-auth-oauthlib>=1.0.0` - OAuth2 flow support
- `google-auth-httplib2>=0.2.0` - HTTP transport for Google APIs
- `google-api-python-client>=2.0.0` - Gmail API client
- `cryptography>=41.0.0` - Token encryption
- `click>=8.0.0` - Command-line interface
**Development dependencies** (installed with `[dev]`):
- `pylint` - Code linting
- `pylint-plugin-utils` - Pylint utilities
- `black` - Code formatting
### Installation Examples
#### Quick Start (Production)
```bash
# Clone and install for production use
git clone <repository-url>
cd gmail-attachment-dl
python -m venv venv
.\venv\Scripts\Activate.ps1 # Windows
pip install -e "."
```
#### Developer Setup
```bash
# Clone and setup development environment
git clone <repository-url>
cd gmail-attachment-dl
python -m venv venv
.\venv\Scripts\Activate.ps1 # Windows
pip install -e ".[dev]"
# Run development tools
black src/
ruff check src/
```
## Setup
### 1. Google Cloud Configuration
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing one
3. Enable Gmail API:
- Go to "APIs & Services" > "Library"
- Search for "Gmail API"
- Click "Enable"
4. Create OAuth2 credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose "Desktop app" as application type
- Download the credentials JSON file
5. Save the file as `client_secret.json` in:
- Windows: `%APPDATA%\gmail-attachment-dl\credentials\`
- macOS: `~/Library/Application Support/gmail-attachment-dl/credentials/`
- Linux: `~/.config/gmail-attachment-dl/credentials/`
### 2. Create Configuration File
Create a `config.json` file (see `config.example.json` for reference):
```json
{
"default_days": 7,
"app_dir": null,
"credentials_path": null,
"download_base_path": null,
"encryption_salt": null,
"accounts": {
"user@gmail.com": [
{
"from": "invoice@.*\\.example\\.com",
"subject": ["Receipt", "Invoice"],
"body": "Payment.*confirmed",
"attachments": ["*.pdf"]
},
{
"from": "billing@.*\\.example\\.com",
"attachments": ["report_*.pdf", "invoice_*.pdf"]
}
],
"user@company.com": [
{
"from": ["billing@.*", "accounting@.*"],
"subject": "Statement",
"attachments": null
}
]
}
}
```
**Configuration Structure:**
- Each email account has an **array of filter sets**
- Multiple filter sets per account allow different rules
- All conditions within a filter set must match (AND)
- Filter sets are processed independently (OR)
**Path Configuration:**
- `app_dir`: Application data directory (default: platform-specific)
- `credentials_path`: Directory for credential storage (default: `{app_dir}/credentials`)
- `download_base_path`: Base directory for downloads (default: `{app_dir}/downloads`)
- `encryption_salt`: Salt for credential encryption
**Note:** Authentication without config file saves credentials to current directory.
### 3. Authenticate Accounts
Authenticate each account (one-time setup):
```bash
gmail-attachment-dl --auth user@gmail.com
gmail-attachment-dl --auth user@company.com
```
This will:
1. Open a browser for OAuth2 authentication
2. Ask you to authorize the application
3. Save encrypted credentials for future use
**Authentication Behavior:**
- **With config file**: Credentials saved to configured `credentials_path`
- **Without config file**: Credentials saved to current directory
## Usage
### Command Line Options
```bash
gmail-attachment-dl --help
```
```text
usage: gmail-attachment-dl [-h] [--version] [--config CONFIG] [--days DAYS]
[--auth EMAIL] [--verbose]
Gmail Attachment Downloader
options:
-h, --help show this help message and exit
--version show program's version number and exit
--config CONFIG path to configuration file (default: ./config.json)
--days DAYS number of days to search back (default: from config)
--auth EMAIL authenticate specific email account
--verbose, -v enable verbose output
```
### Command Examples
```bash
# Check version
gmail-attachment-dl --version
```
### Basic Usage
```bash
# Download attachments from last 7 days (default)
gmail-attachment-dl
# Specify number of days
gmail-attachment-dl --days 30
# Use custom config file
gmail-attachment-dl --config /path/to/config.json
# Verbose output
gmail-attachment-dl -v
```
Downloaded files will be organized by:
- Email account
- Year
- Date and message ID
- Original attachment filename
### Scheduled Execution (Cron)
```bash
# Add to crontab for daily execution at 2 AM
0 2 * * * /usr/local/bin/gmail-attachment-dl --days 1
```
### Using with uv
```bash
# Run directly
uvx gmail-attachment-dl --days 7
# With specific Python version
uv run --python 3.11 gmail-attachment-dl
```
## Configuration
### Filter Options
Each filter set can have the following fields (all optional):
- **from**: Sender email pattern (string or array of strings)
- **to**: Recipient email pattern (string or array of strings)
- **subject**: Subject line pattern (string or array of strings)
- **body**: Email body pattern (string or array of strings)
- **attachments**: Attachment filename patterns (string or array of strings)
**Pattern Types:**
- **Email fields** (from/to/subject/body): Full regex syntax
- **Attachment filenames**: Wildcard patterns (`*.pdf`, `invoice_*.pdf`, etc.)
- `null` or omitted means no filtering on that field
**Matching Logic:**
- Within a filter set: All specified fields must match (AND)
- Multiple patterns in an array: Any pattern can match (OR)
- Multiple filter sets per account: Process each independently
### Examples
```json
{
"default_days": 30,
"app_dir": "~/my-gmail-app",
"credentials_path": "~/.private/gmail-creds",
"download_base_path": "~/Documents/receipts",
"encryption_salt": "my-custom-salt-string",
"accounts": {
"user@gmail.com": [
{
"from": ".*@company\\.com",
"subject": ["Invoice", "Receipt", "Bill"],
"body": "(Paid|Confirmed|Processed)",
"attachments": ["*.pdf"]
},
{
"from": "accounting@vendor\\.com",
"attachments": ["invoice_*.pdf", "receipt_*.pdf"]
},
{
"subject": "Monthly Report",
"attachments": ["report_202*.pdf"]
}
]
}
}
```
**Attachment Pattern Examples:**
- `"*.pdf"` - All PDF files
- `"invoice_*.pdf"` - PDFs starting with "invoice_"
- `["*.pdf", "*.xlsx"]` - PDFs and Excel files
- `null` or omitted - All attachments (no filtering)
**Path Options:**
- Relative paths: `"./downloads"` (relative to current working directory)
- Absolute paths: `"/home/user/downloads"` or `"C:\\Users\\name\\Downloads"`
- Home directory: `"~/Downloads"` (expanded automatically)
- If omitted, uses `{app_dir}/subdirectory` defaults
## File Storage
Downloaded attachments are organized in a hierarchical structure:
```text
downloads/
├── user@gmail.com/
│ ├── 2025/
│ │ ├── 0108_abc123def456_invoice.pdf
│ │ ├── 0108_abc123def456_receipt.pdf
│ │ ├── 0109_ghi789jkl012_statement.pdf
│ │ └── 0110_mno345pqr678_report.pdf
│ └── 2024/
│ └── 1231_stu901vwx234_document.pdf
└── user@company.com/
└── 2025/
└── 0108_yza567bcd890_summary.pdf
```
**File naming:** `MMDD_messageId_originalname.pdf`
- Each email account has its own directory
- Files are organized by year
- Filename prefix includes date (MMDD) and Gmail message ID
- Multiple attachments from the same email share the same prefix
- Duplicate filenames are automatically renamed with `_01`, `_02`, etc.
## Security
- OAuth2 refresh tokens are encrypted using Fernet (symmetric encryption)
- Credentials are stored with restricted file permissions (600 on Unix)
- No passwords are stored - only OAuth2 tokens
- Each account requires individual authorization
## Error Handling
The tool includes comprehensive error handling for common issues:
- **Authentication errors**: Automatic token refresh with fallback to re-authentication
- **Network issues**: Retries with exponential backoff for API calls
- **File system errors**: Proper handling of permission and disk space issues
- **Gmail API limits**: Rate limiting and quota management
## Troubleshooting
### Token Expired
If you see "Token expired" errors:
```bash
gmail-attachment-dl --auth user@gmail.com
```
### Missing Credentials
If credentials are not found, re-authenticate:
```bash
gmail-attachment-dl --auth user@gmail.com
```
### Configuration Issues
If configuration is invalid:
```bash
# Check config file format
gmail-attachment-dl --config /path/to/config.json --verbose
```
### API Limits
Gmail API has generous quotas (1 billion units/day), but be aware of:
- 250 units per message send
- 5 units per message read
- 5 units per attachment download
## Development
### Development Environment Setup
1. **Clone and setup environment:**
```bash
git clone https://github.com/yourusername/gmail-attachment-dl.git
cd gmail-attachment-dl
python -m venv venv
# Activate virtual environment
# Windows:
.\venv\Scripts\Activate.ps1
# Linux/macOS:
source venv/bin/activate
# Install in development mode
pip install -e ".[dev]"
```
1. **Code formatting and linting:**
```bash
# Format code
black src/
# Run linter
ruff check src/
# Type checking
mypy src/
```
1. **Testing during development:**
```bash
# Run tests
pytest
# Run tests with coverage
pytest --cov=src/
# Test the CLI
gmail-attachment-dl --help
# Test with different options
gmail-attachment-dl --config config.example.json --days 1 --verbose
```
Raw data
{
"_id": null,
"home_page": null,
"name": "gmail-attachment-dl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "gmail, attachment, download, email, automation",
"author": "kakehashi",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ff/c5/eae4da5be167bfcb42340dd1bb7212d76f2a55db93a9c3dd0441ab607926/gmail_attachment_dl-0.1.0.tar.gz",
"platform": null,
"description": "# Gmail Attachment Downloader\r\n\r\nAutomatically download Gmail attachments (PDFs) based on regex filters. Supports multiple accounts and works with both personal Gmail and Google Workspace accounts.\r\n\r\n## Features\r\n\r\n- **Multi-account support** - Process multiple Gmail/Google Workspace accounts\r\n- **Regex filtering** - Filter emails by From, To, Subject, and Body using regex patterns\r\n- **Wildcard attachment filtering** - Filter attachments by filename patterns\r\n- **Secure credential storage** - OAuth2 tokens are encrypted and stored securely\r\n- **Cross-platform** - Works on Windows, macOS, and Linux\r\n- **Batch processing** - Perfect for scheduled/cron jobs\r\n- **Date range search** - Configurable search period\r\n\r\n## Installation\r\n\r\n### Quick Install from PyPI\r\n\r\nOnce published to PyPI, you can install and run easily:\r\n\r\n```bash\r\n# Install with uv (recommended)\r\nuvx gmail-attachment-dl # Run directly without installation\r\n\r\n# Or install globally\r\nuv tool install gmail-attachment-dl\r\n\r\n# Or install with pip\r\npip install gmail-attachment-dl\r\n```\r\n\r\n### Install from Source\r\n\r\n#### Prerequisites\r\n\r\nCreate and activate a virtual environment:\r\n\r\n```bash\r\npython -m venv venv\r\n\r\n# On Windows\r\n.\\venv\\Scripts\\Activate.ps1\r\n\r\n# On Linux/macOS\r\nsource venv/bin/activate\r\n```\r\n\r\n### Basic Installation\r\n\r\nInstall the project in editable mode:\r\n\r\n#### For Production Use\r\n\r\n```bash\r\npip install -e \".\"\r\n```\r\n\r\n#### For Development\r\n\r\nInstall with development tools included:\r\n\r\n```bash\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Dependencies\r\n\r\n**Core dependencies** (automatically installed):\r\n\r\n- `google-auth>=2.0.0` - Google authentication library\r\n- `google-auth-oauthlib>=1.0.0` - OAuth2 flow support\r\n- `google-auth-httplib2>=0.2.0` - HTTP transport for Google APIs\r\n- `google-api-python-client>=2.0.0` - Gmail API client\r\n- `cryptography>=41.0.0` - Token encryption\r\n- `click>=8.0.0` - Command-line interface\r\n\r\n**Development dependencies** (installed with `[dev]`):\r\n\r\n- `pylint` - Code linting\r\n- `pylint-plugin-utils` - Pylint utilities\r\n- `black` - Code formatting\r\n\r\n### Installation Examples\r\n\r\n#### Quick Start (Production)\r\n\r\n```bash\r\n# Clone and install for production use\r\ngit clone <repository-url>\r\ncd gmail-attachment-dl\r\npython -m venv venv\r\n.\\venv\\Scripts\\Activate.ps1 # Windows\r\npip install -e \".\"\r\n```\r\n\r\n#### Developer Setup\r\n\r\n```bash\r\n# Clone and setup development environment\r\ngit clone <repository-url>\r\ncd gmail-attachment-dl\r\npython -m venv venv\r\n.\\venv\\Scripts\\Activate.ps1 # Windows\r\npip install -e \".[dev]\"\r\n\r\n# Run development tools\r\nblack src/\r\nruff check src/\r\n```\r\n\r\n## Setup\r\n\r\n### 1. Google Cloud Configuration\r\n\r\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\r\n2. Create a new project or select existing one\r\n3. Enable Gmail API:\r\n - Go to \"APIs & Services\" > \"Library\"\r\n - Search for \"Gmail API\"\r\n - Click \"Enable\"\r\n4. Create OAuth2 credentials:\r\n - Go to \"APIs & Services\" > \"Credentials\"\r\n - Click \"Create Credentials\" > \"OAuth client ID\"\r\n - Choose \"Desktop app\" as application type\r\n - Download the credentials JSON file\r\n5. Save the file as `client_secret.json` in:\r\n - Windows: `%APPDATA%\\gmail-attachment-dl\\credentials\\`\r\n - macOS: `~/Library/Application Support/gmail-attachment-dl/credentials/`\r\n - Linux: `~/.config/gmail-attachment-dl/credentials/`\r\n\r\n### 2. Create Configuration File\r\n\r\nCreate a `config.json` file (see `config.example.json` for reference):\r\n\r\n```json\r\n{\r\n \"default_days\": 7,\r\n \"app_dir\": null,\r\n \"credentials_path\": null,\r\n \"download_base_path\": null,\r\n \"encryption_salt\": null,\r\n \"accounts\": {\r\n \"user@gmail.com\": [\r\n {\r\n \"from\": \"invoice@.*\\\\.example\\\\.com\",\r\n \"subject\": [\"Receipt\", \"Invoice\"],\r\n \"body\": \"Payment.*confirmed\",\r\n \"attachments\": [\"*.pdf\"]\r\n },\r\n {\r\n \"from\": \"billing@.*\\\\.example\\\\.com\",\r\n \"attachments\": [\"report_*.pdf\", \"invoice_*.pdf\"]\r\n }\r\n ],\r\n \"user@company.com\": [\r\n {\r\n \"from\": [\"billing@.*\", \"accounting@.*\"],\r\n \"subject\": \"Statement\",\r\n \"attachments\": null\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n**Configuration Structure:**\r\n\r\n- Each email account has an **array of filter sets**\r\n- Multiple filter sets per account allow different rules\r\n- All conditions within a filter set must match (AND)\r\n- Filter sets are processed independently (OR)\r\n\r\n**Path Configuration:**\r\n\r\n- `app_dir`: Application data directory (default: platform-specific)\r\n- `credentials_path`: Directory for credential storage (default: `{app_dir}/credentials`)\r\n- `download_base_path`: Base directory for downloads (default: `{app_dir}/downloads`)\r\n- `encryption_salt`: Salt for credential encryption\r\n\r\n**Note:** Authentication without config file saves credentials to current directory.\r\n\r\n### 3. Authenticate Accounts\r\n\r\nAuthenticate each account (one-time setup):\r\n\r\n```bash\r\ngmail-attachment-dl --auth user@gmail.com\r\ngmail-attachment-dl --auth user@company.com\r\n```\r\n\r\nThis will:\r\n\r\n1. Open a browser for OAuth2 authentication\r\n2. Ask you to authorize the application\r\n3. Save encrypted credentials for future use\r\n\r\n**Authentication Behavior:**\r\n\r\n- **With config file**: Credentials saved to configured `credentials_path`\r\n- **Without config file**: Credentials saved to current directory\r\n\r\n## Usage\r\n\r\n### Command Line Options\r\n\r\n```bash\r\ngmail-attachment-dl --help\r\n```\r\n\r\n```text\r\nusage: gmail-attachment-dl [-h] [--version] [--config CONFIG] [--days DAYS]\r\n [--auth EMAIL] [--verbose]\r\n\r\nGmail Attachment Downloader\r\n\r\noptions:\r\n -h, --help show this help message and exit\r\n --version show program's version number and exit\r\n --config CONFIG path to configuration file (default: ./config.json)\r\n --days DAYS number of days to search back (default: from config)\r\n --auth EMAIL authenticate specific email account\r\n --verbose, -v enable verbose output\r\n```\r\n\r\n### Command Examples\r\n\r\n```bash\r\n# Check version\r\ngmail-attachment-dl --version\r\n```\r\n\r\n### Basic Usage\r\n\r\n```bash\r\n# Download attachments from last 7 days (default)\r\ngmail-attachment-dl\r\n\r\n# Specify number of days\r\ngmail-attachment-dl --days 30\r\n\r\n# Use custom config file\r\ngmail-attachment-dl --config /path/to/config.json\r\n\r\n# Verbose output\r\ngmail-attachment-dl -v\r\n```\r\n\r\nDownloaded files will be organized by:\r\n\r\n- Email account\r\n- Year\r\n- Date and message ID\r\n- Original attachment filename\r\n\r\n### Scheduled Execution (Cron)\r\n\r\n```bash\r\n# Add to crontab for daily execution at 2 AM\r\n0 2 * * * /usr/local/bin/gmail-attachment-dl --days 1\r\n```\r\n\r\n### Using with uv\r\n\r\n```bash\r\n# Run directly\r\nuvx gmail-attachment-dl --days 7\r\n\r\n# With specific Python version\r\nuv run --python 3.11 gmail-attachment-dl\r\n```\r\n\r\n## Configuration\r\n\r\n### Filter Options\r\n\r\nEach filter set can have the following fields (all optional):\r\n\r\n- **from**: Sender email pattern (string or array of strings)\r\n- **to**: Recipient email pattern (string or array of strings)\r\n- **subject**: Subject line pattern (string or array of strings)\r\n- **body**: Email body pattern (string or array of strings)\r\n- **attachments**: Attachment filename patterns (string or array of strings)\r\n\r\n**Pattern Types:**\r\n\r\n- **Email fields** (from/to/subject/body): Full regex syntax\r\n- **Attachment filenames**: Wildcard patterns (`*.pdf`, `invoice_*.pdf`, etc.)\r\n- `null` or omitted means no filtering on that field\r\n\r\n**Matching Logic:**\r\n\r\n- Within a filter set: All specified fields must match (AND)\r\n- Multiple patterns in an array: Any pattern can match (OR)\r\n- Multiple filter sets per account: Process each independently\r\n\r\n### Examples\r\n\r\n```json\r\n{\r\n \"default_days\": 30,\r\n \"app_dir\": \"~/my-gmail-app\",\r\n \"credentials_path\": \"~/.private/gmail-creds\",\r\n \"download_base_path\": \"~/Documents/receipts\",\r\n \"encryption_salt\": \"my-custom-salt-string\",\r\n \"accounts\": {\r\n \"user@gmail.com\": [\r\n {\r\n \"from\": \".*@company\\\\.com\",\r\n \"subject\": [\"Invoice\", \"Receipt\", \"Bill\"],\r\n \"body\": \"(Paid|Confirmed|Processed)\",\r\n \"attachments\": [\"*.pdf\"]\r\n },\r\n {\r\n \"from\": \"accounting@vendor\\\\.com\",\r\n \"attachments\": [\"invoice_*.pdf\", \"receipt_*.pdf\"]\r\n },\r\n {\r\n \"subject\": \"Monthly Report\",\r\n \"attachments\": [\"report_202*.pdf\"]\r\n }\r\n ]\r\n }\r\n}\r\n```\r\n\r\n**Attachment Pattern Examples:**\r\n\r\n- `\"*.pdf\"` - All PDF files\r\n- `\"invoice_*.pdf\"` - PDFs starting with \"invoice_\"\r\n- `[\"*.pdf\", \"*.xlsx\"]` - PDFs and Excel files\r\n- `null` or omitted - All attachments (no filtering)\r\n\r\n**Path Options:**\r\n\r\n- Relative paths: `\"./downloads\"` (relative to current working directory)\r\n- Absolute paths: `\"/home/user/downloads\"` or `\"C:\\\\Users\\\\name\\\\Downloads\"`\r\n- Home directory: `\"~/Downloads\"` (expanded automatically)\r\n- If omitted, uses `{app_dir}/subdirectory` defaults\r\n\r\n## File Storage\r\n\r\nDownloaded attachments are organized in a hierarchical structure:\r\n\r\n```text\r\ndownloads/\r\n\u251c\u2500\u2500 user@gmail.com/\r\n\u2502 \u251c\u2500\u2500 2025/\r\n\u2502 \u2502 \u251c\u2500\u2500 0108_abc123def456_invoice.pdf\r\n\u2502 \u2502 \u251c\u2500\u2500 0108_abc123def456_receipt.pdf\r\n\u2502 \u2502 \u251c\u2500\u2500 0109_ghi789jkl012_statement.pdf\r\n\u2502 \u2502 \u2514\u2500\u2500 0110_mno345pqr678_report.pdf\r\n\u2502 \u2514\u2500\u2500 2024/\r\n\u2502 \u2514\u2500\u2500 1231_stu901vwx234_document.pdf\r\n\u2514\u2500\u2500 user@company.com/\r\n \u2514\u2500\u2500 2025/\r\n \u2514\u2500\u2500 0108_yza567bcd890_summary.pdf\r\n```\r\n\r\n**File naming:** `MMDD_messageId_originalname.pdf`\r\n\r\n- Each email account has its own directory\r\n- Files are organized by year\r\n- Filename prefix includes date (MMDD) and Gmail message ID\r\n- Multiple attachments from the same email share the same prefix\r\n- Duplicate filenames are automatically renamed with `_01`, `_02`, etc.\r\n\r\n## Security\r\n\r\n- OAuth2 refresh tokens are encrypted using Fernet (symmetric encryption)\r\n- Credentials are stored with restricted file permissions (600 on Unix)\r\n- No passwords are stored - only OAuth2 tokens\r\n- Each account requires individual authorization\r\n\r\n## Error Handling\r\n\r\nThe tool includes comprehensive error handling for common issues:\r\n\r\n- **Authentication errors**: Automatic token refresh with fallback to re-authentication\r\n- **Network issues**: Retries with exponential backoff for API calls\r\n- **File system errors**: Proper handling of permission and disk space issues\r\n- **Gmail API limits**: Rate limiting and quota management\r\n\r\n## Troubleshooting\r\n\r\n### Token Expired\r\n\r\nIf you see \"Token expired\" errors:\r\n\r\n```bash\r\ngmail-attachment-dl --auth user@gmail.com\r\n```\r\n\r\n### Missing Credentials\r\n\r\nIf credentials are not found, re-authenticate:\r\n\r\n```bash\r\ngmail-attachment-dl --auth user@gmail.com\r\n```\r\n\r\n### Configuration Issues\r\n\r\nIf configuration is invalid:\r\n\r\n```bash\r\n# Check config file format\r\ngmail-attachment-dl --config /path/to/config.json --verbose\r\n```\r\n\r\n### API Limits\r\n\r\nGmail API has generous quotas (1 billion units/day), but be aware of:\r\n\r\n- 250 units per message send\r\n- 5 units per message read\r\n- 5 units per attachment download\r\n\r\n## Development\r\n\r\n### Development Environment Setup\r\n\r\n1. **Clone and setup environment:**\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/gmail-attachment-dl.git\r\ncd gmail-attachment-dl\r\npython -m venv venv\r\n\r\n# Activate virtual environment\r\n# Windows:\r\n.\\venv\\Scripts\\Activate.ps1\r\n# Linux/macOS:\r\nsource venv/bin/activate\r\n\r\n# Install in development mode\r\npip install -e \".[dev]\"\r\n```\r\n\r\n1. **Code formatting and linting:**\r\n\r\n```bash\r\n# Format code\r\nblack src/\r\n\r\n# Run linter\r\nruff check src/\r\n\r\n# Type checking\r\nmypy src/\r\n```\r\n\r\n1. **Testing during development:**\r\n\r\n```bash\r\n# Run tests\r\npytest\r\n\r\n# Run tests with coverage\r\npytest --cov=src/\r\n\r\n# Test the CLI\r\ngmail-attachment-dl --help\r\n\r\n# Test with different options\r\ngmail-attachment-dl --config config.example.json --days 1 --verbose\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT License\r\n \r\n Copyright (c) 2024 [Your Name]\r\n \r\n Permission is hereby granted, free of charge, to any person obtaining a copy\r\n of this software and associated documentation files (the \"Software\"), to deal\r\n in the Software without restriction, including without limitation the rights\r\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n copies of the Software, and to permit persons to whom the Software is\r\n furnished to do so, subject to the following conditions:\r\n \r\n The above copyright notice and this permission notice shall be included in all\r\n copies or substantial portions of the Software.\r\n \r\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n SOFTWARE.",
"summary": "Gmail attachment downloader with regex filtering support",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/kakehashi-inc/gmail-attachment-dl",
"Issues": "https://github.com/kakehashi-inc/gmail-attachment-dl/issues",
"Repository": "https://github.com/kakehashi-inc/gmail-attachment-dl.git"
},
"split_keywords": [
"gmail",
" attachment",
" download",
" email",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "66df0ec533c338ebcbd9211abbc18d65e121e4d30689aea2df0303b3d1196ea9",
"md5": "854c78139db15aa07dba27bc511c708e",
"sha256": "d32248f624efcad51b9c7355ad243be0141720a85cb99f58e2fbc29171eb507e"
},
"downloads": -1,
"filename": "gmail_attachment_dl-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "854c78139db15aa07dba27bc511c708e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19256,
"upload_time": "2025-08-12T06:23:53",
"upload_time_iso_8601": "2025-08-12T06:23:53.006174Z",
"url": "https://files.pythonhosted.org/packages/66/df/0ec533c338ebcbd9211abbc18d65e121e4d30689aea2df0303b3d1196ea9/gmail_attachment_dl-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ffc5eae4da5be167bfcb42340dd1bb7212d76f2a55db93a9c3dd0441ab607926",
"md5": "4e2ad0dfc65bcb5943eba366463294fd",
"sha256": "16331f4b1b70800c05c7c82b8e3896c2599dc0734f4bd48435726f949109c8de"
},
"downloads": -1,
"filename": "gmail_attachment_dl-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4e2ad0dfc65bcb5943eba366463294fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26803,
"upload_time": "2025-08-12T06:23:54",
"upload_time_iso_8601": "2025-08-12T06:23:54.161506Z",
"url": "https://files.pythonhosted.org/packages/ff/c5/eae4da5be167bfcb42340dd1bb7212d76f2a55db93a9c3dd0441ab607926/gmail_attachment_dl-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 06:23:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kakehashi-inc",
"github_project": "gmail-attachment-dl",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gmail-attachment-dl"
}
