email.charset: Đại diện cho bộ ký tự

Source code: Lib/email/charset.py

Mô-đun này là một phần của email API cũ (Compat32). Trong API mới chỉ sử dụng bảng bí danh.

Văn bản còn lại trong phần này là tài liệu gốc của mô-đun.

Mô-đun này cung cấp một lớp Charset để thể hiện các bộ ký tự và chuyển đổi bộ ký tự trong thông báo email, cũng như một sổ đăng ký bộ ký tự và một số phương pháp thuận tiện để thao tác sổ đăng ký này. Các phiên bản của Charset được sử dụng trong một số mô-đun khác trong gói email.

Nhập lớp này từ mô-đun email.charset.

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

Ánh xạ các bộ ký tự vào thuộc tính email của chúng.

Lớp này cung cấp thông tin về các yêu cầu áp đặt đối với email đối với một bộ ký tự cụ thể. Nó cũng cung cấp các quy trình thuận tiện để chuyển đổi giữa các bộ ký tự, dựa trên sự sẵn có của các codec hiện hành. Với một bộ ký tự được cung cấp, nó sẽ cố gắng hết sức để cung cấp thông tin về cách sử dụng bộ ký tự đó trong thư email theo cách tuân thủ RFC.

Một số bộ ký tự nhất định phải được mã hóa bằng mã có thể in được trích dẫn hoặc base64 khi được sử dụng trong tiêu đề hoặc nội dung email. Một số bộ ký tự nhất định phải được chuyển đổi hoàn toàn và không được phép sử dụng trong email.

input_charset tùy chọn như được mô tả bên dưới; nó luôn bị ép viết thường. Sau khi được chuẩn hóa bí danh, nó cũng được sử dụng để tra cứu sổ đăng ký các bộ ký tự để tìm ra mã hóa tiêu đề, mã hóa nội dung và codec chuyển đổi đầu ra sẽ được sử dụng cho bộ ký tự. Ví dụ: nếu input_charset là iso-8859-1 thì tiêu đề và nội dung sẽ được mã hóa bằng cách sử dụng dấu ngoặc kép có thể in được và không cần codec chuyển đổi đầu ra. Nếu input_charset là euc-jp thì các tiêu đề sẽ được mã hóa bằng base64, nội dung sẽ không được mã hóa nhưng văn bản đầu ra sẽ được chuyển đổi từ bộ ký tự euc-jp thành bộ ký tự iso-2022-jp.

Các phiên bản Charset có các thuộc tính dữ liệu sau:

input_charset

Bộ ký tự ban đầu được chỉ định. Các bí danh phổ biến được chuyển đổi thành tên email official (ví dụ: latin_1 được chuyển đổi thành iso-8859-1). Mặc định là us-ascii 7 bit.

header_encoding

Nếu bộ ký tự phải được mã hóa trước khi có thể sử dụng trong tiêu đề email thì thuộc tính này sẽ được đặt thành charset.QP (đối với mã hóa có thể in được trích dẫn), charset.BASE64 (đối với mã hóa base64) hoặc charset.SHORTEST đối với mã hóa QP hoặc BASE64 ngắn nhất. Nếu không thì sẽ là None.

body_encoding

Tương tự như header_encoding, nhưng mô tả mã hóa cho nội dung thư, thực tế có thể khác với mã hóa tiêu đề. charset.SHORTEST không được phép đối với body_encoding.

output_charset

Một số bộ ký tự phải được chuyển đổi trước khi chúng có thể được sử dụng trong tiêu đề hoặc nội dung email. Nếu input_charset là một trong số đó, thuộc tính này sẽ chứa tên của bộ ký tự đầu ra sẽ được chuyển đổi thành. Nếu không thì sẽ là None.

input_codec

Tên của codec Python được sử dụng để chuyển đổi input_charset sang Unicode. Nếu không cần codec chuyển đổi thì thuộc tính này sẽ là None.

output_codec

Tên của codec Python được sử dụng để chuyển đổi Unicode sang output_charset. Nếu không cần codec chuyển đổi thì thuộc tính này sẽ có cùng giá trị với input_codec.

Các phiên bản Charset cũng có các phương thức sau:

get_body_encoding()

Trả về mã hóa truyền nội dung được sử dụng để mã hóa nội dung.

