email.headerregistry：カスタムヘッダーオブジェクト—Pythonドキュメント

提供：Dev Guides
< PythonPython/docs/3.8/library/email.headerregistry
移動先:案内、検索

email.headerregistry ：カスタムヘッダーオブジェクト

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


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


ヘッダーは、 str のカスタマイズされたサブクラスで表されます。 特定のヘッダーを表すために使用される特定のクラスは、ヘッダーの作成時に有効な policy の header_factory によって決定されます。 このセクションでは、 RFC 5322 準拠の電子メールメッセージを処理するために電子メールパッケージによって実装される特定のheader_factoryについて説明します。アプリケーションが独自のカスタムヘッダータイプを追加するための拡張メカニズムを提供します。

EmailPolicy から派生したポリシーオブジェクトのいずれかを使用する場合、すべてのヘッダーは HeaderRegistry によって生成され、最後の基本クラスとして BaseHeader を持ちます。 各ヘッダークラスには、ヘッダーのタイプによって決定される追加の基本クラスがあります。 たとえば、多くのヘッダーには、他の基本クラスとしてクラス UnstructuredHeader があります。 ヘッダーの特殊な2番目のクラスは、 HeaderRegistry に格納されているルックアップテーブルを使用して、ヘッダーの名前によって決定されます。 これらはすべて、一般的なアプリケーションプログラムに対して透過的に管理されますが、より複雑なアプリケーションで使用するためにデフォルトの動作を変更するためのインターフェイスが提供されています。

以下のセクションでは、最初にヘッダーの基本クラスとその属性について説明し、次に HeaderRegistry の動作を変更するためのAPIについて説明し、最後に構造化ヘッダーから解析されたデータを表すために使用されるサポートクラスについて説明します。

class email.headerregistry.BaseHeader(name, value)

name および value は、 header_factory 呼び出しからBaseHeaderに渡されます。 ヘッダーオブジェクトの文字列値は、Unicodeに完全にデコードされた value です。

この基本クラスは、次の読み取り専用プロパティを定義します。

name

ヘッダーの名前（「：」の前のフィールドの部分）。 これは、[X43X] name の header_factory 呼び出しで渡された値とまったく同じです。 つまり、大文字と小文字は区別されます。

defects

解析中に見つかったRFCコンプライアンスの問題を報告するHeaderDefectインスタンスのタプル。 電子メールパッケージは、コンプライアンスの問題の検出について完全にしようとします。 報告される可能性のある欠陥の種類については、エラーモジュールを参照してください。

max_count

同じnameを持つことができるこのタイプのヘッダーの最大数。 Noneの値は、無制限を意味します。 この属性のBaseHeader値はNoneです。 特殊なヘッダークラスが必要に応じてこの値をオーバーライドすることが期待されます。

BaseHeaderは、次のメソッドも提供します。これは、電子メールライブラリコードによって呼び出され、通常はアプリケーションプログラムによって呼び出されるべきではありません。

fold(*, policy)

ポリシーに従ってヘッダーを正しく折りたたむために、必要に応じて linesep 文字を含む文字列を返します。 8bitの cte_type は、ヘッダーに任意のバイナリデータが含まれていない可能性があるため、7bitであるかのように扱われます。 utf8 がFalseの場合、非ASCIIデータは RFC 2047 でエンコードされます。

BaseHeader自体を使用して、ヘッダーオブジェクトを作成することはできません。 これは、ヘッダーオブジェクトを生成するために各特殊ヘッダーが連携するプロトコルを定義します。 具体的には、BaseHeaderでは、特殊クラスがparseという名前の classmethod（）を提供する必要があります。 このメソッドは次のように呼び出されます。

parse(string, kwds)

kwdsは、事前に初期化された1つのキーdefectsを含む辞書です。 defectsは空のリストです。 parseメソッドは、検出された欠陥をこのリストに追加する必要があります。 戻ったとき、kwdsディクショナリ must には、少なくともキーdecodedおよびdefectsの値が含まれている必要があります。 decodedは、ヘッダーの文字列値（つまり、Unicodeに完全にデコードされたヘッダー値）である必要があります。 parseメソッドは、 string にコンテンツ転送でエンコードされた部分が含まれている可能性があると想定する必要がありますが、エンコードされていないヘッダー値を解析できるように、すべての有効なUnicode文字も正しく処理する必要があります。

