email.mime: Tạo email và đối tượng MIME từ đầu

Source code: Lib/email/mime/

Mô-đun này là một phần của email API cũ (Compat32). Chức năng của nó được thay thế một phần bằng contentmanager trong API mới, nhưng trong một số ứng dụng nhất định, các lớp này vẫn có thể hữu ích, ngay cả trong mã không kế thừa.

Thông thường, bạn nhận được cấu trúc đối tượng thông báo bằng cách chuyển một tệp hoặc một số văn bản tới trình phân tích cú pháp, trình phân tích cú pháp này sẽ phân tích văn bản và trả về đối tượng thông báo gốc. Tuy nhiên, bạn cũng có thể xây dựng cấu trúc thông báo hoàn chỉnh từ đầu hoặc thậm chí các đối tượng Message riêng lẻ bằng tay. Trên thực tế, bạn cũng có thể lấy cấu trúc hiện có và thêm các đối tượng Message mới, di chuyển chúng xung quanh, v.v. Điều này tạo ra một giao diện rất thuận tiện cho việc cắt và cắt các thông báo MIME.

Bạn có thể tạo cấu trúc đối tượng mới bằng cách tạo các phiên bản Message, thêm tệp đính kèm và tất cả các tiêu đề thích hợp theo cách thủ công. Tuy nhiên, đối với các tin nhắn MIME, gói email cung cấp một số lớp con tiện lợi để giúp mọi việc dễ dàng hơn.

Dưới đây là các lớp học:

class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)

Mô-đun: email.mime.base

Đây là lớp cơ sở cho tất cả các lớp con dành riêng cho MIME của Message. Thông thường, bạn sẽ không tạo các phiên bản cụ thể của MIMEBase, mặc dù bạn có thể. MIMEBase được cung cấp chủ yếu dưới dạng lớp cơ sở thuận tiện cho các lớp con nhận biết MIME cụ thể hơn.

_maintype là loại Content-Type chính (ví dụ: text hoặc image) và _subtype là loại phụ Content-Type (ví dụ: plain hoặc gif). _params là từ điển khóa/giá trị tham số và được truyền trực tiếp tới Message.add_header.

Nếu policy được chỉ định, (mặc định là chính sách compat32), nó sẽ được chuyển tới Message.

Lớp MIMEBase luôn thêm tiêu đề Content-Type (dựa trên _maintype, _subtype và _params) và tiêu đề MIME-Version (luôn được đặt thành 1.0).

Thay đổi trong phiên bản 3.6: Đã thêm tham số chỉ từ khóa policy.

class email.mime.nonmultipart.MIMENonMultipart

Mô-đun: email.mime.nonmultipart

Một lớp con của MIMEBase, đây là lớp cơ sở trung gian dành cho các tin nhắn MIME không phải là multipart. Mục đích chính của lớp này là ngăn chặn việc sử dụng phương thức attach(), phương thức này chỉ có ý nghĩa đối với các tin nhắn multipart. Nếu attach() được gọi, một ngoại lệ MultipartConversionError sẽ xuất hiện.

class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

Mô-đun: email.mime.multipart

Một lớp con của MIMEBase, đây là lớp cơ sở trung gian cho các tin nhắn MIME là multipart. _subtype tùy chọn mặc định là mixed, nhưng có thể được sử dụng để chỉ định loại phụ của tin nhắn. Tiêu đề Content-Type của multipart/_subtype sẽ được thêm vào đối tượng tin nhắn. Tiêu đề MIME-Version cũng sẽ được thêm vào.

boundary tùy chọn là chuỗi ranh giới nhiều phần. Khi None (mặc định), ranh giới được tính khi cần (ví dụ: khi tin nhắn được tuần tự hóa).

_subparts là một chuỗi các phần phụ ban đầu dành cho tải trọng. Phải có khả năng chuyển đổi chuỗi này thành một danh sách. Bạn luôn có thể đính kèm các phần phụ mới vào tin nhắn bằng phương pháp Message.attach.

Đối số policy tùy chọn mặc định là compat32.

Các tham số bổ sung cho tiêu đề Content-Type được lấy từ các đối số từ khóa hoặc được chuyển vào đối số _params, là một từ điển từ khóa.

Thay đổi trong phiên bản 3.6: Đã thêm tham số chỉ từ khóa policy.

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Mô-đun: email.mime.application

Một lớp con của MIMENonMultipart, lớp MIMEApplication được sử dụng để biểu diễn các đối tượng thông báo MIME thuộc loại chính application. _data chứa các byte cho dữ liệu ứng dụng thô. _subtype tùy chọn chỉ định loại phụ MIME và mặc định là octet-stream.

_encoder tùy chọn là một hàm có thể gọi được (tức là hàm) sẽ thực hiện mã hóa thực tế dữ liệu để truyền tải. Lệnh gọi này nhận một đối số, đó là phiên bản MIMEApplication. Nó nên sử dụng get_payload() và set_payload() để thay đổi tải trọng sang dạng được mã hóa. Nó cũng nên thêm bất kỳ Content-Transfer-Encoding hoặc các tiêu đề khác vào đối tượng tin nhắn nếu cần. Mã hóa mặc định là base64. Xem mô-đun email.encoders để biết danh sách các bộ mã hóa tích hợp.

Đối số policy tùy chọn mặc định là compat32.

_params được chuyển thẳng tới hàm tạo của lớp cơ sở.

