gmail-oauth-client

gmail-oauth-client は、Pythonで Gmail API を利用してメールを送信するためのシンプルなラッパーライブラリです。 複雑な OAuth2 認証フローや MIME 形式の構築を意識することなく、数行のコードでメール送信機能を実装できます。

✨ 特徴

• OAuth2 対応: 安全な認証方式（client_secret.json & token.json）を採用。
• 非同期 (Async) 対応: asyncio をサポートし、FastAPI などのモダンなフレームワークでブロッキングなしに利用可能。
• 自動リトライ: レート制限 (429) や一時的なサーバーエラー (5xx) に対する指数関数的バックオフによるリトライ機能を内蔵。
• ヘッドレス環境対応: サーバーや Docker 環境向けに、ローカルでトークンを生成する CLI ツールを同梱。
• リッチなメール作成: HTML / テキスト / 添付ファイル / CC / BCC に完全対応。
• 型ヒント対応: IDE での補完が効きます。

📋 要件

• Python 3.9 以上

📦 インストール

リポジトリから直接インストール

pip install git+https://github.com/hirokobayashi/gmail-oauth-client.git

ローカル開発環境でのインストール

git clone https://github.com/hirokobayashi/gmail-oauth-client.git
cd gmail-oauth-client
pip install .

🚀 セットアップ手順

1. Google Cloud での準備

1. Google Cloud Console にアクセスし、プロジェクトを作成します。
2. 「API とサービス」 > 「ライブラリ」 から Gmail API を有効化します。
3. 「OAuth 同意画面」 を設定します（テスト用なら "External" で自分をテストユーザーに追加）。
4. 「認証情報」 > 「認証情報を作成」 > 「OAuth クライアント ID」 を選択します。
   • アプリケーションの種類: デスクトップ アプリ
5. 作成後、JSON ファイルをダウンロードし、client_secret.json という名前で保存します。

2. 認証トークンの生成 (CLIツール)

サーバーなどのブラウザが使えない環境で動かすために、手元の PC で認証トークン (token.json) を生成します。

# client_secret.json がある場所で実行
gmail-auth --secret client_secret.json

ブラウザが立ち上がるので、Google アカウントでログインし、権限を許可してください。 成功すると、カレントディレクトリに token.json が生成されます。

Note: 本番環境（サーバー）には、この token.json と client_secret.json をアップロードして使用します。

💻 使い方

同期クライアント (Sync)

通常のスクリプトやバッチ処理向けです。一時的なエラー（429, 5xx）が発生した場合、自動的にリトライを行います。

from gmail_oauth_client import GmailAuthenticator, GmailClient

# 1. 認証
auth = GmailAuthenticator(
    client_secret_path="client_secret.json",
    token_path="token.json"
)
# interactive=False はサーバー環境での誤ったブラウザ起動を防ぎます
service = auth.get_service(interactive=False)

# 2. クライアントの初期化
client = GmailClient(service=service, default_sender="me")

# 3. メールの送信
try:
    response = client.send_email(
        to_email="recipient@example.com",
        subject="こんにちは",
        body="これはPythonからのテストメールです。",
        attachments=["./report.pdf"]
    )
    print(f"送信成功: {response['id']}")
except Exception as e:
    print(f"エラー: {e}")

非同期クライアント (Async)

FastAPI や Discord Bot など、イベントループをブロックしたくない環境向けです。

import asyncio
from gmail_oauth_client import GmailAuthenticator, AsyncGmailClient

async def main():
    auth = GmailAuthenticator("client_secret.json", "token.json")
    service = auth.get_service(interactive=False)
    
    # 非同期クライアントを使用
    client = AsyncGmailClient(service=service)

    # await で送信（裏側でスレッドプールを使って実行されます）
    response = await client.send_email(
        to_email="user@example.com",
        subject="非同期テスト",
        body="メインスレッドをブロックしません。"
    )
    print(f"送信成功: {response['id']}")

if __name__ == "__main__":
    asyncio.run(main())

⚠️ エラーハンドリング

このライブラリは以下のカスタム例外を提供しています。

from gmail_oauth_client import (
    GmailClientError,       # ベース例外
    GmailAuthError,         # 認証トークン切れ、ファイル不備など
    GmailSendError,         # API送信エラー（リトライ上限到達後）
    InvalidAttachmentError  # 添付ファイルが見つからない、読めないなど
)

リトライについて: GmailClient および AsyncGmailClient は、API レート制限 (429) やサーバーエラー (5xx) に対して自動的に指数関数バックオフを用いたリトライを行います（最大3回）。 それでも失敗した場合に GmailSendError (または HttpError) が送出されます。

🛠 開発者向け (Development)

テストの実行

pytest を使用してユニットテストを実行できます。非同期テストのために pytest-asyncio が必要です。

# 依存関係のインストール
pip install -e .[dev]
pip install pytest pytest-asyncio mock

# テスト実行
pytest

📝 ライセンス

MIT License