"mailcap" --- mailcap ファイルの操作
************************************

**ソースコード:** Lib/mailcap.py

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The "mailcap"
module is deprecated (see **PEP 594** for details). The "mimetypes"
module provides an alternative.

======================================================================

mailcap ファイルは、メールリーダやウェブブラウザのような MIME 対応のア
プリケーションが、異なる MIME タイプのファイルにどのように反応するかを
設定するために使われます ("mailcap" の名前は "mail capability" から取
られました)。例えば、ある mailcap ファイルに "video/mpeg; xmpeg %s" の
ような行が入っていたとします。ユーザが email メッセージやウェブドキュ
メント上でその MIME タイプ *video/mpeg* に遭遇すると、 "%s" はファイル
名 (通常テンポラリファイルに属するものになります) に置き換えられ、ファ
イルを閲覧するために**xmpeg** プログラムが自動的に起動されます。

mailcap の形式は **RFC 1524**, "A User Agent Configuration Mechanism
For Multimedia Mail Format Information" で文書化されていますが、この文
書はインターネット標準ではありません。しかしながら、 mailcap ファイル
はほとんどの Unix システムでサポートされています。

mailcap.findmatch(caps, MIMEtype, key='view', filename='/dev/null', plist=[])

   2 要素のタプルを返します; 最初の要素は文字列で、実行すべきコマンド
   ("os.system()" に渡されます) が入っています。二つめの要素は与えられ
   た MIME タイプに対する mailcap エントリです。一致する MIME タイプが
   見つからなかった場合、 "(None, None)" が返されます。

   *key* は desired フィールドの値で、実行すべき動作のタイプを表現しま
   す; ほとんどの場合、単に MIME 形式のデータ本体を見たいと思うので、
   標準の値は 'view' になっています。与えられた MIME 型をもつ新たなデ
   ータ本体を作成した場合や、既存のデータ本体を置き換えたい場合には、
   'view' の他に 'compose' および 'edit' を取ることもできます。これら
   フィールドの完全なリストについては **RFC 1524** を参照してください
   。

   *filename* はコマンドライン中で "%s" に代入されるファイル名です; 標
   準の値は "'/dev/null'" で、たいていこの値を使いたいわけではないはず
   です。従って、ファイル名を指定してこのフィールドを上書きする必要が
   あるでしょう。

   *plist* は名前付けされたパラメタのリストです; 標準の値は単なる空の
   リストです。リスト中の各エントリはパラメタ名を含む文字列、等号
   ("'='")、およびパラメタの値でなければなりません。mailcap エントリに
   は "%{foo}" といったような名前つきのパラメタを含めることができ、
   'foo' と名づけられたパラメタの値に置き換えられます。例えば、コマン
   ドライン "showpartial %{id} %{number} %{total}" が mailcap ファイル
   にあり、*plist* が "['id=1', 'number=2', 'total=3']" に設定されてい
   れば、コマンドラインは "'showpartial 1 2 3'" になります。

   mailcap ファイル中では、オプションの "test" フィールドを使って、(計
   算機アーキテクチャや、利用しているウィンドウシステムといった) 何ら
   かの外部条件をテストするよう指定することができます。 "findmatch()"
   はこれらの条件を自動的にチェックし、チェックが失敗したエントリを読
   み飛ばします。

   バージョン 3.11 で変更: To prevent security issues with shell
   metacharacters (symbols that have special effects in a shell
   command line), "findmatch" will refuse to inject ASCII characters
   other than alphanumerics and "@+=:,./-_" into the returned command
   line.If a disallowed character appears in *filename*, "findmatch"
   will always return "(None, None)" as if no entry was found. If such
   a character appears elsewhere (a value in *plist* or in
   *MIMEtype*), "findmatch" will ignore all mailcap entries which use
   that value. A "warning" will be raised in either case.

mailcap.getcaps()

   MIME タイプを mailcap ファイルのエントリに対応付ける辞書を返します
   。この辞書は "findmatch()" 関数に渡されるべきものです。エントリは辞
   書のリストとして記憶されますが、この表現形式の詳細について知ってお
   く必要はないでしょう。

   mailcap 情報はシステム上で見つかった全ての mailcap ファイルから導出
   されます。ユーザ設定の mailcap ファイル "$HOME/.mailcap" はシステム
   の mailcap ファイル "/etc/mailcap" 、 "/usr/etc/mailcap" 、および
   "/usr/local/etc/mailcap" の内容を上書きします。

以下に使用例を示します:

   >>> import mailcap
   >>> d = mailcap.getcaps()
   >>> mailcap.findmatch(d, 'video/mpeg', filename='tmp1223')
   ('xmpeg tmp1223', {'view': 'xmpeg %s'})
