codecs --- Đăng ký Codec và các lớp cơ sở

Source code: Lib/codecs.py

Mô-đun này xác định các lớp cơ sở cho codec Python tiêu chuẩn (bộ mã hóa và giải mã) và cung cấp quyền truy cập vào sổ đăng ký codec Python nội bộ, nơi quản lý quá trình tra cứu codec và xử lý lỗi. Hầu hết các codec tiêu chuẩn là text encodings, mã hóa văn bản thành byte (và giải mã byte thành văn bản), nhưng cũng có những codec cung cấp mã hóa văn bản thành văn bản và byte thành byte. Các codec tùy chỉnh có thể mã hóa và giải mã giữa các loại tùy ý, nhưng một số tính năng mô-đun bị hạn chế sử dụng cụ thể với text encodings hoặc với các codec mã hóa thành bytes.

Mô-đun xác định các chức năng sau để mã hóa và giải mã với bất kỳ codec nào:

codecs.encode(obj, encoding='utf-8', errors='strict')

Mã hóa obj bằng codec đã đăng ký cho encoding.

Errors có thể được cung cấp để thiết lập sơ đồ xử lý lỗi mong muốn. Trình xử lý lỗi mặc định là 'strict' có nghĩa là lỗi mã hóa sẽ gây ra ValueError (hoặc một lớp con cụ thể hơn về codec, chẳng hạn như UnicodeEncodeError). Tham khảo Các lớp cơ sở Codec để biết thêm thông tin về cách xử lý lỗi codec.

codecs.decode(obj, encoding='utf-8', errors='strict')

Giải mã obj bằng codec đã đăng ký cho encoding.

Errors có thể được cung cấp để thiết lập sơ đồ xử lý lỗi mong muốn. Trình xử lý lỗi mặc định là 'strict' có nghĩa là các lỗi giải mã sẽ gây ra ValueError (hoặc một lớp con cụ thể hơn về codec, chẳng hạn như UnicodeDecodeError). Tham khảo Các lớp cơ sở Codec để biết thêm thông tin về cách xử lý lỗi codec.

codecs.charmap_build(string)

Trả về ánh xạ phù hợp để mã hóa bằng mã hóa một byte tùy chỉnh. Cho một str string có tối đa 256 ký tự đại diện cho một bảng giải mã, sẽ trả về một đối tượng ánh xạ bên trong nhỏ gọn EncodingMap hoặc một thứ tự ký tự ánh xạ dictionary thành các giá trị byte. Tăng TypeError khi đầu vào không hợp lệ.

Chi tiết đầy đủ của từng codec cũng có thể được tra cứu trực tiếp:

codecs.lookup(encoding, /)

Tra cứu thông tin codec trong sổ đăng ký codec Python và trả về đối tượng CodecInfo như được xác định bên dưới.

Mã hóa lần đầu tiên được tra cứu trong bộ đệm của sổ đăng ký. Nếu không tìm thấy, danh sách các chức năng tìm kiếm đã đăng ký sẽ được quét. Nếu không tìm thấy đối tượng CodecInfo, LookupError sẽ được nâng lên. Nếu không, đối tượng CodecInfo sẽ được lưu trong bộ đệm và trả về cho người gọi.

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

Chi tiết codec khi tra cứu sổ đăng ký codec. Các đối số của hàm tạo được lưu trữ trong các thuộc tính có cùng tên:

name

Tên của mã hóa.

encode
decode

Các chức năng mã hóa và giải mã không trạng thái. Đây phải là các hàm hoặc phương thức có giao diện giống với phương thức encode() và decode() của các phiên bản Codec (xem Codec Interface). Các hàm hoặc phương thức dự kiến ​​sẽ hoạt động ở chế độ không trạng thái.

incrementalencoder
incrementaldecoder

Các lớp bộ mã hóa và giải mã gia tăng hoặc các hàm xuất xưởng. Chúng phải cung cấp giao diện được xác định bởi các lớp cơ sở IncrementalEncoder và IncrementalDecoder tương ứng. Các codec gia tăng có thể duy trì trạng thái.

streamwriter
streamreader

Truyền phát các lớp người viết và người đọc hoặc các chức năng của nhà máy. Chúng phải cung cấp giao diện được xác định bởi các lớp cơ sở StreamWriter và StreamReader tương ứng. Bộ giải mã luồng có thể duy trì trạng thái.

Để đơn giản hóa việc truy cập vào các thành phần codec khác nhau, mô-đun này cung cấp các chức năng bổ sung sử dụng lookup() để tra cứu codec:

codecs.getencoder(encoding)

Tra cứu codec cho mã hóa đã cho và trả về hàm mã hóa của nó.

Tăng LookupError trong trường hợp không tìm thấy mã hóa.

codecs.getdecoder(encoding)

Tra cứu codec cho mã hóa đã cho và trả về hàm giải mã của nó.

Tăng LookupError trong trường hợp không tìm thấy mã hóa.

codecs.getincrementalencoder(encoding)

Tra cứu codec cho mã hóa đã cho và trả về lớp bộ mã hóa gia tăng hoặc hàm xuất xưởng của nó.

Tăng LookupError trong trường hợp không tìm thấy mã hóa hoặc codec không hỗ trợ bộ mã hóa gia tăng.

codecs.getincrementaldecoder(encoding)

Tra cứu codec cho mã hóa đã cho và trả về lớp bộ giải mã gia tăng hoặc hàm xuất xưởng của nó.

Tăng LookupError trong trường hợp không tìm thấy mã hóa hoặc codec không hỗ trợ bộ giải mã tăng dần.

codecs.getreader(encoding)

Tra cứu codec cho mã hóa đã cho và trả về lớp StreamReader hoặc hàm xuất xưởng của nó.

Tăng LookupError trong trường hợp không tìm thấy mã hóa.

codecs.getwriter(encoding)

Tra cứu codec cho mã hóa đã cho và trả về lớp StreamWriter hoặc hàm xuất xưởng của nó.

Tăng LookupError trong trường hợp không tìm thấy mã hóa.

Codec tùy chỉnh được cung cấp bằng cách đăng ký chức năng tìm kiếm codec phù hợp:

codecs.register(search_function, /)

Đăng ký chức năng tìm kiếm codec. Các hàm tìm kiếm dự kiến ​​sẽ lấy một đối số, là tên mã hóa ở tất cả các chữ cái viết thường có dấu gạch ngang và dấu cách được chuyển đổi thành dấu gạch dưới và trả về một đối tượng CodecInfo. Trong trường hợp chức năng tìm kiếm không thể tìm thấy mã hóa nhất định, nó sẽ trả về None.

Thay đổi trong phiên bản 3.9: Dấu gạch nối và dấu cách được chuyển đổi thành dấu gạch dưới.

codecs.unregister(search_function, /)

Hủy đăng ký chức năng tìm kiếm codec và xóa bộ đệm của sổ đăng ký. Nếu chức năng tìm kiếm chưa được đăng ký, không làm gì cả.

Added in version 3.10.

Mặc dù open() tích hợp và mô-đun io liên quan là phương pháp được đề xuất để làm việc với các tệp văn bản được mã hóa, mô-đun này cung cấp các lớp và hàm tiện ích bổ sung cho phép sử dụng nhiều loại codec hơn khi làm việc với các tệp nhị phân:

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)

Mở tệp được mã hóa bằng cách sử dụng mode đã cho và trả về một phiên bản của StreamReaderWriter, cung cấp mã hóa/giải mã minh bạch. Chế độ file mặc định là 'r', nghĩa là mở file ở chế độ đọc.

Ghi chú

Nếu encoding không phải là None thì các tệp được mã hóa cơ bản luôn được mở ở chế độ nhị phân. Không có chuyển đổi tự động nào của '\n' được thực hiện khi đọc và viết. Đối số mode có thể là bất kỳ chế độ nhị phân nào được chấp nhận bởi hàm open() tích hợp; 'b' được tự động thêm vào.

encoding chỉ định mã hóa sẽ được sử dụng cho tệp. Bất kỳ mã hóa nào mã hóa và giải mã từ byte đều được cho phép và các loại dữ liệu được phương thức tệp hỗ trợ tùy thuộc vào codec được sử dụng.

errors có thể được cung cấp để xác định việc xử lý lỗi. Nó mặc định là 'strict', điều này khiến ValueError được nâng lên trong trường hợp xảy ra lỗi mã hóa.

