Amazon Ion Python Implementation

0.13.0 · active · verified Mon Apr 06

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.

Warnings

breaking Python 2 support was dropped in version 0.10.0. All subsequent versions require Python 3.
Fix: Migrate code to Python 3. (Python 3.8+ is officially supported for current versions).
breaking Support for Python versions older than 3.7 was dropped around the v0.11.1 release. Current versions are designed for Python 3.8+.
Fix: Ensure your environment uses Python 3.8 or newer.
gotcha 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.
Fix: Always test against your target `amazon-ion` version if using `simpleEnum`. It is present in 0.11.1 and later.
gotcha 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.
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.
gotcha 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.
Fix: For streams with multiple top-level Ion values, use `ion.loads(ion_data, single_value=False)`.

Install

pip install amazon-ion Install latest version

Imports

simpleion
```
import amazon.ion.simpleion as ion
```
The `simpleion` module provides the primary high-level API for dumping and loading Ion data, similar to Python's built-in `json` module.
IonPyTimestamp
```
from amazon.ion.simple_types import IonPyTimestamp
```
This type represents Ion Timestamps and is a subclass of native Python `datetime`.

Quickstart

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`.

import amazon.ion.simpleion as ion

# Dump Python objects to Ion text or binary
data_py = {'id': 123, 'name': 'example', 'active': True}
ion_text = ion.dumps(data_py, binary=False, indent='  ')
print('Ion Text:\n', ion_text)

ion_binary = ion.dumps(data_py, binary=True)
print('Ion Binary (bytes):', ion_binary)

# Load Ion data back into Python objects
loaded_py_text = ion.loads(ion_text)
print('Loaded from Text:', loaded_py_text)

loaded_py_binary = ion.loads(ion_binary)
print('Loaded from Binary:', loaded_py_binary)

# Example with a specific Ion type
from datetime import datetime
from amazon.ion.simple_types import IonPyTimestamp
timestamp_py = IonPyTimestamp(datetime(2023, 10, 27, 10, 30, 0))
ion_timestamp = ion.dumps({'event_time': timestamp_py}, binary=False)
print('Ion Timestamp:\n', ion_timestamp)

view raw JSON →