Thay đổi trong phiên bản 3.6: Đã thêm tham số chỉ từ khóa policy.

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Mô-đun: email.mime.audio

Một lớp con của MIMENonMultipart, lớp MIMEAudio được sử dụng để tạo các đối tượng thông báo MIME thuộc loại chính audio. _audiodata chứa các byte cho dữ liệu âm thanh thô. Nếu dữ liệu này có thể được giải mã dưới dạng au, wav, aiff hoặc aifc thì loại phụ sẽ tự động được đưa vào tiêu đề Content-Type. Nếu không, bạn có thể chỉ định rõ ràng loại phụ âm thanh thông qua đối số _subtype. Nếu không thể đoán được loại phụ và _subtype không được đưa ra thì TypeError sẽ được nâng lên.

_encoder tùy chọn là một chức năng có thể gọi được (tức là chức năng) sẽ thực hiện mã hóa thực tế dữ liệu âm thanh để truyền tải. Lệnh gọi này nhận một đối số, đó là phiên bản MIMEAudio. Nó nên sử dụng get_payload() và set_payload() để thay đổi tải trọng sang dạng được mã hóa. Nó cũng nên thêm bất kỳ Content-Transfer-Encoding hoặc các tiêu đề khác vào đối tượng tin nhắn nếu cần. Mã hóa mặc định là base64. Xem mô-đun email.encoders để biết danh sách các bộ mã hóa tích hợp.

Đối số policy tùy chọn mặc định là compat32.

_params được chuyển thẳng tới hàm tạo của lớp cơ sở.

Thay đổi trong phiên bản 3.6: Đã thêm tham số chỉ từ khóa policy.

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Mô-đun: email.mime.image

Một lớp con của MIMENonMultipart, lớp MIMEImage được sử dụng để tạo các đối tượng thông báo MIME thuộc loại chính image. _imagedata chứa các byte cho dữ liệu hình ảnh thô. Nếu loại dữ liệu này có thể được phát hiện (đã thử jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, rast, xbm, bmp, webp và exr), thì loại phụ sẽ tự động được đưa vào tiêu đề Content-Type. Nếu không, bạn có thể chỉ định rõ ràng loại hình ảnh phụ thông qua đối số _subtype. Nếu không thể đoán được loại phụ và _subtype không được đưa ra thì TypeError sẽ được nâng lên.

_encoder tùy chọn là một hàm có thể gọi được (tức là hàm) sẽ thực hiện mã hóa thực tế dữ liệu hình ảnh để truyền tải. Lệnh gọi này nhận một đối số, đó là phiên bản MIMEImage. Nó nên sử dụng get_payload() và set_payload() để thay đổi tải trọng sang dạng được mã hóa. Nó cũng nên thêm bất kỳ Content-Transfer-Encoding hoặc các tiêu đề khác vào đối tượng tin nhắn nếu cần. Mã hóa mặc định là base64. Xem mô-đun email.encoders để biết danh sách các bộ mã hóa tích hợp.

Đối số policy tùy chọn mặc định là compat32.

_params được chuyển thẳng tới hàm tạo MIMEBase.

Thay đổi trong phiên bản 3.6: Đã thêm tham số chỉ từ khóa policy.

class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)

Mô-đun: email.mime.message

Một lớp con của MIMENonMultipart, lớp MIMEMessage được sử dụng để tạo các đối tượng MIME thuộc loại chính message. _msg được sử dụng làm tải trọng và phải là một phiên bản của lớp Message (hoặc một lớp con của lớp đó), nếu không thì TypeError sẽ được nâng lên.

Tùy chọn _subtype đặt loại phụ của tin nhắn; nó mặc định là rfc822.

Đối số policy tùy chọn mặc định là compat32.

Thay đổi trong phiên bản 3.6: Đã thêm tham số chỉ từ khóa policy.

class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)

Mô-đun: email.mime.text

Một lớp con của MIMENonMultipart, lớp MIMEText được sử dụng để tạo các đối tượng MIME thuộc loại chính text. _text là chuỗi cho tải trọng. _subtype là loại nhỏ và mặc định là plain. _charset là bộ ký tự của văn bản và được truyền dưới dạng đối số cho hàm tạo MIMENonMultipart; nó mặc định là us-ascii nếu chuỗi chỉ chứa các điểm mã ascii và utf-8 nếu không. Tham số _charset chấp nhận một chuỗi hoặc một phiên bản Charset.

Trừ khi đối số _charset được đặt rõ ràng thành None, đối tượng MIMEText được tạo sẽ có cả tiêu đề Content-Type với tham số charset và tiêu đề Content-Transfer-Encoding. Điều này có nghĩa là lệnh gọi set_payload tiếp theo sẽ không dẫn đến tải trọng được mã hóa, ngay cả khi bộ ký tự được truyền trong lệnh set_payload. Bạn có thể "đặt lại" hành vi này bằng cách xóa tiêu đề Content-Transfer-Encoding, sau đó lệnh gọi set_payload sẽ tự động mã hóa tải trọng mới (và thêm tiêu đề Content-Transfer-Encoding mới).

Đối số policy tùy chọn mặc định là compat32.

Thay đổi trong phiên bản 3.5: _charset cũng chấp nhận các phiên bản Charset.

Thay đổi trong phiên bản 3.6: Đã thêm tham số chỉ từ khóa policy.