Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 650e322

Browse files
ncoghlanncoghlan
committed
Issue 17844: Clarify meaning of different codec tables
1 parent c1939b8 commit 650e322

1 file changed

Lines changed: 50 additions & 30 deletions

File tree

‎Doc/library/codecs.rst‎

Lines changed: 50 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1142,7 +1142,19 @@ particular, the following variants typically exist:
11421142
| utf_8_sig | | all languages |
11431143
+-----------------+--------------------------------+--------------------------------+
11441144

1145-
.. XXX fix here, should be in above table
1145+
Python Specific Encodings
1146+
-------------------------
1147+
1148+
A number of predefined codecs are specific to Python, so their codec names have
1149+
no meaning outside Python. These are listed in the tables below based on the
1150+
expected input and output types (note that while text encodings are the most
1151+
common use case for codecs, the underlying codec infrastructure supports
1152+
arbitrary data transforms rather than just text encodings). For asymmetric
1153+
codecs, the stated purpose describes the encoding direction.
1154+
1155+
The following codecs provide :class:`str` to :class:`bytes` encoding and
1156+
:term:`bytes-like object` to :class:`str` decoding, similar to the Unicode text
1157+
encodings.
11461158

11471159
.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
11481160

@@ -1186,37 +1198,45 @@ particular, the following variants typically exist:
11861198
| | | .. deprecated:: 3.3 |
11871199
+--------------------+---------+---------------------------+
11881200

1189-
The following codecs provide bytes-to-bytes mappings.
1201+
The following codecs provide :term:`bytes-like object` to :class:`bytes`
1202+
mappings.
1203+
11901204

11911205
.. tabularcolumns:: |l|L|L|
11921206

1193-
+--------------------+---------------------------+------------------------------+
1194-
| Codec | Purpose | Encoder/decoder |
1195-
+====================+===========================+==============================+
1196-
| base64_codec | Convert operand to MIME | :meth:`base64.b64encode`, |
1197-
| | base64 (the result always | :meth:`base64.b64decode` |
1198-
| | includes a trailing | |
1199-
| | ``'\n'``) | |
1200-
+--------------------+---------------------------+------------------------------+
1201-
| bz2_codec | Compress the operand | :meth:`bz2.compress`, |
1202-
| | using bz2 | :meth:`bz2.decompress` |
1203-
+--------------------+---------------------------+------------------------------+
1204-
| hex_codec | Convert operand to | :meth:`base64.b16encode`, |
1205-
| | hexadecimal | :meth:`base64.b16decode` |
1206-
| | representation, with two | |
1207-
| | digits per byte | |
1208-
+--------------------+---------------------------+------------------------------+
1209-
| quopri_codec | Convert operand to MIME | :meth:`quopri.encodestring`, |
1210-
| | quoted printable | :meth:`quopri.decodestring` |
1211-
+--------------------+---------------------------+------------------------------+
1212-
| uu_codec | Convert the operand using | :meth:`uu.encode`, |
1213-
| | uuencode | :meth:`uu.decode` |
1214-
+--------------------+---------------------------+------------------------------+
1215-
| zlib_codec | Compress the operand | :meth:`zlib.compress`, |
1216-
| | using gzip | :meth:`zlib.decompress` |
1217-
+--------------------+---------------------------+------------------------------+
1218-
1219-
The following codecs provide string-to-string mappings.
1207+
+----------------------+---------------------------+------------------------------+
1208+
| Codec | Purpose | Encoder/decoder |
1209+
+======================+===========================+==============================+
1210+
| base64_codec [#b64]_ | Convert operand to MIME | :meth:`base64.b64encode`, |
1211+
| | base64 (the result always | :meth:`base64.b64decode` |
1212+
| | includes a trailing | |
1213+
| | ``'\n'``) | |
1214+
+----------------------+---------------------------+------------------------------+
1215+
| bz2_codec | Compress the operand | :meth:`bz2.compress`, |
1216+
| | using bz2 | :meth:`bz2.decompress` |
1217+
+----------------------+---------------------------+------------------------------+
1218+
| hex_codec | Convert operand to | :meth:`base64.b16encode`, |
1219+
| | hexadecimal | :meth:`base64.b16decode` |
1220+
| | representation, with two | |
1221+
| | digits per byte | |
1222+
+----------------------+---------------------------+------------------------------+
1223+
| quopri_codec | Convert operand to MIME | :meth:`quopri.encodestring`, |
1224+
| | quoted printable | :meth:`quopri.decodestring` |
1225+
+----------------------+---------------------------+------------------------------+
1226+
| uu_codec | Convert the operand using | :meth:`uu.encode`, |
1227+
| | uuencode | :meth:`uu.decode` |
1228+
+----------------------+---------------------------+------------------------------+
1229+
| zlib_codec | Compress the operand | :meth:`zlib.compress`, |
1230+
| | using gzip | :meth:`zlib.decompress` |
1231+
+----------------------+---------------------------+------------------------------+
1232+
1233+
.. [#b64] Rather than accepting any :term:`bytes-like object`,
1234+
``'base64_codec'`` accepts only :class:`bytes` and :class:`bytearray` for
1235+
encoding and only :class:`bytes`, :class:`bytearray`, and ASCII-only
1236+
instances of :class:`str` for decoding
1237+
1238+
1239+
The following codecs provide :class:`str` to :class:`str` mappings.
12201240

12211241
.. tabularcolumns:: |l|L|
12221242

@@ -1228,7 +1248,7 @@ The following codecs provide string-to-string mappings.
12281248
+--------------------+---------------------------+
12291249

12301250
.. versionadded:: 3.2
1231-
bytes-to-bytes and string-to-string codecs.
1251+
bytes-to-bytes and str-to-str codecs.
12321252

12331253

12341254
:mod:`encodings.idna` --- Internationalized Domain Names in Applications

0 commit comments

Comments
 (0)