メインコンテンツへスキップ
Jmail Jmail の Python クライアントは、単一ファイルでインストール不要です。PEP 723 のインライン依存関係を利用しており、uv run がすべてを自動的に処理します。

​
セットアップ

インストールは不要です。uv で実行するだけでOKです。 
uv run clients/python/jmail.py emails --head 5
または、自分のスクリプトでライブラリとして利用できます: 
from jmail import JmailClient

client = JmailClient()
df = client.emails()

​
ライブラリの使用方法

​
基本的な使い方

from jmail import JmailClient

client = JmailClient()

# All emails with full body text
df = client.emails()

# Network-only (no body text, much smaller download)
df = client.emails(slim=True)

# 抽出された全文を含むドキュメント(シャードファイルをダウンロード)
docs = client.documents(include_text=True)

# Photos, people, and facial recognition data
photos = client.photos()
people = client.people()
faces = client.photo_faces()

# iMessage conversations and messages
convos = client.imessage_conversations()
messages = client.imessage_messages()

# Crowd-sourced star counts
stars = client.star_counts()

# Release batch metadata
batches = client.release_batches()

​
生のURLを取得する

DuckDB、Polars、その他のツールで使用する場合: 
url = client.url("emails-slim")
# → "https://data.jmail.world/v1/emails-slim.parquet"

url = client.url("emails-slim", fmt="ndjson.gz")
# → "https://data.jmail.world/v1/emails-slim.ndjson.gz"

​
キャッシュの無効化

# 常に最新データをダウンロード（ローカルキャッシュなし）
client = JmailClient(cache=False)

​
コマンドラインインターフェイス リファレンス

Usage: uv run jmail.py <command> [options]

Commands:
  manifest          Print manifest JSON
  emails            Download emails (--slim for network-only, --head N)
  documents         Download documents (--include-text for full text, --head N)
  photos            Download photos metadata (--head N)
  people            Download people (--head N)
  photo_faces       Download photo face data (--head N)
  imessage_conversations  Download iMessage conversations (--head N)
  imessage_messages       Download iMessage messages (--head N)
  star_counts       Download star counts (--head N)
  release_batches   Download release batches (--head N)
  urls              Print all dataset URLs
  duckdb-examples   Print example DuckDB SQL queries

Options:
  --head N          Show first N rows
  --slim            (emails) Omit body text columns
  --include-text    (documents) Include full extracted text
  --no-cache        Skip local caching, always download fresh

​
使用例

# 最初の10件のメール、本文なし（ネットワーク情報のみ）
uv run jmail.py emails --slim --head 10

# All documents with full text
uv run jmail.py documents --include-text

# Print dataset URLs for use elsewhere
uv run jmail.py urls

# Get manifest with dataset checksums
uv run jmail.py manifest

# Fresh download (skip cache)
uv run jmail.py emails --no-cache --head 5

​
依存関係

クライアントには 3 つの依存関係があり、uv によって自動的に管理されます:
  • pandas — DataFrame の処理
  • pyarrow — Parquet ファイルの読み取り
  • requests — HTTP ダウンロード
これらは PEP 723 に従い、インラインで宣言されています: 
# /// script
# requires-python = ">=3.9"
# dependencies = ["pandas", "pyarrow", "requests"]
# ///