`email.message.Message`: Trình bày thư email bằng `compat32` API¶

Lớp Message rất giống với lớp EmailMessage, không có các phương thức được lớp đó thêm vào và hành vi mặc định của một số phương thức khác hơi khác một chút. Ở đây chúng tôi cũng ghi lại một số phương thức, mặc dù được lớp EmailMessage hỗ trợ, nhưng không được khuyến nghị trừ khi bạn đang xử lý mã kế thừa.

Triết lý và cấu trúc của hai lớp thì giống nhau.

Tài liệu này mô tả hành vi theo chính sách mặc định (dành cho Message) Compat32. Nếu bạn định sử dụng một chính sách khác, thay vào đó bạn nên sử dụng lớp EmailMessage.

Một email bao gồm headers và payload. Tiêu đề phải là tên và giá trị kiểu RFC 5322, trong đó tên và giá trị trường được phân tách bằng dấu hai chấm. Dấu hai chấm không phải là một phần của tên trường hoặc giá trị trường. Tải trọng có thể là một tin nhắn văn bản đơn giản hoặc một đối tượng nhị phân hoặc một chuỗi các tin nhắn phụ có cấu trúc, mỗi tin nhắn có bộ tiêu đề và tải trọng riêng. Loại tải trọng thứ hai được biểu thị bằng thông báo có loại MIME như multipart/* hoặc message/rfc822.

Mô hình khái niệm do đối tượng Message cung cấp là mô hình từ điển có thứ tự gồm các tiêu đề với các phương pháp bổ sung để truy cập cả thông tin chuyên biệt từ tiêu đề, để truy cập tải trọng, để tạo phiên bản tuần tự của thông báo và để duyệt đệ quy trên cây đối tượng. Lưu ý rằng các tiêu đề trùng lặp được hỗ trợ nhưng phải sử dụng các phương pháp đặc biệt để truy cập chúng.

Từ điển giả Message được lập chỉ mục theo tên tiêu đề, phải là giá trị ASCII. Các giá trị của từ điển là các chuỗi được cho là chỉ chứa các ký tự ASCII; có một số cách xử lý đặc biệt đối với đầu vào không phải ASCII, nhưng không phải lúc nào nó cũng tạo ra kết quả chính xác. Các tiêu đề được lưu trữ và trả về ở dạng bảo toàn chữ hoa chữ thường, nhưng tên trường được khớp không phân biệt chữ hoa chữ thường. Cũng có thể có một tiêu đề phong bì duy nhất, còn được gọi là tiêu đề Unix-From hoặc tiêu đề From_. payload là một chuỗi hoặc byte, trong trường hợp đối tượng thông báo đơn giản hoặc danh sách các đối tượng Message, cho các tài liệu chứa MIME (ví dụ: multipart/* và message/rfc822).

Dưới đây là các phương thức của lớp Message:

class email.message.Message(policy=compat32)¶

Nếu policy được chỉ định (nó phải là một phiên bản của lớp policy), hãy sử dụng các quy tắc mà nó chỉ định để cập nhật và tuần tự hóa cách trình bày thông báo. Nếu policy không được đặt, hãy sử dụng chính sách compat32 để duy trì khả năng tương thích ngược với phiên bản Python 3.2 của gói email. Để biết thêm thông tin, hãy xem tài liệu policy.

Thay đổi trong phiên bản 3.3: Đối số từ khóa policy đã được thêm vào.

as_string(unixfrom=False, maxheaderlen=0, policy=None)¶

Trả lại toàn bộ tin nhắn được làm phẳng dưới dạng một chuỗi. Khi tùy chọn unixfrom là đúng, tiêu đề phong bì sẽ được bao gồm trong chuỗi trả về. unixfrom mặc định là False. Vì lý do tương thích ngược, maxheaderlen mặc định là 0, vì vậy nếu muốn một giá trị khác, bạn phải ghi đè nó một cách rõ ràng (giá trị được chỉ định cho max_line_length trong chính sách sẽ bị phương pháp này bỏ qua). Đối số policy có thể được sử dụng để ghi đè chính sách mặc định thu được từ phiên bản thông báo. Điều này có thể được sử dụng để kiểm soát một số định dạng do phương thức tạo ra, vì policy được chỉ định sẽ được chuyển tới Generator.

Việc làm phẳng thông báo có thể kích hoạt các thay đổi đối với Message nếu cần điền các giá trị mặc định để hoàn tất quá trình chuyển đổi thành chuỗi (ví dụ: ranh giới MIME có thể được tạo hoặc sửa đổi).

Lưu ý rằng phương pháp này được cung cấp để thuận tiện và không phải lúc nào cũng định dạng thư theo cách bạn muốn. Ví dụ: theo mặc định, nó không thực hiện việc xáo trộn các dòng bắt đầu bằng From được định dạng mbox Unix yêu cầu. Để linh hoạt hơn, hãy khởi tạo phiên bản Generator và sử dụng trực tiếp phương thức flatten() của nó. Ví dụ:

từ io nhập StringIO
từ nhập email.generator Trình tạo
fp = StringIO()
g = Trình tạo(fp, mangle_from_=True, maxheaderlen=60)
g.làm phẳng(tin nhắn)
văn bản = fp.getvalue()

Nếu đối tượng tin nhắn chứa dữ liệu nhị phân không được mã hóa theo tiêu chuẩn RFC, dữ liệu không tuân thủ sẽ được thay thế bằng các điểm mã "ký tự không xác định" unicode. (Xem thêm as_bytes() và BytesGenerator.)

Thay đổi trong phiên bản 3.4: đối số từ khóa policy đã được thêm vào.

__str__()¶: Tương đương với as_string(). Cho phép str(msg) tạo một chuỗi chứa thông báo được định dạng.

as_bytes(unixfrom=False, policy=None)¶

Trả về toàn bộ tin nhắn được làm phẳng dưới dạng đối tượng byte. Khi unixfrom tùy chọn là đúng, tiêu đề phong bì sẽ được bao gồm trong chuỗi trả về. unixfrom mặc định là False. Đối số policy có thể được sử dụng để ghi đè chính sách mặc định thu được từ phiên bản thông báo. Điều này có thể được sử dụng để kiểm soát một số định dạng do phương thức tạo ra, vì policy được chỉ định sẽ được chuyển tới BytesGenerator.

Việc làm phẳng thông báo có thể kích hoạt các thay đổi đối với Message nếu cần điền các giá trị mặc định để hoàn tất quá trình chuyển đổi thành chuỗi (ví dụ: ranh giới MIME có thể được tạo hoặc sửa đổi).

Lưu ý rằng phương pháp này được cung cấp để thuận tiện và không phải lúc nào cũng định dạng thư theo cách bạn muốn. Ví dụ: theo mặc định, nó không thực hiện việc xáo trộn các dòng bắt đầu bằng From được định dạng mbox Unix yêu cầu. Để linh hoạt hơn, hãy khởi tạo phiên bản BytesGenerator và sử dụng trực tiếp phương thức flatten() của nó. Ví dụ:

từ io nhập ByteIO
từ email.generator nhập BytesGenerator
fp = ByteIO()
g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
g.làm phẳng(tin nhắn)
văn bản = fp.getvalue()

Added in version 3.4.

__bytes__()¶: Tương đương với as_bytes(). Cho phép bytes(msg) tạo đối tượng byte chứa thông báo được định dạng.

Added in version 3.4.

is_multipart()¶: Trả về True nếu tải trọng của tin nhắn là danh sách các đối tượng phụ:class:Message, nếu không thì trả về False. Khi is_multipart() trả về False, tải trọng phải là một đối tượng chuỗi (có thể là tải trọng nhị phân được mã hóa CTE). (Lưu ý rằng is_multipart() trả về True không nhất thiết có nghĩa là "msg.get_content_maintype() == 'multipart'" sẽ trả về True. Ví dụ: is_multipart sẽ trả về True khi Message thuộc loại message/rfc822.)

set_unixfrom(unixfrom)¶: Đặt tiêu đề phong bì của thư thành unixfrom, tiêu đề này phải là một chuỗi.

get_unixfrom()¶: Trả lại tiêu đề phong bì của tin nhắn. Mặc định là None nếu tiêu đề phong bì chưa bao giờ được đặt.

attach(payload)¶

Thêm payload đã cho vào tải trọng hiện tại, tải trọng này phải là None hoặc danh sách các đối tượng Message trước cuộc gọi. Sau cuộc gọi, tải trọng sẽ luôn là danh sách các đối tượng Message. Nếu bạn muốn đặt tải trọng thành đối tượng vô hướng (ví dụ: chuỗi), thay vào đó hãy sử dụng set_payload().

Đây là một phương pháp kế thừa. Trên lớp EmailMessage, chức năng của nó được thay thế bằng set_content() và các phương thức make và add có liên quan.

get_payload(i=None, decode=False)¶

Trả về tải trọng hiện tại, đây sẽ là danh sách các đối tượng Message khi is_multipart() là True hoặc một chuỗi khi is_multipart() là False. Nếu tải trọng là một danh sách và bạn thay đổi đối tượng danh sách, bạn sẽ sửa đổi tải trọng của thông báo tại chỗ.

Với đối số tùy chọn i, get_payload() sẽ trả về phần tử thứ i của tải trọng, tính từ 0, nếu is_multipart() là True. Một IndexError sẽ được tăng lên nếu i nhỏ hơn 0 hoặc lớn hơn hoặc bằng số lượng mục trong tải trọng. Nếu tải trọng là một chuỗi (tức là is_multipart() là False) và i được đưa ra thì TypeError sẽ được nâng lên.

Zz009zz tùy chọn là cờ cho biết tải trọng có nên được giải mã hay không, theo tiêu đề Content-Transfer-Encoding. Khi True và tin nhắn không phải là nhiều phần, tải trọng sẽ được giải mã nếu giá trị của tiêu đề này là quoted-printable hoặc base64. Nếu một số mã hóa khác được sử dụng hoặc tiêu đề Content-Transfer-Encoding bị thiếu, tải trọng sẽ được trả về nguyên trạng (không được mã hóa). Trong mọi trường hợp, giá trị trả về là dữ liệu nhị phân. Nếu thông báo là nhiều phần và cờ decode là True thì None sẽ được trả về. Nếu trọng tải là base64 và nó không được định dạng hoàn hảo (thiếu phần đệm, các ký tự nằm ngoài bảng chữ cái base64), thì một lỗi thích hợp sẽ được thêm vào thuộc tính lỗi của thông báo (tương ứng là InvalidBase64PaddingDefect hoặc InvalidBase64CharactersDefect).

Khi decode là False (mặc định), nội dung được trả về dưới dạng chuỗi mà không giải mã Content-Transfer-Encoding. Tuy nhiên, đối với Content-Transfer-Encoding 8bit, một nỗ lực được thực hiện để giải mã các byte gốc bằng cách sử dụng charset được chỉ định bởi tiêu đề Content-Type, sử dụng trình xử lý lỗi replace. Nếu không chỉ định charset hoặc nếu charset đã cung cấp không được gói email nhận dạng thì nội dung sẽ được giải mã bằng bộ ký tự ASCII mặc định.

Đây là một phương pháp kế thừa. Trên lớp EmailMessage, chức năng của nó được thay thế bằng get_content() và iter_parts().

set_payload(payload, charset=None)¶

Đặt toàn bộ tải trọng của đối tượng tin nhắn thành payload. Trách nhiệm của khách hàng là đảm bảo tải trọng không thay đổi. charset tùy chọn đặt bộ ký tự mặc định của tin nhắn; xem set_charset() để biết chi tiết.

Đây là một phương pháp kế thừa. Trên lớp EmailMessage, chức năng của nó được thay thế bằng set_content().

set_charset(charset)¶

Đặt bộ ký tự của tải trọng thành charset, có thể là phiên bản Charset (xem email.charset), một chuỗi đặt tên cho bộ ký tự hoặc None. Nếu là một chuỗi, nó sẽ được chuyển đổi thành phiên bản Charset. Nếu charset là None, tham số charset sẽ bị xóa khỏi tiêu đề Content-Type (thông báo sẽ không được sửa đổi). Bất cứ điều gì khác sẽ tạo ra một TypeError.

Nếu không có tiêu đề MIME-Version hiện có, tiêu đề này sẽ được thêm vào. Nếu không có tiêu đề Content-Type hiện có, một tiêu đề sẽ được thêm vào với giá trị text/plain. Cho dù tiêu đề Content-Type đã tồn tại hay chưa, tham số charset của nó sẽ được đặt thành charset.output_charset. Nếu charset.input_charset và charset.output_charset khác nhau, tải trọng sẽ được mã hóa lại thành output_charset. Nếu không có tiêu đề Content-Transfer-Encoding hiện có thì tải trọng sẽ được mã hóa truyền, nếu cần, bằng cách sử dụng Charset được chỉ định và tiêu đề có giá trị phù hợp sẽ được thêm vào. Nếu tiêu đề Content-Transfer-Encoding đã tồn tại thì tải trọng được coi là đã được mã hóa chính xác bằng Content-Transfer-Encoding đó và không được sửa đổi.

Đây là một phương pháp kế thừa. Trên lớp EmailMessage, chức năng của nó được thay thế bằng tham số charset của phương thức email.message.EmailMessage.set_content().

get_charset()¶

Trả về phiên bản Charset được liên kết với tải trọng của tin nhắn.

Đây là một phương pháp kế thừa. Trên lớp EmailMessage nó luôn trả về None.

Các phương pháp sau triển khai giao diện giống như ánh xạ để truy cập tiêu đề RFC 2822 của tin nhắn. Lưu ý rằng có một số khác biệt về ngữ nghĩa giữa các phương thức này và giao diện ánh xạ (tức là từ điển) thông thường. Ví dụ: trong từ điển không có khóa trùng lặp nhưng ở đây có thể có tiêu đề thư trùng lặp. Ngoài ra, trong từ điển không có thứ tự đảm bảo cho các khóa được trả về bởi keys(), nhưng trong đối tượng Message, các tiêu đề luôn được trả về theo thứ tự chúng xuất hiện trong thư gốc hoặc được thêm vào thư sau đó. Bất kỳ tiêu đề nào bị xóa và sau đó được thêm lại luôn được thêm vào cuối danh sách tiêu đề.

Những khác biệt về ngữ nghĩa này là có chủ ý và thiên về sự thuận tiện tối đa.

Lưu ý rằng trong mọi trường hợp, mọi tiêu đề phong bì có trong tin nhắn đều không được đưa vào giao diện ánh xạ.

Trong mô hình được tạo từ byte, mọi giá trị tiêu đề (trái với RFC) chứa byte không phải ASCII, khi được truy xuất qua giao diện này, sẽ được biểu diễn dưới dạng đối tượng Header với bộ ký tự unknown-8bit.

__len__()¶: Trả về tổng số tiêu đề, bao gồm cả các tiêu đề trùng lặp.

__contains__(name)¶

Trả về True nếu đối tượng tin nhắn có trường có tên name. Việc so khớp được thực hiện không phân biệt chữ hoa chữ thường và name không được bao gồm dấu hai chấm ở cuối. Được sử dụng cho toán tử in, ví dụ:

nếu 'id tin nhắn' trong myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)¶

Trả về giá trị của trường tiêu đề được đặt tên. name không được bao gồm dấu phân cách trường dấu hai chấm. Nếu thiếu tiêu đề, None sẽ được trả về; một KeyError không bao giờ được nâng lên.

Lưu ý rằng nếu trường được đặt tên xuất hiện nhiều lần trong tiêu đề của thư thì giá trị chính xác của trường nào sẽ được trả về sẽ không được xác định. Sử dụng phương pháp get_all() để lấy giá trị của tất cả các tiêu đề được đặt tên còn tồn tại.

__setitem__(name, val)¶

Thêm tiêu đề vào tin nhắn với tên trường name và giá trị val. Trường này được thêm vào cuối các trường hiện có của tin nhắn.

Lưu ý rằng điều này not ghi đè hoặc xóa bất kỳ tiêu đề hiện có nào có cùng tên. Nếu bạn muốn đảm bảo rằng tiêu đề mới là tiêu đề duy nhất có trong thư có tên trường name, trước tiên hãy xóa trường đó, ví dụ::

del tin nhắn['chủ đề']
msg['subject'] = 'Python roolz!'

__delitem__(name)¶: Xóa tất cả các lần xuất hiện của trường có tên name khỏi tiêu đề của thư. Không có ngoại lệ nào được đưa ra nếu trường được đặt tên không có trong tiêu đề.

keys()¶: Trả về danh sách tất cả tên trường tiêu đề của thư.

values()¶: Trả về danh sách tất cả các giá trị trường của tin nhắn.

items()¶: Trả về danh sách gồm 2 bộ chứa tất cả các tiêu đề và giá trị trường của thông báo.

get(name, failobj=None)¶: Trả về giá trị của trường tiêu đề được đặt tên. Điều này giống hệt với __getitem__() ngoại trừ failobj tùy chọn được trả về nếu thiếu tiêu đề được đặt tên (mặc định là None).

Dưới đây là một số phương pháp hữu ích bổ sung:

get_all(name, failobj=None)¶: Trả về danh sách tất cả các giá trị cho trường có tên name. Nếu không có tiêu đề được đặt tên như vậy trong tin nhắn, failobj sẽ được trả về (mặc định là None).

add_header(_name, _value, **_params)¶

Cài đặt tiêu đề mở rộng. Phương thức này tương tự như __setitem__() ngoại trừ các tham số tiêu đề bổ sung có thể được cung cấp làm đối số từ khóa. _name là trường tiêu đề cần thêm và _value là giá trị primary cho tiêu đề.

Đối với mỗi mục trong từ điển đối số từ khóa _params, khóa được lấy làm tên tham số, với dấu gạch dưới được chuyển thành dấu gạch ngang (vì dấu gạch ngang là không hợp lệ trong mã định danh Python). Thông thường, tham số sẽ được thêm dưới dạng key="value" trừ khi giá trị là None, trong trường hợp đó chỉ có khóa mới được thêm vào. Nếu giá trị chứa các ký tự không phải là ASCII thì giá trị đó có thể được chỉ định dưới dạng bộ ba ở định dạng (CHARSET, LANGUAGE, VALUE), trong đó CHARSET là một chuỗi đặt tên cho bộ ký tự được sử dụng để mã hóa giá trị, LANGUAGE thường có thể được đặt thành None hoặc chuỗi trống (xem RFC 2231 để biết các khả năng khác) và VALUE là giá trị chuỗi chứa các điểm mã không phải ASCII. Nếu bộ ba không được chuyển và giá trị chứa các ký tự không phải là ASCII, thì nó sẽ tự động được mã hóa ở định dạng RFC 2231 bằng cách sử dụng CHARSET của utf-8 và LANGUAGE của None.

Đây là một ví dụ:

msg.add_header('Bố trí nội dung', 'tệp đính kèm', filename='bud.gif')

Điều này sẽ thêm một tiêu đề trông giống như

Bố trí nội dung: tệp đính kèm; tên tệp="bud.gif"

Một ví dụ với các ký tự không phải ASCII:

msg.add_header('Bố trí nội dung', 'tệp đính kèm',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

Cái nào tạo ra

Bố trí nội dung: tệp đính kèm; tên tệp*="iso-8859-1''Fu%DFballer.ppt"

replace_header(_name, _value)¶: Thay thế một tiêu đề. Thay thế tiêu đề đầu tiên được tìm thấy trong thư khớp với _name, giữ nguyên thứ tự tiêu đề và kiểu chữ trường. Nếu không tìm thấy tiêu đề phù hợp, KeyError sẽ được nâng lên.

get_content_type()¶

Trả về loại nội dung của tin nhắn. Chuỗi trả về bị ép buộc phải viết thường ở dạng maintype/subtype. Nếu không có tiêu đề Content-Type trong tin nhắn thì loại mặc định do get_default_type() đưa ra sẽ được trả về. Vì theo RFC 2045, các tin nhắn luôn có loại mặc định nên get_content_type() sẽ luôn trả về một giá trị.

RFC 2045 xác định loại mặc định của tin nhắn là text/plain trừ khi nó xuất hiện bên trong vùng chứa multipart/digest, trong trường hợp đó nó sẽ là message/rfc822. Nếu tiêu đề Content-Type có thông số loại không hợp lệ thì RFC 2045 yêu cầu loại mặc định là text/plain.

get_content_maintype()¶: Trả về loại nội dung chính của tin nhắn. Đây là phần maintype của chuỗi được trả về bởi get_content_type().

get_content_subtype()¶: Trả về loại nội dung phụ của tin nhắn. Đây là phần subtype của chuỗi được trả về bởi get_content_type().

get_default_type()¶: Trả về loại nội dung mặc định. Hầu hết các tin nhắn đều có loại nội dung mặc định là text/plain, ngoại trừ các tin nhắn là phần phụ của vùng chứa multipart/digest. Các phần con như vậy có loại nội dung mặc định là message/rfc822.

set_default_type(ctype)¶: Đặt loại nội dung mặc định. ctype phải là text/plain hoặc message/rfc822, mặc dù điều này không được thực thi. Loại nội dung mặc định không được lưu trữ trong tiêu đề Content-Type.

get_params(failobj=None, header='content-type', unquote=True)¶

Trả về các tham số Content-Type của tin nhắn dưới dạng danh sách. Các phần tử của danh sách trả về là 2 bộ cặp khóa/giá trị, được phân chia bằng dấu '='. Phía bên trái của '=' là khóa, còn phía bên phải là giá trị. Nếu không có dấu '=' trong tham số thì giá trị là chuỗi trống, nếu không thì giá trị như được mô tả trong get_param() và không được trích dẫn nếu unquote tùy chọn là True (mặc định).

failobj tùy chọn là đối tượng cần trả về nếu không có tiêu đề Content-Type. Tùy chọn header là tiêu đề để tìm kiếm thay vì Content-Type.

Đây là một phương pháp kế thừa. Trên lớp EmailMessage, chức năng của nó được thay thế bằng thuộc tính params của các đối tượng tiêu đề riêng lẻ được các phương thức truy cập tiêu đề trả về.

get_param(param, failobj=None, header='content-type', unquote=True)¶

Trả về giá trị của tham số param của tiêu đề Content-Type dưới dạng một chuỗi. Nếu tin nhắn không có tiêu đề Content-Type hoặc nếu không có tham số nào như vậy thì failobj sẽ được trả về (mặc định là None).

header tùy chọn nếu được cung cấp, chỉ định tiêu đề thư sẽ sử dụng thay vì Content-Type.

Các khóa tham số luôn được so sánh không phân biệt chữ hoa chữ thường. Giá trị trả về có thể là một chuỗi hoặc 3 bộ nếu tham số được mã hóa RFC 2231. Khi đó là bộ 3, các phần tử của giá trị có dạng (CHARSET, LANGUAGE, VALUE). Lưu ý rằng cả CHARSET và LANGUAGE đều có thể là None, trong trường hợp đó bạn nên coi VALUE được mã hóa trong bộ ký tự us-ascii. Bạn thường có thể bỏ qua LANGUAGE.

Nếu ứng dụng của bạn không quan tâm liệu tham số có được mã hóa như trong RFC 2231 hay không, bạn có thể thu gọn giá trị tham số bằng cách gọi email.utils.collapse_rfc2231_value(), chuyển giá trị trả về từ get_param(). Điều này sẽ trả về một chuỗi Unicode được giải mã phù hợp khi giá trị là một bộ dữ liệu hoặc chuỗi gốc không được trích dẫn nếu không. Ví dụ:

rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)

Trong mọi trường hợp, giá trị tham số (chuỗi được trả về hoặc mục VALUE trong bộ 3) luôn không được trích dẫn, trừ khi unquote được đặt thành False.

Đây là một phương pháp kế thừa. Trên lớp EmailMessage, chức năng của nó được thay thế bằng thuộc tính params của các đối tượng tiêu đề riêng lẻ được các phương thức truy cập tiêu đề trả về.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)¶

Đặt tham số trong tiêu đề Content-Type. Nếu tham số đã tồn tại trong tiêu đề, giá trị của nó sẽ được thay thế bằng value. Nếu tiêu đề Content-Type chưa được xác định cho thông báo này, nó sẽ được đặt thành text/plain và giá trị tham số mới sẽ được thêm vào theo RFC 2045.

header tùy chọn chỉ định một tiêu đề thay thế cho Content-Type và tất cả các tham số sẽ được trích dẫn khi cần thiết trừ khi requote tùy chọn là False (mặc định là True).

Nếu charset tùy chọn được chỉ định, tham số sẽ được mã hóa theo RFC 2231. language tùy chọn chỉ định ngôn ngữ RFC 2231, mặc định là chuỗi trống. Cả charset và language đều phải là chuỗi.

Nếu replace là False (mặc định) thì tiêu đề sẽ được chuyển đến cuối danh sách các tiêu đề. Nếu replace là True, tiêu đề sẽ được cập nhật tại chỗ.

Thay đổi trong phiên bản 3.4: Từ khóa replace đã được thêm vào.

del_param(param, header='content-type', requote=True)¶: Xóa hoàn toàn tham số đã cho khỏi tiêu đề Content-Type. Tiêu đề sẽ được viết lại tại chỗ mà không có tham số hoặc giá trị của nó. Tất cả các giá trị sẽ được trích dẫn khi cần thiết trừ khi requote là False (mặc định là True). header tùy chọn chỉ định một giải pháp thay thế cho Content-Type.

set_type(type, header='Content-Type', requote=True)¶

Đặt loại chính và loại phụ cho tiêu đề Content-Type. type phải là một chuỗi có dạng maintype/subtype, nếu không thì ValueError sẽ được nâng lên.

Phương pháp này thay thế tiêu đề Content-Type, giữ nguyên tất cả các tham số. Nếu requote là False, điều này sẽ giữ nguyên trích dẫn của tiêu đề hiện có, nếu không thì các tham số sẽ được trích dẫn (mặc định).

Một tiêu đề thay thế có thể được chỉ định trong đối số header. Khi tiêu đề Content-Type được đặt, tiêu đề MIME-Version cũng được thêm vào.

Đây là một phương pháp kế thừa. Trên lớp EmailMessage, chức năng của nó được thay thế bằng các phương thức make_ và add_.

get_filename(failobj=None)¶: Trả về giá trị của tham số filename của tiêu đề Content-Disposition của tin nhắn. Nếu tiêu đề không có tham số filename, phương pháp này sẽ quay lại tìm kiếm tham số name trên tiêu đề Content-Type. Nếu không tìm thấy hoặc thiếu tiêu đề thì failobj sẽ được trả về. Chuỗi trả về sẽ luôn không được trích dẫn theo email.utils.unquote().

get_boundary(failobj=None)¶: Trả về giá trị của tham số boundary của tiêu đề Content-Type của tin nhắn hoặc failobj nếu tiêu đề bị thiếu hoặc không có tham số boundary. Chuỗi trả về sẽ luôn không được trích dẫn theo email.utils.unquote().

set_boundary(boundary)¶

Đặt tham số boundary của tiêu đề Content-Type thành boundary. set_boundary() sẽ luôn trích dẫn boundary nếu cần thiết. Một HeaderParseError được nâng lên nếu đối tượng tin nhắn không có tiêu đề Content-Type.

Lưu ý rằng việc sử dụng phương pháp này hơi khác so với việc xóa tiêu đề Content-Type cũ và thêm tiêu đề mới với ranh giới mới thông qua add_header(), vì set_boundary() giữ nguyên thứ tự của tiêu đề Content-Type trong danh sách các tiêu đề. Tuy nhiên, not giữ lại mọi dòng tiếp tục có thể có trong tiêu đề Content-Type ban đầu.

get_content_charset(failobj=None)¶

Trả về tham số charset của tiêu đề Content-Type, buộc phải viết thường. Nếu không có tiêu đề Content-Type hoặc nếu tiêu đề đó không có tham số charset thì failobj sẽ được trả về.

Lưu ý rằng phương thức này khác với get_charset(), phương thức này trả về phiên bản Charset cho mã hóa mặc định của nội dung thư.

get_charsets(failobj=None)¶

Trả về danh sách chứa tên bộ ký tự trong tin nhắn. Nếu thông báo là multipart thì danh sách sẽ chứa một phần tử cho mỗi phần con trong tải trọng, nếu không, đó sẽ là danh sách có độ dài 1.

Mỗi mục trong danh sách sẽ là một chuỗi là giá trị của tham số charset trong tiêu đề Content-Type cho phần con được đại diện. Tuy nhiên, nếu phần con không có tiêu đề Content-Type, không có tham số charset hoặc không thuộc loại MIME chính text thì mục đó trong danh sách trả về sẽ là failobj.

get_content_disposition()¶: Trả về giá trị viết thường (không có tham số) của tiêu đề Content-Disposition của tin nhắn nếu có hoặc None. Các giá trị có thể có cho phương pháp này là inline, attachment hoặc None nếu thông báo theo sau RFC 2183.

Added in version 3.5.

walk()¶

Phương thức walk() là một trình tạo đa năng có thể được sử dụng để lặp qua tất cả các phần và phần phụ của cây đối tượng thông báo, theo thứ tự duyệt theo chiều sâu. Thông thường, bạn sẽ sử dụng walk() làm trình vòng lặp trong vòng lặp for; mỗi lần lặp trả về phần con tiếp theo.

Dưới đây là ví dụ in loại MIME của mọi phần của cấu trúc thông báo nhiều phần:

>>> cho một phần trong msg.walk():
... in(part.get_content_type())
nhiều phần/báo cáo
văn bản/đồng bằng
tin nhắn/trạng thái giao hàng
văn bản/đồng bằng
văn bản/đồng bằng
tin nhắn/rfc822
văn bản/đồng bằng

walk lặp lại các phần con của bất kỳ phần nào mà is_multipart() trả về True, mặc dù msg.get_content_maintype() == 'multipart' có thể trả về False. Chúng ta có thể thấy điều này trong ví dụ của mình bằng cách sử dụng hàm trợ giúp gỡ lỗi _structure:

>>> cho một phần trong msg.walk():
... print(part.get_content_maintype() == 'multipart',
... part.is_multipart())
Đúng Đúng
Sai Sai
Sai Đúng
Sai Sai
Sai Sai
Sai Đúng
Sai Sai
>>> _cấu trúc (tin nhắn)
nhiều phần/báo cáo
    văn bản/đồng bằng
    tin nhắn/trạng thái giao hàng
        văn bản/đồng bằng
        văn bản/đồng bằng
    tin nhắn/rfc822
        văn bản/đồng bằng

Ở đây các phần message không phải là multiparts nhưng chúng có chứa các phần phụ. is_multipart() trả về True và walk chuyển xuống các phần phụ.

Các đối tượng Message cũng có thể tùy ý chứa hai thuộc tính phiên bản, có thể được sử dụng khi tạo văn bản thuần túy của tin nhắn MIME.

preamble¶

Định dạng của tài liệu MIME cho phép một số văn bản nằm giữa dòng trống theo tiêu đề và chuỗi ranh giới nhiều phần đầu tiên. Thông thường, văn bản này không bao giờ hiển thị trong trình đọc thư nhận biết MIME vì nó nằm ngoài lớp bảo vệ MIME tiêu chuẩn. Tuy nhiên, khi xem văn bản thô của tin nhắn hoặc khi xem tin nhắn trong trình đọc không nhận biết MIME, văn bản này có thể hiển thị.

Thuộc tính preamble chứa văn bản bổ sung hàng đầu này cho các tài liệu MIME. Khi Parser phát hiện một số văn bản sau tiêu đề nhưng trước chuỗi ranh giới đầu tiên, nó sẽ gán văn bản này cho thuộc tính preamble của tin nhắn. Khi Generator đang viết văn bản đơn giản của tin nhắn MIME và nhận thấy tin nhắn có thuộc tính preamble, nó sẽ viết văn bản này vào vùng giữa tiêu đề và ranh giới đầu tiên. Xem email.parser và email.generator để biết chi tiết.

Lưu ý rằng nếu đối tượng thông báo không có phần mở đầu thì thuộc tính preamble sẽ là None.

epilogue¶

Thuộc tính epilogue hoạt động tương tự như thuộc tính preamble, ngoại trừ việc nó chứa văn bản xuất hiện giữa ranh giới cuối cùng và cuối tin nhắn.

Bạn không cần đặt phần kết thành chuỗi trống để Generator in dòng mới ở cuối tệp.

defects¶: Thuộc tính defects chứa danh sách tất cả các vấn đề được tìm thấy khi phân tích thông báo này. Xem email.errors để biết mô tả chi tiết về các lỗi phân tích cú pháp có thể xảy ra.

`email.message.Message`: Trình bày thư email bằng `compat32` API¶

Chủ đề trước

Chủ đề tiếp

Trang này

email.message.Message: Trình bày thư email bằng compat32 API¶

`email.message.Message`: Trình bày thư email bằng `compat32` API¶