An implementation of Amazon Ion for Python.
This package is designed to work with Python 3.8+. Newer language features will be used as deemed valuable. Support may be dropped for versions more than six months past EOL.
Install using pip with the following command.
python3 -m pip install amazon.ionStart with the simpleion
module, which provides four APIs (dump, dumps, load, loads) that will be familiar to users of Python's
built-in JSON parsing module. Simpleion module's performance is improved by an optional C extension.
For example:
>>> import amazon.ion.simpleion as ion
>>> obj = ion.loads('{abc: 123}')
>>> obj['abc']
123
>>> ion.dumps(obj, binary=False)
'$ion_1_0 {abc:123}'
For additional examples, consult the cookbook.
This repository contains two git submodules.
ion-tests holds test data used by ion-python's unit tests and ion-c speeds up ion-python's simpleion module.
The easiest way to clone the ion-python repository and initialize its ion-tests
submodule is to run the following command.
$ git clone --recursive https://github.com/amazon-ion/ion-python.git ion-python
Alternatively, the submodule may be initialized independently from the clone by running the following commands.
$ git submodule init
$ git submodule update
It is recommended to use venv to create a clean environment to build/test Ion Python.
$ python3 -m venv ./venv
...
$ . venv/bin/activate
$ python -m pip install build
$ python -m pip install '.[test]'
You can run the tests through py.test directly:
$ py.test --ignore tests/test_benchmark_cli.py --ignore tests/test_benchmark_spec.py
This recipe skips the benchmark tests because they require additional dependencies:
When in doubt, look at .github/workflows/main.yml to see CI setup
and learn how to build/test the project.
See also ion-python#379 for a writeup of our
adoption of pyproject.toml.
In order to verify that all platforms we support work with Ion Python, we use a combination of tox with pyenv.
We recommend that you use tox within a virtual environment to isolate from whatever is in the system installed Python.
Install relevant versions of Python:
$ for V in 3.8.10 3.9.5 do pyenv install $V; done
Once you have these installations, add them as a local pyenv configuration
$ pyenv local 3.8.10 3.9.5
Assuming you have pyenv properly set up (making sure pyenv init is evaluated into your shell),
you can now run tox:
# Run tox for all versions of python which executes py.test.
$ tox
# Run tox for just Python 3.8 and 3.9.
$ tox -e py38,py39
# Run tox for a specific version and run py.test with high verbosity
$ tox -e py39 -- py.test -vv
# Run tox for a specific version and just the virtual env REPL.
$ tox -e py39 -- python
The following build, deployment, or release tasks are required:
- Add support for code coverage reporting.
- Publish coverage to something like Coverage.io
- Consider using something like PyPy.js to build an interactive shell for playing with Ion python and provide a client-side Ion playground.
tests/test_vectors.py defines skipList variables referencing test vectors that are not expected to work at this time.