次に、BaseHeaderの__new__はヘッダーインスタンスを作成し、そのinitメソッドを呼び出します。 特殊クラスは、BaseHeader自体によって提供される属性以外の追加の属性を設定する場合にのみ、initメソッドを提供する必要があります。 このようなinitメソッドは次のようになります。

def init(self, /, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)

つまり、特殊クラスがkwdsディクショナリに追加したものはすべて削除して処理し、kw（およびargs）の残りの内容を[ X188X] initメソッド。

class email.headerregistry.UnstructuredHeader

「非構造化」ヘッダーは、 RFC 5322 のデフォルトタイプのヘッダーです。 指定された構文を持たないヘッダーは、非構造化として扱われます。 非構造化ヘッダーの典型的な例は、 Subject ヘッダーです。

RFC 5322 では、非構造化ヘッダーはASCII文字セット内の任意のテキストの実行です。 ただし、 RFC 2047 には、ヘッダー値内で非ASCIIテキストをASCII文字としてエンコードするための RFC 5322 互換メカニズムがあります。 エンコードされた単語を含む value がコンストラクターに渡されると、UnstructuredHeaderパーサーは、 RFC 2047 の規則に従って、そのようなエンコードされた単語をUnicodeに変換します。構造化されていないテキストの場合。 パーサーはヒューリスティックを使用して、特定の非準拠のエンコードされた単語のデコードを試みます。 このような場合に欠陥が登録され、エンコードされた単語内の無効な文字やエンコードされていないテキストなどの問題の欠陥も登録されます。

このヘッダータイプは、追加の属性を提供しません。

class email.headerregistry.DateHeader

RFC 5322 は、電子メールヘッダー内の日付の非常に特殊な形式を指定します。 DateHeaderパーサーは、その日付形式を認識し、「実際に」見られることがあるいくつかのバリアント形式を認識します。

このヘッダータイプは、次の追加属性を提供します。

datetime

ヘッダー値が何らかの形式の有効な日付として認識できる場合、この属性には、その日付を表す datetime インスタンスが含まれます。 入力日付のタイムゾーンが-0000として指定されている場合（UTCであるが、ソースタイムゾーンに関する情報が含まれていないことを示します）、 datetime は単純な datetime になります。 ]。 特定のタイムゾーンオフセットが見つかった場合（ +0000 を含む）、 datetime には、 datetime.timezone を使用して記録する認識可能なdatetimeが含まれます。タイムゾーンオフセット。

ヘッダーのdecoded値は、 RFC 5322 ルールに従ってdatetimeをフォーマットすることによって決定されます。 つまり、次のように設定されます。

email.utils.format_datetime(self.datetime)

DateHeaderを作成する場合、 value は datetime インスタンスである可能性があります。 これは、たとえば、次のコードが有効であり、期待どおりの動作をすることを意味します。

msg['Date'] = datetime(2011, 7, 15, 21)

これはナイーブなdatetimeであるため、UTCタイムスタンプとして解釈され、結果の値のタイムゾーンは-0000になります。 さらに便利なのは、 utils モジュールの localtime（）関数を使用することです。

msg['Date'] = utils.localtime()

この例では、現在のタイムゾーンオフセットを使用して、日付ヘッダーを現在の時刻と日付に設定します。

class email.headerregistry.AddressHeader

アドレスヘッダーは、最も複雑な構造化ヘッダータイプの1つです。 AddressHeaderクラスは、任意のアドレスヘッダーへの汎用インターフェイスを提供します。

このヘッダータイプは、次の追加属性を提供します。

groups

ヘッダー値で見つかったアドレスとグループをエンコードする Group オブジェクトのタプル。 グループの一部ではないアドレスは、このリストでは、 display_name がNoneである単一アドレスGroupsとして表されます。

addresses

