email.generator: Tạo tài liệu MIME

Source code: Lib/email/generator.py

Một trong những tác vụ phổ biến nhất là tạo phiên bản phẳng (được tuần tự hóa) của thư email được biểu thị bằng cấu trúc đối tượng thư. Bạn sẽ cần thực hiện việc này nếu muốn gửi tin nhắn của mình qua smtplib.SMTP.sendmail() hoặc in tin nhắn trên bảng điều khiển. Lấy cấu trúc đối tượng thông báo và tạo ra một biểu diễn được tuần tự hóa là công việc của các lớp trình tạo.

Giống như mô-đun email.parser, bạn không bị giới hạn chức năng của trình tạo đi kèm; bạn có thể tự mình viết một cái từ đầu. Tuy nhiên, trình tạo đi kèm biết cách tạo hầu hết email theo cách tuân thủ tiêu chuẩn, xử lý tốt các email MIME và không phải MIME, đồng thời được thiết kế sao cho các hoạt động tạo và phân tích cú pháp theo định hướng byte là nghịch đảo, giả sử sử dụng cùng một policy không chuyển đổi cho cả hai. Nghĩa là, phân tích luồng byte được tuần tự hóa thông qua lớp BytesParser và sau đó tạo lại luồng byte được tuần tự hóa bằng BytesGenerator sẽ tạo ra đầu ra giống hệt với đầu vào [1]. (Mặt khác, việc sử dụng trình tạo trên EmailMessage do chương trình xây dựng có thể dẫn đến thay đổi đối tượng EmailMessage khi các giá trị mặc định được điền vào.)

Lớp Generator có thể được sử dụng để làm phẳng một tin nhắn thành một biểu diễn tuần tự hóa văn bản (ngược lại với nhị phân), nhưng vì Unicode không thể biểu diễn trực tiếp dữ liệu nhị phân nên cần phải chuyển đổi tin nhắn thành một thứ chỉ chứa các ký tự ASCII, sử dụng kỹ thuật Mã hóa chuyển nội dung RFC email tiêu chuẩn để mã hóa tin nhắn email để truyền qua các kênh không "sạch 8 bit".

Để phù hợp với việc xử lý có thể lặp lại các tin nhắn có chữ ký SMIME, Generator vô hiệu hóa việc gấp tiêu đề cho các phần tin nhắn thuộc loại multipart/signed và tất cả các phần phụ.

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Trả về một đối tượng BytesGenerator sẽ ghi bất kỳ thông báo nào được cung cấp cho phương thức flatten() hoặc bất kỳ văn bản được mã hóa thay thế nào được cung cấp cho phương thức write(), cho file-like object outfp. outfp phải hỗ trợ phương thức write chấp nhận dữ liệu nhị phân.

Nếu mangle_from_ tùy chọn là True, hãy đặt ký tự > trước bất kỳ dòng nào trong nội dung bắt đầu bằng chuỗi chính xác "From ", tức là From, theo sau là khoảng trắng ở đầu dòng. mangle_from_ mặc định là giá trị cài đặt mangle_from_ của policy (là True cho chính sách compat32 và False cho tất cả các chính sách khác). mangle_from_ được thiết kế để sử dụng khi tin nhắn được lưu trữ ở định dạng Unix mbox (xem mailbox và WHY THE CONTENT-LENGTH FORMAT IS BAD).

Nếu maxheaderlen không phải là None, hãy gấp lại bất kỳ dòng tiêu đề nào dài hơn maxheaderlen hoặc nếu 0, đừng gói lại bất kỳ tiêu đề nào. Nếu manheaderlen là None (mặc định), hãy gói tiêu đề và các dòng thông báo khác theo cài đặt policy.

Nếu policy được chỉ định, hãy sử dụng chính sách đó để kiểm soát việc tạo thông báo. Nếu policy là None (mặc định), hãy sử dụng chính sách được liên kết với đối tượng Message hoặc EmailMessage được truyền cho flatten để kiểm soát việc tạo thông báo. Xem email.policy để biết chi tiết về những gì policy điều khiển.

Added in version 3.2.

Thay đổi trong phiên bản 3.3: Đã thêm từ khóa policy.

Thay đổi trong phiên bản 3.6: Hành vi mặc định của các tham số mangle_from_ và maxheaderlen là tuân theo chính sách.

flatten(msg, unixfrom=False, linesep=None)

In bản trình bày văn bản của cấu trúc đối tượng thông báo bắt nguồn từ msg vào tệp đầu ra được chỉ định khi phiên bản BytesGenerator được tạo.

