Commit 51d42482 authored by SVN-Git Migration's avatar SVN-Git Migration

Imported Upstream version 2.0.1

parent f3d64090
Authors of the demjson python module.
* Deron Meranda <deron.meranda@gmail.com>
Metadata-Version: 1.0
Metadata-Version: 1.1
Name: demjson
Version: 1.6
Summary: encoder, decoder, and lint/validator for JSON (JavaScript Object Notation) compliant with RFC 4627
Version: 2.0.1
Summary: encoder, decoder, and lint/validator for JSON (JavaScript Object Notation) compliant with RFC 7159
Home-page: http://deron.meranda.us/python/demjson/
Author: Deron Meranda
Author-email: deron.meranda@gmail.com
License: GNU LGPL 3.0
Download-URL: http://deron.meranda.us/python/demjson/dist/demjson-1.6.tar.gz
Description: This module provides classes and functions for encoding or decoding data
represented in the language-neutral JSON format (which is often used as a
simpler substitute for XML in Ajax web applications). This implementation tries
to be as compliant to the JSON specification (RFC 4627) as possible, while
still providing many optional extensions to allow less restrictive JavaScript
syntax. It includes complete Unicode support, including UTF-32, BOM, and
surrogate pair processing. It can also support JavaScript's
NaN and Infinity numeric types as well as it's 'undefined' type.
It also includes a lint-like JSON syntax validator which tests JSON text
for strict compliance to the standard.
Download-URL: http://deron.meranda.us/python/demjson/dist/demjson-2.0.1.tar.gz
Description: The "demjson" module, and the included "jsonlint" script, provide methods
for encoding and decoding JSON formatted data, as well as checking JSON
data for errors and/or portability issues. The jsonlint command/script
can be used from the command line without needing any programming.
Although the standard Python library now includes basic JSON support
(which it did not when demjson was first written), this module
provides a much more comprehensive implementation with many features
not found elsewhere. It is especially useful for error checking or
for parsing JavaScript data which may not strictly be valid JSON data.
Keywords: JSON,jsonlint,JavaScript,UTF-32
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
demjson
=======
<b>demjson</b> is a [Python language](http://python.org/) module for
encoding, decoding, and syntax-checking [JSON](http://json.org/)
data. It works under both Python 2 and Python 3.
It comes with a <b>jsonlint</b> script which can be used to validate
your JSON documents for strict conformance to the JSON specification,
and to detect potential data portability issues. It can also reformat
or pretty-print JSON documents; either by re-indenting or removing
unnecessary whitespace.
What's new
==========
<b>Version 2.0.1</b> is a re-packaging of 2.0, after discovering
problems with incorrect checksums in the PyPI distribution of 2.0. No
changes were made from 2.0.
<b>Version 2.0</b>, released 2014-05-21, is a MAJOR new version with many
changes and improvements.
Visit http://deron.meranda.us/python/demjson/ for complete details
and documentation. Additional documentation may also be found
under the "docs/" folder of the source.
The biggest changes in 2.0 include:
* Now works in Python 3; minimum version supported is Python 2.6
* Much improved reporting of errors and warnings
* Extensible with user-supplied hooks
* Handles many additional Python data types automatically
* Statistics
There are many more changes, as well as a small number of backwards
incompatibilities. Where possible these incompatibilities were kept
to a minimum, however it is highly recommended that you read the
change notes thoroughly.
Example use
===========
To use demjson from within your Python programs:
```python
>>> import demjson
>>> demjson.encode( ['one',42,True,None] ) # From Python to JSON
'["one",42,true,null]'
>>> demjson.decode( '["one",42,true,null]' ) # From JSON to Python
['one', 42, True, None]
```
To check a JSON data file for errors or problems:
```bash
$ jsonlint my.json
my.json:1:8: Error: Numbers may not have extra leading zeros: '017'
| At line 1, column 8, offset 8
my.json:4:10: Warning: Object contains same key more than once: 'Name'
| At line 4, column 10, offset 49
| Object started at line 1, column 0, offset 0 (AT-START)
my.json:9:11: Warning: Integers larger than 53-bits are not portable
| At line 9, column 11, offset 142
my.json: has errors
```
Why use demjson?
================
I wrote demjson before Python had any JSON support in its standard
library. If all you need is to be able to read or write JSON data,
then you may wish to just use what's built into Python.
However demjson is extremely feature rich and is quite useful in
certain applications. It is especially good at error checking
JSON data and for being able to parse more of the JavaScript syntax
than is permitted by strict JSON.
A few advantages of demjson are:
* It works in old Python versions that don't have JSON built in;
* It generally has better error handling and "lint" checking capabilities;
* It will automatically use the Python Decimal (bigfloat) class
instead of a floating-point number whenever there might be an
overflow or loss of precision otherwise.
* It can correctly deal with different Unicode encodings, including ASCII.
It will automatically adapt when to use \u-escapes based on the encoding.
* It generates more conservative JSON, such as escaping Unicode
format control characters or line terminators, which should improve
data portability.
* In non-strict mode it can also deal with slightly non-conforming
input that is more JavaScript than JSON (such as allowing comments).
* It supports a broader set of Python types during conversion.
Installation
============
To install, type:
```bash
python setup.py install
```
or optionally just copy the file "demjson.py" to whereever you want.
See "docs/INSTALL.txt" for more detailed instructions, including how
to run the self-tests.
More information
================
See the files under the "docs" subdirectory. The module is also
self-documented, so within the python interpreter type:
```python
import demjson
help(demjson)
```
or from a shell command line:
```bash
pydoc demjson
```
The "jsonlint" command script which gets installed as part of demjson
has built-in usage instructions as well. Just type:
```bash
jsonlint --help
```
Complete documentation and additional information is also available on
the project homepage at http://deron.meranda.us/python/demjson/
It is also available on the Python Package Index (PyPI) at
http://pypi.python.org/pypi/demjson/
License
=======
LGPLv3 - See the included "LICENSE.txt" file.
This software is Free Software and is licensed under the terms of the
GNU LGPL (GNU Lesser General Public License). More information is
found at the top of the demjson.py source file and the included
LICENSE.txt file.
Releases prior to 1.4 were released under a different license, be
sure to check the corresponding LICENSE.txt file included with them.
This software was written by Deron Meranda, http://deron.meranda.us/
'demjson' is a Python language module for encoding and decoding JSON data.
demjson
=======
REQUIRES PYTHON 2.3 OR HIGHER, DOES NOT WORK IN PYTHON 3000 (3.x)
MORE DOCUMENTATION IS IN THE "docs" SUBDIRECTORY.
'demjson' is a Python language module for encoding, decoding, and
syntax-checking JSON data. It works under both Python 2 and Python 3.
It comes with a "jsonlint" script which can be used to validate your
JSON documents for strict conformance to the JSON specification. It
can also reformat or pretty-print JSON documents; either by
re-indenting or removing unnecessary whitespace for minimal/canonical
JSON output.
demjson tries to be as closely conforming to the JSON specification,
published as IETF RFC 7159 <http://tools.ietf.org/html/rfc7159>, as
possible. It can also be used in a non-strict mode where it is much
closer to the JavaScript/ECMAScript syntax (published as ECMA 262).
The demjson module has full Unicode support and can deal with very
large numbers.
Example use
===========
To use demjson from within your Python programs:
import demjson
# Convert a Python value into JSON
demjson.encode( {'Happy': True, 'Other': None} )
# returns string => {"Happy":true,"Other":null}
# Convert a JSON document into a Python value
demjson.decode( '{"Happy":true,"Other":null}' )
# returns dict => {'Other': None, 'Happy': True}
To use the accompaning "jsonlint" command script:
# To check whether a file contains valid JSON
jsonlint sample.json
# To pretty-print (reformat) a JSON file
jsonlint --format sample.json
Why use demjson rather than the Python standard library?
========================================================
demjson was written before Python had any built-in JSON support in its
standard library, and there were just a handful of third-party
libraries. None of those at that time were completely compliant with
the RFC, and the best of those required compiled C extensions rather
than being pure Python code.
So I wrote demjson to be:
* Pure Python, requiring no compiled extension.
* 100% RFC compliant. It should follow the JSON specification exactly.
It should be noted that Python has since added JSON into its standard
library -- which was actually an absorption of "simplejson", written
by Bob Ippolito, and which had by then been fixed to remove bugs and
improve RFC conformance.
For most uses, the standard Python JSON library should be sufficient.
However demjson may still be useful:
* It works in old Python versions that don't have JSON built in;
* It generally has better error handling and "lint" checking capabilities;
* It will automatically use the Python Decimal (bigfloat) class
instead of a floating-point number whenever there might be an
overflow or loss of precision otherwise.
* It can correctly deal with different Unicode encodings, including ASCII.
It will automatically adapt when to use \u-escapes based on the encoding.
* It generates more conservative JSON, such as escaping Unicode
format control characters or line terminators, which should improve
data portability.
* In non-strict mode it can also deal with slightly non-conforming
input that is more JavaScript than JSON (such as allowing comments).
* It supports a broader set of types during conversion, including
Python's Decimal or UserString.
Installation
============
To install, type:
python setup.py install
or optionally just copy the file "demjson.py" to whereever you want.
See INSTALL.txt for mo detailed instructions.
See docs/INSTALL.txt for more detailed instructions, including how to
run the self-tests.
In addition to the module "demjson", there is also an included script
"jsonlint" which is meant to be used as a command-line tool. You can
invoke "jsonlint --help" for its usage instructions.
More information
================
The module is self-documented, so within the python interpreter type:
See the files under the "docs" subdirectory. The module is
self-documented, so within the python interpreter type:
import demjson
help(demjson)
......@@ -25,11 +114,29 @@ or from a command line:
pydoc demjson
The "jsonlint" command script which gets installed as part of demjson
has built-in usage instructions as well. Just type:
jsonlint --help
Complete documentation and additional information is also available on
the project homepage at http://deron.meranda.us/python/demjson/
It is also available on the Python Package Index (PyPI) at
http://pypi.python.org/pypi/demjson/
License
=======
LGPLv3 - See the included "LICENSE.txt" file.
This software is Free Software and is licensed under the terms of the
GNU LGPL (GNU Lesser General Public License). More information is
found at the top of the demjson.py source file and the included
LICENSE.txt file.
Written by Deron Meranda
http://deron.meranda.us/python/demjson/
Releases prior to 1.4 were released under a different license, be
sure to check the corresponding LICENSE.txt file included with them.
This software was written by Deron Meranda, http://deron.meranda.us/
In general thanks to the entire Python community for providing such
a wonderful language. Thanks also to the folks at json.org for
developing the JSON data format and pursuing an RFC standard for it.
Reported bugs:
* Adam Braun -- reported bug in 1.0 release regarding newlines being
rejected during decoding if at the beginning of the input.
* Nicolas Bonardelle -- reported bug in 1.1 release where the wrong
kind of exception could be raised by encode_default().
* Tom Kho and Yanxin Shi -- independently reported bug in the 1.4
release, that when encoding Python strings to JSON, occurances
of character U+00FF (ASCII 255 or 0xFF) may result in an
error.
* Brian Bloniarz -- reported a bug in 1.5 for the jsonlint
command where it could not properly accept and parse from
standard input (stdin).
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
== Basic installation
Requirements for demjson
========================
demjson is a pure Python module; it does not contain any C code
extensions. It also does not have any dependencies on any third-party
modules; it only uses the standard Python library.
It will work with both Python 2 and Python 3; though at least Python
2.4 is recommended. If you plan to use it with Python 3, also read
the "docs/PYTHON3.txt" file included with this release.
Note: for full Unicode support of non-BMP (Basic Multilingual Plane)
characters, your Python interpreter must have been compiled for UCS-4
support. You can check this with:
import sys
sys.maxunicode > 0xffff # If True you have UCS-4 support
Installation of demjson
=======================
This software is published in the Python Package Index (PYPI),
at <http://pypi.python.org/>, which may make it easy to install.
If your system has either "pip" or "easy_install", then you may
try one of the following commands to install this module:
pip install demjson
pip-python install demjson
easy_install demjson
pip install demjson
pip-python install demjson
easy_install demjson
Otherwise, you can install it by downloading the distrubtion and
unpacking it in some temporary directory. Then inside that
......@@ -19,14 +39,19 @@ Optionally, for a minimal installation, you can also just copy the
"demjson.py" file into your own project's directory.
== jsonlint command
jsonlint command
================
The installation should have installed the script file "jsonlint".
You can optionally install the script jsonlint by copying it to
any directory on your PATH, such as into /usr/local/bin under
Unix/Linux. Make sure the script is set as being executable.
If it did not, you can simply copy the file "jsonlint" to any
directory in your executable PATH, such as into /usr/local/bin under
Unix/Linux. Make sure the script is set as being executable, and if
needed adjust the first "#!" line to point to your python interpreter.
== Running self tests
Running self tests
==================
Self tests are included which conform to the Python unittest
framework. To run these tests, do
......
News announcements regarding the demjson python module.
See the file CHANGES.txt for more details.
2014-05-26 Release 2.0.1, No changes. Bumping version because of confused checksums.
2014-05-21 Release 2.0, major enhancements, Python 3, callback hooks, etc.
2011-04-01 Release 1.6, bug fix in jsonlint
2010-10-10 Release 1.5, bug fix with code point U+00FF
2008-12-17 Release 1.4, license changed to LGPL 3 (no code changes).
......
Using demjson with Python 3
===========================
Starting with release 2.0, demjson and jsonlint, can support either
Python 2 or Python 3 -- though it must be installed as described below
to work with Python 3.
Be aware that the API will have slightly different behavior in Python 3,
mainly because it uses the 'bytes' type in a few places.
Installing for Python 3
=======================
The source for the demjson module is written for Python 2.x. However,
since release 2.0, it has been designed to be converted to a Python 3
equivalent form by using the standard "2to3" Python conversion utility.
If you have installed demjson with a standard PyPI package
distribution mechanism; such as pip, easy_install, or just typing
"python3 setup.py install"; then the 2to3 conversion will be performed
automatically as part of the installation process.
Running self-tests: if you install using a PyPI distribution mechanism
then the test program "tests/test_demjson.py" may either not be
installed or may not have been converted to Python 3. You can do this
manually if needed by:
cd test
2to3 -w test_demjson.py
PYTHONPATH=.. python3 test_demjson.py
Bytes versus strings
====================
When calling demjson functions and classes from a Python 3 environment,
be aware that there are a few differences from what is documented for
Python 2. Most of these differences involve Python's byte-oriented
types ('bytes', 'bytearray', and 'memoryview').
Decoding JSON into Python values
--------------------------------
When you decode a JSON document you can pass either a string or
a bytes type.
If you pass a string, then it is assumed to already be a sequence
of Unicode characters. So demjson's own Unicode decoding step will be
skipped.
When you pass a byte-oriented type the decode() function will
attempt to detect the Unicode encoding and appropriately convert the
bytes into a Unicode string first. You can override the guessed
encoding by specifying the appropriate codec name, or codec object.
For example, the following are equivalent and have the same result:
demjson.decode( '"\u2014"' )
demjson.decode( b'"\xe2\x80\x94"' )
demjson.decode( bytes([ 0x22, 0xE2, 0x80, 0x94, 0x22 ]) )
Notice that with the last two examples the decode() function has
automatically detected that the byte array was UTF-8 encoded. You can
of course pass in an 'encoding' argument to force the Unicode decoding
codec to use -- though if you get this wrong a UnicodeDecodeError may
be raised.
Reading JSON from a file
------------------------
When reading from a file the bytes it contains must be converted into
Unicode characters. If you want demjson to do that be sure to open the
file in binary mode:
json_data = open("myfile.json", "rb").read()
# => json_data is a bytes array
py_data = demjson.decode( json_data, encoding="utf8" )
But if you read the file in text mode then the Unicode decoding is
done by Python's own IO core, and demjson will parse the
already-Unicode string without doing any decoding:
json_data = open("myfile.json", "r", encoding="utf8").read()
# => json_data is a (unicode) string
py_data = demjson.decode( json_data )
Encoding Python values to JSON
------------------------------
When encoding a Python value into a JSON document, you will
generally get a string result (which is a sequence of Unicode
characters).
However if you specify a particular encoding, then you will
instead get a byte array as a result.
demjson.encode( "\u2012" )
# => Returns a string of length 3
demjson.encode( "\u2012", encoding="utf-8" )
# => Returns 5 bytes b'"\xe2\x80\x94"'
Writing JSON to a file
----------------------
When generating JSON and writing it to a file all the Unicode
characters must be encoded into bytes. You can let demjson do that by
specifying an encoding, though be sure that you open the output file
in binary mode:
json_data = demjson.encode( py_data, encoding="utf-8" )
# json_data will be a bytes array
open("myfile.json", "wb" ).write( json_data )
The above has the advantage that demjson can automatically adjust the
\u-escaping depending on the output encoding.
But if you don't ask for any encoding you'll get the JSON output as a
Unicode string, in which case you need to open your output file in
text mode with a specific encoding. You must choose a suitable
encoding or you could get a UnicodeEncodeError.
json_data = demjson.encode( py_data )
# json_data will be a (unicode) string
open("myfile.json", "w", encoding="utf-8" ).write( json_data )
Encoding byte types
-------------------
If you are encoding into JSON and the Python value you pass is, or
contains, any byte-oriented type ('bytes', 'bytearray', or
'memoryview') value; then the bytes must be converted into a different
value that can be represented in JSON.
The default is to convert bytes into an array of integers, each with
a value from 0 to 255 representing a single byte. For example:
py_data = b'\x55\xff'
demjson.encode( py_data )
# Gives => '[85,255]'
You can supply a function to the 'encode_bytes' hook to change how
bytes get encoded.
def to_hex( bytes_val ):
return ":".join([ "%02x" % b for b in bytes_val ])
demjson.encode( py_data, encode_bytes=to_hex )
# Gives => '"55:ff"'
See the 'encode_bytes' hook description in HOOKS.txt for further details.
Other Python 3 specifics
========================
Data types
----------
When encoding JSON, most of the new data types introduced with
Python 3 will be encoded. Note only does this include the
byte-oriented types, but also Enum and ChainMap.</p>
Chained exceptions
------------------
Any errors that are incidentally raised during JSON encoding or
decoding will be wrapped in a 'JSONError' (or subclass). In Python 3,
this wrapping uses the standard Exception Chaining (PEP 3134)
mechanism.</p>
See the Exception Handling example in the file HOOKS.txt
This diff is collapsed.
This diff is collapsed.
Usage: jsonlint [-v] [-s|-S] [-f|-F] [-e codec] inputfile.json ...
Usage: jsonlint [<options> ...] [--] inputfile.json ...
There is NO OUTPUT by default. Use -v to see any warning details.
With no input filename, or "-", it will read from standard input.
The return status will be 0 if the file is conforming JSON (per the
RFC 4627 specification), or non-zero otherwise.
RFC 7159 specification), or non-zero otherwise.
GENERAL OPTIONS:
Options are:
-v | --verbose Show details of lint checking
-s | --strict Be strict in what is considered conforming JSON (the default)
-S | --nonstrict Be loose in what is considered conforming JSON
-q | --quiet Don't show any output (except for reformatting)
STRICTNESS OPTIONS (WARNINGS AND ERRORS):
-W | --tolerant Be tolerant, but warn about non-conformance (default)
-s | --strict Be strict in what is considered conforming JSON
-S | --nonstrict Be tolerant in what is considered conforming JSON
--allow=... -\
--warn=... |-- These options let you pick specific behaviors.
--forbid=... -/ Use --help-behaviors for more
STATISTICS OPTIONS:
--stats Show statistics about JSON document
REFORMATTING OPTIONS:
-f | --format Reformat the JSON text (if conforming) to stdout
-F | --format-compactly
Reformat the JSON simlar to -f, but do so compactly by
removing all unnecessary whitespace
-e codec | --encoding=codec
--input-encoding=codec
--output-encoding=codec
Set the input and output character encoding codec (e.g.,
ascii, utf8, utf-16). The -e will set both the input and
output encodings to the same thing. If not supplied, the
input encoding is guessed according to the JSON
specification. The output encoding defaults to UTF-8, and is
used when reformatting (via the -f or -F options).
When reformatting, all members of objects (associative arrays) are
always output in lexigraphical sort order. The default output codec
is UTF-8, unless the -e option is provided. Any Unicode characters
will be output as literal characters if the encoding permits,
otherwise they will be \u-escaped. You can use "-e ascii" to force
all Unicode characters to be escaped.
Use 'jsonlint --version' to see versioning information.
Use 'jsonlint --copyright' to see author and copyright details.'
-o filename | --output filename
The filename to which reformatted JSON is to be written.
Without this option the standard output is used.
--sort <kind> How to sort object/dictionary keys, <kind> is one of:
alpha - Sort strictly alphabetically
alpha_ci - Sort alphabetically case-insensitive
preserve - Preserve original order when reformatting
smart - Sort alphabetically and numerically (DEFAULT)
--indent tabs | <nnn> Number of spaces to use per indentation level,
or use tab characters if "tabs" given.
UNICODE OPTIONS:
-e codec | --encoding=codec Set both input and output encodings
--input-encoding=codec Set the input encoding
--output-encoding=codec Set the output encoding
These options set the character encoding codec (e.g., "ascii",
"utf-8", "utf-16"). The -e will set both the input and output
encodings to the same thing. The output encoding is used when
reformatting with the -f or -F options.
Unless set, the input encoding is guessed and the output
encoding will be "utf-8".
OTHER OPTIONS:
--recursion-limit=nnn Set the Python recursion limit to number
--leading-zero-radix=8|10 The radix to use for numbers with leading
zeros. 8=octal, 10=decimal.
REFORMATTING / PRETTY-PRINTING:
When reformatting JSON with -f or -F, output is only produced if
the input passed validation. By default the reformatted JSON will
be written to standard output, unless the -o option was given.
The default output codec is UTF-8, unless an encoding option is
provided. Any Unicode characters will be output as literal
characters if the encoding permits, otherwise they will be
\u-escaped. You can use "--output-encoding ascii" to force all
Unicode characters to be escaped.
MORE INFORMATION:
Use 'jsonlint --version [-v]' to see versioning information.
Use 'jsonlint --copyright' to see author and copyright details.
Use 'jsonlint [-W|-s|-S] --help-behaviors' for help on specific checks.
jsonlint is distributed as part of the "demjson" Python module.
See http://deron.meranda.us/python/demjson/
BEHAVIOR OPTIONS:
These set of options let you control which checks are to be performed.
They may be turned on or off by listing them as arguments to one of
the options --allow, --warn, or --forbid ; for example:
jsonlint --allow comments,hex-numbers --forbid duplicate-keys
The default shown is for strict mode
Default Behavior_name Description
------- ------------------------- --------------------------------------------------
forbid all-numeric-signs Numbers may be prefixed by any '+' and '-', e.g., +4, -+-+77
allow any-type-at-start A JSON document may start with any type, not just arrays or objects
forbid binary-numbers Binary numbers, e.g., 0b1001
warn bom A JSON document may start with a Unicode BOM (Byte Order Mark)
forbid comments JavaScript comments, both /*...*/ and //... styles
forbid control-char-in-string Strings may contain raw control characters without \u-escaping
warn duplicate-keys Objects may have repeated keys
forbid extended-unicode-escapes Extended Unicode escape sequence \u{..} for non-BMP characters
forbid format-control-chars Unicode "format control characters" may appear in the input
forbid hex-numbers Hexadecimal numbers, e.g., 0x1f
forbid identifier-keys JavaScript identifiers are converted to strings when used as object keys
forbid initial-decimal-point Floating-point numbers may start with a decimal point (no units digit)
forbid js-string-escapes All JavaScript character \-escape sequences may be in strings
forbid leading-zeros Numbers may have extra leading zeros (see --leading-zero-radix option)
forbid non-numbers Non-numbers may be used, such as NaN or Infinity
warn non-portable Anything technically valid but likely to cause data portablibity issues