GeezerVison

Issue #, if available: #305

Description of changes:
This PR migrates ion-python away from a setup.py/install.py based project to a PEP 517 compliant build system. By updating the build system we are able to adopt better tooling through the formalized nature of PEP 517 projects, and how tooling can integrate with the build tree.

One tool that we can use is a PEP 517 build system called py-build-cmake which allows us use CMake for building our C extension. By using CMake, we're able to place ion-c into the build tree and include it as a subdirectory, letting py-build-cmake handle the python build flags.

A side effect of this, is that the code layout now splits the C module into src/ and the python code into src-python/.

Building the Package

Building the extension is now a simple:

$ python -m build
* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
  - py-build-cmake~=0.1.8
* Getting build dependencies for sdist...
...
* Building wheel...
...
[100%] Built target _ioncmodule
-- Installing: /var/folders/ld/sktjjrk132z_f7_95g908dxr0000gr/T/tmp4ekl7bjs/staging/amazon/_ioncmodule.so
Successfully built amazon_ion-0.12.0.tar.gz and amazon_ion-0.12.0-cp312-cp312-macosx_13_0_x86_64.whl
(venv) glitch@147dda5e5395 ~/C/ion-python>

This will build both the sdist (source distribution) and a binary wheel for the current platform & python version. This can be used to ensure the module compiles, but does not install the package. By default everything is built in isolation, using a virtual environment and pip, everything (including the C module) is built in a temporary directory.

C Extension Changes

Prior to this PR when installing the package the C extension would be present under amazon.ion.ionc. Due to a limitation in py-build-cmake (at the time of implementation) the C extension is now under top-level package, and has been renamed _ioncmodule. This is reflected in the simpleion module when testing for the extension's existance.

Dependencies

Prior to pyproject.toml, it was common practice to put dependencies into a text file called requirements.txt. With PEP 517 dependency management has been formalized, along with other metadata that previously could be provided differently depending on which build tools you were actually using.

In pyproject.toml we have a section [project] which includes a dependencies field, containing all of the dependencies needed for the package to work. We also have some optional dependencies that we can install for benchmarking, and/or unit testing. Unit testing and benchmarking are not something that most users would need when installing ion-python, so these dependencies are kept separate in the [project.optional-dependencies] section. Each list in this section is a named set of dependencies or extras that can be installed, but are not installed by default.

pip supports these optional dependencies through PEP 517, and they can be installed with pip using a command like:

$ python -m pip install -e '.[test]'

The above command would install the package in editable mode, which only installs the dependencies. Since we reference test, it includes the optional dependencies named test with the required dependencies. This allows us to keep benchmarking dependencies (like ujson, rapidjson, etc) separate so that our users do not need to install them unless they want to do benchmarking. Likewise, if the user isn't contributing or changing ion-python, there's no need for specific versions of venv and tox, required by ion-python.

Configuration

All of the 3rd party tooling configuration (eg. tox, pytest, etc) has been moved into the pyproject.toml.

Additional Changes

In addition to the pyproject.toml migration, I added in a new function for the C extension. Ion C has had a version API since Oct 2023, that can return the version and revision. I've added a new method within the _ioncmodule package that exposes this functionality:

>>> import amazon._ioncmodule
>>> amazon._ioncmodule.ionc_version()
'v1.1.3 (rev: d61c09a)'
>>>

This should make it easier to determine what Ion C fixes/bugs/etc are present in a given ion-python installation.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.