buffering có ý nghĩa tương tự như đối với chức năng open() tích hợp. Nó mặc định là -1 có nghĩa là kích thước bộ đệm mặc định sẽ được sử dụng.

Thay đổi trong phiên bản 3.11: Chế độ 'U' đã bị loại bỏ.

Sắp loại bỏ từ phiên bản 3.14: codecs.open() đã được thay thế bởi open().

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')

Trả về một phiên bản StreamRecoder, một phiên bản được bao bọc của file cung cấp khả năng chuyển mã minh bạch. Tệp gốc bị đóng khi đóng phiên bản được gói.

Dữ liệu được ghi vào tệp được gói sẽ được giải mã theo data_encoding đã cho và sau đó được ghi vào tệp gốc dưới dạng byte bằng file_encoding. Byte đọc từ tệp gốc được giải mã theo file_encoding và kết quả được mã hóa bằng data_encoding.

Nếu file_encoding không được cung cấp, nó sẽ mặc định là data_encoding.

errors có thể được cung cấp để xác định việc xử lý lỗi. Nó mặc định là 'strict', điều này khiến ValueError được nâng lên trong trường hợp xảy ra lỗi mã hóa.

codecs.iterencode(iterator, encoding, errors='strict', **kwargs)

Sử dụng bộ mã hóa gia tăng để mã hóa lặp lại đầu vào do iterator cung cấp. iterator phải mang lại đối tượng str. Chức năng này là generator. Đối số errors (cũng như bất kỳ đối số từ khóa nào khác) được chuyển qua bộ mã hóa gia tăng.

Chức năng này yêu cầu codec chấp nhận các đối tượng văn bản str để mã hóa. Do đó, nó không hỗ trợ các bộ mã hóa byte-to-byte như base64_codec.

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)

Sử dụng bộ giải mã gia tăng để giải mã lặp lại đầu vào do iterator cung cấp. iterator phải mang lại đối tượng bytes. Chức năng này là generator. Đối số errors (cũng như bất kỳ đối số từ khóa nào khác) được chuyển tới bộ giải mã gia tăng.

Chức năng này yêu cầu codec chấp nhận đối tượng bytes để giải mã. Do đó, nó không hỗ trợ các bộ mã hóa chuyển văn bản thành văn bản như rot_13, mặc dù rot_13 có thể được sử dụng tương đương với iterencode().

codecs.readbuffer_encode(buffer, errors=None, /)

Trả về tuple chứa các byte thô của buffer, buffer-compatible object hoặc str (được mã hóa thành UTF-8 trước khi xử lý) và độ dài của chúng tính bằng byte.

Đối số errors bị bỏ qua.

>>> codecs.readbuffer_encode(b"Zito")
(b'Zito', 4)

Mô-đun này cũng cung cấp các hằng số sau rất hữu ích cho việc đọc và ghi vào các tệp phụ thuộc vào nền tảng:

codecs.BOM
codecs.BOM_BE
codecs.BOM_LE
codecs.BOM_UTF8
codecs.BOM_UTF16
codecs.BOM_UTF16_BE
codecs.BOM_UTF16_LE
codecs.BOM_UTF32
codecs.BOM_UTF32_BE
codecs.BOM_UTF32_LE

Các hằng số này xác định các chuỗi byte khác nhau, là các dấu thứ tự byte Unicode (BOM) cho một số bảng mã. Chúng được sử dụng trong luồng dữ liệu UTF-16 và UTF-32 để biểu thị thứ tự byte được sử dụng và trong UTF-8 dưới dạng chữ ký Unicode. BOM_UTF16 là BOM_UTF16_BE hoặc BOM_UTF16_LE tùy thuộc vào thứ tự byte gốc của nền tảng, BOM là bí danh của BOM_UTF16, BOM_LE cho BOM_UTF16_LE và BOM_BE cho BOM_UTF16_BE. Những cái khác đại diện cho BOM trong bảng mã UTF-8 và UTF-32.

Các lớp cơ sở Codec

Mô-đun codecs xác định một tập hợp các lớp cơ sở xác định giao diện để làm việc với các đối tượng codec và cũng có thể được sử dụng làm cơ sở cho việc triển khai codec tùy chỉnh.

Mỗi codec phải xác định bốn giao diện để có thể sử dụng nó như codec trong Python: bộ mã hóa không trạng thái, bộ giải mã không trạng thái, trình đọc luồng và trình ghi luồng. Trình đọc luồng và trình ghi thường sử dụng lại bộ mã hóa/giải mã không trạng thái để triển khai các giao thức tệp. Tác giả codec cũng cần xác định cách codec sẽ xử lý các lỗi mã hóa và giải mã.

Trình xử lý lỗi

Để đơn giản hóa và tiêu chuẩn hóa việc xử lý lỗi, codec có thể triển khai các sơ đồ xử lý lỗi khác nhau bằng cách chấp nhận đối số chuỗi errors:

>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German ß, ♬'

Các trình xử lý lỗi sau có thể được sử dụng với tất cả các codec Python Mã hóa tiêu chuẩn:

Giá trị

Ý nghĩa

'strict'

Tăng UnicodeError (hoặc một lớp con), đây là mặc định. Được triển khai trong strict_errors().

'ignore'

Bỏ qua dữ liệu không đúng định dạng và tiếp tục mà không cần thông báo thêm. Được triển khai trong ignore_errors().

'replace'

Thay thế bằng một điểm đánh dấu thay thế. Về mã hóa, sử dụng ? (ký tự ASCII). Khi giải mã, hãy sử dụng � (U+FFFD, REPLACEMENT CHARACTER chính thức). Được triển khai trong replace_errors().

'backslashreplace'

Thay thế bằng chuỗi thoát bị gạch chéo ngược. Về mã hóa, sử dụng dạng thập lục phân của điểm mã Unicode với các định dạng \xhh \uxxxx \Uxxxxxxxx. Khi giải mã, sử dụng dạng giá trị byte thập lục phân với định dạng \xhh. Được triển khai trong backslashreplace_errors().

'surrogateescape'

Khi giải mã, thay thế byte bằng mã thay thế riêng lẻ từ U+DC80 đến U+DCFF. Mã này sau đó sẽ được chuyển trở lại cùng một byte khi trình xử lý lỗi 'surrogateescape' được sử dụng khi mã hóa dữ liệu. (Xem PEP 383 để biết thêm.)

Các trình xử lý lỗi sau chỉ áp dụng được cho mã hóa (trong text encodings):

Giá trị

Ý nghĩa

'xmlcharrefreplace'

Thay thế bằng tham chiếu ký tự số XML/HTML, là dạng thập phân của điểm mã Unicode có định dạng &#num;. Được triển khai trong xmlcharrefreplace_errors().

'namereplace'

Thay thế bằng chuỗi thoát \N{...}, những gì xuất hiện trong dấu ngoặc nhọn là thuộc tính Tên từ Cơ sở dữ liệu ký tự Unicode. Được triển khai trong namereplace_errors().

Ngoài ra, trình xử lý lỗi sau đây dành riêng cho các codec đã cho:

Giá trị

Codec

Ý nghĩa

'surrogatepass'

utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le

Cho phép mã hóa và giải mã điểm mã thay thế (U+D800 - U+DFFF) như điểm mã thông thường. Mặt khác, các codec này coi sự hiện diện của điểm mã thay thế trong str là một lỗi.

Added in version 3.1: Trình xử lý lỗi 'surrogateescape' và 'surrogatepass'.

Thay đổi trong phiên bản 3.4: Trình xử lý lỗi 'surrogatepass' hiện hoạt động với codec utf-16* và utf-32*.

Added in version 3.5: Trình xử lý lỗi 'namereplace'.

Thay đổi trong phiên bản 3.5: Trình xử lý lỗi 'backslashreplace' hiện hoạt động với giải mã và dịch.

Tập hợp các giá trị được phép có thể được mở rộng bằng cách đăng ký trình xử lý lỗi có tên mới:

codecs.register_error(name, error_handler, /)

Đăng ký chức năng xử lý lỗi error_handler dưới tên name. Đối số error_handler sẽ được gọi trong quá trình mã hóa và giải mã trong trường hợp xảy ra lỗi, khi name được chỉ định làm tham số lỗi.

