diff -r 545feebd58fb Doc/tutorial/inputoutput.rst --- a/Doc/tutorial/inputoutput.rst Tue Nov 05 22:02:17 2013 +0200 +++ b/Doc/tutorial/inputoutput.rst Tue Nov 05 19:40:42 2013 -0500 @@ -377,47 +377,70 @@ Reference for a complete guide to file objects. +.. _tut-json: + +Saving complex data with :mod:`json` +------------------------------------ + +.. index:: module: json + +Strings can easily be written to and read from a file. Numbers take a bit more +effort, since the :meth:`read` method only returns strings, which will have to +be passed to a function like :func:`int`, which takes a string like ``'123'`` +and returns its numeric value 123. However, when you want to save more complex +data types like nested lists and dictionaries, things get a lot more +complicated. + +Rather than having users constantly writing and debugging code to save +complicated data types to files, Python allows you to use the popular data +interchange format called `JSON (JavaScript Object Notation) +`_. The standard module called :mod:`json` can take Python +data hierarchies, and convert them to string representations; this process is +called :dfn:`encoding`. Reconstructing the data from the string representation +is called :dfn:`decoding`. Between encoding and decoding, the string +representing the object may have been stored in a file or data, or sent over a +network connection to some distant machine. + +If you have an object ``x``, you can view its JSON string representation with a +simple line of code:: + + >>> json.dumps([1, 'simple', 'list']) + '[1, "simple", "list"]' + +Another variant of the :meth:`dumps` method, called :meth:`dump`, simply +encodes the object in a string and writes it to a file. So if ``f`` is a file +object opened for writing, we can do this:: + + json.dump(x, f) + +To decode the object again, if ``f`` is a file object which has been opened for +reading:: + + x = json.load(f) + +This simple encoding technique can handle lists and dictionaries, but encoding +class instances in JSON requires a small extra step. The Python Library +Reference for :mod:`json` contains an explanation of this, but there is another +alternative to mention as well. + .. _tut-pickle: -The :mod:`pickle` Module +The :mod:`pickle` module ------------------------ .. index:: module: pickle +.. warning:: -Strings can easily be written to and read from a file. Numbers take a bit more -effort, since the :meth:`read` method only returns strings, which will have to -be passed to a function like :func:`int`, which takes a string like ``'123'`` -and returns its numeric value 123. However, when you want to save more complex -data types like lists, dictionaries, or class instances, things get a lot more -complicated. + The :mod:`pickle` module is not intended to be secure against erroneous or + maliciously constructed data. Never unpickle data received from an + untrusted or unauthenticated source. -Rather than have users be constantly writing and debugging code to save -complicated data types, Python provides a standard module called :mod:`pickle`. -This is an amazing module that can take almost any Python object (even some -forms of Python code!), and convert it to a string representation; this process -is called :dfn:`pickling`. Reconstructing the object from the string -representation is called :dfn:`unpickling`. Between pickling and unpickling, -the string representing the object may have been stored in a file or data, or -sent over a network connection to some distant machine. +:mod:`pickle` is the standard way to make Python objects which can be stored +and reused by other programs or by a future invocation of the same program; the +technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` +is so widely used, many authors who write Python extensions take care to ensure +that new data types such as matrices can be properly pickled and unpickled. The +module has a very simlar interface to :mod:`json`, and is fully explained in +the Python Library Reference. -If you have an object ``x``, and a file object ``f`` that's been opened for -writing, the simplest way to pickle the object takes only one line of code:: - pickle.dump(x, f) - -To unpickle the object again, if ``f`` is a file object which has been opened -for reading:: - - x = pickle.load(f) - -(There are other variants of this, used when pickling many objects or when you -don't want to write the pickled data to a file; consult the complete -documentation for :mod:`pickle` in the Python Library Reference.) - -:mod:`pickle` is the standard way to make Python objects which can be stored and -reused by other programs or by a future invocation of the same program; the -technical term for this is a :dfn:`persistent` object. Because :mod:`pickle` is -so widely used, many authors who write Python extensions take care to ensure -that new data types such as matrices can be properly pickled and unpickled. - -