email.policy ：ポリシーオブジェクト

バージョン3.3の新機能。

ソースコード： ：source： `Lib / email / policy.py`

email パッケージの主な焦点は、さまざまな電子メールおよびMIMERFCで説明されている電子メールメッセージの処理です。ただし、電子メールメッセージの一般的な形式（名前、コロン、値、ブロック全体、空白行、任意の「本文」で構成されるヘッダーフィールドのブロック）は、次のような形式です。電子メールの領域外のユーティリティ。これらの使用法のいくつかは、主要な電子メールRFCにかなり厳密に準拠していますが、準拠していないものもあります。電子メールを使用する場合でも、RFCの厳密な準拠を破ることが望ましい場合があります。たとえば、それ自体が標準に準拠していない電子メールサーバーと相互運用する電子メールを生成したり、違反する方法で使用する拡張機能を実装したりします。標準。

ポリシーオブジェクトは、これらの異なるユースケースすべてを処理する柔軟性を電子メールパッケージに提供します。

Policy オブジェクトは、使用中の電子メールパッケージのさまざまなコンポーネントの動作を制御する一連の属性とメソッドをカプセル化します。 Policy インスタンスを電子メールパッケージのさまざまなクラスおよびメソッドに渡して、デフォルトの動作を変更できます。設定可能な値とそのデフォルトについて以下に説明します。

電子メールパッケージのすべてのクラスで使用されるデフォルトのポリシーがあります。すべての parser クラスと関連する便利な関数、および Message クラスの場合、これは Compat32 ポリシーであり、対応する事前定義されたインスタンス[ X195X] compat32 。このポリシーは、Python3.3より前のバージョンの電子メールパッケージとの完全な下位互換性（場合によってはバグ互換性を含む）を提供します。

EmailMessage に対する policy キーワードのこのデフォルト値は、事前定義されたインスタンス default を介した EmailPolicy ポリシーです。

Message または EmailMessage オブジェクトが作成されると、ポリシーを取得します。メッセージがパーサーによって作成された場合、パーサーに渡されるポリシーは、パーサーが作成するメッセージによって使用されるポリシーになります。メッセージがプログラムによって作成された場合、作成時にポリシーを指定できます。メッセージが generator に渡されると、ジェネレータはデフォルトでメッセージのポリシーを使用しますが、メッセージオブジェクトに保存されているポリシーを上書きする特定のポリシーをジェネレータに渡すこともできます。

email.parser クラスおよびパーサーコンビニエンス関数の policy キーワードのデフォルト値は、Pythonの将来のバージョンで変更される予定です。したがって、パーサーモジュールで説明されているクラスおよび関数を呼び出すときは、使用するポリシーを常に明示的に指定する必要があります。

このドキュメントの最初の部分では、 compat32 を含む、すべてのポリシーオブジェクトに共通の機能を定義する抽象基本クラスである Policy の機能について説明します。これには、電子メールパッケージによって内部的に呼び出される特定のフックメソッドが含まれます。これらのメソッドは、カスタムポリシーがオーバーライドして、さまざまな動作を取得できます。 2番目の部分では、具象クラス EmailPolicy と Compat32 について説明します。これらは、それぞれ標準動作と下位互換性のある動作と機能を提供するフックを実装します。

Policy インスタンスは不変ですが、クローンを作成して、クラスコンストラクターと同じキーワード引数を受け入れ、元のインスタンスのコピーであるが指定された属性を持つ新しい Policy インスタンスを返すことができます。値が変更されました。

例として、次のコードを使用して、ディスク上のファイルから電子メールメッセージを読み取り、Unixシステム上のシステムsendmailプログラムに渡すことができます。

>>> from email import message_from_binary_file
>>> from email.generator import BytesGenerator
>>> from email import policy
>>> from subprocess import Popen, PIPE
>>> with open('mymsg.txt', 'rb') as f:
...     msg = message_from_binary_file(f, policy=policy.default)
>>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)
>>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\r\n'))
>>> g.flatten(msg)
>>> p.stdin.close()
>>> rc = p.wait()