Để mã hóa, error_handler sẽ được gọi với phiên bản UnicodeEncodeError, chứa thông tin về vị trí lỗi. Trình xử lý lỗi phải đưa ra ngoại lệ này hoặc ngoại lệ khác hoặc trả về một bộ dữ liệu có phần thay thế cho phần đầu vào không thể mã hóa và vị trí mà quá trình mã hóa sẽ tiếp tục. Sự thay thế có thể là str hoặc bytes. Nếu thay thế là byte, bộ mã hóa sẽ chỉ sao chép chúng vào bộ đệm đầu ra. Nếu thay thế là một chuỗi, bộ mã hóa sẽ mã hóa thay thế. Quá trình mã hóa tiếp tục trên đầu vào ban đầu ở vị trí đã chỉ định. Các giá trị vị trí âm sẽ được coi là tương đối với phần cuối của chuỗi đầu vào. Nếu vị trí kết quả nằm ngoài giới hạn thì IndexError sẽ được nâng lên.

Giải mã và dịch thuật hoạt động tương tự, ngoại trừ UnicodeDecodeError hoặc UnicodeTranslateError sẽ được chuyển đến trình xử lý và việc thay thế từ trình xử lý lỗi sẽ được đưa trực tiếp vào đầu ra.

Các trình xử lý lỗi đã đăng ký trước đó (bao gồm các trình xử lý lỗi tiêu chuẩn) có thể được tra cứu theo tên:

codecs.lookup_error(name, /)

Trả về trình xử lý lỗi đã đăng ký trước đó dưới tên name.

Tăng LookupError trong trường hợp không tìm thấy trình xử lý.

Các trình xử lý lỗi tiêu chuẩn sau đây cũng được cung cấp dưới dạng các hàm cấp mô-đun:

codecs.strict_errors(exception)

Triển khai xử lý lỗi 'strict'.

Mỗi lỗi mã hóa hoặc giải mã sẽ gây ra UnicodeError.

codecs.ignore_errors(exception)

Triển khai xử lý lỗi 'ignore'.

Dữ liệu không đúng định dạng sẽ bị bỏ qua; mã hóa hoặc giải mã được tiếp tục mà không cần thông báo thêm.

codecs.replace_errors(exception)

Triển khai xử lý lỗi 'replace'.

Thay thế ? (ký tự ASCII) cho lỗi mã hóa hoặc � (U+FFFD, REPLACEMENT CHARACTER chính thức) cho lỗi giải mã.

codecs.backslashreplace_errors(exception)

Triển khai xử lý lỗi 'backslashreplace'.

Dữ liệu không đúng định dạng được thay thế bằng chuỗi thoát bị gạch chéo ngược. Về mã hóa, sử dụng dạng thập lục phân của điểm mã Unicode với các định dạng \xhh \uxxxx \Uxxxxxxxx. Khi giải mã, sử dụng dạng thập lục phân của giá trị byte với định dạng \xhh.

Thay đổi trong phiên bản 3.5: Hoạt động với giải mã và dịch thuật.

codecs.xmlcharrefreplace_errors(exception)

Triển khai xử lý lỗi 'xmlcharrefreplace' (chỉ dành cho mã hóa trong text encoding).

Ký tự không thể mã hóa được thay thế bằng tham chiếu ký tự số XML/HTML thích hợp, là dạng thập phân của điểm mã Unicode có định dạng &#num; .

codecs.namereplace_errors(exception)

Triển khai xử lý lỗi 'namereplace' (chỉ dành cho mã hóa trong text encoding).

Ký tự không thể mã hóa được thay thế bằng chuỗi thoát \N{...}. Tập hợp các ký tự xuất hiện trong dấu ngoặc nhọn là thuộc tính Tên từ Cơ sở dữ liệu ký tự Unicode. Ví dụ: chữ cái viết thường của Đức 'ß' sẽ được chuyển đổi thành chuỗi byte \N{LATIN SMALL LETTER SHARP S}.

Added in version 3.5.

Mã hóa và giải mã không trạng thái

Lớp Codec cơ sở xác định các phương thức này cũng xác định các giao diện chức năng của bộ mã hóa và giải mã không trạng thái:

class codecs.Codec
encode(input, errors='strict')

Mã hóa đối tượng input và trả về một bộ dữ liệu (đối tượng đầu ra, độ dài đã tiêu thụ). Ví dụ: text encoding chuyển đổi một đối tượng chuỗi thành đối tượng byte bằng cách sử dụng mã hóa bộ ký tự cụ thể (ví dụ: cp1252 hoặc iso-8859-1).

Đối số errors xác định cách xử lý lỗi cần áp dụng. Nó mặc định xử lý 'strict'.

Phương thức này có thể không lưu trữ trạng thái trong phiên bản Codec. Sử dụng StreamWriter cho các codec phải giữ trạng thái để mã hóa hiệu quả.

Bộ mã hóa phải có khả năng xử lý đầu vào có độ dài bằng 0 và trả về một đối tượng trống thuộc loại đối tượng đầu ra trong tình huống này.

decode(input, errors='strict')

Giải mã đối tượng input và trả về một bộ dữ liệu (đối tượng đầu ra, độ dài đã tiêu thụ). Ví dụ: đối với text encoding, việc giải mã sẽ chuyển đổi một đối tượng byte được mã hóa bằng cách sử dụng mã hóa bộ ký tự cụ thể thành đối tượng chuỗi.

Đối với mã hóa văn bản và codec chuyển từ byte sang byte, input phải là đối tượng byte hoặc đối tượng cung cấp giao diện bộ đệm chỉ đọc -- ví dụ: đối tượng bộ đệm và tệp ánh xạ bộ nhớ.

Đối số errors xác định cách xử lý lỗi cần áp dụng. Nó mặc định xử lý 'strict'.

Phương thức này có thể không lưu trữ trạng thái trong phiên bản Codec. Sử dụng StreamReader cho các codec phải giữ trạng thái để giải mã hiệu quả.

Bộ giải mã phải có khả năng xử lý đầu vào có độ dài bằng 0 và trả về một đối tượng trống thuộc loại đối tượng đầu ra trong tình huống này.

Mã hóa và giải mã gia tăng

Các lớp IncrementalEncoder và IncrementalDecoder cung cấp giao diện cơ bản cho việc mã hóa và giải mã gia tăng. Việc mã hóa/giải mã đầu vào không được thực hiện bằng một lệnh gọi đến hàm bộ mã hóa/giải mã không trạng thái mà bằng nhiều lệnh gọi đến phương thức encode()/decode() của bộ mã hóa/giải mã gia tăng. Bộ mã hóa/giải mã gia tăng theo dõi quá trình mã hóa/giải mã trong khi gọi phương thức.

Đầu ra được nối của các lệnh gọi đến phương thức encode()/decode() giống như khi tất cả các đầu vào đơn lẻ được nối thành một và đầu vào này được mã hóa/giải mã bằng bộ mã hóa/giải mã không trạng thái.

Đối tượng mã hóa gia tăng

Lớp IncrementalEncoder được sử dụng để mã hóa đầu vào theo nhiều bước. Nó xác định các phương thức sau mà mọi bộ mã hóa gia tăng phải xác định để tương thích với sổ đăng ký codec Python.

class codecs.IncrementalEncoder(errors='strict')

Trình xây dựng cho phiên bản IncrementalEncoder.

Tất cả các bộ mã hóa gia tăng phải cung cấp giao diện hàm tạo này. Họ có thể tự do thêm các đối số từ khóa bổ sung, nhưng chỉ những đối số được xác định ở đây mới được cơ quan đăng ký codec Python sử dụng.

Zz000zz có thể triển khai các sơ đồ xử lý lỗi khác nhau bằng cách cung cấp đối số từ khóa errors. Xem Trình xử lý lỗi để biết các giá trị có thể có.

Đối số errors sẽ được gán cho một thuộc tính có cùng tên. Việc gán cho thuộc tính này giúp có thể chuyển đổi giữa các chiến lược xử lý lỗi khác nhau trong suốt vòng đời của đối tượng IncrementalEncoder.

encode(object, final=False)

Mã hóa object (có tính đến trạng thái hiện tại của bộ mã hóa) và trả về đối tượng được mã hóa kết quả. Nếu đây là lệnh gọi cuối cùng tới encode() thì final phải đúng (mặc định là sai).

reset()

Đặt lại bộ mã hóa về trạng thái ban đầu. Đầu ra bị loại bỏ: gọi .encode(object, final=True), truyền một byte trống hoặc chuỗi văn bản nếu cần, để đặt lại bộ mã hóa và nhận đầu ra.

getstate()

