Skip to content
GitLab
Explore
Sign in
Register
Primary navigation
Search or go to…
Project
S
simplejson
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Deploy
Releases
Container registry
Model registry
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
OpenVMS
Python
Modules
simplejson
Commits
3bfe32988a3c
Commit
3bfe32988a3c
authored
10 years ago
by
Bob Ippolito
Browse files
Options
Downloads
Patches
Plain Diff
update documentation per #102
parent
efd37532e4e9
No related branches found
No related tags found
No related merge requests found
Changes
5
Show whitespace changes
Inline
Side-by-side
Showing
5 changed files
CHANGES.txt
+5
-0
5 additions, 0 deletions
CHANGES.txt
conf.py
+1
-1
1 addition, 1 deletion
conf.py
index.rst
+216
-39
216 additions, 39 deletions
index.rst
setup.py
+1
-1
1 addition, 1 deletion
setup.py
simplejson/__init__.py
+1
-1
1 addition, 1 deletion
simplejson/__init__.py
with
224 additions
and
42 deletions
CHANGES.txt
+
5
−
0
View file @
3bfe3298
Version 3.6.1 released 2014-08-09
* Documentation updates
https://github.com/simplejson/simplejson/issues/102
Version 3.6.0 released 2014-07-21
* Automatically strip any UTF-8 BOM from input to more closely
...
...
This diff is collapsed.
Click to expand it.
conf.py
+
1
−
1
View file @
3bfe3298
...
...
@@ -44,7 +44,7 @@
# The short X.Y version.
version
=
'
3.6
'
# The full version, including alpha/beta/rc tags.
release
=
'
3.6.
0
'
release
=
'
3.6.
1
'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
...
...
This diff is collapsed.
Click to expand it.
index.rst
+
216
−
39
View file @
3bfe3298
...
...
@@ -6,8 +6,10 @@
.. moduleauthor:: Bob Ippolito <bob@redivi.com>
.. sectionauthor:: Bob Ippolito <bob@redivi.com>
JSON (JavaScript Object Notation) <http://json.org> is a subset of JavaScript
syntax (ECMA-262 3rd edition) used as a lightweight data interchange format.
`JSON (JavaScript Object Notation) <http://json.org>`_, specified by
:rfc:`4627`, is a lightweight data interchange format based on a subset of
`JavaScript <http://en.wikipedia.org/wiki/JavaScript>`_ syntax (`ECMA-262 3rd
edition <http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf>`_).
:mod:`simplejson` exposes an API familiar to users of the standard library
:mod:`marshal` and :mod:`pickle` modules. It is the externally maintained
...
...
@@ -107,7 +109,7 @@
'[2.0, 1.0]'
.. highlight::
none
.. highlight::
bash
Using :mod:`simplejson.tool` from the shell to validate and pretty-print::
...
...
@@ -122,10 +124,12 @@
.. note::
The JSON produced by this module's default settings is a subset of
YAML, so it may be used as a serializer for that as well.
JSON is a subset of `YAML <http://yaml.org/>`_ 1.2. The JSON produced by
this module's default settings (in particular, the default *separators*
value) is also a subset of YAML 1.0 and 1.1. This module can thus also be
used as a YAML serializer.
Basic Usage
-----------
...
...
@@ -127,8 +131,15 @@
Basic Usage
-----------
.. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, sort_keys[, item_sort_key[, [for_json[, ignore_nan[, int_as_string_bitcount[, **kw]]]]]]]]]]]]]]]]]]])
.. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, cls=None, \
indent=None, separators=None, encoding='utf-8', \
default=None, use_decimal=True, \
namedtuple_as_object=True, tuple_as_array=True, \
bigint_as_string=False, sort_keys=False, \
item_sort_key=None, for_json=None, ignore_nan=False, \
int_as_string_bitcount=None, **kw)
Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
...
...
@@ -133,9 +144,9 @@
Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
file-like object).
file-like object)
using this :ref:`conversion table <py-to-json-table>`
.
If *skipkeys* is true (default: ``False``), then dict keys that are not
of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
:class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
:exc:`TypeError`.
...
...
@@ -136,9 +147,13 @@
If *skipkeys* is true (default: ``False``), then dict keys that are not
of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
:class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
:exc:`TypeError`.
The :mod:`simplejson` module will produce :class:`str` objects in Python 3,
not :class:`bytes` objects. Therefore, ``fp.write()`` must support
:class:`str` input.
If *ensure_ascii* is false (default: ``True``), then some chunks written
to *fp* may be :class:`unicode` instances, subject to normal Python
:class:`str` to :class:`unicode` coercion rules. Unless ``fp.write()``
...
...
@@ -262,7 +277,7 @@
.. versionchanged:: 3.2.0
*ignore_nan* is new in 3.2.0.
If *int_as_string_bitcount* is a positive number ``n`` (default: ``
Fals
e``),
If *int_as_string_bitcount* is a positive number ``n`` (default: ``
Non
e``),
:class:`int` ``2**n`` and higher or lower than ``-2**n`` will be encoded as strings. This is to
avoid the rounding that happens in Javascript otherwise. Note that this
option loses type information, so use with extreme caution.
...
...
@@ -278,10 +293,17 @@
container protocol to delimit them.
.. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, sort_keys[, item_sort_key[, for_json[, ignore_nan[, int_as_string_bitcount[, **kw]]]]]]]]]]]]]]]]]])
.. function:: dumps(obj, skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, cls=None, \
indent=None, separators=None, encoding='utf-8', \
default=None, use_decimal=True, \
namedtuple_as_object=True, tuple_as_array=True, \
bigint_as_string=False, sort_keys=False, \
item_sort_key=None, for_json=None, ignore_nan=False, \
int_as_string_bitcount=None, **kw)
Serialize *obj* to a JSON formatted :class:`str`.
If *ensure_ascii* is false, then the return value will be a
:class:`unicode` instance. The other arguments have the same meaning as in
:func:`dump`. Note that the default *ensure_ascii* setting has much
...
...
@@ -282,11 +304,11 @@
Serialize *obj* to a JSON formatted :class:`str`.
If *ensure_ascii* is false, then the return value will be a
:class:`unicode` instance. The other arguments have the same meaning as in
:func:`dump`. Note that the default *ensure_ascii* setting has much
better performance.
better performance
in Python 2
.
The other options have the same meaning as in :func:`dump`.
...
...
@@ -289,7 +311,10 @@
The other options have the same meaning as in :func:`dump`.
.. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, use_decimal[, **kw]]]]]]]]])
.. function:: load(fp, encoding='utf-8', cls=None, object_hook=None, \
parse_float=None, parse_int=None, \
parse_constant=None, object_pairs_hook=None, \
use_decimal=None, **kw)
Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
...
...
@@ -294,6 +319,7 @@
Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
document) to a Python object. :exc:`JSONDecodeError` will be
document) to a Python object using this
:ref:`conversion table <json-to-py-table>`. :exc:`JSONDecodeError` will be
raised if the given JSON document is not valid.
If the contents of *fp* are encoded with an ASCII based encoding other than
...
...
@@ -311,7 +337,8 @@
*object_hook* is an optional function that will be called with the result of
any object literal decode (a :class:`dict`). The return value of
*object_hook* will be used instead of the :class:`dict`. This feature can be used
to implement custom decoders (e.g. JSON-RPC class hinting).
to implement custom decoders (e.g. `JSON-RPC <http://www.jsonrpc.org>`_
class hinting).
*object_pairs_hook* is an optional function that will be called with the
result of any object literal decode with an ordered list of pairs. The
...
...
@@ -363,7 +390,10 @@
only one JSON document, it is recommended to use :func:`loads`.
.. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, use_decimal[, **kw]]]]]]]]])
.. function:: loads(fp, encoding='utf-8', cls=None, object_hook=None, \
parse_float=None, parse_int=None, \
parse_constant=None, object_pairs_hook=None, \
use_decimal=None, **kw)
Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON
document) to a Python object. :exc:`JSONDecodeError` will be
...
...
@@ -385,9 +415,11 @@
Encoders and decoders
---------------------
.. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, strict]]]]]]])
.. class:: JSONDecoder(encoding='utf-8', object_hook=None, parse_float=None, \
parse_int=None, parse_constant=None, \
object_pairs_hook=None, strict=True)
Simple JSON decoder.
Performs the following translations in decoding by default:
...
...
@@ -389,27 +421,29 @@
Simple JSON decoder.
Performs the following translations in decoding by default:
+---------------+-------------------+
| JSON | Python |
+===============+===================+
| object | dict |
+---------------+-------------------+
| array | list |
+---------------+-------------------+
| string | unicode |
+---------------+-------------------+
| number (int) | int, long |
+---------------+-------------------+
| number (real) | float |
+---------------+-------------------+
| true | True |
+---------------+-------------------+
| false | False |
+---------------+-------------------+
| null | None |
+---------------+-------------------+
.. _json-to-py-table:
+---------------+-----------+-----------+
| JSON | Python 2 | Python 3 |
+===============+===========+===========+
| object | dict | dict |
+---------------+-----------+-----------+
| array | list | list |
+---------------+-----------+-----------+
| string | unicode | str |
+---------------+-----------+-----------+
| number (int) | int, long | int |
+---------------+-----------+-----------+
| number (real) | float | float |
+---------------+-----------+-----------+
| true | True | True |
+---------------+-----------+-----------+
| false | False | False |
+---------------+-----------+-----------+
| null | None | None |
+---------------+-----------+-----------+
It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
corresponding ``float`` values, which is outside the JSON spec.
...
...
@@ -484,9 +518,16 @@
:exc:`JSONDecodeError` will be raised if the given JSON
document is not valid.
.. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, item_sort_key[, for_json[, ignore_nan]]]]]]]]]]]]]]]])
.. class:: JSONEncoder(skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, sort_keys=False, \
indent=None, separators=None, encoding='utf-8', \
default=None, use_decimal=True, \
namedtuple_as_object=True, tuple_as_array=True, \
bigint_as_string=False, item_sort_key=None, \
for_json=True, ignore_nan=False, \
int_as_string_bitcount=None)
Extensible JSON encoder for Python data structures.
Supports the following objects and types by default:
...
...
@@ -488,8 +529,10 @@
Extensible JSON encoder for Python data structures.
Supports the following objects and types by default:
.. _py-to-json-table:
+-------------------+---------------+
| Python | JSON |
+===================+===============+
...
...
@@ -508,6 +551,9 @@
| None | null |
+-------------------+---------------+
It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
corresponding ``float`` values, which is outside the JSON spec.
.. versionchanged:: 2.2.0
Changed *namedtuple* encoding from JSON array to object.
...
...
@@ -529,7 +575,7 @@
:class:`str` objects with all incoming unicode characters escaped. If
*ensure_ascii* is false, the output will be a unicode object.
If *check_circular* is
fals
e (the default), then lists, dicts, and custom
If *check_circular* is
tru
e (the default), then lists, dicts, and custom
encoded objects will be checked for circular references during encoding to
prevent an infinite recursion (which would cause an :exc:`OverflowError`).
Otherwise, no such check takes place.
...
...
@@ -675,7 +721,16 @@
Note that :meth:`encode` has much better performance than
:meth:`iterencode`.
.. class:: JSONEncoderForHTML([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, item_sort_key[, for_json[, ignore_nan]]]]]]]]]]]]]]]])
.. class:: JSONEncoderForHTML(skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, \
sort_keys=False, indent=None, separators=None, \
encoding='utf-8', \
default=None, use_decimal=True, \
namedtuple_as_object=True, \
tuple_as_array=True, \
bigint_as_string=False, item_sort_key=None, \
for_json=True, ignore_nan=False, \
int_as_string_bitcount=None)
Subclass of :class:`JSONEncoder` that escapes &, <, and > for embedding in HTML.
...
...
@@ -685,7 +740,7 @@
Exceptions
----------
.. exception:: JSONDecodeError(msg, doc, pos
[
, end
]
)
.. exception:: JSONDecodeError(msg, doc, pos, end
=None
)
Subclass of :exc:`ValueError` with the following additional attributes:
...
...
@@ -720,3 +775,125 @@
.. attribute:: endcolno
The column corresponding to end (may be ``None``)
Standard Compliance
-------------------
The JSON format is specified by :rfc:`4627`. This section details this
module's level of compliance with the RFC. For simplicity,
:class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and parameters other
than those explicitly mentioned, are not considered.
This module does not comply with the RFC in a strict fashion, implementing some
extensions that are valid JavaScript but not valid JSON. In particular:
- Top-level non-object, non-array values are accepted and output;
- Infinite and NaN number values are accepted and output;
- Repeated names within an object are accepted, and only the value of the last
name-value pair is used.
Since the RFC permits RFC-compliant parsers to accept input texts that are not
RFC-compliant, this module's deserializer is technically RFC-compliant under
default settings.
Character Encodings
^^^^^^^^^^^^^^^^^^^
The RFC recommends that JSON be represented using either UTF-8, UTF-16, or
UTF-32, with UTF-8 being the default.
As permitted, though not required, by the RFC, this module's serializer sets
*ensure_ascii=True* by default, thus escaping the output so that the resulting
strings only contain ASCII characters.
Other than the *ensure_ascii* parameter, this module is defined strictly in
terms of conversion between Python objects and
:class:`Unicode strings <str>`, and thus does not otherwise address the issue
of character encodings.
Infinite and NaN Number Values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The RFC does not permit the representation of infinite or NaN number values.
Despite that, by default, this module accepts and outputs ``Infinity``,
``-Infinity``, and ``NaN`` as if they were valid JSON number literal values::
>>> # Neither of these calls raises an exception, but the results are not valid JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same when deserializing
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan
In the serializer, the *allow_nan* parameter can be used to alter this
behavior. In the deserializer, the *parse_constant* parameter can be used to
alter this behavior.
Repeated Names Within an Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The RFC specifies that the names within a JSON object should be unique, but
does not specify how repeated names in JSON objects should be handled. By
default, this module does not raise an exception; instead, it ignores all but
the last name-value pair for a given name::
>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json) == {'x': 3}
True
The *object_pairs_hook* parameter can be used to alter this behavior.
.. highlight:: bash
.. _json-commandline:
Command Line Interface
----------------------
The :mod:`simplejson.tool` module provides a simple command line interface to
validate and pretty-print JSON.
If the optional :option:`infile` and :option:`outfile` arguments are not
specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively::
$ echo '{"json": "obj"}' | python -m simplejson.tool
{
"json": "obj"
}
$ echo '{1.2:3.4}' | python -m simplejson.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
Command line options
^^^^^^^^^^^^^^^^^^^^
.. cmdoption:: infile
The JSON file to be validated or pretty-printed::
$ python -m simplejson.tool mp_films.json
[
{
"title": "And Now for Something Completely Different",
"year": 1971
},
{
"title": "Monty Python and the Holy Grail",
"year": 1975
}
]
If *infile* is not specified, read from :attr:`sys.stdin`.
.. cmdoption:: outfile
Write the output of the *infile* to the given *outfile*. Otherwise, write it
to :attr:`sys.stdout`.
This diff is collapsed.
Click to expand it.
setup.py
+
1
−
1
View file @
3bfe3298
...
...
@@ -11,7 +11,7 @@
DistutilsPlatformError
IS_PYPY
=
hasattr
(
sys
,
'
pypy_translation_info
'
)
VERSION
=
'
3.6.
0
'
VERSION
=
'
3.6.
1
'
DESCRIPTION
=
"
Simple, fast, extensible JSON encoder/decoder for Python
"
with
open
(
'
README.rst
'
,
'
r
'
)
as
f
:
...
...
This diff is collapsed.
Click to expand it.
simplejson/__init__.py
+
1
−
1
View file @
3bfe3298
...
...
@@ -98,7 +98,7 @@
Expecting property name: line 1 column 3 (char 2)
"""
from
__future__
import
absolute_import
__version__
=
'
3.6.
0
'
__version__
=
'
3.6.
1
'
__all__
=
[
'
dump
'
,
'
dumps
'
,
'
load
'
,
'
loads
'
,
'
JSONDecoder
'
,
'
JSONDecodeError
'
,
'
JSONEncoder
'
,
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment