email.contentmanager: Quản lý nội dung MIME

Source code: Lib/email/contentmanager.py

Added in version 3.6: [1]

class email.contentmanager.ContentManager

Lớp cơ sở dành cho người quản lý nội dung. Cung cấp các cơ chế đăng ký tiêu chuẩn để đăng ký bộ chuyển đổi giữa nội dung MIME và các cách thể hiện khác, cũng như các phương thức gửi get_content và set_content.

get_content(msg, *args, **kw)

Tra cứu hàm xử lý dựa trên mimetype của msg (xem đoạn tiếp theo), gọi nó, chuyển qua tất cả các đối số và trả về kết quả của lệnh gọi. Kỳ vọng là trình xử lý sẽ trích xuất tải trọng từ msg và trả về một đối tượng mã hóa thông tin về dữ liệu được trích xuất.

Để tìm trình xử lý, hãy tìm các khóa sau trong sổ đăng ký, dừng lại ở khóa đầu tiên được tìm thấy:

  • chuỗi đại diện cho loại MIME đầy đủ (maintype/subtype)

  • chuỗi đại diện cho maintype

  • chuỗi trống

Nếu không có phím nào trong số này tạo ra trình xử lý, hãy tăng KeyError cho loại MIME đầy đủ.

set_content(msg, obj, *args, **kw)

Nếu maintype là multipart, hãy tăng TypeError; mặt khác, hãy tra cứu hàm xử lý dựa trên loại obj (xem đoạn tiếp theo), gọi clear_content() trên msg và gọi hàm xử lý, chuyển qua tất cả các đối số. Kỳ vọng là trình xử lý sẽ chuyển đổi và lưu trữ obj thành msg, có thể thực hiện các thay đổi khác đối với msg, chẳng hạn như thêm các tiêu đề MIME khác nhau để mã hóa thông tin cần thiết nhằm diễn giải dữ liệu được lưu trữ.

Để tìm trình xử lý, hãy lấy loại obj (typ = type(obj)) và tìm các khóa sau trong sổ đăng ký, dừng lại ở khóa đầu tiên được tìm thấy:

  • chính loại đó (typ)

  • tên đầy đủ của loại (typ.__module__ + '.' + typ.__qualname__).

  • loại qualname (typ.__qualname__)

  • loại name (typ.__name__).

Nếu không có kết quả nào ở trên khớp, hãy lặp lại tất cả các bước kiểm tra ở trên cho từng loại trong MRO (typ.__mro__). Cuối cùng, nếu không có khóa nào khác tạo ra trình xử lý, hãy kiểm tra trình xử lý cho khóa None. Nếu không có trình xử lý nào cho None, hãy tăng KeyError cho tên đủ điều kiện của loại.

Đồng thời thêm tiêu đề MIME-Version nếu không có tiêu đề này (xem thêm MIMEPart).

add_get_handler(key, handler)

Ghi lại hàm handler làm trình xử lý cho key. Để biết các giá trị có thể có của key, hãy xem get_content().

add_set_handler(typekey, handler)

Ghi lại handler làm hàm để gọi khi một đối tượng thuộc loại khớp với typekey được chuyển tới set_content(). Để biết các giá trị có thể có của typekey, hãy xem set_content().

Phiên bản trình quản lý nội dung

Hiện tại gói email chỉ cung cấp một trình quản lý nội dung cụ thể, raw_data_manager, mặc dù trong tương lai có thể bổ sung thêm nhiều trình quản lý nội dung hơn. raw_data_manager là content_manager được cung cấp bởi EmailPolicy và các dẫn xuất của nó.

email.contentmanager.raw_data_manager

Trình quản lý nội dung này chỉ cung cấp một giao diện tối thiểu ngoài giao diện do chính Message cung cấp: nó chỉ xử lý văn bản, chuỗi byte thô và các đối tượng Message. Tuy nhiên, nó mang lại những lợi thế đáng kể so với API cơ sở: get_content trên một phần văn bản sẽ trả về một chuỗi unicode mà không cần ứng dụng giải mã thủ công, set_content cung cấp một bộ tùy chọn phong phú để kiểm soát các tiêu đề được thêm vào một phần và kiểm soát mã hóa truyền nội dung, đồng thời cho phép sử dụng các phương thức add_ khác nhau, từ đó đơn giản hóa việc tạo các tin nhắn nhiều phần.

email.contentmanager.get_content(msg, errors='replace')