ここでは、 BytesGenerator に、sendmail's stdinにフィードするバイナリ文字列を作成するときに、RFCの正しい行区切り文字を使用するように指示しています。デフォルトのポリシーでは [ X198X]行区切り文字。

一部の電子メールパッケージメソッドは、 policy キーワード引数を受け入れ、そのメソッドのポリシーをオーバーライドできるようにします。たとえば、次のコードは、前の例の msg オブジェクトの as_bytes（）メソッドを使用し、メッセージを、そのプラットフォームのネイティブ行区切り記号を使用してファイルに書き込みます。が走っています：

>>> import os
>>> with open('converted.txt', 'wb') as f:
...     f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))
17

ポリシーオブジェクトは、加算演算子を使用して結合することもでき、その設定が、合計されたオブジェクトのデフォルト以外の値の組み合わせであるポリシーオブジェクトを生成します。

>>> compat_SMTP = policy.compat32.clone(linesep='\r\n')
>>> compat_strict = policy.compat32.clone(raise_on_defect=True)
>>> compat_strict_SMTP = compat_SMTP + compat_strict

この操作は可換ではありません。つまり、オブジェクトが追加される順序が重要です。説明する：

>>> policy100 = policy.compat32.clone(max_line_length=100)
>>> policy80 = policy.compat32.clone(max_line_length=80)
>>> apolicy = policy100 + policy80
>>> apolicy.max_line_length
80
>>> apolicy = policy80 + policy100
>>> apolicy.max_line_length
100

class email.policy.Policy(**kw)

これは、すべてのポリシークラスの抽象基本クラスです。これは、いくつかの簡単なメソッドのデフォルトの実装に加えて、不変性プロパティ、 clone（）メソッド、およびコンストラクターのセマンティクスの実装を提供します。

ポリシークラスのコンストラクターには、さまざまなキーワード引数を渡すことができます。指定できる引数は、このクラスの非メソッドプロパティと、具象クラスの追加の非メソッドプロパティです。コンストラクターで指定された値は、対応する属性のデフォルト値をオーバーライドします。

このクラスは次のプロパティを定義するため、次の値は任意のポリシークラスのコンストラクターに渡されます。

max_line_length: 行末文字を数えない、シリアル化された出力の任意の行の最大長。 RFC 5322 ごとに、デフォルトは78です。 0または None の値は、行の折り返しをまったく行わないことを示します。

linesep: シリアル化された出力の行を終了するために使用される文字列。デフォルトは\nです。これは、Pythonで使用される内部の行末の分野ですが、RFCでは\r\nが必要です。

cte_type

使用する必要がある、または使用する必要があるコンテンツ転送エンコーディングのタイプを制御します。可能な値は次のとおりです。

`7bit`	すべてのデータは「7ビットクリーン」（ASCIIのみ）である必要があります。これは、必要に応じて、quoted-printableまたはbase64エンコーディングを使用してデータがエンコードされることを意味します。
`8bit`	データは7ビットクリーンに制限されていません。ヘッダーのデータは引き続きASCIIのみである必要があるため、エンコードされます（例外については、以下の fold_binary（）および utf8 を参照）が、本体部分は [を使用できます。 X174X] CTE。

cte_typeの8bitの値は、BytesGeneratorでのみ機能し、Generatorでは機能しません。これは、文字列にバイナリデータを含めることができないためです。 Generatorがcte_type=8bitを指定するポリシーの下で動作している場合、cte_typeが7bitであるかのように動作します。

raise_on_defect: True の場合、発生した欠陥はすべてエラーとして発生します。 False （デフォルト）の場合、欠陥は register_defect（）メソッドに渡されます。

mangle_from_: True の場合、本文の「From」で始まる行は、その前に>を置くことでエスケープされます。このパラメーターは、メッセージがジェネレーターによってシリアル化されるときに使用されます。デフォルト： False 。