ヘッダー値からの個々のアドレスのすべてをエンコードする Address オブジェクトのタプル。 ヘッダー値にグループが含まれている場合、グループの個々のアドレスは、値内でグループが発生するポイントでリストに含まれます（つまり、アドレスのリストは1次元リストに「フラット化」されます）。

ヘッダーのdecoded値では、エンコードされたすべての単語がUnicodeにデコードされます。 idna でエンコードされたドメイン名もUnicodeにデコードされます。 decoded値は、groups属性の要素の str 値を', 'と結合することによって設定されます。

Address オブジェクトと Group オブジェクトの任意の組み合わせのリストを使用して、アドレスヘッダーの値を設定できます。 display_nameがNoneであるGroupオブジェクトは、単一のアドレスとして解釈されます。これにより、 [から取得したリストを使用して、アドレスリストをグループのままコピーできます。 X189X]ソースヘッダーの属性。

class email.headerregistry.SingleAddressHeader
AddressHeader のサブクラスで、次の1つの属性が追加されます。
address
ヘッダー値によってエンコードされた単一のアドレス。 ヘッダー値に実際に複数のアドレスが含まれている場合（デフォルトのポリシーではRFCに違反します）、この属性にアクセスすると ValueError になります。

上記のクラスの多くには、Uniqueバリアント（たとえば、UniqueUnstructuredHeader）もあります。 唯一の違いは、Uniqueバリアントでは、 max_count が1に設定されていることです。

class email.headerregistry.MIMEVersionHeader

MIME-Version ヘッダーの有効な値は、実際には1.0の1つだけです。 将来の校正のために、このヘッダークラスは他の有効なバージョン番号をサポートします。 バージョン番号が RFC 2045 ごとに有効な値を持っている場合、ヘッダーオブジェクトは次の属性に対してNone以外の値を持ちます。

version

空白やコメントが削除された、文字列としてのバージョン番号。

major

整数としてのメジャーバージョン番号

minor

整数としてのマイナーバージョン番号

class email.headerregistry.ParameterizedMIMEHeader
MIMEヘッダーはすべて、プレフィックス「Content-」で始まります。 特定の各ヘッダーには特定の値があり、そのヘッダーのクラスの下に記述されています。 いくつかはまた、共通のフォーマットを持つ補足パラメータのリストを取ることができます。 このクラスは、パラメーターを受け取るすべてのMIMEヘッダーのベースとして機能します。
params
パラメータ名をパラメータ値にマッピングする辞書。
class email.headerregistry.ContentTypeHeader

Content-Type ヘッダーを処理する ParameterizedMIMEHeader クラス。

content_type

maintype/subtypeの形式のコンテンツタイプ文字列。

maintype
subtype
class email.headerregistry.ContentDispositionHeader
Content-Disposition ヘッダーを処理する ParameterizedMIMEHeader クラス。
content_disposition
inlineとattachmentは、一般的に使用されている唯一の有効な値です。
class email.headerregistry.ContentTransferEncoding
Content-Transfer-Encoding ヘッダーを処理します。
cte
有効な値は、7bit、8bit、base64、およびquoted-printableです。 詳細については、 RFC 2045 を参照してください。
class email.headerregistry.HeaderRegistry(base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)

これは、 EmailPolicy がデフォルトで使用するファクトリです。 HeaderRegistryは、 base_class と、それが保持するレジストリから取得した特殊なクラスを使用して、ヘッダーインスタンスを動的に作成するために使用されるクラスを構築します。 指定されたヘッダー名がレジストリに表示されない場合、 default_class で指定されたクラスが特殊クラスとして使用されます。 use_default_map がTrue（デフォルト）の場合、ヘッダー名のクラスへの標準マッピングは、初期化中にレジストリにコピーされます。 base_class は常に、生成されたクラスの__bases__リストの最後のクラスです。

デフォルトのマッピングは次のとおりです。

主題

UniqueUnstructuredHeader

日にち

UniqueDateHeader

再送日

DateHeader

元の日付

UniqueDateHeader

送信者

UniqueSingleAddressHeader

再送-送信者

SingleAddressHeader

に

UniqueAddressHeader

憤慨-

AddressHeader

cc

UniqueAddressHeader

resent-cc

AddressHeader

bcc

