[issue4783] json documentation needs a BAWM (Big A** Warning Message)

[David M. Beazley]

New submission from David M. Beazley <beazley at users.sourceforge.net>:

The json module is described as having an interface similar to pickle:
  
    json.dump()
    json.dumps()
    json.load()
    json.loads()

I think it would be a WISE idea to add a huge warning message to the 
documentation that these functions should *NOT* be used to serialize or 
unserialize multiple objects on the same file stream like pickle. For 
example:

    f = open("stuff","w")
    json.dump(obj1, f)
    json.dump(obj2, f)        # NO!  FLAMING DEATH!

    f = open("stuff","r")
    obj1 = json.load(f)  
    obj2 = json.load(f)       # NO!  EXTRA CRIPSY FLAMING DEATH!

For one, it doesn't work. load() actually reads the whole file into a 
big string and tries to parse it as a single object.  If there are 
multiple objects in the file, you get a nasty exeption.   Second, I'm 
not even sure this is technically allowed by the JSON spec.

As far as I call tell, concatenating JSON objects together in the same 
file falls into the same category as concatenating two HTML documents 
together in the same file (something you just don't do).

Related: json.load() should probably not be used on any streaming input 
source such as a file wrapped around a socket.  The first thing it does 
is consume the entire input by calling f.read()---which probably not 
what someone is expecting (and it might even cause the whole program to 
hang).

----------
assignee: georg.brandl
components: Documentation
messages: 78547
nosy: beazley, georg.brandl
severity: normal
status: open
title: json documentation needs a BAWM (Big A** Warning Message)
type: behavior
versions: Python 2.6, Python 3.0

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue4783>
_______________________________________