# `email.headerregistry`: Custom Header Objects

ソースコード: Lib/email/headerregistry.py

Added in version 3.6: [1]

ヘッダーは `str` のカスタマイズされたサブクラスで表現されます。 与えられたヘッダーを表現するために使用される特定のクラスは、ヘッダーが作成されるときに有効な `policy` の `header_factory` で決定されます。 このセクションでは、email ライブラリが RFC 5322 に準拠したメールメッセージを扱うために実装している、特定の `header_factory` について説明します。このヘッダーは、様々なヘッダータイプに対してカスタマイズされたヘッダーオブジェクトを提供するだけでなく、アプリケーションが独自のカスタムヘッダータイプを追加できるような拡張メカニズムも備えています。

`EmailPolicy` から派生したポリシーオブジェクトのいずれかを使用する場合、すべてのヘッダーは `HeaderRegistry` によって生成され、最終的な基底クラスとして `BaseHeader` を有します。 各ヘッダクラスには、ヘッダの種類によって決まる追加のベースクラスがあります。 例えば、多くのヘッダーは `UnstructuredHeader` というクラスをもうひとつの基底クラスとして持っています。 ヘッダーに特化した第二のクラスは、ヘッダーの名前によって決定され、 `HeaderRegistry` に格納されたルックアップテーブルを使用します。 これらすべては、典型的なアプリケーションプログラムに対しては透過的に管理されますが、より複雑なアプリケーションで使用するためにデフォルトの動作を変更するためのインタフェースが提供されています。

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

class email.headerregistry.BaseHeader(name, value)

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

  基底クラスは以下の読み出し専用属性を定義しています:

  name

    ヘッダーの名前(フィールドの':'の前の部分)。これは `header_factory` の name の呼び出しで渡された値と全く同じです; つまり、大文字・小文字が保持されます。

  defects

    パース中に見つかったRFCのコンプライアンス問題を報告する `HeaderDefect` インスタンスのタプルです。 email パッケージはコンプライアンスに関する問題を完全に検出するように努めています。 報告されるかもしれない欠陥の種類の議論については、 `errors` モジュールを参照してください。

  max_count

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

  `BaseHeader` は以下のメソッドも提供します。このメソッドはemail ライブラリのコードから呼び出され、一般にアプリケーションプログラムからは呼び出されません：

  fold(*, policy)

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

  `BaseHeader` 自身はヘッダーオブジェクトを生成するために使用することはできません。このクラスは、それぞれの特殊化ヘッダーがヘッダーオブジェクトを生成するために協力するプロトコルを定義しています。 具体的には、 `BaseHeader` は `parse` という名前の `classmethod()` を特殊化されたクラスが提供することを要求しています。このメソッドは以下のように呼び出されます:

      parse(string, kwds)

  `kwds` は、初期化されたキー `defects` を含む辞書です。`defects` は空のリストです。 解析メソッドは、検出された不具合をこのリストに追加するべきです。 returnの際には、 `kwds` 辞書に少なくとも `decoded` と``defects`` のキーを含む必要があります。 `decoded` はヘッダの文字列値 (つまり、ヘッダを Unicode に完全にデコードした値) でなければなりません。 parseメソッドは、 string がcontent-transfer-encodedな部分を含む可能性があると仮定すべきですが、エンコードされていないヘッダ値をパースできるように、すべての有効なUnicode文字も正しく処理する必要があります。

  その後、 `BaseHeader` の `__new__` がヘッダのインスタンスを生成し、 `init` メソッドを呼び出します。 特殊クラスは、 `BaseHeader` が提供しない属性を設定したい場合にのみ `init` メソッドを提供する必要があります。 このような``init`` メソッドは以下のようなものです：

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

  つまり、特殊クラスが `kwds` の辞書に追加したものはすべて削除して処理し、 `kw``の残りの内容 (と ``args`) は``BaseHeader`` の``init`` メソッドに渡す必要があるのです。