Nếu tùy chọn policy cte_type là 8bit (mặc định), hãy sao chép mọi tiêu đề trong thông báo được phân tích cú pháp ban đầu chưa được sửa đổi thành đầu ra với bất kỳ byte nào có tập bit cao được sao chép như trong bản gốc và giữ nguyên Content-Transfer-Encoding không phải ASCII của bất kỳ bộ phận cơ thể nào có chúng. Nếu cte_type là 7bit, hãy chuyển đổi các byte có bit cao được đặt nếu cần bằng cách sử dụng Content-Transfer-Encoding tương thích với ASCII. Tức là chuyển đổi các phần có Content-Transfer-Encoding không phải ASCII (Content-Transfer-Encoding: 8bit) thành Content-Transfer-Encoding tương thích với ASCII và mã hóa các byte không phải ASCII không hợp lệ RFC trong tiêu đề bằng cách sử dụng bộ ký tự MIME unknown-8bit, từ đó hiển thị chúng tuân thủ RFC.

Nếu unixfrom là True, hãy in dấu phân cách tiêu đề phong bì được sử dụng bởi định dạng hộp thư Unix (xem mailbox) trước tiêu đề RFC 5322 đầu tiên của đối tượng thư gốc. Nếu đối tượng gốc không có tiêu đề phong bì, hãy tạo một tiêu đề tiêu chuẩn. Mặc định là False. Lưu ý rằng đối với các phần phụ, không có tiêu đề phong bì nào được in.

Nếu linesep không phải là None, hãy sử dụng nó làm ký tự phân cách giữa tất cả các dòng của thông báo được làm phẳng. Nếu linesep là None (mặc định), hãy sử dụng giá trị được chỉ định trong policy.

clone(fp)

Trả về một bản sao độc lập của phiên bản BytesGenerator này với các cài đặt tùy chọn giống hệt nhau và fp là outfp mới.

write(s)

Mã hóa s bằng cách sử dụng codec ASCII và trình xử lý lỗi surrogateescape, đồng thời chuyển nó sang phương thức write của outfp được truyền cho hàm tạo của BytesGenerator.

Để thuận tiện, EmailMessage cung cấp các phương thức as_bytes() và bytes(aMessage) (còn gọi là __bytes__()), giúp đơn giản hóa việc tạo biểu diễn nhị phân được tuần tự hóa của một đối tượng thông báo. Để biết thêm chi tiết, xem email.message.

Vì các chuỗi không thể biểu thị dữ liệu nhị phân nên lớp Generator phải chuyển đổi bất kỳ dữ liệu nhị phân nào trong bất kỳ thông báo nào mà nó chuyển sang định dạng tương thích với ASCII, bằng cách chuyển đổi chúng thành Content-Transfer_Encoding tương thích với ASCII. Sử dụng thuật ngữ của RFC email, bạn có thể coi đây là Generator tuần tự hóa thành luồng I/O không "sạch 8 bit". Nói cách khác, hầu hết các ứng dụng sẽ muốn sử dụng BytesGenerator chứ không phải Generator.

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Trả về một đối tượng Generator sẽ ghi bất kỳ thông báo nào được cung cấp cho phương thức flatten() hoặc bất kỳ văn bản nào được cung cấp cho phương thức write(), cho file-like object outfp. outfp phải hỗ trợ phương thức write chấp nhận dữ liệu chuỗi.

Nếu mangle_from_ tùy chọn là True, hãy đặt ký tự > trước bất kỳ dòng nào trong nội dung bắt đầu bằng chuỗi chính xác "From ", tức là From, theo sau là khoảng trắng ở đầu dòng. mangle_from_ mặc định là giá trị cài đặt mangle_from_ của policy (là True cho chính sách compat32 và False cho tất cả các chính sách khác). mangle_from_ được thiết kế để sử dụng khi tin nhắn được lưu trữ ở định dạng Unix mbox (xem mailbox và WHY THE CONTENT-LENGTH FORMAT IS BAD).

Nếu maxheaderlen không phải là None, hãy gấp lại bất kỳ dòng tiêu đề nào dài hơn maxheaderlen hoặc nếu 0, đừng gói lại bất kỳ tiêu đề nào. Nếu manheaderlen là None (mặc định), hãy gói tiêu đề và các dòng thông báo khác theo cài đặt policy.

Nếu policy được chỉ định, hãy sử dụng chính sách đó để kiểm soát việc tạo thông báo. Nếu policy là None (mặc định), hãy sử dụng chính sách được liên kết với đối tượng Message hoặc EmailMessage được truyền cho flatten để kiểm soát việc tạo thông báo. Xem email.policy để biết chi tiết về những gì policy điều khiển.