バージョン3.5の新機能： mangle_from_ パラメーター。

message_factory: 新しい空のメッセージオブジェクトを作成するためのファクトリ関数。メッセージを作成するときにパーサーによって使用されます。デフォルトはNoneです。この場合、メッセージが使用されます。

バージョン3.6の新機能。

次の Policy メソッドは、電子メールライブラリを使用してコードによって呼び出され、カスタム設定でポリシーインスタンスを作成することを目的としています。

clone(**kw): 属性が現在のインスタンスと同じ値を持つ新しい Policy インスタンスを返します。ただし、これらの属性にはキーワード引数によって新しい値が指定されます。

残りの Policy メソッドは、電子メールパッケージコードによって呼び出され、電子メールパッケージを使用するアプリケーションによって呼び出されることを意図していません。カスタムポリシーは、これらすべてのメソッドを実装する必要があります。

handle_defect(obj, defect)

obj で見つかった欠陥を処理します。電子メールパッケージがこのメソッドを呼び出すと、欠陥は常にDefectのサブクラスになります。

デフォルトの実装では、 raise_on_defect フラグがチェックされます。 Trueの場合、例外として欠陥が発生します。 False（デフォルト）の場合、 obj と defect が register_defect（）に渡されます。

register_defect(obj, defect)

欠陥を obj に登録します。電子メールパッケージでは、欠陥は常にDefectのサブクラスになります。

デフォルトの実装では、 obj のdefects属性のappendメソッドが呼び出されます。電子メールパッケージが handle_defect を呼び出す場合、 obj には通常、appendメソッドを持つdefects属性があります。電子メールパッケージで使用されるカスタムオブジェクトタイプ（たとえば、カスタムMessageオブジェクト）もそのような属性を提供する必要があります。そうしないと、解析されたメッセージの欠陥によって予期しないエラーが発生します。

header_max_count(name)

name という名前のヘッダーの最大許容数を返します。

EmailMessage または Message オブジェクトにヘッダーが追加されたときに呼び出されます。戻り値が0またはNoneでなく、 name という名前のヘッダーが、返された値以上の数になっている場合は、[X170X ] ValueError が発生します。

Message.__setitem__のデフォルトの動作は、ヘッダーのリストに値を追加することであるため、気付かないうちに重複するヘッダーを簡単に作成できます。このメソッドを使用すると、プログラムでMessageに追加できるヘッダーのインスタンス数を特定のヘッダーに制限できます。（制限はパーサーによって監視されません。パーサーは、解析されるメッセージに存在するのと同じ数のヘッダーを忠実に生成します。）

デフォルトの実装では、すべてのヘッダー名に対してNoneが返されます。

header_source_parse(sourcelines)

電子メールパッケージは、文字列のリストを使用してこのメソッドを呼び出します。各文字列は、解析されるソースで見つかった行区切り文字で終わります。最初の行には、フィールドヘッダー名と区切り文字が含まれています。ソース内のすべての空白が保持されます。このメソッドは、解析されたヘッダーを表すためにMessageに格納される(name, value)タプルを返す必要があります。

実装が既存の電子メールパッケージポリシーとの互換性を維持したい場合は、 name を大文字と小文字を区別して保持する名前（「:」区切り文字までのすべての文字）、 value [ X207X]は、展開された値（すべての行区切り文字は削除されますが、空白はそのまま保持されます）であり、先頭の空白が削除されている必要があります。

sourcelines には、サロゲートエスケープされたバイナリデータが含まれる場合があります。

デフォルトの実装はありません

header_store_parse(name, value)

電子メールパッケージは、アプリケーションプログラムがMessageをプログラムで変更するときに（パーサーによって作成されたMessageとは対照的に）、アプリケーションプログラムによって提供された名前と値を使用してこのメソッドを呼び出します。このメソッドは、ヘッダーを表すためにMessageに格納される(name, value)タプルを返す必要があります。

