diff options
| author | Bob Ippolito <bob@redivi.com> | 2008-12-30 19:00:33 +0000 |
|---|---|---|
| committer | Bob Ippolito <bob@redivi.com> | 2008-12-30 19:00:33 +0000 |
| commit | aa95b2226ed8566a643378f0995ee626b8200368 (patch) | |
| tree | 7400c0070e2746a6c80d7b7ab1716444bfd92656 | |
| parent | ab589fa80b65895376cfb942ef786eb6b036f14a (diff) | |
| download | simplejson-aa95b2226ed8566a643378f0995ee626b8200368.tar.gz | |
version bump, fixes to docs re http://bugs.python.org/issue4783
git-svn-id: http://simplejson.googlecode.com/svn/trunk@157 a4795897-2c25-0410-b006-0d3caba88fa1
| -rw-r--r-- | docs/_sources/index.txt | 44 | ||||
| -rw-r--r-- | docs/genindex.html | 12 | ||||
| -rw-r--r-- | docs/index.html | 61 | ||||
| -rw-r--r-- | docs/search.html | 2 | ||||
| -rw-r--r-- | docs/searchindex.json | 2 | ||||
| -rw-r--r-- | index.rst | 44 | ||||
| -rw-r--r-- | setup.py | 2 | ||||
| -rw-r--r-- | simplejson/__init__.py | 86 |
8 files changed, 174 insertions, 79 deletions
diff --git a/docs/_sources/index.txt b/docs/_sources/index.txt index 2f950e2..ddf7e66 100644 --- a/docs/_sources/index.txt +++ b/docs/_sources/index.txt @@ -13,11 +13,11 @@ syntax (ECMA-262 3rd edition) used as a lightweight data interchange format. :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained version of the :mod:`json` library contained in Python 2.6, but maintains compatibility with Python 2.4 and Python 2.5 and (currently) has -significant performance advantages, even without using the optional C +significant performance advantages, even without using the optional C extension for speedups. Encoding basic Python object hierarchies:: - + >>> import simplejson as json >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) '["foo", {"bar": ["baz", null, 1.0, 2]}]' @@ -46,12 +46,12 @@ Pretty printing:: >>> import simplejson as json >>> print json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4) { - "4": 5, + "4": 5, "6": 7 } Decoding JSON:: - + >>> import simplejson as json >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj @@ -70,7 +70,7 @@ Specializing JSON object decoding:: ... if '__complex__' in dct: ... return complex(dct['real'], dct['imag']) ... return dct - ... + ... >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', ... object_hook=as_complex) (1+2j) @@ -79,7 +79,7 @@ Specializing JSON object decoding:: True Specializing JSON object encoding:: - + >>> import simplejson as json >>> def encode_complex(obj): ... if isinstance(obj, complex): @@ -92,12 +92,12 @@ Specializing JSON object encoding:: '[2.0, 1.0]' >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j)) '[2.0, 1.0]' - + .. highlight:: none Using simplejson.tool from the shell to validate and pretty-print:: - + $ echo '{"json":"obj"}' | python -msimplejson.tool { "json": "obj" @@ -107,7 +107,7 @@ Using simplejson.tool from the shell to validate and pretty-print:: .. highlight:: python -.. note:: +.. 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. @@ -156,10 +156,16 @@ Basic Usage *default(obj)* is a function that should return a serializable version of *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. - To use a custom :class:`JSONEncoder`` subclass (e.g. one that overrides the + To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the :meth:`default` method to serialize additional types), specify it with the *cls* kwarg. +.. note:: + + JSON is not a framed protocol so unlike :mod:`pickle` or :mod:`marshal` it + does not make sense to serialize more than one JSON document without some + container protocol to delimit them. + .. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]]) @@ -171,7 +177,7 @@ Basic Usage better performance. -.. function load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) +.. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON document) to a Python object. @@ -206,8 +212,16 @@ Basic Usage kwarg. Additional keyword arguments will be passed to the constructor of the class. +.. note:: + + :func:`load` will read the rest of the file-like object as a string and + then call :func:`loads`. It does not stop at the end of the first valid + JSON document it finds and it will raise an error if there is anything + other than whitespace after the document. Except for files containing + only one JSON document, it is recommended to use :func:`loads`. + -.. function loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) +.. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON document) to a Python object. @@ -372,7 +386,7 @@ Encoders and decoders For example, to support arbitrary iterators, you could implement default like this:: - + def default(self, o): try: iterable = iter(o) @@ -397,9 +411,9 @@ Encoders and decoders Encode the given object, *o*, and yield each string representation as available. For example:: - + for chunk in JSONEncoder().iterencode(bigobject): mysocket.write(chunk) - + Note that :meth:`encode` has much better performance than :meth:`iterencode`. diff --git a/docs/genindex.html b/docs/genindex.html index 102efdf..eb50807 100644 --- a/docs/genindex.html +++ b/docs/genindex.html @@ -39,7 +39,7 @@ <h1 id="index">Index</h1> - <a href="#D"><strong>D</strong></a> | <a href="#E"><strong>E</strong></a> | <a href="#I"><strong>I</strong></a> | <a href="#J"><strong>J</strong></a> | <a href="#R"><strong>R</strong></a> | <a href="#S"><strong>S</strong></a> + <a href="#D"><strong>D</strong></a> | <a href="#E"><strong>E</strong></a> | <a href="#I"><strong>I</strong></a> | <a href="#J"><strong>J</strong></a> | <a href="#L"><strong>L</strong></a> | <a href="#R"><strong>R</strong></a> | <a href="#S"><strong>S</strong></a> <hr /> @@ -76,6 +76,14 @@ <dt><a href="index.html#simplejson.JSONEncoder">JSONEncoder (class in simplejson)</a></dt></dl></td><td width="33%" valign="top"><dl> </dl></td></tr></table> +<h2 id="L">L</h2> +<table width="100%" class="indextable"><tr><td width="33%" valign="top"> +<dl> + +<dt><a href="index.html#simplejson.load">load() (in module simplejson)</a></dt> +<dt><a href="index.html#simplejson.loads">loads() (in module simplejson)</a></dt></dl></td><td width="33%" valign="top"><dl> +</dl></td></tr></table> + <h2 id="R">R</h2> <table width="100%" class="indextable"><tr><td width="33%" valign="top"> <dl> @@ -120,7 +128,7 @@ </div> <div class="footer"> © Copyright 2008, Bob Ippolito. - Last updated on Nov 07, 2008. + Last updated on Dec 30, 2008. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>. </div> </body> diff --git a/docs/index.html b/docs/index.html index 734da7c..e6702e7 100644 --- a/docs/index.html +++ b/docs/index.html @@ -165,11 +165,17 @@ will be used instead of the default <tt class="docutils literal"><span class="pr <p><em>encoding</em> is the character encoding for str instances, default is UTF-8.</p> <p><em>default(obj)</em> is a function that should return a serializable version of <em>obj</em> or raise <tt class="xref docutils literal"><span class="pre">TypeError</span></tt>. The default simply raises <tt class="xref docutils literal"><span class="pre">TypeError</span></tt>.</p> -<p>To use a custom <tt class="xref docutils literal"><span class="pre">JSONEncoder`</span></tt> subclass (e.g. one that overrides the +<p>To use a custom <a title="simplejson.JSONEncoder" class="reference internal" href="#simplejson.JSONEncoder"><tt class="xref docutils literal"><span class="pre">JSONEncoder</span></tt></a> subclass (e.g. one that overrides the <tt class="xref docutils literal"><span class="pre">default()</span></tt> method to serialize additional types), specify it with the <em>cls</em> kwarg.</p> </dd></dl> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">JSON is not a framed protocol so unlike <tt class="xref docutils literal"><span class="pre">pickle</span></tt> or <tt class="xref docutils literal"><span class="pre">marshal</span></tt> it +does not make sense to serialize more than one JSON document without some +container protocol to delimit them.</p> +</div> <dl class="function"> <dt id="simplejson.dumps"> <!--[simplejson.dumps]--><tt class="descclassname">simplejson.</tt><tt class="descname">dumps</tt><big>(</big><em>obj</em><span class="optional">[</span>, <em>skipkeys</em><span class="optional">[</span>, <em>ensure_ascii</em><span class="optional">[</span>, <em>check_circular</em><span class="optional">[</span>, <em>allow_nan</em><span class="optional">[</span>, <em>cls</em><span class="optional">[</span>, <em>indent</em><span class="optional">[</span>, <em>separators</em><span class="optional">[</span>, <em>encoding</em><span class="optional">[</span>, <em>default</em><span class="optional">[</span>, <em>**kw</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#simplejson.dumps" title="Permalink to this definition">¶</a></dt> @@ -180,6 +186,57 @@ will be used instead of the default <tt class="docutils literal"><span class="pr better performance.</p> </dd></dl> +<dl class="function"> +<dt id="simplejson.load"> +<!--[simplejson.load]--><tt class="descclassname">simplejson.</tt><tt class="descname">load</tt><big>(</big><em>fp</em><span class="optional">[</span>, <em>encoding</em><span class="optional">[</span>, <em>cls</em><span class="optional">[</span>, <em>object_hook</em><span class="optional">[</span>, <em>parse_float</em><span class="optional">[</span>, <em>parse_int</em><span class="optional">[</span>, <em>parse_constant</em><span class="optional">[</span>, <em>**kw</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#simplejson.load" title="Permalink to this definition">¶</a></dt> +<dd><p>Deserialize <em>fp</em> (a <tt class="docutils literal"><span class="pre">.read()</span></tt>-supporting file-like object containing a JSON +document) to a Python object.</p> +<p>If the contents of <em>fp</em> are encoded with an ASCII based encoding other than +UTF-8 (e.g. latin-1), then an appropriate <em>encoding</em> name must be specified. +Encodings that are not ASCII based (such as UCS-2) are not allowed, and +should be wrapped with <tt class="docutils literal"><span class="pre">codecs.getreader(fp)(encoding)</span></tt>, or simply decoded +to a <tt class="xref docutils literal"><span class="pre">unicode</span></tt> object and passed to <a title="simplejson.loads" class="reference internal" href="#simplejson.loads"><tt class="xref docutils literal"><span class="pre">loads()</span></tt></a>. The default +setting of <tt class="docutils literal"><span class="pre">'utf-8'</span></tt> is fastest and should be using whenever possible.</p> +<p><em>object_hook</em> is an optional function that will be called with the result of +any object literal decode (a <tt class="xref docutils literal"><span class="pre">dict</span></tt>). The return value of +<em>object_hook</em> will be used instead of the <tt class="xref docutils literal"><span class="pre">dict</span></tt>. This feature can be used +to implement custom decoders (e.g. JSON-RPC class hinting).</p> +<p><em>parse_float</em>, if specified, will be called with the string of every JSON +float to be decoded. By default, this is equivalent to <tt class="docutils literal"><span class="pre">float(num_str)</span></tt>. +This can be used to use another datatype or parser for JSON floats +(e.g. <tt class="xref docutils literal"><span class="pre">decimal.Decimal</span></tt>).</p> +<p><em>parse_int</em>, if specified, will be called with the string of every JSON int +to be decoded. By default, this is equivalent to <tt class="docutils literal"><span class="pre">int(num_str)</span></tt>. This can +be used to use another datatype or parser for JSON integers +(e.g. <tt class="xref docutils literal"><span class="pre">float</span></tt>).</p> +<p><em>parse_constant</em>, if specified, will be called with one of the following +strings: <tt class="docutils literal"><span class="pre">'-Infinity'</span></tt>, <tt class="docutils literal"><span class="pre">'Infinity'</span></tt>, <tt class="docutils literal"><span class="pre">'NaN'</span></tt>. This can be used to +raise an exception if invalid JSON numbers are encountered.</p> +<p>To use a custom <a title="simplejson.JSONDecoder" class="reference internal" href="#simplejson.JSONDecoder"><tt class="xref docutils literal"><span class="pre">JSONDecoder</span></tt></a> subclass, specify it with the <tt class="docutils literal"><span class="pre">cls</span></tt> +kwarg. Additional keyword arguments will be passed to the constructor of the +class.</p> +</dd></dl> + +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last"><a title="simplejson.load" class="reference internal" href="#simplejson.load"><tt class="xref docutils literal"><span class="pre">load()</span></tt></a> will read the rest of the file-like object as a string and +then call <a title="simplejson.loads" class="reference internal" href="#simplejson.loads"><tt class="xref docutils literal"><span class="pre">loads()</span></tt></a>. It does not stop at the end of the first valid +JSON document it finds and it will raise an error if there is anything +other than whitespace after the document. Except for files containing +only one JSON document, it is recommended to use <a title="simplejson.loads" class="reference internal" href="#simplejson.loads"><tt class="xref docutils literal"><span class="pre">loads()</span></tt></a>.</p> +</div> +<dl class="function"> +<dt id="simplejson.loads"> +<!--[simplejson.loads]--><tt class="descclassname">simplejson.</tt><tt class="descname">loads</tt><big>(</big><em>s</em><span class="optional">[</span>, <em>encoding</em><span class="optional">[</span>, <em>cls</em><span class="optional">[</span>, <em>object_hook</em><span class="optional">[</span>, <em>parse_float</em><span class="optional">[</span>, <em>parse_int</em><span class="optional">[</span>, <em>parse_constant</em><span class="optional">[</span>, <em>**kw</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#simplejson.loads" title="Permalink to this definition">¶</a></dt> +<dd><p>Deserialize <em>s</em> (a <tt class="xref docutils literal"><span class="pre">str</span></tt> or <tt class="xref docutils literal"><span class="pre">unicode</span></tt> instance containing a JSON +document) to a Python object.</p> +<p>If <em>s</em> is a <tt class="xref docutils literal"><span class="pre">str</span></tt> instance and is encoded with an ASCII based encoding +other than UTF-8 (e.g. latin-1), then an appropriate <em>encoding</em> name must be +specified. Encodings that are not ASCII based (such as UCS-2) are not +allowed and should be decoded to <tt class="xref docutils literal"><span class="pre">unicode</span></tt> first.</p> +<p>The other arguments have the same meaning as in <a title="simplejson.dump" class="reference internal" href="#simplejson.dump"><tt class="xref docutils literal"><span class="pre">dump()</span></tt></a>.</p> +</dd></dl> + </div> <div class="section" id="encoders-and-decoders"> <h2 id="encoders-and-decoders">Encoders and decoders<a class="headerlink" href="#encoders-and-decoders" title="Permalink to this headline">¶</a></h2> @@ -426,7 +483,7 @@ available. For example:</p> </div> <div class="footer"> © Copyright 2008, Bob Ippolito. - Last updated on Nov 07, 2008. + Last updated on Dec 30, 2008. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>. </div> </body> diff --git a/docs/search.html b/docs/search.html index 3c12d77..0e36a62 100644 --- a/docs/search.html +++ b/docs/search.html @@ -74,7 +74,7 @@ </div> <div class="footer"> © Copyright 2008, Bob Ippolito. - Last updated on Nov 07, 2008. + Last updated on Dec 30, 2008. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>. </div> </body> diff --git a/docs/searchindex.json b/docs/searchindex.json index ed82190..732c5f4 100644 --- a/docs/searchindex.json +++ b/docs/searchindex.json @@ -1 +1 @@ -[["index"],["<tt class=\"docutils literal\"><span class=\"pre\">simplejson</span></tt> — JSON encoder and decoder"],{"represent":[0],"all":[0],"skip":[0],"interchang":[0],"signific":[0],"follow":[0],"compact":[0],"typeerror":[0],"tt":[0],"decim":[0],"0":[0],"spec":[0],"isinst":[0],"liter":[0],"everi":[0],"string":[0],"raw_decod":[0],"fals":[0],"jsonencod":[0],"level":[0],"list":[0],"iter":[0],"try":[0],"item":[0],"prevent":[0],"pass":[0],"compat":[0],"index":[0],"compar":[0],"neg":[0],"current":[0],"version":[0],"method":[0],"item_separ":[0],"elimin":[0],"valu":[0],"num_str":[0],"prior":[0],"implement":[0],"modul":[0],"api":[0],"coercion":[0],"select":[0],"highli":[0],"from":[0],"would":[0],"to":[0],"call":[0],"6":[0],"type":[0],"sort":[0],"must":[0],"none":[0],"join":[0],"bigobject":[0],"work":[0],"skipkei":[0],"wors":[0],"can":[0],"def":[0],"overrid":[0],"stream":[0],"lightweight":[0],"serial":[0],"end":[0],"newlin":[0],"anoth":[0],"1":[0],"instead":[0],"simpl":[0],"circular":[0],"fp":[0],"recogn":[0],"mai":[0],"such":[0],"data":[0],"a":[0],"attempt":[0],"correspond":[0],"or":[0],"caus":[0],"maintain":[0],"so":[0],"allow":[0],"becaus":[0],"hierarchi":[0],"write":[0],"better":[0],"yaml":[0],"then":[0],"non":[0],"return":[0],"thei":[0],"python":[0],"safe":[0],"dai":[0],"not":[0],"jsondecod":[0],"superset":[0],"name":[0],"edit":[0],"separ":[0],"getvalu":[0],"each":[0],"unicod":[0],"2j":[0],"mean":[0],"subset":[0],"chunk":[0],"ensur":[0],"expect":[0],"special":[0],"out":[0],"3rd":[0],"content":[0],"7":[0],"print":[0],"infin":[0],"standard":[0],"base":[0],"dictionari":[0],"element":[0],"org":[0],"basi":[0],"indent":[0],"g":[0],"could":[0],"place":[0],"outsid":[0],"regress":[0],"first":[0],"rang":[0],"arrai":[0],"number":[0],"echo":[0],"given":[0],"their":[0],"2":[0],"1j":[0],"shell":[0],"option":[0],"that":[0],"tool":[0],"specifi":[0],"than":[0],"b":[0],"keyword":[0],"whenev":[0],"provid":[0],"structur":[0],"charact":[0],"r":[0],"str":[0],"pre":[0],"encode_complex":[0],"ani":[0],"have":[0],"null":[0],"equival":[0],"self":[0],"note":[0],"also":[0],"without":[0],"take":[0],"which":[0],"even":[0],"begin":[0],"unless":[0],"normal":[0],"object":[0],"most":[0],"getread":[0],"class":[0],"marshal":[0],"kw":[0],"determin":[0],"serializ":[0],"speedup":[0],"syntax":[0],"onli":[0],"explicitli":[0],"parse_float":[0],"pretti":[0],"with":[0],"3":[0],"should":[0],"iterencod":[0],"dict":[0],"8":[0],"object_hook":[0],"get":[0],"familiar":[0],"fastest":[0],"key_separ":[0],"bar":[0],"baz":[0],"yield":[0],"contain":[0],"where":[0],"valid":[0],"set":[0],"dump":[0],"datatyp":[0],"result":[0],"best":[0],"subject":[0],"infinit":[0],"extend":[0],"dict_separ":[0],"written":[0],"import":[0],"latin":[0],"kei":[0],"parse_const":[0],"javascript":[0],"extens":[0],"addit":[0],"c":[0],"s":[0],"instanc":[0],"ecma":[0],"load":[0],"and":[0],"simpli":[0],"cl":[0],"8212":[0],"rpc":[0],"getwrit":[0],"__complex__":[0],"json":[0],"much":[0],"interpret":[0],"basic":[0],"valueerror":[0],"imag":[0],"argument":[0],"understand":[0],"func":[0],"input":[0],"sort_kei":[0],"x08ar":[0],"properti":[0],"will":[0],"behavior":[0],"error":[0],"advantag":[0],"is":[0],"it":[0],"kwarg":[0],"io":[0],"in":[0],"incom":[0],"ascii":[0],"if":[0],"u1234":[0],"perform":[0],"same":[0],"member":[0],"complex":[0],"decod":[0],"document":[0],"http":[0],"optim":[0],"effect":[0],"rais":[0],"user":[0],"extern":[0],"appropri":[0],"well":[0],"pickl":[0],"exampl":[0],"thi":[0],"the":[0],"mysocket":[0],"allow_nan":[0],"as_complex":[0],"parse_int":[0],"expos":[0],"hint":[0],"except":[0],"other":[0],"4":[0],"els":[0],"real":[0],"msimplejson":[0],"format":[0],"read":[0],"262":[0],"recurs":[0],"insert":[0],"like":[0],"specif":[0],"whitespac":[0],"docutil":[0],"arbitrari":[0],"integ":[0],"t":[0],"output":[0],"encount":[0],"some":[0],"check_circular":[0],"superclass":[0],"guarante":[0],"5":[0],"librari":[0],"for":[0],"subclass":[0],"when":[0],"leav":[0],"foo":[0],"refer":[0],"be":[0],"usag":[0],"dct":[0],"by":[0],"on":[0],"obj":[0],"column":[0],"of":[0],"o":[0],"constructor":[0],"produc":[0],"into":[0],"float":[0],"encod":[0],"wrap":[0],"span":[0],"complianc":[0],"support":[0],"transform":[0],"long":[0],"custom":[0],"avail":[0],"strict":[0],"compliant":[0],"overflowerror":[0],"function":[0],"simplejson":[0],"tupl":[0],"but":[0],"translat":[0],"line":[0],"ha":[0],"true":[0],"notat":[0],"utf":[0],"consist":[0],"possibl":[0],"default":[0],"us":[0],"otherwis":[0],"ensure_ascii":[0],"uc":[0],"featur":[0],"int":[0],"dure":[0],"parser":[0],"an":[0],"char":[0],"as":[0],"ar":[0],"at":[0],"file":[0],"inf":[0],"check":[0],"no":[0],"complexencod":[],"nan":[0],"invalid":[0],"codec":[0],"bool":[0],"test":[0],"you":[0],"deseri":[0],"stringio":[0],"e":[0],"extran":[0],"rule":[0],"u":[0],"escap":[0]}]
\ No newline at end of file +[["index"],["<tt class=\"docutils literal\"><span class=\"pre\">simplejson</span></tt> — JSON encoder and decoder"],{"represent":[0],"all":[0],"skip":[0],"interchang":[0],"signific":[0],"follow":[0],"compact":[0],"typeerror":[0],"tt":[0],"decim":[0],"0":[0],"sens":[0],"spec":[0],"isinst":[0],"liter":[0],"everi":[0],"string":[0],"raw_decod":[0],"fals":[0],"jsonencod":[0],"level":[0],"list":[0],"iter":[0],"try":[0],"item":[0],"prevent":[0],"pass":[0],"compat":[0],"index":[0],"compar":[0],"neg":[0],"current":[0],"version":[0],"method":[0],"item_separ":[0],"elimin":[0],"valu":[0],"num_str":[0],"prior":[0],"implement":[0],"modul":[0],"api":[0],"coercion":[0],"select":[0],"highli":[0],"from":[0],"would":[0],"to":[0],"call":[0],"6":[0],"type":[0],"more":[0],"sort":[0],"it":[0],"must":[0],"none":[0],"join":[0],"bigobject":[0],"work":[0],"skipkei":[0],"wors":[0],"can":[0],"def":[0],"overrid":[0],"stream":[0],"lightweight":[0],"serial":[0],"end":[0],"newlin":[0],"anoth":[0],"1":[0],"instead":[0],"simpl":[0],"circular":[0],"fp":[0],"recogn":[0],"after":[0],"mai":[0],"such":[0],"data":[0],"a":[0],"attempt":[0],"correspond":[0],"or":[0],"caus":[0],"maintain":[0],"so":[0],"allow":[0],"becaus":[0],"hierarchi":[0],"write":[0],"better":[0],"yaml":[0],"then":[0],"them":[0],"return":[0],"thei":[0],"python":[0],"safe":[0],"dai":[0],"not":[0],"jsondecod":[0],"superset":[0],"name":[0],"anyth":[0],"edit":[0],"separ":[0],"getvalu":[0],"each":[0],"unicod":[0],"2j":[0],"mean":[0],"subset":[0],"chunk":[0],"ensur":[0],"expect":[0],"special":[0],"out":[0],"3rd":[0],"content":[0],"7":[0],"print":[0],"infin":[0],"standard":[0],"base":[0],"dictionari":[0],"element":[0],"org":[0],"basi":[0],"indent":[0],"g":[0],"could":[0],"place":[0],"outsid":[0],"regress":[0],"first":[0],"rang":[0],"arrai":[0],"number":[0],"echo":[0],"unlik":[0],"given":[0],"their":[0],"2":[0],"1j":[0],"shell":[0],"option":[0],"that":[0],"tool":[0],"specifi":[0],"than":[0],"b":[0],"keyword":[0],"whenev":[0],"provid":[0],"structur":[0],"charact":[0],"r":[0],"str":[0],"pre":[0],"encode_complex":[0],"argument":[0],"have":[0],"null":[0],"equival":[0],"self":[0],"note":[0],"also":[0],"without":[0],"take":[0],"which":[0],"even":[0],"begin":[0],"unless":[0],"normal":[0],"object":[0],"most":[0],"getread":[0],"class":[0],"marshal":[0],"doe":[0],"kw":[0],"determin":[0],"serializ":[0],"speedup":[0],"syntax":[0],"find":[0],"onli":[0],"explicitli":[0],"parse_float":[0],"pretti":[0],"with":[0],"3":[0],"should":[0],"iterencod":[0],"dict":[0],"8":[0],"object_hook":[0],"get":[0],"familiar":[0],"stop":[0],"fastest":[0],"key_separ":[0],"bar":[0],"baz":[0],"yield":[0],"contain":[0],"where":[0],"valid":[0],"set":[0],"dump":[0],"frame":[0],"datatyp":[0],"result":[0],"best":[0],"subject":[0],"infinit":[0],"extend":[0],"dict_separ":[0],"written":[0],"import":[0],"latin":[0],"kei":[0],"parse_const":[0],"javascript":[0],"extens":[0],"addit":[0],"c":[0],"delimit":[0],"s":[0],"instanc":[0],"ecma":[0],"load":[0],"and":[0],"simpli":[0],"cl":[0],"8212":[0],"rpc":[0],"getwrit":[0],"__complex__":[0],"json":[0],"much":[0],"interpret":[0],"basic":[0],"valueerror":[0],"imag":[0],"ani":[0],"understand":[0],"func":[],"input":[0],"sort_kei":[0],"x08ar":[0],"properti":[0],"will":[0],"behavior":[0],"error":[0],"advantag":[0],"is":[0],"non":[0],"kwarg":[0],"io":[0],"in":[0],"incom":[0],"ascii":[0],"if":[0],"u1234":[0],"perform":[0],"make":[0],"same":[0],"member":[0],"complex":[0],"decod":[0],"document":[0],"http":[0],"optim":[0],"effect":[0],"rais":[0],"user":[0],"extern":[0],"appropri":[0],"well":[0],"pickl":[0],"exampl":[0],"thi":[0],"the":[0],"protocol":[0],"mysocket":[0],"rest":[0],"allow_nan":[0],"as_complex":[0],"parse_int":[0],"expos":[0],"hint":[0],"except":[0],"other":[0],"4":[0],"els":[0],"real":[0],"msimplejson":[0],"format":[0],"read":[0],"262":[0],"recurs":[0],"insert":[0],"like":[0],"specif":[0],"arbitrari":[0],"docutil":[0],"whitespac":[0],"integ":[0],"t":[0],"output":[0],"encount":[0],"some":[0],"check_circular":[0],"superclass":[0],"guarante":[0],"5":[0],"librari":[0],"for":[0],"subclass":[0],"when":[0],"leav":[0],"foo":[0],"refer":[0],"be":[0],"usag":[0],"dct":[0],"by":[0],"on":[0],"obj":[0],"column":[0],"of":[0],"o":[0],"constructor":[0],"produc":[0],"into":[0],"float":[0],"encod":[0],"wrap":[0],"span":[0],"complianc":[0],"support":[0],"there":[0],"transform":[0],"long":[0],"custom":[0],"avail":[0],"strict":[0],"compliant":[0],"overflowerror":[0],"function":[0],"simplejson":[0],"tupl":[0],"recommend":[0],"but":[0],"translat":[0],"line":[0],"ha":[0],"true":[0],"notat":[0],"utf":[0],"consist":[0],"possibl":[0],"default":[0],"us":[0],"otherwis":[0],"ensure_ascii":[0],"uc":[0],"featur":[0],"int":[0],"dure":[0],"parser":[0],"an":[0],"char":[0],"as":[0],"ar":[0],"at":[0],"file":[0],"inf":[0],"check":[0],"no":[0],"complexencod":[],"nan":[0],"invalid":[0],"codec":[0],"bool":[0],"test":[0],"you":[0],"deseri":[0],"stringio":[0],"e":[0],"extran":[0],"rule":[0],"u":[0],"escap":[0]}]
\ No newline at end of file @@ -13,11 +13,11 @@ syntax (ECMA-262 3rd edition) used as a lightweight data interchange format. :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained version of the :mod:`json` library contained in Python 2.6, but maintains compatibility with Python 2.4 and Python 2.5 and (currently) has -significant performance advantages, even without using the optional C +significant performance advantages, even without using the optional C extension for speedups. Encoding basic Python object hierarchies:: - + >>> import simplejson as json >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) '["foo", {"bar": ["baz", null, 1.0, 2]}]' @@ -46,12 +46,12 @@ Pretty printing:: >>> import simplejson as json >>> print json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4) { - "4": 5, + "4": 5, "6": 7 } Decoding JSON:: - + >>> import simplejson as json >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj @@ -70,7 +70,7 @@ Specializing JSON object decoding:: ... if '__complex__' in dct: ... return complex(dct['real'], dct['imag']) ... return dct - ... + ... >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', ... object_hook=as_complex) (1+2j) @@ -79,7 +79,7 @@ Specializing JSON object decoding:: True Specializing JSON object encoding:: - + >>> import simplejson as json >>> def encode_complex(obj): ... if isinstance(obj, complex): @@ -92,12 +92,12 @@ Specializing JSON object encoding:: '[2.0, 1.0]' >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j)) '[2.0, 1.0]' - + .. highlight:: none Using simplejson.tool from the shell to validate and pretty-print:: - + $ echo '{"json":"obj"}' | python -msimplejson.tool { "json": "obj" @@ -107,7 +107,7 @@ Using simplejson.tool from the shell to validate and pretty-print:: .. highlight:: python -.. note:: +.. 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. @@ -156,10 +156,16 @@ Basic Usage *default(obj)* is a function that should return a serializable version of *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. - To use a custom :class:`JSONEncoder`` subclass (e.g. one that overrides the + To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the :meth:`default` method to serialize additional types), specify it with the *cls* kwarg. + .. note:: + + JSON is not a framed protocol so unlike :mod:`pickle` or :mod:`marshal` it + does not make sense to serialize more than one JSON document without some + container protocol to delimit them. + .. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]]) @@ -171,7 +177,7 @@ Basic Usage better performance. -.. function load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) +.. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON document) to a Python object. @@ -206,8 +212,16 @@ Basic Usage kwarg. Additional keyword arguments will be passed to the constructor of the class. + .. note:: + + :func:`load` will read the rest of the file-like object as a string and + then call :func:`loads`. It does not stop at the end of the first valid + JSON document it finds and it will raise an error if there is anything + other than whitespace after the document. Except for files containing + only one JSON document, it is recommended to use :func:`loads`. + -.. function loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) +.. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON document) to a Python object. @@ -372,7 +386,7 @@ Encoders and decoders For example, to support arbitrary iterators, you could implement default like this:: - + def default(self, o): try: iterable = iter(o) @@ -397,9 +411,9 @@ Encoders and decoders Encode the given object, *o*, and yield each string representation as available. For example:: - + for chunk in JSONEncoder().iterencode(bigobject): mysocket.write(chunk) - + Note that :meth:`encode` has much better performance than :meth:`iterencode`. @@ -18,7 +18,7 @@ from distutils.command.build_ext import build_ext from distutils.errors import CCompilerError, DistutilsExecError, \ DistutilsPlatformError -VERSION = '2.0.6' +VERSION = '2.0.7' DESCRIPTION = "Simple, fast, extensible JSON encoder/decoder for Python" LONG_DESCRIPTION = """ simplejson is a simple, fast, complete, correct and extensible diff --git a/simplejson/__init__.py b/simplejson/__init__.py index 2de3b59..f385d4c 100644 --- a/simplejson/__init__.py +++ b/simplejson/__init__.py @@ -1,91 +1,93 @@ -r"""A simple, fast, extensible JSON encoder and decoder - -JSON (JavaScript Object Notation) <http://json.org> is a subset of +r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data interchange format. -simplejson exposes an API familiar to uses of the standard library -marshal and pickle modules. +:mod:`simplejson` exposes an API familiar to users of the standard library +:mod:`marshal` and :mod:`pickle` modules. It is the externally maintained +version of the :mod:`json` library contained in Python 2.6, but maintains +compatibility with Python 2.4 and Python 2.5 and (currently) has +significant performance advantages, even without using the optional C +extension for speedups. Encoding basic Python object hierarchies:: - >>> import simplejson - >>> simplejson.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) + >>> import simplejson as json + >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) '["foo", {"bar": ["baz", null, 1.0, 2]}]' - >>> print simplejson.dumps("\"foo\bar") + >>> print json.dumps("\"foo\bar") "\"foo\bar" - >>> print simplejson.dumps(u'\u1234') + >>> print json.dumps(u'\u1234') "\u1234" - >>> print simplejson.dumps('\\') + >>> print json.dumps('\\') "\\" - >>> print simplejson.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True) + >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True) {"a": 0, "b": 0, "c": 0} >>> from StringIO import StringIO >>> io = StringIO() - >>> simplejson.dump(['streaming API'], io) + >>> json.dump(['streaming API'], io) >>> io.getvalue() '["streaming API"]' Compact encoding:: - >>> import simplejson - >>> compact = simplejson.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':')) - >>> # Can't assume dict ordering - >>> compact in ('[1,2,3,{"4":5,"6":7}]', '[1,2,3,{"6":7,"4":5}]') - True + >>> import simplejson as json + >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':')) + '[1,2,3,{"4":5,"6":7}]' -Pretty printing (using repr() because of extraneous whitespace in the output):: +Pretty printing:: - >>> import simplejson - >>> print repr(simplejson.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)) - '{\n "4": 5, \n "6": 7\n}' + >>> import simplejson as json + >>> print json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4) + { + "4": 5, + "6": 7 + } Decoding JSON:: - >>> import simplejson - >>> simplejson.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == ["foo", {"bar":["baz", None, 1.0, 2]}] + >>> import simplejson as json + >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] + >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj True - >>> simplejson.loads('"\\"foo\\bar"') == '"foo\x08ar' + >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar' True >>> from StringIO import StringIO >>> io = StringIO('["streaming API"]') - >>> simplejson.load(io) == ["streaming API"] + >>> json.load(io)[0] == 'streaming API' True Specializing JSON object decoding:: - >>> import simplejson + >>> import simplejson as json >>> def as_complex(dct): ... if '__complex__' in dct: ... return complex(dct['real'], dct['imag']) ... return dct ... - >>> simplejson.loads('{"__complex__": true, "real": 1, "imag": 2}', + >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', ... object_hook=as_complex) (1+2j) - >>> from decimal import Decimal - >>> simplejson.loads('1.1', parse_float=Decimal) == Decimal("1.1") + >>> import decimal + >>> json.loads('1.1', parse_float=decimal.Decimal) == decimal.Decimal('1.1') True -Extending JSONEncoder:: +Specializing JSON object encoding:: - >>> import simplejson - >>> class ComplexEncoder(simplejson.JSONEncoder): - ... def default(self, obj): - ... if isinstance(obj, complex): - ... return [obj.real, obj.imag] - ... return simplejson.JSONEncoder.default(self, obj) + >>> import simplejson as json + >>> def encode_complex(obj): + ... if isinstance(obj, complex): + ... return [obj.real, obj.imag] + ... raise TypeError("%r is not JSON serializable" % (o,)) ... - >>> dumps(2 + 1j, cls=ComplexEncoder) + >>> json.dumps(2 + 1j, default=encode_complex) '[2.0, 1.0]' - >>> ComplexEncoder().encode(2 + 1j) + >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j) '[2.0, 1.0]' - >>> ''.join(ComplexEncoder().iterencode(2 + 1j)) + >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j)) '[2.0, 1.0]' -Using simplejson from the shell to validate and -pretty-print:: +Using simplejson.tool from the shell to validate and pretty-print:: $ echo '{"json":"obj"}' | python -msimplejson.tool { @@ -94,7 +96,7 @@ pretty-print:: $ echo '{ 1.2:3.4}' | python -msimplejson.tool Expecting property name: line 1 column 2 (char 2) """ -__version__ = '2.0.6' +__version__ = '2.0.7' __all__ = [ 'dump', 'dumps', 'load', 'loads', 'JSONDecoder', 'JSONEncoder', |