Thay đổi trong phiên bản 3.3: Đã thêm từ khóa policy.

Thay đổi trong phiên bản 3.6: Hành vi mặc định của các tham số mangle_from_ và maxheaderlen là tuân theo chính sách.

flatten(msg, unixfrom=False, linesep=None)

In bản trình bày văn bản của cấu trúc đối tượng thông báo bắt nguồn từ msg vào tệp đầu ra được chỉ định khi phiên bản Generator được tạo.

Nếu tùy chọn policy cte_type là 8bit, hãy tạo thông báo như thể tùy chọn được đặt thành 7bit. (Điều này là bắt buộc vì các chuỗi không thể biểu thị các byte không phải ASCII.) Chuyển đổi bất kỳ byte nào có bit cao được đặt nếu cần bằng cách sử dụng Content-Transfer-Encoding tương thích với ASCII. Tức là chuyển đổi các phần có Content-Transfer-Encoding không phải ASCII (Content-Transfer-Encoding: 8bit) thành Content-Transfer-Encoding tương thích với ASCII và mã hóa các byte không phải ASCII không hợp lệ RFC trong tiêu đề bằng cách sử dụng bộ ký tự MIME unknown-8bit, từ đó hiển thị chúng tuân thủ RFC.

Nếu unixfrom là True, hãy in dấu phân cách tiêu đề phong bì được sử dụng bởi định dạng hộp thư Unix (xem mailbox) trước tiêu đề RFC 5322 đầu tiên của đối tượng thư gốc. Nếu đối tượng gốc không có tiêu đề phong bì, hãy tạo một tiêu đề tiêu chuẩn. Mặc định là False. Lưu ý rằng đối với các phần phụ, không có tiêu đề phong bì nào được in.

Nếu linesep không phải là None, hãy sử dụng nó làm ký tự phân cách giữa tất cả các dòng của thông báo được làm phẳng. Nếu linesep là None (mặc định), hãy sử dụng giá trị được chỉ định trong policy.

Thay đổi trong phiên bản 3.2: Đã thêm hỗ trợ mã hóa lại nội dung thư 8bit và đối số linesep.

clone(fp)

Trả về một bản sao độc lập của phiên bản Generator này với các tùy chọn giống hệt nhau và fp là outfp mới.

write(s)

Viết s vào phương thức write của outfp được truyền cho hàm tạo của Generator. Điều này cung cấp vừa đủ API giống như tệp để các phiên bản Generator được sử dụng trong hàm print().

Để thuận tiện, EmailMessage cung cấp các phương thức as_string() và str(aMessage) (còn gọi là __str__()), giúp đơn giản hóa việc tạo biểu diễn chuỗi được định dạng của đối tượng thông báo. Để biết thêm chi tiết, xem email.message.

Mô-đun email.generator cũng cung cấp một lớp dẫn xuất, DecodedGenerator, giống như lớp cơ sở Generator, ngoại trừ các phần không phải text không được tuần tự hóa mà thay vào đó được biểu thị trong luồng đầu ra bằng một chuỗi bắt nguồn từ một mẫu chứa đầy thông tin về phần đó.

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Hoạt động giống như Generator, ngoại trừ đối với bất kỳ phần phụ nào của tin nhắn được chuyển đến Generator.flatten(), nếu phần phụ thuộc loại chính text, hãy in tải trọng đã giải mã của phần phụ và nếu loại chính không phải là text, thay vì in, hãy điền vào chuỗi fmt bằng cách sử dụng thông tin từ phần đó và in chuỗi đã điền kết quả.

Để điền fmt, hãy thực thi fmt % part_info, trong đó part_info là một từ điển bao gồm các khóa và giá trị sau:

  • type -- Loại MIME đầy đủ của phần không phảitext

  • maintype -- Loại MIME chính của phần không phảitext

  • subtype -- Loại phụ MIME của phần không phảitext

  • filename -- Tên tệp của phần không phảitext

  • description -- Mô tả được liên kết với phần không phải:mimetype:text

  • encoding -- Mã hóa truyền nội dung của phần không phảitext

Nếu fmt là None, hãy sử dụng fmt mặc định sau:

"[Phần không phải văn bản (%(type)s) của tin nhắn bị bỏ qua, tên tệp %(tên tệp)s]"

_mangle_from_ và maxheaderlen tùy chọn giống như với lớp cơ sở Generator.

Chú thích cuối trang