Trả về trạng thái hiện tại của bộ mã hóa phải là số nguyên. Việc triển khai phải đảm bảo rằng 0 là trạng thái phổ biến nhất. (Các trạng thái phức tạp hơn số nguyên có thể được chuyển đổi thành số nguyên bằng cách sắp xếp/chọn lọc trạng thái và mã hóa các byte của chuỗi kết quả thành số nguyên.)

setstate(state)

Đặt trạng thái của bộ mã hóa thành state. state phải là trạng thái bộ mã hóa được getstate() trả về.

Đối tượng giải mã gia tăng

Lớp IncrementalDecoder được sử dụng để giải mã đầu vào theo nhiều bước. Nó xác định các phương thức sau mà mọi bộ giải mã gia tăng phải xác định để tương thích với sổ đăng ký codec Python.

class codecs.IncrementalDecoder(errors='strict')

Trình xây dựng cho phiên bản IncrementalDecoder.

Tất cả các bộ giải mã gia tăng phải cung cấp giao diện hàm tạo này. Họ có thể tự do thêm các đối số từ khóa bổ sung, nhưng chỉ những đối số được xác định ở đây mới được cơ quan đăng ký codec Python sử dụng.

Zz000zz có thể triển khai các sơ đồ xử lý lỗi khác nhau bằng cách cung cấp đối số từ khóa errors. Xem Trình xử lý lỗi để biết các giá trị có thể có.

Đối số errors sẽ được gán cho một thuộc tính có cùng tên. Việc gán cho thuộc tính này giúp có thể chuyển đổi giữa các chiến lược xử lý lỗi khác nhau trong suốt vòng đời của đối tượng IncrementalDecoder.

decode(object, final=False)

Giải mã object (có tính đến trạng thái hiện tại của bộ giải mã) và trả về đối tượng được giải mã kết quả. Nếu đây là lệnh gọi cuối cùng tới decode() thì final phải đúng (mặc định là sai). Nếu final đúng, bộ giải mã phải giải mã hoàn toàn đầu vào và phải xóa tất cả bộ đệm. Nếu điều này là không thể (ví dụ: do chuỗi byte không đầy đủ ở cuối đầu vào), nó phải bắt đầu xử lý lỗi giống như trong trường hợp không trạng thái (có thể gây ra ngoại lệ).

reset()

Đặt lại bộ giải mã về trạng thái ban đầu.

getstate()

Trả về trạng thái hiện tại của bộ giải mã. Đây phải là một bộ dữ liệu có hai mục, mục đầu tiên phải là bộ đệm chứa dữ liệu đầu vào vẫn chưa được mã hóa. Số thứ hai phải là số nguyên và có thể là thông tin trạng thái bổ sung. (Việc triển khai phải đảm bảo rằng 0 là thông tin trạng thái bổ sung phổ biến nhất.) Nếu thông tin trạng thái bổ sung này là 0 thì phải có thể đặt bộ giải mã về trạng thái không có bộ đệm đầu vào và 0 làm thông tin trạng thái bổ sung, để việc cung cấp đầu vào được lưu vào bộ đệm trước đó cho bộ giải mã sẽ đưa nó về trạng thái trước đó mà không tạo ra bất kỳ đầu ra nào. (Thông tin trạng thái bổ sung phức tạp hơn số nguyên có thể được chuyển đổi thành số nguyên bằng cách sắp xếp/chọn lọc thông tin và mã hóa các byte của chuỗi kết quả thành số nguyên.)

setstate(state)

Đặt trạng thái của bộ giải mã thành state. state phải là trạng thái giải mã được getstate() trả về.

Mã hóa và giải mã luồng

Các lớp StreamWriter và StreamReader cung cấp các giao diện làm việc chung có thể được sử dụng để triển khai các mô-đun con mã hóa mới rất dễ dàng. Xem encodings.utf_8 để biết ví dụ về cách thực hiện việc này.

Đối tượng StreamWriter

Lớp StreamWriter là lớp con của Codec và định nghĩa các phương thức sau mà mọi người viết luồng phải xác định để tương thích với sổ đăng ký codec Python.

class codecs.StreamWriter(stream, errors='strict')

Trình xây dựng cho phiên bản StreamWriter.

Tất cả người viết luồng phải cung cấp giao diện hàm tạo này. Họ có thể tự do thêm các đối số từ khóa bổ sung, nhưng chỉ những đối số được xác định ở đây mới được cơ quan đăng ký codec Python sử dụng.

Đối số stream phải là một đối tượng giống như tệp mở để ghi văn bản hoặc dữ liệu nhị phân, nếu phù hợp với codec cụ thể.

Zz000zz có thể triển khai các sơ đồ xử lý lỗi khác nhau bằng cách cung cấp đối số từ khóa errors. Xem Trình xử lý lỗi để biết các trình xử lý lỗi tiêu chuẩn mà codec luồng cơ bản có thể hỗ trợ.

Đối số errors sẽ được gán cho một thuộc tính có cùng tên. Việc gán cho thuộc tính này giúp có thể chuyển đổi giữa các chiến lược xử lý lỗi khác nhau trong suốt vòng đời của đối tượng StreamWriter.

write(object)

Ghi nội dung của đối tượng được mã hóa vào luồng.

writelines(list)

Ghi chuỗi lặp được nối vào luồng (có thể bằng cách sử dụng lại phương thức write()). Các lần lặp vô hạn hoặc rất lớn không được hỗ trợ. Các codec byte-to-byte tiêu chuẩn không hỗ trợ phương pháp này.

reset()

Đặt lại bộ đệm codec được sử dụng để giữ trạng thái bên trong.

Việc gọi phương thức này phải đảm bảo rằng dữ liệu trên đầu ra được đưa vào trạng thái sạch cho phép thêm dữ liệu mới mới mà không cần phải quét lại toàn bộ luồng để khôi phục trạng thái.

Ngoài các phương thức trên, StreamWriter cũng phải kế thừa tất cả các phương thức và thuộc tính khác từ luồng cơ bản.

Đối tượng StreamReader

Lớp StreamReader là lớp con của Codec và định nghĩa các phương thức sau mà mọi trình đọc luồng phải xác định để tương thích với sổ đăng ký codec Python.

class codecs.StreamReader(stream, errors='strict')

Trình xây dựng cho phiên bản StreamReader.

Tất cả các trình đọc luồng phải cung cấp giao diện hàm tạo này. Họ có thể tự do thêm các đối số từ khóa bổ sung, nhưng chỉ những đối số được xác định ở đây mới được cơ quan đăng ký codec Python sử dụng.

Đối số stream phải là một đối tượng giống như tệp mở để đọc văn bản hoặc dữ liệu nhị phân, nếu phù hợp với codec cụ thể.

Zz000zz có thể triển khai các sơ đồ xử lý lỗi khác nhau bằng cách cung cấp đối số từ khóa errors. Xem Trình xử lý lỗi để biết các trình xử lý lỗi tiêu chuẩn mà codec luồng cơ bản có thể hỗ trợ.

Đối số errors sẽ được gán cho một thuộc tính có cùng tên. Việc gán cho thuộc tính này giúp có thể chuyển đổi giữa các chiến lược xử lý lỗi khác nhau trong suốt vòng đời của đối tượng StreamReader.

Tập hợp các giá trị được phép cho đối số errors có thể được mở rộng bằng register_error().

read(size=-1, chars=-1, firstline=False)

Giải mã dữ liệu từ luồng và trả về đối tượng kết quả.

Đối số chars cho biết số lượng điểm mã hoặc byte được giải mã sẽ trả về. Phương thức read() sẽ không bao giờ trả về nhiều dữ liệu hơn yêu cầu nhưng có thể trả về ít dữ liệu hơn nếu không có đủ dữ liệu.

Đối số size cho biết số byte hoặc điểm mã hóa tối đa gần đúng cần đọc để giải mã. Bộ giải mã có thể sửa đổi cài đặt này cho phù hợp. Giá trị mặc định -1 biểu thị việc đọc và giải mã càng nhiều càng tốt. Tham số này nhằm ngăn chặn việc phải giải mã các tệp lớn trong một bước.

Cờ firstline chỉ ra rằng chỉ cần trả về dòng đầu tiên là đủ nếu có lỗi giải mã ở các dòng sau.

Phương thức này nên sử dụng chiến lược đọc tham lam, nghĩa là nó sẽ đọc càng nhiều dữ liệu càng tốt trong phạm vi định nghĩa của mã hóa và kích thước nhất định, ví dụ: nếu phần cuối mã hóa tùy chọn hoặc điểm đánh dấu trạng thái có sẵn trên luồng thì chúng cũng phải được đọc.