class email.headerregistry.UnstructuredHeader

  "unstructured" ヘッダは RFC 5322 におけるデフォルトのヘッダのタイプです。指定された構文を持たないすべてのヘッダは、unstructuredとして扱われます。 構造化されていないヘッダの典型的な例は Subject ヘッダです。

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

  このヘッダ型には追加の属性はありません。

class email.headerregistry.DateHeader

  RFC 5322 specifies a very specific format for dates within email headers. The `DateHeader` parser recognizes that date format, as well as recognizing a number of variant forms that are sometimes found "in the wild".

  このヘッダ型は以下の属性も提供しています:

  datetime

    If the header value can be recognized as a valid date of one form or another, this attribute will contain a `datetime` instance representing that date. If the timezone of the input date is specified as `-0000` (indicating it is in UTC but contains no information about the source timezone), then `datetime` will be a naive `datetime`. If a specific timezone offset is found (including `+0000`), then `datetime` will contain an aware `datetime` that uses `datetime.timezone` to record the timezone offset.

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

      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` オブジェクトのタプルです。 ヘッダ値にグループが含まれている場合、そのグループに含まれる個々のアドレスは、ヘッダ値でグループが出現した時点でリストに含まれます (つまり、アドレスのリストは一次元のリストに「フラット化」されます)。

  The `decoded` value of the header will have all encoded words decoded to unicode. `idna` encoded domain names are also decoded to unicode. The `decoded` value is set by joining the `str` value of the elements of the `groups` attribute with `', '`.

  A list of `Address` and `Group` objects in any combination may be used to set the value of an address header. `Group` objects whose `display_name` is `None` will be interpreted as single addresses, which allows an address list to be copied with groups intact by using the list obtained from the `groups` attribute of the source header.

class email.headerregistry.SingleAddressHeader

  追加の属性を 1 つ持つ、`AddressHeader` の派生クラスです:

  address

    The single address encoded by the header value. If the header value actually contains more than one address (which would be a violation of the RFC under the default `policy`), accessing this attribute will result in a `ValueError`.

Many of the above classes also have a `Unique` variant (for example, `UniqueUnstructuredHeader`). The only difference is that in the `Unique` variant, `max_count` is set to 1.

class email.headerregistry.MIMEVersionHeader

  There is really only one valid value for the MIME-Version header, and that is `1.0`. For future proofing, this header class supports other valid version numbers. If a version number has a valid value per RFC 2045, then the header object will have non-`None` values for the following attributes:

  version

    バージョン番号 (文字列)、空白やコメントは除かれます。

  major

    メジャーバージョン番号 (整数)

  minor

    マイナーバージョン番号 (整数)

class email.headerregistry.ParameterizedMIMEHeader

  MIME headers all start with the prefix 'Content-'. Each specific header has a certain value, described under the class for that header. Some can also take a list of supplemental parameters, which have a common format. This class serves as a base for all the MIME headers that take parameters.

  params

    A dictionary mapping parameter names to parameter values.

class email.headerregistry.ContentTypeHeader

  Content-Type ヘッダを扱う `ParameterizedMIMEHeader` クラスです。

  content_type

    The content type string, in the form `maintype/subtype`.

  maintype
  subtype

class email.headerregistry.ContentDispositionHeader

  Content-Disposition ヘッダを扱う `ParameterizedMIMEHeader` クラスです。

  content_disposition

    `inline` and `attachment` are the only valid values in common use.

class email.headerregistry.ContentTransferEncodingHeader

  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)

  This is the factory used by `EmailPolicy` by default. `HeaderRegistry` builds the class used to create a header instance dynamically, using base_class and a specialized class retrieved from a registry that it holds. When a given header name does not appear in the registry, the class specified by default_class is used as the specialized class. When use_default_map is `True` (the default), the standard mapping of header names to classes is copied in to the registry during initialization. base_class is always the last class in the generated class's `__bases__` list.

  デフォルトのマッピング:

  > subject:

  >   UniqueUnstructuredHeader

  > date:

  >   UniqueDateHeader

  > resent-date:

  >   DateHeader

  > orig-date:

  >   UniqueDateHeader

  > sender:

  >   UniqueSingleAddressHeader

  > resent-sender:

  >   SingleAddressHeader

  > to:

  >   UniqueAddressHeader

  > resent-to:

  >   AddressHeader

  > cc:

  >   UniqueAddressHeader

  > resent-cc:

  >   AddressHeader

  > bcc:

  >   UniqueAddressHeader

  > resent-bcc:

  >   AddressHeader

  > from:

  >   UniqueAddressHeader

  > resent-from:

  >   AddressHeader

  > reply-to:

  >   UniqueAddressHeader

  > mime-version:

  >   MIMEVersionHeader

  > content-type:

  >   ContentTypeHeader

  > content-disposition:

  >   ContentDispositionHeader

  > content-transfer-encoding:

  >   ContentTransferEncodingHeader

  > message-id:

  >   MessageIDHeader

  `HeaderRegistry` には以下のメソッドがあります:

  map_to_type(self, name, cls)

    name is the name of the header to be mapped. It will be converted to lower case in the registry. cls is the specialized class to be used, along with base_class, to create the class used to instantiate headers that match name.

  __getitem__(name)

    Construct and return a class to handle creating a name header.

  __call__(name, value)

    Retrieves the specialized header associated with name from the registry (using default_class if name does not appear in the registry) and composes it with base_class to produce a class, calls the constructed class's constructor, passing it the same argument list, and finally returns the class instance created thereby.

The following classes are the classes used to represent data parsed from structured headers and can, in general, be used by an application program to construct structured values to assign to specific headers.

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

  このクラスは電子メールのアドレスを表すのに使われます。アドレスの一般的な形式は:

      [display_name] <username@domain>

  もしくは:

      username@domain

  where each part must conform to specific syntax rules spelled out in RFC 5322.

  As a convenience addr_spec can be specified instead of username and domain, in which case username and domain will be parsed from the addr_spec. An addr_spec must be a properly RFC quoted string; if it is not `Address` will raise an error. Unicode characters are allowed and will be property encoded when serialized. However, per the RFCs, unicode is not allowed in the username portion of the address.

  display_name

    The display name portion of the address, if any, with all quoting removed. If the address does not have a display name, this attribute will be an empty string.

  username

    アドレスの `username` 部分、クォートは取り除かれます。

  domain

    アドレスの `domain` 部分。

  addr_spec

    The `username@domain` portion of the address, correctly quoted for use as a bare address (the second form shown above). This attribute is not mutable.

  __str__()

    The `str` value of the object is the address quoted according to RFC 5322 rules, but with no Content Transfer Encoding of any non-ASCII characters.

  To support SMTP (RFC 5321), `Address` handles one special case: if `username` and `domain` are both the empty string (or `None`), then the string value of the `Address` is `<>`.

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

  このクラスはアドレスグループを表すのに使われます。アドレスグループの一般的な形式は:

      display_name: [address-list];

  As a convenience for processing lists of addresses that consist of a mixture of groups and single addresses, a `Group` may also be used to represent single addresses that are not part of a group by setting display_name to `None` and providing a list of the single address as addresses.

  display_name

    The `display_name` of the group. If it is `None` and there is exactly one `Address` in `addresses`, then the `Group` represents a single address that is not in a group.

  addresses

    A possibly empty tuple of `Address` objects representing the addresses in the group.

  __str__()

    The `str` value of a `Group` is formatted according to RFC 5322, but with no Content Transfer Encoding of any non-ASCII characters. If `display_name` is none and there is a single `Address` in the `addresses` list, the `str` value will be the same as the `str` of that single `Address`.

脚注

[1]

Originally added in 3.3 as a provisional module