実装が既存の電子メールパッケージポリシーとの互換性を維持したい場合、 name および value は、渡された引数の内容を変更しない文字列または文字列サブクラスである必要があります。

デフォルトの実装はありません

header_fetch_parse(name, value)

電子メールパッケージは、そのヘッダーがアプリケーションプログラムによって要求されたときに、現在Messageに格納されている name および value を使用してこのメソッドを呼び出し、メソッドが返すものは何でも取得されるヘッダーの値としてアプリケーションに返されます。 Messageに同じ名前のヘッダーが複数保存されている場合があることに注意してください。メソッドには、アプリケーションに返される予定のヘッダーの特定の名前と値が渡されます。

value には、サロゲートエスケープされたバイナリデータが含まれる場合があります。メソッドによって返される値には、サロゲートエスケープされたバイナリデータがあってはなりません。

デフォルトの実装はありません

fold(name, value)

電子メールパッケージは、特定のヘッダーのMessageに現在格納されている name および value を使用してこのメソッドを呼び出します。このメソッドは、名前を値で構成し、 linesep 文字を挿入することにより、（ポリシー設定に従って）正しく「折りたたまれた」ヘッダーを表す文字列を返す必要があります。適切な場所で。電子メールヘッダーを折りたたむための規則の説明については、 RFC 5322 を参照してください。

value には、サロゲートエスケープされたバイナリデータが含まれる場合があります。メソッドによって返される文字列には、サロゲートエスケープされたバイナリデータがあってはなりません。

fold_binary(name, value)

fold（）と同じですが、戻り値が文字列ではなくバイトオブジェクトである必要がある点が異なります。

value には、サロゲートエスケープされたバイナリデータが含まれる場合があります。これらは、返されたバイトオブジェクトでバイナリデータに変換して戻すことができます。

class email.policy.EmailPolicy(**kw)

この具体的なポリシーは、現在の電子メールRFCに完全に準拠することを目的とした動作を提供します。これらには、 RFC 5322 、 RFC 2047 、および現在のMIME RFCが含まれます（ただし、これらに限定されません）。

このポリシーは、新しいヘッダー解析および折りたたみアルゴリズムを追加します。単純な文字列の代わりに、ヘッダーはフィールドのタイプに依存する属性を持つstrサブクラスです。解析および折りたたみアルゴリズムは、 RFC 2047 および RFC 5322 を完全に実装します。

message_factory 属性のデフォルト値は EmailMessage です。

すべてのポリシーに適用される上記の設定可能な属性に加えて、このポリシーは次の追加属性を追加します。

バージョン3.6の新機能： 1

utf8: Falseの場合は、 RFC 5322 に従い、ヘッダーで非ASCII文字を「エンコードされた単語」としてエンコードすることでサポートします。 Trueの場合は、 RFC 6532 に従い、ヘッダーにutf-8エンコーディングを使用します。この方法でフォーマットされたメッセージは、SMTPUTF8拡張機能（ RFC 6531 ）をサポートするSMTPサーバーに渡される場合があります。

refold_source

Messageオブジェクトのヘッダーの値が（プログラムによって設定されるのではなく）パーサーに由来する場合、この属性は、変換時にジェネレーターがその値をリフォールディングする必要があるかどうかを示します。メッセージをシリアル化された形式に戻します。可能な値は次のとおりです。

`none`	すべてのソース値は元の折りたたみを使用します
`long`	`max_line_length`より長い行を持つソース値はリフォールディングされます
`all`	すべての値がリフォールディングされます。

デフォルトはlongです。

header_factory: nameとvalueの2つの引数を取る呼び出し可能オブジェクト。ここで、nameはヘッダーフィールド名、valueは展開されたヘッダーフィールド値であり、そのヘッダーを表す文字列サブクラス。デフォルトのheader_factory（ headerregistry を参照）が提供され、さまざまなアドレスと日付 RFC 5322 ヘッダーフィールドタイプのカスタム解析をサポートします。主要なMIMEヘッダーフィールドのstype。追加のカスタム解析のサポートは、将来追加される予定です。