Trả về tải trọng của bộ phận dưới dạng chuỗi (đối với các bộ phận text), đối tượng EmailMessage (đối với bộ phận message/rfc822) hoặc đối tượng bytes (đối với tất cả các loại không có nhiều bộ phận khác). Tăng KeyError nếu được gọi trên multipart. Nếu phần này là phần text và errors được chỉ định, hãy sử dụng phần đó làm trình xử lý lỗi khi giải mã tải trọng sang unicode. Trình xử lý lỗi mặc định là replace.

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

Thêm tiêu đề và tải trọng vào msg:

Thêm tiêu đề Content-Type với giá trị maintype/subtype.

  • Đối với str, đặt MIME maintype thành text và đặt loại phụ thành subtype nếu được chỉ định hoặc plain nếu không được chỉ định.

  • Đối với bytes, hãy sử dụng maintype và subtype được chỉ định hoặc tăng TypeError nếu chúng không được chỉ định.

  • Đối với các đối tượng EmailMessage, hãy đặt loại chính thành message và đặt loại phụ thành subtype nếu được chỉ định hoặc rfc822 nếu không được chỉ định. Nếu subtype là partial, hãy đưa ra lỗi (phải sử dụng các đối tượng bytes để xây dựng các bộ phận message/partial).

Nếu charset được cung cấp (chỉ hợp lệ cho str), hãy mã hóa chuỗi thành byte bằng cách sử dụng bộ ký tự được chỉ định. Mặc định là utf-8. Nếu charset được chỉ định là bí danh đã biết cho tên bộ ký tự MIME tiêu chuẩn, hãy sử dụng bộ ký tự tiêu chuẩn thay thế.

Nếu cte được đặt, hãy mã hóa tải trọng bằng mã hóa truyền nội dung được chỉ định và đặt tiêu đề Content-Transfer-Encoding thành giá trị đó. Các giá trị có thể có của cte là quoted-printable, base64, 7bit, 8bit và binary. Nếu đầu vào không thể được mã hóa theo mã hóa đã chỉ định (ví dụ: chỉ định cte của 7bit cho đầu vào chứa các giá trị không phải ASCII), hãy tăng ValueError.

  • Đối với các đối tượng str, nếu cte không được đặt, hãy sử dụng phương pháp phỏng đoán để xác định mã hóa nhỏ gọn nhất. Trước khi mã hóa, str.splitlines() được sử dụng để chuẩn hóa tất cả các ranh giới dòng, đảm bảo rằng mỗi dòng của tải trọng đều bị chấm dứt bởi thuộc tính linesep của chính sách hiện tại (ngay cả khi chuỗi gốc không kết thúc bằng một).

  • Đối với các đối tượng bytes, cte được coi là base64 nếu không được đặt và bản dịch dòng mới nói trên sẽ không được thực hiện.

  • Đối với EmailMessage, mỗi RFC 2046, sẽ phát sinh lỗi nếu yêu cầu cte của quoted-printable hoặc base64 cho subtype rfc822 và đối với bất kỳ cte nào ngoài 7bit cho subtype external-body. Đối với message/rfc822, hãy sử dụng 8bit nếu cte không được chỉ định. Đối với tất cả các giá trị khác của subtype, hãy sử dụng 7bit.

Ghi chú

Một cte của binary chưa thực sự hoạt động chính xác. Đối tượng EmailMessage được sửa đổi bởi set_content là chính xác, nhưng BytesGenerator không tuần tự hóa nó một cách chính xác.

Nếu disposition được đặt, hãy sử dụng nó làm giá trị của tiêu đề Content-Disposition. Nếu không được chỉ định và filename được chỉ định, hãy thêm tiêu đề có giá trị attachment. Nếu disposition không được chỉ định và filename cũng không được chỉ định, đừng thêm tiêu đề. Các giá trị hợp lệ duy nhất cho disposition là attachment và inline.

Nếu filename được chỉ định, hãy sử dụng nó làm giá trị của tham số filename của tiêu đề Content-Disposition.

Nếu cid được chỉ định, hãy thêm tiêu đề Content-ID với cid làm giá trị.

Nếu params được chỉ định, hãy lặp lại phương thức items của nó và sử dụng các cặp (key, value) thu được để đặt các tham số bổ sung trên tiêu đề Content-Type.

Nếu headers được chỉ định và là danh sách các chuỗi có dạng headername: headervalue hoặc danh sách các đối tượng header (được phân biệt với các chuỗi bằng cách có thuộc tính name), hãy thêm tiêu đề vào msg.

Chú thích cuối trang