UniqueAddressHeader

resent-bcc

AddressHeader

から

UniqueAddressHeader

憤慨-から

AddressHeader

に返信

UniqueAddressHeader

mimeバージョン

MIMEVersionHeader

コンテンツタイプ

ContentTypeHeader

コンテンツ処理

ContentDispositionHeader

content-transfer-encoding

ContentTransferEncodingHeader

メッセージID

MessageIDHeader


HeaderRegistryには次のメソッドがあります。

map_to_type(self, name, cls)

name は、マップされるヘッダーの名前です。 レジストリでは小文字に変換されます。 cls は、 base_class とともに、 name に一致するヘッダーをインスタンス化するために使用されるクラスを作成するために使用される特殊なクラスです。

__getitem__(name)

name ヘッダーの作成を処理するクラスを作成して返します。

__call__(name, value)

name に関連付けられた特殊なヘッダーをレジストリから取得し（ name がレジストリに表示されない場合は default_class を使用）、 base_class で構成します。 ]クラスを生成するには、構築されたクラスのコンストラクターを呼び出し、同じ引数リストを渡し、最後にそれによって作成されたクラスインスタンスを返します。

次のクラスは、構造化ヘッダーから解析されたデータを表すために使用されるクラスであり、通常、アプリケーションプログラムで使用して、特定のヘッダーに割り当てる構造化値を作成できます。

class email.headerregistry.Address(display_name=, username=, domain=, addr_spec=None)

電子メールアドレスを表すために使用されるクラス。 アドレスの一般的な形式は次のとおりです。

[display_name] <username@domain>

また：

username@domain

ここで、各部分は、 RFC 5322 で説明されている特定の構文規則に準拠する必要があります。

便宜上、 username および domain の代わりに、 addr_spec を指定できます。この場合、 username および domain は指定されます。 addr_spec から解析されます。 addr_spec は、適切にRFCで引用された文字列である必要があります。 Addressでない場合、エラーが発生します。 Unicode文字は許可されており、シリアル化されるとプロパティでエンコードされます。 ただし、RFCによると、アドレスのユーザー名部分でのUnicodeの使用は許可されていません。

display_name

アドレスの表示名の部分（ある場合）。すべての引用符が削除されています。 アドレスに表示名がない場合、この属性は空の文字列になります。

username

アドレスのusername部分、すべての引用符が削除されています。

domain

アドレスのdomain部分。

addr_spec

アドレスのusername@domain部分。裸のアドレスとして使用するために正しく引用されています（上記の2番目の形式）。 この属性は変更できません。

__str__()

オブジェクトのstr値は、 RFC 5322 規則に従って引用されたアドレスですが、非ASCII文字のコンテンツ転送エンコーディングはありません。

SMTP（ RFC 5321 ）をサポートするために、Addressは1つの特殊なケースを処理します。usernameとdomainが両方とも空の文字列である場合（またはNone）の場合、Addressの文字列値は<>になります。

class email.headerregistry.Group(display_name=None, addresses=None)

アドレスグループを表すために使用されるクラス。 アドレスグループの一般的な形式は次のとおりです。

display_name: [address-list];

グループと単一アドレスの混合で構成されるアドレスのリストを処理するための便宜のために、Groupを使用して、 display_name を設定することにより、グループの一部ではない単一アドレスを表すこともできます。 Noneに移動し、単一アドレスのリストをアドレスとして提供します。

display_name

グループのdisplay_name。 それがNoneであり、addressesにAddressが1つしかない場合、Groupはグループにない単一のアドレスを表します。

addresses

グループ内のアドレスを表す Address オブジェクトの空の可能性のあるタプル。

__str__()

Groupのstr値は、 RFC 5322 に従ってフォーマットされますが、非ASCII文字のコンテンツ転送エンコーディングはありません。 display_nameがなしで、addressesリストにAddressが1つある場合、strの値はstrと同じになります。そのシングルAddressの。

脚注

1
もともとは3.3で暫定モジュールとして追加されました



「https://www.finddevguides.com/index.php?title=Python/docs/3.8/library/email.headerregistry&oldid=99054」から取得
Powered by MediaWiki