content_manager: get_contentとset_contentの少なくとも2つのメソッドを持つオブジェクト。 EmailMessage オブジェクトの get_content（）または set_content（）メソッドが呼び出されると、このオブジェクトの対応するメソッドが呼び出され、メッセージオブジェクトとして渡されます。その最初の引数、および追加の引数として渡された引数またはキーワード。デフォルトでは、content_managerは raw_data_manager に設定されています。

バージョン3.4の新機能。

このクラスは、 Policy の抽象メソッドの次の具体的な実装を提供します。

header_max_count(name): 指定された名前のヘッダーを表すために使用される特殊クラスの max_count 属性の値を返します。

header_source_parse(sourcelines): 名前は「:」までのすべてとして解析され、変更されずに返されます。値は、最初の行の残りの部分から先頭の空白を取り除き、後続のすべての行を結合し、末尾のキャリッジリターンまたはラインフィード文字を取り除くことによって決定されます。

header_store_parse(name, value): 名前は変更されずに返されます。入力値にname属性があり、大文字と小文字を区別せずに name と一致する場合、値は変更されずに返されます。それ以外の場合は、 name および value がheader_factoryに渡され、結果のヘッダーオブジェクトが値として返されます。この場合、入力値にCRまたはLF文字が含まれていると、ValueErrorが発生します。

header_fetch_parse(name, value): 値にname属性がある場合、変更されていない状態に戻されます。それ以外の場合は、 name 、およびCRまたはLF文字が削除された value がheader_factoryに渡され、結果のヘッダーオブジェクトが返されます。サロゲートエスケープされたバイトは、Unicodeの不明な文字のグリフに変換されます。

fold(name, value)

ヘッダーの折りたたみは、 refold_source ポリシー設定によって制御されます。値は、name属性がない場合にのみ「ソース値」と見なされます（name属性があるということは、ある種のヘッダーオブジェクトであることを意味します）。ポリシーに従ってソース値をリフォールディングする必要がある場合は、 name と value を、CR文字とLF文字を削除してheader_factory。ヘッダーオブジェクトの折りたたみは、現在のポリシーでfoldメソッドを呼び出すことによって行われます。

ソース値は、 splitlines（）を使用して行に分割されます。値を折りたたまない場合は、ポリシーのlinesepを使用して行が再結合され、返されます。例外は、ASCII以外のバイナリデータを含む行です。その場合、refold_source設定に関係なく値がリフォールディングされ、unknown-8bit文字セットを使用してバイナリデータがCTEエンコードされます。

fold_binary(name, value)

cte_type が7bitの場合、戻り値がバイトであることを除いて、 fold（）と同じです。

cte_type が8bitの場合、非ASCIIバイナリデータはバイトに変換されます。 refold_headerの設定に関係なく、バイナリデータがシングルバイト文字で構成されているかマルチバイト文字で構成されているかを知る方法がないため、バイナリデータを含むヘッダーはリフォールディングされません。

EmailPolicy の次のインスタンスは、特定のアプリケーションドメインに適したデフォルトを提供します。将来、これらのインスタンス（特に、HTTPインスタンス）の動作は、それらのドメインに関連するRFCにさらに厳密に準拠するように調整される可能性があることに注意してください。

email.policy.default: EmailPolicyのインスタンス。すべてのデフォルトは変更されていません。このポリシーは、RFCが正しい\r\nではなく、標準のPython \n行末を使用します。

email.policy.SMTP: 電子メールRFCに準拠したメッセージのシリアル化に適しています。 defaultと同様ですが、linesepが\r\nに設定されており、RFCに準拠しています。

email.policy.SMTPUTF8: utf8 がTrueであることを除いて、SMTPと同じです。ヘッダーでエンコードされた単語を使用せずにメッセージをメッセージストアにシリアル化する場合に便利です。送信者または受信者のアドレスに非ASCII文字が含まれている場合にのみSMTP送信に使用する必要があります（ smtplib.SMTP.send_message（）メソッドはこれを自動的に処理します）。