readline(size=None, keepends=True)

Đọc một dòng từ luồng đầu vào và trả về dữ liệu đã giải mã.

size, nếu được cung cấp, sẽ được chuyển dưới dạng đối số kích thước cho phương thức read() của luồng.

Nếu keepends là kết thúc dòng sai sẽ bị loại bỏ khỏi các dòng được trả về.

readlines(sizehint=None, keepends=True)

Đọc tất cả các dòng có sẵn trên luồng đầu vào và trả về chúng dưới dạng danh sách các dòng.

Kết thúc dòng được triển khai bằng phương pháp decode() của codec và được đưa vào các mục danh sách nếu keepends là đúng.

sizehint, nếu được đưa ra, sẽ được chuyển dưới dạng đối số size cho phương thức read() của luồng.

reset()

Đặt lại bộ đệm codec được sử dụng để giữ trạng thái bên trong.

Lưu ý rằng không nên thay đổi vị trí luồng. Phương pháp này chủ yếu nhằm mục đích có thể phục hồi sau các lỗi giải mã.

Ngoài các phương thức trên, StreamReader cũng phải kế thừa tất cả các phương thức và thuộc tính khác từ luồng cơ bản.

Đối tượng StreamReaderWriter

Zz000zz là một lớp tiện lợi cho phép gói các luồng hoạt động ở cả chế độ đọc và ghi.

Thiết kế sao cho người ta có thể sử dụng các hàm xuất xưởng được hàm lookup() trả về để xây dựng phiên bản.

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')

Tạo một phiên bản StreamReaderWriter. stream phải là một đối tượng giống như tập tin. Reader và Writer phải là các hàm hoặc lớp gốc cung cấp giao diện StreamReader và StreamWriter. Việc xử lý lỗi được thực hiện theo cách tương tự như được xác định đối với trình đọc và ghi luồng.

Các phiên bản StreamReaderWriter xác định giao diện kết hợp của các lớp StreamReader và StreamWriter. Chúng kế thừa tất cả các phương thức và thuộc tính khác từ luồng cơ bản.

Đối tượng StreamRecode

Zz000zz dịch dữ liệu từ mã hóa này sang mã hóa khác, điều này đôi khi hữu ích khi xử lý các môi trường mã hóa khác nhau.

Thiết kế sao cho người ta có thể sử dụng các hàm xuất xưởng được hàm lookup() trả về để xây dựng phiên bản.

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')

Tạo một phiên bản StreamRecoder thực hiện chuyển đổi hai chiều: encode và decode hoạt động trên giao diện người dùng — dữ liệu hiển thị khi mã gọi read() và write(), trong khi Reader và Writer hoạt động trên phần phụ trợ — dữ liệu trong stream.

Bạn có thể sử dụng các đối tượng này để thực hiện chuyển mã minh bạch, ví dụ: từ Latin-1 đến UTF-8 và ngược lại.

Đối số stream phải là một đối tượng giống như tệp.

Các đối số encode và decode phải tuân theo giao diện Codec. Reader và Writer phải là các hàm hoặc lớp xuất xưởng cung cấp các đối tượng của giao diện StreamReader và StreamWriter tương ứng.

Việc xử lý lỗi được thực hiện theo cách tương tự như được xác định đối với trình đọc và ghi luồng.

Các phiên bản StreamRecoder xác định giao diện kết hợp của các lớp StreamReader và StreamWriter. Chúng kế thừa tất cả các phương thức và thuộc tính khác từ luồng cơ bản.

Mã hóa và Unicode

Các chuỗi được lưu trữ nội bộ dưới dạng chuỗi các điểm mã trong phạm vi U+0000--U+10FFFF. (Xem PEP 393 để biết thêm chi tiết về cách triển khai.) Khi một đối tượng chuỗi được sử dụng bên ngoài CPU và bộ nhớ, độ bền và cách các mảng này được lưu trữ dưới dạng byte sẽ trở thành một vấn đề. Giống như các codec khác, việc tuần tự hóa một chuỗi thành một chuỗi byte được gọi là encoding và việc tạo lại chuỗi từ chuỗi byte được gọi là decoding. Có nhiều loại codec tuần tự hóa văn bản khác nhau, được gọi chung là text encodings.

Mã hóa văn bản đơn giản nhất (được gọi là 'latin-1' hoặc 'iso-8859-1') ánh xạ các điểm mã 0--255 tới các byte 0x0--0xff, có nghĩa là không thể mã hóa một đối tượng chuỗi chứa các điểm mã trên U+00FF bằng codec này. Làm như vậy sẽ tạo ra một UnicodeEncodeError trông giống như sau (mặc dù chi tiết về thông báo lỗi có thể khác nhau): UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256).

Có một nhóm mã hóa khác (được gọi là mã hóa charmap) chọn một tập hợp con khác của tất cả các điểm mã Unicode và cách các điểm mã này được ánh xạ tới các byte 0x0--0xff. Để xem việc này được thực hiện như thế nào, chỉ cần mở ví dụ: encodings/cp1252.py (là mã hóa được sử dụng chủ yếu trên Windows). Có một hằng số chuỗi có 256 ký tự cho bạn biết ký tự nào được ánh xạ tới giá trị byte nào.

Tất cả các bảng mã này chỉ có thể mã hóa 256 trong số 1114112 điểm mã được xác định bằng Unicode. Một cách đơn giản và dễ hiểu để có thể lưu trữ từng điểm mã Unicode là lưu trữ mỗi điểm mã dưới dạng bốn byte liên tiếp. Có hai khả năng: lưu trữ các byte theo thứ tự endian lớn hoặc endian nhỏ. Hai bảng mã này lần lượt được gọi là UTF-32-BE và UTF-32-LE. Nhược điểm của chúng là, chẳng hạn, nếu bạn sử dụng UTF-32-BE trên một máy endian nhỏ, bạn sẽ luôn phải trao đổi byte khi mã hóa và giải mã. Các codec UTF-16 và UTF-32 của Python tránh được vấn đề này bằng cách sử dụng thứ tự byte gốc của nền tảng khi không có BOM. Python tuân theo thông lệ nền tảng phổ biến, do đó, các chuyến đi khứ hồi dữ liệu gốc-endian mà không cần hoán đổi byte dư thừa, mặc dù Tiêu chuẩn Unicode mặc định là big-endian khi thứ tự byte không được chỉ định. Khi các byte này được đọc bởi CPU với độ cuối khác nhau, các byte phải được hoán đổi. Để có thể phát hiện độ cuối của chuỗi byte UTF-16 hoặc UTF-32, BOM ("Dấu thứ tự byte") được sử dụng. Đây là ký tự Unicode U+FEFF. Ký tự này có thể được thêm vào trước mỗi chuỗi byte UTF-16 hoặc UTF-32. Phiên bản hoán đổi byte của ký tự này (0xFFFE) là một ký tự không hợp lệ có thể không xuất hiện trong văn bản Unicode. Khi ký tự đầu tiên của chuỗi byte UTF-16 hoặc UTF-32 là U+FFFE, các byte phải được hoán đổi khi giải mã.

Thật không may, ký tự U+FEFF có mục đích thứ hai là ZERO WIDTH NO-BREAK SPACE: một ký tự không có chiều rộng và không cho phép phân chia một từ. Nó có thể ví dụ. được sử dụng để đưa ra gợi ý cho một thuật toán ghép. Với Unicode 4.0 sử dụng U+FEFF làm ZERO WIDTH NO-BREAK SPACE đã không còn được dùng nữa (với U+2060 (WORD JOINER) đảm nhận vai trò này). Tuy nhiên, phần mềm Unicode vẫn phải có khả năng xử lý U+FEFF ở cả hai vai trò: với tư cách là BOM, nó là một thiết bị xác định bố cục lưu trữ của các byte được mã hóa và biến mất sau khi chuỗi byte được giải mã thành chuỗi; với tư cách là ZERO WIDTH NO-BREAK SPACE, đó là một ký tự bình thường sẽ được giải mã như mọi ký tự khác.

Có một mã hóa khác có thể mã hóa đầy đủ các ký tự Unicode: UTF-8. UTF-8 là mã hóa 8 bit, có nghĩa là không có vấn đề gì với thứ tự byte trong UTF-8. Mỗi byte trong chuỗi byte UTF-8 bao gồm hai phần: bit đánh dấu (bit quan trọng nhất) và bit tải trọng. Các bit đánh dấu là một chuỗi từ 0 đến 4 bit 1, theo sau là bit 0. Các ký tự Unicode được mã hóa như thế này (với x là các bit tải trọng, khi nối sẽ tạo ra ký tự Unicode):

