### ナビゲーション

- 索引
- モジュール |
- 次へ |
- 前へ |
- Python v2.6.2 documentation »
- Python 標準ライブラリ »
- 19. インターネット上のデータの操作 »

# 19.2. `json` — JSON エンコーダおよびデコーダ

バージョン 2.6 で追加.

JSON (JavaScript Object Notation) <http://json.org> は JavaScript 文法 (ECMA-262 3rd edition) のサブセットで軽量のデータ交換形式として使われています。

`json` の API は標準ライブラリの `marshal` や `pickle` のユーザに馴染み深いものです。

基本的な Python オブジェクト階層のエンコーディング:

    >>> import json
    >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
    '["foo", {"bar": ["baz", null, 1.0, 2]}]'
    >>> print json.dumps("\"foo\bar")
    "\"foo\bar"
    >>> print json.dumps(u'\u1234')
    "\u1234"
    >>> print json.dumps('\\')
    "\\"
    >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
    {"a": 0, "b": 0, "c": 0}
    >>> from StringIO import StringIO
    >>> io = StringIO()
    >>> json.dump(['streaming API'], io)
    >>> io.getvalue()
    '["streaming API"]'

コンパクトなエンコーディング:

    >>> import json
    >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
    '[1,2,3,{"4":5,"6":7}]'

見やすい表示:

    >>> import json
    >>> print json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)
    {
        "4": 5,
        "6": 7
    }

JSON のデコーディング:

    >>> import json
    >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
    [u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
    >>> json.loads('"\\"foo\\bar"')
    u'"foo\x08ar'
    >>> from StringIO import StringIO
    >>> io = StringIO('["streaming API"]')
    >>> json.load(io)
    [u'streaming API']

JSON オブジェクトのデコーディング方法を誂える:

    >>> import json
    >>> def as_complex(dct):
    ...     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)
    >>> import decimal
    >>> json.loads('1.1', parse_float=decimal.Decimal)
    Decimal('1.1')

`JSONEncoder` の拡張:

    >>> import json
    >>> class ComplexEncoder(json.JSONEncoder):
    ...     def default(self, obj):
    ...         if isinstance(obj, complex):
    ...             return [obj.real, obj.imag]
    ...         return json.JSONEncoder.default(self, obj)
    ...
    >>> dumps(2 + 1j, cls=ComplexEncoder)
    '[2.0, 1.0]'
    >>> ComplexEncoder().encode(2 + 1j)
    '[2.0, 1.0]'
    >>> list(ComplexEncoder().iterencode(2 + 1j))
    ['[', '2.0', ', ', '1.0', ']']

シェルから json.tool を使って妥当性チェックをして見やすく表示:

    $ echo '{"json":"obj"}' | python -mjson.tool
    {
        "json": "obj"
    }
    $ echo '{ 1.2:3.4}' | python -mjson.tool
    Expecting property name: line 1 column 2 (char 2)

ノート

このモジュールのデフォルト設定で生成される JSON は YAML のサブセットですので、 その直列化にも使うことができるでしょう。

## 19.2.1. 基本的な使い方

`json.``dump`(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])

  obj を JSON 形式の fp (`.write()` をサポートするファイル的オブジェクト) へのストリームとして直列化します。

  skipkeys が `True` (デフォルトは `False`) ならば、基本型 (`str`, `unicode`, `int`, `long`, `float`, `bool`, `None`) 以外の辞書のキーは `TypeError` を送出せずに読み飛ばされます。

  ensure_ascii が `False` (デフォルトは `True`) ならば、 fp へ書き込まれるチャンクは通常の Python における `str` から `unicode` への型強制ルールに従って `unicode` インスタンスになることがあります。 `fp.write()` が (`codecs.getwriter()` のように) 前もって `unicode` に対応していると判っているもの以外では恐らくこれによってエラーが起こるでしょう。

  check_circular が `False` (デフォルトは `True`) ならば、 コンテナ型の循環参照チェックが省かれ、循環参照があれば `OverflowError` (またはもっと悪い結果) に終わります。

  allow_nan が `False` (デフォルトは `True`) ならば、許容範囲外の `float` 値 (`nan`, `inf`, `-inf`) を直列化しようとした場合、 JSON 仕様を厳格に守って JavaScript の等価なもの (`NaN`, `Infinity`, `-Infinity`) を使うことなく `ValueError` になります。

  indent が非負の整数であれば、JSON の配列要素とオブジェクトメンバはそのインデントレベルで見やすく表示されます。インデントレベルが 0 ならば改行だけが挿入されます。 `None` (デフォルト) では最もコンパクトな表現が選択されます。

  separators がタプル `(item_separator, dict_separator)` ならば、 デフォルト区切り文字 `(', ', ': ')` の代わりに使われます。 `(',', ':')` が最もコンパクトな JSON の表現です。

  encoding は文字列のエンコーディングで、デフォルトは UTF-8 です。

  default(obj) は関数で、 obj の直列化可能なバージョンを返すか、さもなくば `TypeError` を送出します。デフォルトでは単に `TypeError` を送出します。

  カスタマイズされた `JSONEncoder` のサブクラス (たとえば追加の型を直列化するように `default()` メソッドをオーバーライドしたもの) を使うには、 cls キーワード引数に指定します。