email.policy.HTTP: HTTPトラフィックで使用するためにヘッダーをシリアル化するのに適しています。 max_line_lengthがNone（無制限）に設定されていることを除いて、SMTPと同様です。

email.policy.strict

コンビニエンスインスタンス。 raise_on_defectがTrueに設定されていることを除いて、defaultと同じです。これにより、次のように記述して、ポリシーを厳密にすることができます。

somepolicy + policy.strict

これらすべての EmailPolicies を使用すると、電子メールパッケージの有効なAPIがPython 3.2APIから次のように変更されます。

メッセージにヘッダーを設定すると、そのヘッダーが解析され、ヘッダーオブジェクトが作成されます。

メッセージからヘッダー値をフェッチすると、そのヘッダーが解析され、ヘッダーオブジェクトが作成されて返されます。

ヘッダーオブジェクト、またはポリシー設定のために再折り畳まれたヘッダーは、エンコードされた単語が必要で許可されている場所を知ることを含め、RFC折り畳みアルゴリズムを完全に実装するアルゴリズムを使用して折り畳まれます。

アプリケーションビューから見ると、これは、 EmailMessage を介して取得されたヘッダーが、追加の属性を持つヘッダーオブジェクトであり、その文字列値がヘッダーの完全にデコードされたUnicode値であることを意味します。同様に、Unicode文字列を使用して、ヘッダーに新しい値を割り当てるか、新しいヘッダーを作成することができます。ポリシーは、Unicode文字列を正しいRFCエンコード形式に変換します。

ヘッダーオブジェクトとその属性については、 headerregistry で説明されています。

class email.policy.Compat32(**kw)

この具体的なポリシーは、下位互換性ポリシーです。 Python3.2の電子メールパッケージの動作を複製します。 policy モジュールは、このクラスのインスタンス compat32 も定義します。これは、デフォルトのポリシーとして使用されます。したがって、電子メールパッケージのデフォルトの動作は、Python3.2との互換性を維持することです。

次の属性の値は、ポリシーのデフォルトとは異なります。

mangle_from_: デフォルトはTrueです。

このクラスは、 Policy の抽象メソッドの次の具体的な実装を提供します。

header_source_parse(sourcelines): 名前は「:」までのすべてとして解析され、変更されずに返されます。値は、最初の行の残りの部分から先頭の空白を取り除き、後続のすべての行を結合し、末尾のキャリッジリターンまたはラインフィード文字を取り除くことによって決定されます。

header_store_parse(name, value): 名前と値は変更されずに返されます。

header_fetch_parse(name, value): 値にバイナリデータが含まれている場合は、unknown-8bit文字セットを使用して Header オブジェクトに変換されます。それ以外の場合は、変更せずに返されます。

fold(name, value): ヘッダーは、 Header 折りたたみアルゴリズムを使用して折りたたまれます。このアルゴリズムは、値の既存の改行を保持し、結果の各行をmax_line_lengthに折り返します。非ASCIIバイナリデータは、unknown-8bit文字セットを使用してCTEエンコードされます。

fold_binary(name, value): ヘッダーは、 Header 折りたたみアルゴリズムを使用して折りたたまれます。このアルゴリズムは、値の既存の改行を保持し、結果の各行をmax_line_lengthに折り返します。 cte_typeが7bitの場合、非ASCIIバイナリデータはunknown-8bit文字セットを使用してCTEエンコードされます。それ以外の場合は、元のソースヘッダーが使用され、既存の改行とそれに含まれる可能性のある（RFC無効な）バイナリデータが含まれます。

email.policy.compat32: Compat32 のインスタンスであり、Python3.2の電子メールパッケージの動作との下位互換性を提供します。

脚注

1: もともとは3.3で暫定機能として追加されました。

email.policy：ポリシーオブジェクト—Pythonドキュメント

email.policy ：ポリシーオブジェクト