amazon-ion

library0.14.6pypypi✓ verified 25d ago

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.

serialization aws

pip install amazon-ion

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AMAZON-ION

amazon-ion

serializationpythonv0.14.6

Install

3.8s avg

Import

63ms

Disk

92MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.14.6 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.062s · 91.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.8s · import 0.064s · 88MB

92MB installed

● package 92MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

simpleion

✓ import amazon.ion.simpleion as ion

✗ import amazon.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`.

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)

ion --version

Debug

Known issues

breakingPython 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).

affects: 0.10.0 and later

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

affects: Versions after 0.10.0, specifically from 0.11.x onwards.

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

affects: Potentially versions between an unnamed removal and 0.11.1

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

affects: All versions with C extension support (0.9.0 and later)

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

affects: All versions

gotchaThe `IonPyTimestamp` constructor expects individual date/time components (year, month, day, hour, minute, second, microsecond, tzinfo) as arguments, not a single `datetime.datetime` object. Passing a `datetime.datetime` object directly results in a `TypeError` because the `datetime` object is interpreted as the `year` component.

fix

Deconstruct the `datetime.datetime` object into its individual components when initializing `IonPyTimestamp`. For example: `dt = datetime(2023, 10, 27, 10, 30, 0); timestamp_py = IonPyTimestamp(dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, dt.microsecond, dt.tzinfo)`.

affects: All versions

breakingInstantiating `IonPyTimestamp` directly with a `datetime.datetime` object results in a `TypeError` because the constructor expects individual year, month, day, hour, minute, second, microsecond, and tzinfo arguments, not a single `datetime` object.

fix

When converting a `datetime.datetime` object to `IonPyTimestamp`, you must pass its components individually. For example: `dt = datetime(2023, 10, 27, 10, 30, 0)`; then `timestamp_py = IonPyTimestamp(dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, dt.microsecond, dt.tzinfo)`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'amazon.ion'

The 'amazon.ion' package is not installed in the Python environment.

fix

Install the package using pip: 'pip install amazon.ion'.

ImportError: cannot import name 'simpleion' from 'amazon.ion'

The 'simpleion' module is not directly accessible from 'amazon.ion'.

fix

Use the correct import statement: 'from amazon.ion import simpleion'.

AttributeError: module 'amazon.ion.simpleion' has no attribute 'load'

The 'load' function is not present in the 'simpleion' module.

fix

Use the 'loads' function instead: 'from amazon.ion import simpleion; data = simpleion.loads(ion_string)'.

TypeError: 'NoneType' object is not subscriptable

Attempting to access elements of a None object, possibly due to a failed 'loads' operation.

fix

Ensure the Ion data is correctly formatted and 'loads' returns a valid object: 'data = simpleion.loads(ion_string); if data is not None: value = data['key']'.

ValueError: Invalid Ion data

The provided Ion data string is malformed or contains syntax errors.

fix

Verify the Ion data string for correctness and ensure it adheres to the Ion format specifications.

Upgrade

Version history

0.14.6latest on PyPI · released Jun 26, 2026

Audit

Dependencies

PythonrequiredRequired for execution. The library is designed for Python 3.8+.

cmakeoptionalRequired to build the optional C extension for improved performance; falls back to pure Python if not present.

Agent activity

66 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttp://github.com/amazon-ion/ion-python ↗

packagehttps://pypi.org/project/amazon-ion/ ↗

homepagehttps://amazon-ion.github.io/ion-docs/ ↗