`json.``dumps`(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])

  obj を JSON 形式の `str` に直列化します。

  ensure_ascii が `False` ならば、返値は `unicode` インスタンスになります。その他の引数は `dump()` におけるものと同じ意味です。

`json.``load`(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]])

  直列化された fp (`.read()` をサポートするファイル的オブジェクトで JSON 文書を収めたもの) の内容を Python オブジェクトに戻します。

  fp の内容が ASCII に基づいたしかし UTF-8 ではないエンコーディング (たとえば latin-1) を使っているならば、適切な encoding 名が指定されなければなりません。 エンコーディングが ASCII に基づかないもの (UCS-2 など) であることは許されないので、 `codecs.getreader(fp)(encoding)` というように包むか、または単に `unicode` オブジェクトにデコードしたものを `loads()` に渡して下さい。

  object_hook はオプションで渡す関数で全てのオブジェクトリテラルのデコード結果 (`dict`) に対して呼ばれます。 object_hook の返値は `dict` の代わりに使われます。この機能は独自のデコーダ (たとえば JSON-RPC クラスヒンティング) を実装するのに使えます。

  parse_float は、もし指定されれば、全てのデコードされる JSON の浮動小数点数文字列に対して呼ばれます。デフォルトでは、 `float(num_str)` と等価です。これは JSON 浮動小数点数に対して他のデータ型やパーサ (たとえば `decimal.Decimal`) を使うのに使えます。

  parse_int は、もし指定されれば、全てのデコードされる JSON の整数文字列に対して呼ばれます。デフォルトでは、 `int(num_str)` と等価です。これは JSON 整数に対して他のデータ型やパーサ (たとえば `float`) を使うのに使えます。

  parse_constant は、もし指定されれば、次の文字列に対して呼ばれます: `'-Infinity'`, `'Infinity'`, `'NaN'`, `'null'`, `'true'`, `'false'` 。これは不正な JSON 数値に遭遇したときに例外を送出するのに使えます。

  カスタマイズされた `JSONDecoder` のサブクラスを使うには、 cls キーワード引数に指定します。追加のキーワード引数は このクラスのコンストラクタに引き渡されます。

`json.``loads`(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]])

  直列化された s (`str` または `unicode` インスタンスで JSON 文書を含むもの) を Python オブジェクトに戻します。

  s が ASCII に基づいたしかし UTF-8 ではないエンコーディング (たとえば latin-1) でエンコードされた `str` ならば、適切な encoding 名が指定されなければなりません。エンコーディングが ASCII に基づかないもの (UCS-2 など) であることは許されないので、まず `unicode` にデコードして下さい。

  その他の引数は `load()` におけるものと同じ意味です。

## 19.2.2. エンコーダおよびデコーダ

class `json.``JSONDecoder`([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, strict]]]]]])

  単純な JSON デコーダ。

  デフォルトではデコーディングの際、以下の変換を行います。

  JSON | Python
  --- | ---
  object | dict
  array | list
  string | unicode
  number (int) | int, long
  number (real) | float
  true | True
  false | False
  null | None

  また、このデコーダは `NaN`, `Infinity`, `-Infinity` を対応する `float` の値として、JSON の仕様からは外れますが、理解します。

  encoding はこのインスタンスでデコードされる `str` オブジェクトを解釈するために使われるエンコーディング (デフォルトは UTF-8) を定めます。 `unicode` オブジェクトのデコーディングには影響を与えません。

  注意して欲しいのは現状では ASCII のスーパーセットであるようなエンコーディングだけ うまく動くということです。他のエンコーディングの文字列は `unicode` にして渡して下さい。

  object_hook は、もし指定されれば、全てのデコードされた JSON オブジェクトに対して呼ばれその返値は与えられた `dict` の代わりに使われます。この機能は独自の脱直列化 (たとえば JSON-RPC クラスヒンティングをサポートするような) を提供するのに使えます。

  parse_float は、もし指定されれば、全てのデコードされる JSON の浮動小数点数文字列に対して呼ばれます。デフォルトでは、 `float(num_str)` と等価です。これは JSON 浮動小数点数に対して他のデータ型やパーサ (たとえば `decimal.Decimal`) を使うのに使えます。

  parse_int は、もし指定されれば、全てのデコードされる JSON の整数文字列に対して呼ばれます。デフォルトでは、 `int(num_str)` と等価です。これは JSON 整数に対して他のデータ型やパーサ (たとえば `float`) を使うのに使えます。

  parse_constant は、もし指定されれば、次の文字列に対して呼ばれます: `'-Infinity'`, `'Infinity'`, `'NaN'`, `'null'`, `'true'`, `'false'` 。これは不正な JSON 数値に遭遇したときに例外を送出するのに使えます。

  `decode`(s)

    s (`str` または `unicode` インスタンスで JSON 文書を含むもの) の Python 表現を返します。

  `raw_decode`(s)

    s (`str` または `unicode` インスタンスで JSON 文書で始まるもの) から JSON 文書をデコードし、Python 表現と s の文書の終わるところのインデックスからなる 2 要素のタプルを返します。

    このメソッドは後ろに余分なデータを従えた文字列から JSON 文書をデコードするのに使えます。