Đây là chuỗi quoted-printable hoặc base64 tùy thuộc vào mã hóa được sử dụng hoặc đây là một hàm, trong trường hợp đó bạn nên gọi hàm với một đối số duy nhất, đối tượng Message đang được mã hóa. Sau đó, hàm sẽ tự đặt tiêu đề Content-Transfer-Encoding thành bất cứ thứ gì phù hợp.

Trả về chuỗi quoted-printable nếu body_encoding là QP, trả về chuỗi base64 nếu body_encoding là BASE64 và trả về chuỗi 7bit nếu ngược lại.

get_output_charset()

Trả về bộ ký tự đầu ra.

Đây là thuộc tính output_charset nếu đó không phải là None, nếu không thì là input_charset.

header_encode(string)

Tiêu đề-mã hóa chuỗi string.

Loại mã hóa (base64 hoặc có thể in được trong trích dẫn) sẽ dựa trên thuộc tính header_encoding.

header_encode_lines(string, maxlengths)

Tiêu đề mã hóa string bằng cách chuyển đổi nó thành byte trước tiên.

Điều này tương tự với header_encode() ngoại trừ việc chuỗi phù hợp với độ dài dòng tối đa như được đưa ra bởi đối số maxlengths, phải là một trình lặp: mỗi phần tử được trả về từ trình lặp này sẽ cung cấp độ dài dòng tối đa tiếp theo.

body_encode(string)

Mã hóa nội dung chuỗi string.

Loại mã hóa (base64 hoặc có thể in được trong trích dẫn) sẽ dựa trên thuộc tính body_encoding.

Lớp Charset cũng cung cấp một số phương thức để hỗ trợ các hoạt động tiêu chuẩn và các hàm dựng sẵn.

__str__()

Trả về input_charset dưới dạng một chuỗi được chuyển thành chữ thường. __repr__() là bí danh của __str__().

__eq__(other)

Phương pháp này cho phép bạn so sánh hai trường hợp Charset về sự bằng nhau.

__ne__(other)

Phương pháp này cho phép bạn so sánh hai trường hợp Charset về sự bất bình đẳng.

Mô-đun email.charset cũng cung cấp các chức năng sau để thêm các mục mới vào bộ ký tự chung, bí danh và đăng ký codec:

email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)

Thêm thuộc tính ký tự vào sổ đăng ký chung.

charset là bộ ký tự đầu vào và phải là tên chuẩn của bộ ký tự.

header_enc và body_enc tùy chọn là charset.QP cho mã hóa có thể in được trích dẫn, charset.BASE64 cho mã hóa base64, charset.SHORTEST cho mã hóa có thể in được trích dẫn hoặc base64 ngắn nhất hoặc None cho không mã hóa. SHORTEST chỉ hợp lệ cho header_enc. Mặc định là None không có mã hóa.

output_charset tùy chọn là bộ ký tự mà đầu ra phải có. Quá trình chuyển đổi sẽ tiến hành từ bộ ký tự đầu vào, sang Unicode, sang bộ ký tự đầu ra khi phương thức Charset.convert() được gọi. Giá trị mặc định là đầu ra có cùng bộ ký tự với đầu vào.

Cả input_charset và output_charset đều phải có các mục nhập codec Unicode trong ánh xạ bộ ký tự thành codec của mô-đun; sử dụng add_codec() để thêm codec mà mô-đun không biết. Xem tài liệu của mô-đun codecs để biết thêm thông tin.

Sổ đăng ký bộ ký tự chung được lưu giữ trong từ điển toàn cầu của mô-đun CHARSETS.

email.charset.add_alias(alias, canonical)

Thêm bí danh bộ ký tự. alias là tên bí danh, ví dụ: latin-1. canonical là tên chuẩn của bộ ký tự, ví dụ: iso-8859-1.

Sổ đăng ký bí danh bộ ký tự chung được lưu giữ trong từ điển toàn cầu của mô-đun ALIASES.

email.charset.add_codec(charset, codecname)

Thêm một codec ánh xạ các ký tự trong bộ ký tự đã cho sang và từ Unicode.

charset là tên chuẩn của bộ ký tự. codecname là tên của codec Python, phù hợp với đối số thứ hai của phương thức encode() của str.