Phạm vi

Mã hóa

U-00000000... U-0000007F

0xxxxxxx

U-00000080... U-000007FF

110xxxxx 10xxxxxx

U-00000800... U-0000FFFF

1110xxxx 10xxxxxx 10xxxxxx

U-00010000... U-0010FFFF

11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

Bit có ý nghĩa nhỏ nhất của ký tự Unicode là bit x ngoài cùng bên phải.

Vì UTF-8 là mã hóa 8 bit nên không cần BOM và mọi ký tự U+FEFF trong chuỗi được giải mã (ngay cả khi đó là ký tự đầu tiên) đều được coi là ZERO WIDTH NO-BREAK SPACE.

Nếu không có thông tin bên ngoài thì không thể xác định một cách đáng tin cậy mã hóa nào được sử dụng để mã hóa một chuỗi. Mỗi mã hóa charmap có thể giải mã bất kỳ chuỗi byte ngẫu nhiên nào. Tuy nhiên, điều đó là không thể với UTF-8, vì chuỗi byte UTF-8 có cấu trúc không cho phép các chuỗi byte tùy ý. Để tăng độ tin cậy mà mã hóa UTF-8 có thể được phát hiện, Microsoft đã phát minh ra một biến thể của UTF-8 (mà Python gọi là "utf-8-sig") cho chương trình Notepad của mình: Trước khi bất kỳ ký tự Unicode nào được ghi vào tệp, một BOM được mã hóa UTF-8 (trông giống như một chuỗi byte: 0xef, 0xbb, 0xbf) được viết. Vì rất khó có khả năng bất kỳ tệp được mã hóa charmap nào cũng bắt đầu bằng các giá trị byte này (ví dụ: ánh xạ tới

LATIN SMALL LETTER tôi WITH DIAERESIS
RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
INVERTED QUESTION MARK

trong iso-8859-1), điều này làm tăng khả năng đoán chính xác mã hóa utf-8-sig từ chuỗi byte. Vì vậy, ở đây BOM không được sử dụng để xác định thứ tự byte được sử dụng để tạo chuỗi byte mà được sử dụng như một chữ ký giúp đoán mã hóa. Khi mã hóa, codec utf-8-sig sẽ ghi 0xef, 0xbb, 0xbf làm ba byte đầu tiên vào tệp. Khi giải mã utf-8-sig sẽ bỏ qua ba byte đó nếu chúng xuất hiện dưới dạng ba byte đầu tiên trong tệp. Trong UTF-8, việc sử dụng BOM không được khuyến khích và thường nên tránh.

Mã hóa tiêu chuẩn

Python đi kèm với một số codec được tích hợp sẵn, được triển khai dưới dạng hàm C hoặc với từ điển dưới dạng bảng ánh xạ. Bảng sau liệt kê các codec theo tên, cùng với một số bí danh phổ biến và ngôn ngữ mà mã hóa có thể được sử dụng. Cả danh sách bí danh lẫn danh sách ngôn ngữ đều không đầy đủ. Lưu ý rằng các cách viết thay thế chỉ khác nhau về cách viết hoa chữ thường hoặc sử dụng dấu gạch nối thay vì dấu gạch dưới cũng là các bí danh hợp lệ vì chúng tương đương nhau khi được chuẩn hóa bởi normalize_encoding(). Ví dụ: 'utf-8' là bí danh hợp lệ cho codec 'utf_8'.

Ghi chú

Bảng bên dưới liệt kê các bí danh phổ biến nhất, để có danh sách đầy đủ hãy tham khảo tệp aliases.py nguồn.

Trên Windows, codec cpXXX có sẵn cho tất cả các trang mã. Nhưng chỉ những codec được liệt kê trong bảng sau mới được đảm bảo tồn tại trên các nền tảng khác.

