Merge pull request #257 from simplejson/python3-doc-updates

Start transitioning docs to be Python 3 centric

CHANGES.txt

+Version 3.17.0 released 2019-11-17
+
+* Updated documentation to be Python 3 first, and
+  have removed documentation notes about version changes
+  that occurred more than five years ago.
+  https://github.com/simplejson/simplejson/pull/257
+  https://github.com/simplejson/simplejson/pull/254
+* Update build matrix for Python 3.8
+  https://github.com/simplejson/simplejson/pull/255
+  https://github.com/simplejson/simplejson/pull/256
+
 Version 3.16.1 released 2018-09-07
 
 * Added examples for JSON lines use cases

README.rst

@@ -8,11 +8,12 @@
     :target: https://ci.appveyor.com/project/etrepum/simplejson/branch/master
 
 simplejson is a simple, fast, complete, correct and extensible
-JSON <http://json.org> encoder and decoder for Python 2.5+
-and Python 3.3+.  It is pure Python code with no dependencies,
-but includes an optional C extension for a serious speed boost.
+JSON <http://json.org> encoder and decoder for Python 3.3+
+with legacy support for Python 2.5+.  It is pure Python code
+with no dependencies, but includes an optional C extension
+for a serious speed boost.
 
 The latest documentation for simplejson can be read online here:
 https://simplejson.readthedocs.io/
 
 simplejson is the externally maintained development version of the
@@ -14,10 +15,11 @@
 
 The latest documentation for simplejson can be read online here:
 https://simplejson.readthedocs.io/
 
 simplejson is the externally maintained development version of the
-json library included with Python 2.6 and Python 3.0, but maintains
-backwards compatibility with Python 2.5.
+json library included with Python (since 2.6). This version is tested
+with the latest Python 3.8 and maintains backwards compatibility
+with Python 3.3+ and the legacy Python 2.5 - Python 2.7 releases.
 
 The encoder can be specialized to provide serialization in any kind of
 situation, without any special support by the objects to be serialized

conf.py

@@ -42,5 +42,5 @@
 # other places throughout the built documents.
 #
 # The short X.Y version.
-version = '3.16'
+version = '3.17'
 # The full version, including alpha/beta/rc tags.
@@ -46,5 +46,5 @@
 # The full version, including alpha/beta/rc tags.
-release = '3.16.1'
+release = '3.17.0'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

simplejson/__init__.py

@@ -118,7 +118,7 @@
 
 """
 from __future__ import absolute_import
-__version__ = '3.16.1'
+__version__ = '3.17.0'
 __all__ = [
     'dump', 'dumps', 'load', 'loads',
     'JSONDecoder', 'JSONDecodeError', 'JSONEncoder',
@@ -180,6 +180,6 @@
     ``.write()``-supporting file-like object).
 
     If *skipkeys* is true then ``dict`` keys that are not basic types
-    (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
+    (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``)
     will be skipped instead of raising a ``TypeError``.
 
@@ -184,14 +184,8 @@
     will be skipped instead of raising a ``TypeError``.
 
-    If *ensure_ascii* is false, then the some chunks written to ``fp``
-    may be ``unicode`` instances, subject to normal Python ``str`` to
-    ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
-    understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
-    to cause an error.
-
-    If *check_circular* is false, then the circular reference check
-    for container types will be skipped and a circular reference will
-    result in an ``OverflowError`` (or worse).
+    If *ensure_ascii* is false (default: ``True``), then the output may
+    contain non-ASCII characters, so long as they do not need to be escaped
+    by JSON. When it is true, all non-ASCII characters are escaped.
 
     If *allow_nan* is false, then it will be a ``ValueError`` to
     serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
@@ -202,9 +196,7 @@
     If *indent* is a string, then JSON array elements and object members
     will be pretty-printed with a newline followed by that string repeated
     for each level of nesting. ``None`` (the default) selects the most compact
-    representation without any newlines. For backwards compatibility with
-    versions of simplejson earlier than 2.1.0, an integer is also accepted
-    and is converted to a string with that many spaces.
+    representation without any newlines.
 
     If specified, *separators* should be an
     ``(item_separator, key_separator)`` tuple.  The default is ``(', ', ': ')``
@@ -309,6 +301,6 @@
     """Serialize ``obj`` to a JSON formatted ``str``.
 
     If ``skipkeys`` is false then ``dict`` keys that are not basic types
-    (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
+    (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``)
     will be skipped instead of raising a ``TypeError``.
 
@@ -313,8 +305,8 @@
     will be skipped instead of raising a ``TypeError``.
 
-    If ``ensure_ascii`` is false, then the return value will be a
-    ``unicode`` instance subject to normal Python ``str`` to ``unicode``
-    coercion rules instead of being escaped to an ASCII ``str``.
+    If *ensure_ascii* is false (default: ``True``), then the output may
+    contain non-ASCII characters, so long as they do not need to be escaped
+    by JSON. When it is true, all non-ASCII characters are escaped.
 
     If ``check_circular`` is false, then the circular reference check
     for container types will be skipped and a circular reference will
@@ -338,7 +330,8 @@
     compact JSON representation, you should specify ``(',', ':')`` to eliminate
     whitespace.
 
-    ``encoding`` is the character encoding for str instances, default is UTF-8.
+    ``encoding`` is the character encoding for bytes instances, default is
+    UTF-8.
 
     ``default(obj)`` is a function that should return a serializable version
     of obj or raise TypeError. The default simply raises TypeError.
@@ -428,6 +421,6 @@
         use_decimal=False, namedtuple_as_object=True, tuple_as_array=True,
         **kw):
     """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
-    a JSON document) to a Python object.
+    a JSON document as `str` or `bytes`) to a Python object.
 
     *encoding* determines the encoding used to interpret any
@@ -432,10 +425,7 @@
 
     *encoding* determines the encoding used to interpret any
-    :class:`str` objects decoded by this instance (``'utf-8'`` by
-    default).  It has no effect when decoding :class:`unicode` objects.
-
-    Note that currently only encodings that are a superset of ASCII work,
-    strings of other encodings should be passed in as :class:`unicode`.
+    `bytes` objects decoded by this instance (``'utf-8'`` by
+    default). It has no effect when decoding `str` objects.
 
     *object_hook*, if specified, will be called with the result of every
     JSON object decoded and its return value will be used in place of the
@@ -488,6 +478,6 @@
     document) to a Python object.
 
     *encoding* determines the encoding used to interpret any
-    :class:`str` objects decoded by this instance (``'utf-8'`` by
+    :class:`bytes` objects decoded by this instance (``'utf-8'`` by
     default). It has no effect when decoding :class:`unicode` objects.
 
@@ -492,8 +482,5 @@
     default). It has no effect when decoding :class:`unicode` objects.
 
-    Note that currently only encodings that are a superset of ASCII work,
-    strings of other encodings should be passed in as :class:`unicode`.
-
     *object_hook*, if specified, will be called with the result of every
     JSON object decoded and its return value will be used in place of the
     given :class:`dict`.  This can be used to provide custom