class `json.``JSONEncoder`([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]])

  Python データ構造に対する拡張可能な JSON エンコーダ。

  デフォルトでは以下のオブジェクトと型をサポートします:

  Python | JSON
  --- | ---
  dict | object
  list, tuple | array
  str, unicode | string
  int, long, float | number
  True | true
  False | false
  None | null

  このクラスを拡張して他のオブジェクトも認識するようにするには、 サブクラスを作って `default()` メソッドを次のように実装します。 もう一つ別のメソッドでオブジェクト `o` に対する直列化可能なオブジェクトを返すものを呼び出すようにします。 変換できない時はスーパークラスの実装を (`TypeError` を送出させるために) 呼ばなければなりません。

  skipkeys が `False` (デフォルト) ならば、str, int, long, float, None 以外のキーをエンコードする試みは `TypeError` に終わります。 skipkeys が `True` の場合は、それらのアイテムは単に読み飛ばされます。

  ensure_ascii が `True` (デフォルト) ならば、入ってくるユニコード文字が全てエスケープされた `str` オブジェクトが出力になることが保証されます。 ensure_ascii が `False` の場合は、出力はユニコードオブジェクトです。

  check_circular が `True` (デフォルト) ならば、リスト、辞書および自作でエンコードしたオブジェクトは循環参照がないかエンコード中にチェックされ、 無限再帰 (これは `OverflowError` を引き起こします) を防止します。 `True` でない場合は、そういったチェックは施されません。

  allow_nan が `True` (デフォルト) ならば、 `NaN`, `Infinity`, `-Infinity` はそのままエンコードされます。この振る舞いは JSON 仕様に従っていませんが、大半の JavaScript ベースのエンコーダ、デコーダと 矛盾しません。 `True` でない場合は、そのような浮動小数点数をエンコードすると `ValueError` が送出されます。

  sort_keys が `True` (デフォルト) ならば、辞書の出力がキーでソートされます。 これは JSON の直列化がいつでも比較できるようになるので回帰試験の際に便利です。

  indent が非負の整数であれば (デフォルトでは `None` です)、JSON の配列要素とオブジェクトメンバはそのインデントレベルで見やすく表示されます。 インデントレベルが 0 ならば改行だけが挿入されます。 `None` では最もコンパクトな表現が選択されます。

  separators はもし指定するなら `(item_separator, key_separator)` というタプルでなければなりません。デフォルトは `(', ', ': ')` です。 最もコンパクトな JSON の表現を得たければ空白を削った `(',', ':')` を指定すればいいでしょう。

  default はもし指定するなら関数で、それがなければ直列化できないオブジェクトに対して呼び出されます。その関数はオブジェクトを JSON でエンコードできるバージョンにして返すか、さもなければ `TypeError` を送出しなければなりません。

  encoding が `None` でなければ、入力文字列は全て JSON エンコーディングに先立ってこのエンコーディングでユニコードに変換されます。 デフォルトは UTF-8 です。

  `default`(o)

    このメソッドをサブクラスで実装する際には o に対して直列化可能なオブジェクトを返すか、基底クラスの実装を (`TypeError` を送出するために) 呼び出すかします。

    たとえば、任意のイテレータをサポートするために、次のように実装します:

        def default(self, o):
           try:
               iterable = iter(o)
           except TypeError:
               pass
           else:
               return list(iterable)
           return JSONEncoder.default(self, o)

  `encode`(o)

    Python データ構造 o の JSON 文字列表現を返します。たとえば:

        >>> JSONEncoder().encode({"foo": ["bar", "baz"]})
        '{"foo": ["bar", "baz"]}'

  `iterencode`(o)

    与えられたオブジェクト o をエンコードし、得られた文字列表現ごとに yield します。たとえば:

        for chunk in JSONEncoder().iterencode(bigobject):
            mysocket.write(chunk)

### ナビゲーション

- 索引
- モジュール |
- 次へ |
- 前へ |
- Python v2.6.2 documentation »
- Python 標準ライブラリ »
- 19. インターネット上のデータの操作 »