Một số mã hóa phổ biến có thể bỏ qua bộ máy tra cứu codec để cải thiện hiệu suất. Các cơ hội tối ưu hóa này chỉ được CPython công nhận đối với một nhóm bí danh giới hạn (không phân biệt chữ hoa chữ thường): utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (chỉ dành cho Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32 và tương tự bằng cách sử dụng dấu gạch dưới thay vì dấu gạch ngang. Việc sử dụng các bí danh thay thế cho các mã hóa này có thể dẫn đến việc thực thi chậm hơn.

Thay đổi trong phiên bản 3.6: Cơ hội tối ưu hóa được công nhận cho us-ascii.

Nhiều bộ ký tự hỗ trợ cùng một ngôn ngữ. Chúng khác nhau về các ký tự riêng lẻ (ví dụ: EURO SIGN có được hỗ trợ hay không) và việc gán các ký tự cho các vị trí mã. Đối với các ngôn ngữ châu Âu nói riêng, các biến thể sau thường tồn tại:

  • bộ mã ISO 8859

  • một trang mã Microsoft Windows, thường có nguồn gốc từ bộ mã 8859, nhưng thay thế các ký tự điều khiển bằng các ký tự đồ họa bổ sung

  • một trang mã IBM EBCDIC

  • trang mã PC IBM, tương thích với ASCII

Bộ giải mã

Bí danh

Ngôn ngữ

ascii

646, us-ascii

Tiếng Anh

big5

big5-tw, csbig5

Tiếng Trung phồn thể

big5hkscs

big5-hkscs, hkscs

Tiếng Trung phồn thể

cp037

IBM037, IBM039

Tiếng Anh

cp273

273, IBM273, csIBM273

tiếng Đức

Added in version 3.4.

cp424

EBCDIC-CP-HE, IBM424

tiếng Do Thái

cp437

437, IBM437

Tiếng Anh

cp500

EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500

Tây Âu

cp720

tiếng Ả Rập

cp737

tiếng Hy Lạp

cp775

IBM775

ngôn ngữ vùng Baltic

cp850

850, IBM850

Tây Âu

cp852

852, IBM852

Trung và Đông Âu

cp855

855, IBM855

Tiếng Belarus, Tiếng Bulgaria, Tiếng Macedonia, Tiếng Nga, Tiếng Serbia

cp856

tiếng Do Thái

cp857

857, IBM857

tiếng Thổ Nhĩ Kỳ

cp858

858, IBM858

Tây Âu

cp860

860, IBM860

tiếng Bồ Đào Nha

cp861

861, CP-IS, IBM861

tiếng Iceland

cp862

862, IBM862

tiếng Do Thái

cp863

863, IBM863

người Canada

cp864

IBM864

tiếng Ả Rập

cp865

865, IBM865

Đan Mạch, Na Uy

cp866

866, IBM866

tiếng Nga

cp869

869, CP-GR, IBM869

tiếng Hy Lạp

cp874

tiếng Thái

cp875

tiếng Hy Lạp

cp932

932, ms932, mskanji, ms-kanji, windows-31j

tiếng Nhật

cp949

949, ms949, uhc

Tiếng Hàn

cp950

950, ms950

Tiếng Trung phồn thể

cp1006

tiếng Urdu

cp1026

ibm1026

tiếng Thổ Nhĩ Kỳ

cp1125

1125, ibm1125, cp866u, ruscii

tiếng Ukraina

Added in version 3.4.

cp1140

ibm1140

Tây Âu

cp1250

windows-1250

Trung và Đông Âu

cp1251

windows-1251

Tiếng Belarus, Tiếng Bulgaria, Tiếng Macedonia, Tiếng Nga, Tiếng Serbia

cp1252

windows-1252

Tây Âu

cp1253

windows-1253

tiếng Hy Lạp

cp1254

windows-1254

tiếng Thổ Nhĩ Kỳ

cp1255

windows-1255

tiếng Do Thái

cp1256

windows-1256

tiếng Ả Rập

cp1257

windows-1257

ngôn ngữ vùng Baltic

cp1258

windows-1258

Tiếng Việt

euc_jp

eucjp, ujis, u-jis

tiếng Nhật

euc_jis_2004

jisx0213, eucjis2004

tiếng Nhật

euc_jisx0213

eucjisx0213

tiếng Nhật

euc_kr

euckr, hàn quốc, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001

Tiếng Hàn

gb2312

tiếng Trung, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58

Tiếng Trung giản thể

gbk

936, cp936, ms936

Tiếng Trung Quốc thống nhất

gb18030

gb18030-2000

Tiếng Trung Quốc thống nhất

hz

hzgb, hz-gb, hz-gb-2312

Tiếng Trung giản thể

iso2022_jp

csiso2022jp, iso2022jp, iso-2022-jp

tiếng Nhật

iso2022_jp_1

iso2022jp-1, iso-2022-jp-1

tiếng Nhật

iso2022_jp_2

iso2022jp-2, iso-2022-jp-2

Nhật Bản, Hàn Quốc, Trung Quốc giản thể, Tây Âu, Hy Lạp

iso2022_jp_2004

iso2022jp-2004, iso-2022-jp-2004

tiếng Nhật

iso2022_jp_3

iso2022jp-3, iso-2022-jp-3

tiếng Nhật

iso2022_jp_ext

iso2022jp-ext, iso-2022-jp-ext

tiếng Nhật

iso2022_kr

csiso2022kr, iso2022kr, iso-2022-kr

Tiếng Hàn

latin_1

iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1

Tây Âu

iso8859_2

iso-8859-2, latin2, L2

Trung và Đông Âu

iso8859_3

iso-8859-3, latin3, L3

Quốc tế ngữ, tiếng Malta

iso8859_4

iso-8859-4, latin4, L4

Bắc Âu

iso8859_5

iso-8859-5, chữ cyrillic

Tiếng Belarus, Tiếng Bulgaria, Tiếng Macedonia, Tiếng Nga, Tiếng Serbia

iso8859_6

iso-8859-6, tiếng Ả Rập

tiếng Ả Rập

iso8859_7

iso-8859-7, tiếng Hy Lạp, tiếng Hy Lạp8

tiếng Hy Lạp

iso8859_8

iso-8859-8, tiếng Do Thái

tiếng Do Thái

iso8859_9

iso-8859-9, latin5, L5

tiếng Thổ Nhĩ Kỳ

iso8859_10

iso-8859-10, latin6, L6

Ngôn ngữ Bắc Âu

iso8859_11

iso-8859-11, tiếng Thái

tiếng Thái

iso8859_13

iso-8859-13, latin7, L7

ngôn ngữ vùng Baltic

iso8859_14

iso-8859-14, latin8, L8

ngôn ngữ Celtic

iso8859_15

iso-8859-15, latin9, L9

Tây Âu

iso8859_16

iso-8859-16, latin10, L10

Đông Nam Âu

johab

cp1361, ms1361

Tiếng Hàn

koi8_r

tiếng Nga

koi8_t

Tiếng Tajik

Added in version 3.5.

koi8_u

tiếng Ukraina

kz1048

kz_1048, strk1048_2002, rk1048

Kazakhstan

Added in version 3.5.

mac_cyrillic

maccyrillic

Tiếng Belarus, Tiếng Bulgaria, Tiếng Macedonia, Tiếng Nga, Tiếng Serbia

mac_greek

người Hy Lạp

tiếng Hy Lạp

mac_iceland

xứ macice

tiếng Iceland

mac_latin2

maclatin2, maccentraleurope, mac_centeuro

Trung và Đông Âu

mac_roman

macroman, macintosh

Tây Âu

mac_thổ nhĩ kỳ

kiểu macturk

tiếng Thổ Nhĩ Kỳ

ptcp154

csptcp154, pt154, cp154, chữ cyrillic-châu Á

Kazakhstan

shift_jis

csshiftjis, shiftjis, sjis, s_jis

tiếng Nhật

shift_jis_2004

shiftjis2004, sjis_2004, sjis2004

tiếng Nhật

shift_jisx0213

shiftjisx0213, sjisx0213, s_jisx0213

tiếng Nhật

utf_32

U32, utf32

tất cả các ngôn ngữ

utf_32_be

UTF-32BE

tất cả các ngôn ngữ

utf_32_le

UTF-32LE

tất cả các ngôn ngữ

utf_16

U16, utf16

tất cả các ngôn ngữ

utf_16_be

UTF-16BE

tất cả các ngôn ngữ

utf_16_le

UTF-16LE

tất cả các ngôn ngữ

utf_7

U7, unicode-1-1-utf-7

tất cả các ngôn ngữ

utf_8

U8, UTF, utf8, cp65001

tất cả các ngôn ngữ

utf_8_sig

tất cả các ngôn ngữ

Thay đổi trong phiên bản 3.4: Bộ mã hóa utf-16* và utf-32* không còn cho phép mã hóa các điểm mã thay thế (U+D800--U+DFFF). Bộ giải mã utf-32* không còn giải mã các chuỗi byte tương ứng với các điểm mã thay thế.

Thay đổi trong phiên bản 3.8: cp65001 hiện là bí danh của utf_8.

Thay đổi trong phiên bản 3.14: Trên Windows, codec cpXXX hiện có sẵn cho tất cả các trang mã.

Mã hóa cụ thể của Python

Một số codec được xác định trước dành riêng cho Python, vì vậy tên codec của chúng không có ý nghĩa gì ngoài Python. Chúng được liệt kê trong bảng bên dưới dựa trên loại đầu vào và đầu ra dự kiến ​​(lưu ý rằng mặc dù mã hóa văn bản là trường hợp sử dụng phổ biến nhất cho codec, cơ sở hạ tầng codec cơ bản hỗ trợ chuyển đổi dữ liệu tùy ý thay vì chỉ mã hóa văn bản). Đối với các codec bất đối xứng, ý nghĩa đã nêu mô tả hướng mã hóa.

Mã hóa văn bản

Các codec sau cung cấp mã hóa str đến bytes và giải mã bytes-like object đến str, tương tự như mã hóa văn bản Unicode.

Bộ giải mã

Bí danh

Ý nghĩa

danh tính

Triển khai RFC 3490, xem thêm encodings.idna. Chỉ errors='strict' được hỗ trợ.

MBC

ansi, dbcs

Chỉ dành cho Windows: Mã hóa toán hạng theo bảng mã ANSI (CP_ACP).

oem

Chỉ dành cho Windows: Mã hóa toán hạng theo bảng mã OEM (CP_OEMCP).

Added in version 3.6.

cây cọ

Mã hóa PalmOS 3.5.

mã trừng phạt

Triển khai RFC 3492. Codec trạng thái không được hỗ trợ.

raw_unicode_escape

Mã hóa Latin-1 với \uXXXX và \UXXXXXXXX cho các điểm mã khác. Dấu gạch chéo ngược hiện tại không được thoát theo bất kỳ cách nào. Nó được sử dụng trong giao thức dưa chua Python.

không xác định

Codec này chỉ nên được sử dụng cho mục đích thử nghiệm.

Đưa ra một ngoại lệ cho tất cả các chuyển đổi, thậm chí cả các chuỗi trống. Trình xử lý lỗi bị bỏ qua.

unicode_escape

Mã hóa phù hợp với nội dung của một chữ Unicode trong mã nguồn Python được mã hóa ASCII, ngoại trừ các dấu ngoặc kép không được thoát. Giải mã từ mã nguồn Latin-1. Xin lưu ý rằng mã nguồn Python thực sự sử dụng UTF-8 theo mặc định.

Thay đổi trong phiên bản 3.8: Codec "unicode_internal" bị xóa.

Biến đổi nhị phân

Các codec sau đây cung cấp các phép biến đổi nhị phân: ánh xạ bytes-like object đến bytes. Chúng không được bytes.decode() hỗ trợ (chỉ tạo ra đầu ra str).

Bộ giải mã

Bí danh

Ý nghĩa

Bộ mã hóa/giải mã

base64_codec [1]

cơ sở64, cơ sở_64

Chuyển đổi toán hạng thành MIME base64 nhiều dòng (kết quả luôn bao gồm '\n' ở cuối).

Thay đổi trong phiên bản 3.4: chấp nhận bất kỳ bytes-like object nào làm đầu vào để mã hóa và giải mã

base64.encodebytes() / base64.decodebytes()

bz2_codec

bz2

Nén toán hạng bằng bz2.

bz2.compress() / bz2.decompress()

hex_codec

thập lục phân

Chuyển đổi toán hạng thành biểu diễn thập lục phân, với hai chữ số trên mỗi byte.

binascii.b2a_hex() / binascii.a2b_hex()

quopri_codec

quopri, trích dẫn có thể in được, trích dẫn_printable

Chuyển đổi toán hạng thành MIME trích dẫn có thể in được.

quopri.encode() với quotetabs=True / quopri.decode()

uu_codec

ừ

Chuyển đổi toán hạng bằng uuencode.

zlib_codec

zip, zlib

Nén toán hạng bằng gzip.

zlib.compress() / zlib.decompress()

Added in version 3.2: Khôi phục các phép biến đổi nhị phân.

Thay đổi trong phiên bản 3.4: Khôi phục bí danh cho các phép biến đổi nhị phân.

Chức năng Codec độc lập

Các chức năng sau đây cung cấp chức năng mã hóa và giải mã tương tự như codec nhưng không có sẵn dưới dạng codec được đặt tên thông qua codecs.encode() hoặc codecs.decode(). Chúng được sử dụng nội bộ (ví dụ: bởi pickle) và hoạt động tương tự như codec string_escape đã bị xóa trong Python 3.

codecs.escape_encode(input, errors=None)

Mã hóa input bằng cách sử dụng chuỗi thoát. Tương tự như cách repr() trên byte tạo ra các giá trị byte thoát.

input phải là đối tượng bytes.

Trả về một bộ (output, length) trong đó output là đối tượng bytes và length là số byte đã sử dụng.

codecs.escape_decode(input, errors=None)

Giải mã input từ chuỗi thoát trở lại byte ban đầu.

input phải là bytes-like object.

Trả về một bộ (output, length) trong đó output là đối tượng bytes và length là số byte đã sử dụng.

Chuyển đổi văn bản

Codec sau đây cung cấp một phép biến đổi văn bản: ánh xạ str sang str. Nó không được hỗ trợ bởi str.encode() (chỉ tạo ra đầu ra bytes).

Bộ giải mã

Bí danh

Ý nghĩa

thối_13

thối13

Trả về mã hóa Caesar-cypher của toán hạng.

Added in version 3.2: Khôi phục chuyển đổi văn bản rot_13.

Thay đổi trong phiên bản 3.4: Khôi phục bí danh rot13.

encodings --- Gói mã hóa

Mô-đun này thực hiện các chức năng sau:

encodings.normalize_encoding(encoding)

Chuẩn hóa tên mã hóa encoding.

Quá trình chuẩn hóa hoạt động như sau: tất cả các ký tự không phải chữ và số ngoại trừ dấu chấm được sử dụng cho tên gói Python được thu gọn và thay thế bằng một dấu gạch dưới duy nhất, dấu gạch dưới đầu và cuối đều bị xóa. Ví dụ: '  -;#' trở thành '_'.

Lưu ý rằng encoding chỉ nên là ASCII.

Ghi chú

Không nên sử dụng trực tiếp các chức năng sau, ngoại trừ mục đích thử nghiệm; codecs.lookup() nên được sử dụng thay thế.

encodings.search_function(encoding)

Tìm kiếm mô-đun codec tương ứng với tên mã hóa đã cho encoding.

Hàm này trước tiên chuẩn hóa encoding bằng normalize_encoding(), sau đó tìm bí danh tương ứng. Nó cố gắng nhập mô-đun codec từ gói mã hóa bằng cách sử dụng bí danh hoặc tên chuẩn hóa. Nếu mô-đun được tìm thấy và xác định hàm getregentry() hợp lệ trả về đối tượng codecs.CodecInfo, thì codec sẽ được lưu vào bộ nhớ đệm và trả về.

Nếu mô-đun codec xác định hàm getaliases() thì mọi bí danh trả về sẽ được đăng ký để sử dụng trong tương lai.

encodings.win32_code_page_search_function(encoding)

Tìm kiếm trang mã Windows mã hóa encoding có dạng cpXXXX.

Nếu trang mã hợp lệ và được hỗ trợ, hãy trả về đối tượng codecs.CodecInfo cho nó.

sẵn có: Windows.

Added in version 3.14.

Mô-đun này thực hiện ngoại lệ sau:

exception encodings.CodecRegistryError

Xảy ra khi codec không hợp lệ hoặc không tương thích.

encodings.idna --- Tên miền quốc tế hóa trong ứng dụng

Mô-đun này triển khai RFC 3490 (Tên miền quốc tế hóa trong ứng dụng) và RFC 3492 (Nameprep: Cấu hình Stringprep cho tên miền quốc tế hóa (IDN)). Nó được xây dựng dựa trên mã hóa punycode và stringprep.

Nếu bạn cần tiêu chuẩn IDNA 2008 từ RFC 5891 và RFC 5895, hãy sử dụng mô-đun idna của bên thứ ba.

Các RFC này cùng nhau xác định một giao thức để hỗ trợ các ký tự không phải ASCII trong tên miền. Tên miền chứa các ký tự không phải ASCII (chẳng hạn như www.Alliancefrançaise.nu) được chuyển đổi thành mã hóa tương thích với ASCII (ACE, chẳng hạn như www.xn--alliancefranaise-npb.nu). Sau đó, dạng ACE của tên miền được sử dụng ở tất cả những nơi mà giao thức không cho phép các ký tự tùy ý, chẳng hạn như truy vấn DNS, trường HTTP Host, v.v. Việc chuyển đổi này được thực hiện trong ứng dụng; nếu có thể ẩn với người dùng: Ứng dụng phải chuyển đổi một cách trong suốt các nhãn miền Unicode thành IDNA trên dây và chuyển đổi lại các nhãn ACE thành Unicode trước khi hiển thị chúng cho người dùng.

Python hỗ trợ chuyển đổi này theo nhiều cách: codec idna thực hiện chuyển đổi giữa Unicode và ACE, tách chuỗi đầu vào thành các nhãn dựa trên các ký tự phân tách được xác định trong section 3.1 of RFC 3490 và chuyển đổi từng nhãn thành ACE theo yêu cầu và ngược lại, tách chuỗi byte đầu vào thành các nhãn dựa trên dấu phân cách . và chuyển đổi bất kỳ nhãn ACE nào được tìm thấy thành unicode. Hơn nữa, mô-đun socket chuyển đổi tên máy chủ Unicode thành ACE một cách trong suốt, do đó các ứng dụng không cần phải lo lắng về việc tự chuyển đổi tên máy chủ khi chúng chuyển chúng sang mô-đun ổ cắm. Ngoài ra, các mô-đun có tên máy chủ làm tham số chức năng, chẳng hạn như http.client và ftplib, chấp nhận tên máy chủ Unicode (http.client sau đó cũng gửi tên máy chủ IDNA trong trường Host một cách minh bạch nếu nó gửi trường đó).

Khi nhận tên máy chủ từ dây (chẳng hạn như tra cứu tên ngược), không có chuyển đổi tự động sang Unicode được thực hiện: các ứng dụng muốn hiển thị tên máy chủ đó cho người dùng nên giải mã chúng thành Unicode.

Mô-đun encodings.idna cũng triển khai quy trình chuẩn bị tên, thực hiện một số chuẩn hóa nhất định trên tên máy chủ, để đạt được tên miền quốc tế không phân biệt chữ hoa chữ thường và để thống nhất các ký tự tương tự. Các chức năng nameprep có thể được sử dụng trực tiếp nếu muốn.

encodings.idna.nameprep(label)

Trả lại phiên bản đã được đặt tên trước của label. Việc triển khai hiện giả định các chuỗi truy vấn, vì vậy AllowUnassigned là đúng.

encodings.idna.ToASCII(label)

Chuyển đổi nhãn thành ASCII, như được chỉ định trong RFC 3490. UseSTD3ASCIIRules được coi là sai.

encodings.idna.ToUnicode(label)

Chuyển đổi nhãn thành Unicode, như được chỉ định trong RFC 3490.

encodings.mbcs --- bảng mã Windows ANSI

Mô-đun này triển khai bảng mã ANSI (CP_ACP).

sẵn có: Windows.

Thay đổi trong phiên bản 3.2: Trước 3.2, đối số errors bị bỏ qua; 'replace' luôn được sử dụng để mã hóa và 'ignore' để giải mã.

Thay đổi trong phiên bản 3.3: Hỗ trợ bất kỳ trình xử lý lỗi nào.

encodings.utf_8_sig --- codec UTF-8 có chữ ký BOM

Mô-đun này triển khai một biến thể của codec UTF-8. Khi mã hóa, BOM được mã hóa UTF-8 sẽ được thêm vào trước các byte được mã hóa UTF-8. Đối với bộ mã hóa trạng thái, việc này chỉ được thực hiện một lần (trong lần ghi đầu tiên vào luồng byte). Khi giải mã, một BOM được mã hóa UTF-8 tùy chọn ở đầu dữ liệu sẽ bị bỏ qua.