{"library":"amazon-ion","title":"Amazon Ion Python Implementation","description":"A Python implementation of Amazon Ion, a richly-typed, self-describing, hierarchical data serialization format. It offers interchangeable binary and text representations, with text being a superset of JSON. The library is currently at version 0.13.0 and is actively maintained with regular updates.","status":"active","version":"0.13.0","language":"en","source_language":"en","source_url":"https://github.com/amazon-ion/ion-python","tags":["serialization","data-format","amazon","ion","json-superset","aws"],"install":[{"cmd":"pip install amazon-ion","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for execution. The library is designed for Python 3.8+.","package":"Python","optional":false},{"reason":"Required to build the optional C extension for improved performance; falls back to pure Python if not present.","package":"cmake","optional":true}],"imports":[{"note":"The `simpleion` module provides the primary high-level API for dumping and loading Ion data, similar to Python's built-in `json` module.","wrong":"import amazon.ion","symbol":"simpleion","correct":"import amazon.ion.simpleion as ion"},{"note":"This type represents Ion Timestamps and is a subclass of native Python `datetime`.","symbol":"IonPyTimestamp","correct":"from amazon.ion.simple_types import IonPyTimestamp"}],"quickstart":{"code":"import amazon.ion.simpleion as ion\n\n# Dump Python objects to Ion text or binary\ndata_py = {'id': 123, 'name': 'example', 'active': True}\nion_text = ion.dumps(data_py, binary=False, indent='  ')\nprint('Ion Text:\\n', ion_text)\n\nion_binary = ion.dumps(data_py, binary=True)\nprint('Ion Binary (bytes):', ion_binary)\n\n# Load Ion data back into Python objects\nloaded_py_text = ion.loads(ion_text)\nprint('Loaded from Text:', loaded_py_text)\n\nloaded_py_binary = ion.loads(ion_binary)\nprint('Loaded from Binary:', loaded_py_binary)\n\n# Example with a specific Ion type\nfrom datetime import datetime\nfrom amazon.ion.simple_types import IonPyTimestamp\ntimestamp_py = IonPyTimestamp(datetime(2023, 10, 27, 10, 30, 0))\nion_timestamp = ion.dumps({'event_time': timestamp_py}, binary=False)\nprint('Ion Timestamp:\\n', ion_timestamp)","lang":"python","description":"This quickstart demonstrates how to use the `simpleion` module to serialize Python dictionaries into Ion text and binary formats, and deserialize them back. It also shows how to work with Ion-specific types like `IonPyTimestamp`."},"warnings":[{"fix":"Migrate code to Python 3. (Python 3.8+ is officially supported for current versions).","message":"Python 2 support was dropped in version 0.10.0. All subsequent versions require Python 3.","severity":"breaking","affected_versions":"0.10.0 and later"},{"fix":"Ensure your environment uses Python 3.8 or newer.","message":"Support for Python versions older than 3.7 was dropped around the v0.11.1 release. Current versions are designed for Python 3.8+.","severity":"breaking","affected_versions":"Versions after 0.10.0, specifically from 0.11.x onwards."},{"fix":"Always test against your target `amazon-ion` version if using `simpleEnum`. It is present in 0.11.1 and later.","message":"The `simpleEnum` class was briefly removed and then re-added for backward compatibility in version 0.11.1. Depending on the exact version, code relying on `simpleEnum` might have failed.","severity":"gotcha","affected_versions":"Potentially versions between an unnamed removal and 0.11.1"},{"fix":"Ensure `cmake` is installed in your build environment to guarantee the C extension is utilized for optimal performance. You can check `ion.__IS_C_EXTENSION_SUPPORTED` to verify.","message":"The library includes an optional C extension for performance with the `simpleion` module. If `cmake` is not installed or the C extension build fails, the library will silently fall back to a pure Python implementation, which may result in unexpected performance degradation.","severity":"gotcha","affected_versions":"All versions with C extension support (0.9.0 and later)"},{"fix":"For streams with multiple top-level Ion values, use `ion.loads(ion_data, single_value=False)`.","message":"When using `simpleion.loads()` for Ion data that contains multiple top-level values, you must explicitly set `single_value=False` to parse the entire stream. Otherwise, it may raise an `IonException` or only load the first value.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-06T20:01:23.122Z","next_check":"2026-07-05T00:00:00.000Z"}