Skip to content

C
cpython
Commit 650e322f authored by Nick Coghlan's avatar Nick Coghlan
Browse files
Options

Issue 17844: Clarify meaning of different codec tables

parent c1939b8f
Hide whitespace changes
Inline Side-by-side
Showing with 50 additions and 30 deletions
Doc/library/codecs.rst
View file @ 650e322f
......@@ -1142,7 +1142,19 @@ particular, the following variants typically exist:
| utf_8_sig | | all languages |
+-----------------+--------------------------------+--------------------------------+
.. XXX fix here, should be in above table
Python Specific Encodings
-------------------------
A number of predefined codecs are specific to Python, so their codec names have
no meaning outside Python. These are listed in the tables below based on the
expected input and output types (note that while text encodings are the most
common use case for codecs, the underlying codec infrastructure supports
arbitrary data transforms rather than just text encodings). For asymmetric
codecs, the stated purpose describes the encoding direction.
The following codecs provide :class:`str` to :class:`bytes` encoding and
:term:`bytes-like object` to :class:`str` decoding, similar to the Unicode text
encodings.
.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
......@@ -1186,37 +1198,45 @@ particular, the following variants typically exist:
| | | .. deprecated:: 3.3 |
+--------------------+---------+---------------------------+
The following codecs provide bytes-to-bytes mappings.
The following codecs provide :term:`bytes-like object` to :class:`bytes`
mappings.
.. tabularcolumns:: |l|L|L|
+--------------------+---------------------------+------------------------------+
| Codec | Purpose | Encoder/decoder |
+====================+===========================+==============================+
| base64_codec | Convert operand to MIME | :meth:`base64.b64encode`, |
| | base64 (the result always | :meth:`base64.b64decode` |
| | includes a trailing | |
| | ``'\n'``) | |
+--------------------+---------------------------+------------------------------+
| bz2_codec | Compress the operand | :meth:`bz2.compress`, |
| | using bz2 | :meth:`bz2.decompress` |
+--------------------+---------------------------+------------------------------+
| hex_codec | Convert operand to | :meth:`base64.b16encode`, |
| | hexadecimal | :meth:`base64.b16decode` |
| | representation, with two | |
| | digits per byte | |
+--------------------+---------------------------+------------------------------+
| quopri_codec | Convert operand to MIME | :meth:`quopri.encodestring`, |
| | quoted printable | :meth:`quopri.decodestring` |
+--------------------+---------------------------+------------------------------+
| uu_codec | Convert the operand using | :meth:`uu.encode`, |
| | uuencode | :meth:`uu.decode` |
+--------------------+---------------------------+------------------------------+
| zlib_codec | Compress the operand | :meth:`zlib.compress`, |
| | using gzip | :meth:`zlib.decompress` |
+--------------------+---------------------------+------------------------------+
The following codecs provide string-to-string mappings.
+----------------------+---------------------------+------------------------------+
| Codec | Purpose | Encoder/decoder |
+======================+===========================+==============================+
| base64_codec [#b64]_ | Convert operand to MIME | :meth:`base64.b64encode`, |
| | base64 (the result always | :meth:`base64.b64decode` |
| | includes a trailing | |
| | ``'\n'``) | |
+----------------------+---------------------------+------------------------------+
| bz2_codec | Compress the operand | :meth:`bz2.compress`, |
| | using bz2 | :meth:`bz2.decompress` |
+----------------------+---------------------------+------------------------------+
| hex_codec | Convert operand to | :meth:`base64.b16encode`, |
| | hexadecimal | :meth:`base64.b16decode` |
| | representation, with two | |
| | digits per byte | |
+----------------------+---------------------------+------------------------------+
| quopri_codec | Convert operand to MIME | :meth:`quopri.encodestring`, |
| | quoted printable | :meth:`quopri.decodestring` |
+----------------------+---------------------------+------------------------------+
| uu_codec | Convert the operand using | :meth:`uu.encode`, |
| | uuencode | :meth:`uu.decode` |
+----------------------+---------------------------+------------------------------+
| zlib_codec | Compress the operand | :meth:`zlib.compress`, |
| | using gzip | :meth:`zlib.decompress` |
+----------------------+---------------------------+------------------------------+
.. [#b64] Rather than accepting any :term:`bytes-like object`,
``'base64_codec'`` accepts only :class:`bytes` and :class:`bytearray` for
encoding and only :class:`bytes`, :class:`bytearray`, and ASCII-only
instances of :class:`str` for decoding
The following codecs provide :class:`str` to :class:`str` mappings.
.. tabularcolumns:: |l|L|
......@@ -1228,7 +1248,7 @@ The following codecs provide string-to-string mappings.
+--------------------+---------------------------+
.. versionadded:: 3.2
bytes-to-bytes and string-to-string codecs.
bytes-to-bytes and str-to-str codecs.
:mod:`encodings.idna` --- Internationalized Domain Names in Applications
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7