gh-125063: marshal: Add version 5, improve documentation (GH-126829)

* Document that slices can be marshalled
* Deduplicate and organize the list of supported types
  in docs
* Organize the type code list in marshal.c, to make
  it more obvious that this is a versioned format
* Back-fill some historical info

Co-authored-by: Michael Droettboom <mdboom@gmail.com>

2 files changed, 51 insertions, 22 deletions

diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst
index b9085ad..61218a1 100644
--- a/Doc/c-api/marshal.rst
+++ b/Doc/c-api/marshal.rst
@@ -13,11 +13,12 @@ binary mode.
 
 Numeric values are stored with the least significant byte first.
 
-The module supports two versions of the data format: version 0 is the
-historical version, version 1 shares interned strings in the file, and upon
-unmarshalling.  Version 2 uses a binary format for floating-point numbers.
-``Py_MARSHAL_VERSION`` indicates the current file format (currently 2).
+The module supports several versions of the data format; see
+the :py:mod:`Python module documentation <marshal>` for details.
 
+.. c:macro:: Py_MARSHAL_VERSION
+
+   The current format version. See :py:data:`marshal.version`.
 
 .. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
 
diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst
index 9e4606d..8b14ee4 100644
--- a/Doc/library/marshal.rst
+++ b/Doc/library/marshal.rst
@@ -38,23 +38,39 @@ supports a substantially wider range of objects than marshal.
    maliciously constructed data.  Never unmarshal data received from an
    untrusted or unauthenticated source.
 
+There are functions that read/write files as well as functions operating on
+bytes-like objects.
+
 .. index:: object; code, code object
 
 Not all Python object types are supported; in general, only objects whose value
 is independent from a particular invocation of Python can be written and read by
-this module.  The following types are supported: booleans, integers, floating-point
-numbers, complex numbers, strings, bytes, bytearrays, tuples, lists, sets,
-frozensets, dictionaries, and code objects (if *allow_code* is true),
-where it should be understood that
-tuples, lists, sets, frozensets and dictionaries are only supported as long as
-the values contained therein are themselves supported.  The
-singletons :const:`None`, :const:`Ellipsis` and :exc:`StopIteration` can also be
-marshalled and unmarshalled.
-For format *version* lower than 3, recursive lists, sets and dictionaries cannot
-be written (see below).
+this module.  The following types are supported:
+
+* Numeric types: :class:`int`, :class:`bool`, :class:`float`, :class:`complex`.
+* Strings (:class:`str`) and :class:`bytes`.
+  :term:`Bytes-like objects <bytes-like object>` like :class:`bytearray` are
+  marshalled as :class:`!bytes`.
+* Containers: :class:`tuple`, :class:`list`, :class:`set`, :class:`frozenset`,
+  and (since :data:`version` 5), :class:`slice`.
+  It should be understood that these are supported only if the values contained
+  therein are themselves supported.
+  Recursive containers are supported since :data:`version` 3.
+* The singletons :const:`None`, :const:`Ellipsis` and :exc:`StopIteration`.
+* :class:`code` objects, if *allow_code* is true. See note above about
+  version dependence.
+
+.. versionchanged:: 3.4
+
+   * Added format version 3, which supports marshalling recursive lists, sets
+     and dictionaries.
+   * Added format version 4, which supports efficient representations
+     of short strings.
+
+.. versionchanged:: next
+
+   Added format version 5, which allows marshalling slices.
 
-There are functions that read/write files as well as functions operating on
-bytes-like objects.
 
 The module defines these functions:
 
@@ -140,11 +156,24 @@ In addition, the following constants are defined:
 
 .. data:: version
 
-   Indicates the format that the module uses. Version 0 is the historical
-   format, version 1 shares interned strings and version 2 uses a binary format
-   for floating-point numbers.
-   Version 3 adds support for object instancing and recursion.
-   The current version is 4.
+   Indicates the format that the module uses.
+   Version 0 is the historical first version; subsequent versions
+   add new features.
+   Generally, a new version becomes the default when it is introduced.
+
+   ======= =============== ====================================================
+   Version Available since New features
+   ======= =============== ====================================================
+   1       Python 2.4      Sharing interned strings
+   ------- --------------- ----------------------------------------------------
+   2       Python 2.5      Binary representation of floats
+   ------- --------------- ----------------------------------------------------
+   3       Python 3.4      Support for object instancing and recursion
+   ------- --------------- ----------------------------------------------------
+   4       Python 3.4      Efficient representation of short strings
+   ------- --------------- ----------------------------------------------------
+   5       Python 3.14     Support for :class:`slice` objects
+   ======= =============== ====================================================
 
 
 .. rubric:: Footnotes
@@ -154,4 +183,3 @@ In addition, the following constants are defined:
    around in a self-contained form. Strictly speaking, "to marshal" means to
    convert some data from internal to external form (in an RPC buffer for instance)
    and "unmarshalling" for the reverse process.
-