Use Python wheels with ZOAU
Python wheels are now available for installing ZOAU Python APIs.
Introduction
We’re excited to announce that you can now use the industry standard Python wheel method to install ZOAU Python APIs!
Python wheels are the preferred way to provide precompiled installation packages that target specific Python versions. The wheel method is available starting with ZOAU v1.2.3.
According to PEP 427:
A wheel is a ZIP-format archive with a specially formatted file name and the
.whlextension. It contains a single distribution nearly as it would be installed according to PEP 376 with a particular installation scheme.
This means that Python modules no longer need custom installers. Decoupling the module from the build system eliminates the need to install a build toolchain in the target environment.
Many benefits come from using wheels instead of traditional tar.gz source packages:
- Custom packages are available for each supported version of IBM Open Enterprise Python for z/OS. This ensures compatibility without extra configuration.
- No more compilation dependencies. Wheel packages include all dependencies along with precompiled extension code. You can install the package without a C compiler.
- Native
pip3support. Python’s default package manager will identify, install, upgrade, remove, and clean wheel modules without extra steps.
When you install ZOAU with either the SMP/E package or the distributed pax.Z file, the .whl files for each supported Python version are included in the base directory.
Wheels are labeled according to pip3 naming standards. For example, the ZOAU v1.2.3 release includes the following .whl files:
| File name | z/OS CPython version | Compiler |
|---|---|---|
zoautil_py-1.2.3-cp39-none-any.whl | 3.9 | xlc |
zoautil_py-1.2.3-cp310-none-any.whl | 3.10 | xlc |
zoautil_py-1.2.3-cp311-none-any.whl | 3.11 | clang |
Do not modify .whl filenames. Python’s pip3 install performs version matching on the .whl filename, and a mismatch can cause the installation to fail. The library is available only for IBM Z (s390x).
Installation
To install a Python wheel, first install ZOAU v1.2.3 or later. For instructions, see Installing and configuring ZOAU.
Next, determine your Python wheel install destination. Python wheel installs the module to the current active Python. You can install globally, to a local directory, or within a virtual environment.
Install the Python wheel with the following single command:
pip3 install <Path to File>.whl
In most cases, that’s all you need to do to successfully install your ZOAU Python API.
Note for users of IBM Open Enterprise SDK for Python 3.9: A bug in Python 3.9 causes the ZOAU extension module to be installed with incorrect permissions and file tag. To fix this, apply Python APAR PH55814. Alternatively, issue the the chmod +x and chtag -b commands for the ZOAU .so files, which are usually located in the active Python /lib directory. These commands add execute permission and properly set the file tag to “binary”.
chmod +x <Python Library Path>/lib/python3.*/site-packages/zoautil_py/*.abi3.sochtag -b <Python Library Path>/lib/python3.*/site-packages/zoautil_py/*.abi3.so
The type command can be used to find the the active python directory as follows:
> type pythonpython is hashed (/u/IBMUSER/venv1/bin/python)
Using Python wheel is the simple, modern, and preferred way to install ZOAU Python APIs. However, other installation methods remain available. To learn more, see Install ZOAU Python APIs.
Rolling forward with Python wheels The ZOAU team has the goal of providing standalone Python module installation. By adopting the Python wheel installation method, we’re excited to be moving forward in that direction.
Keep up with more ZOAU updates by visiting What’s new and noteworthy. For code samples, discussion, and more, visit the ZOAU community repo.
About the authors
Fernando Lopez Rubio is an Advisory Software Engineer who is new to the IBM Z platform. He works on the ZOAU team in Guadalajara, Mexico. He holds a BS in Computer Systems Engineering from the Tecnológico de Monterrey (ITESM) and is currently working towards a master’s degree in the same field from the ITESO university.
Anthony Giorgio is a Senior Software Engineer with over 20 years of mainframe experience. He is the lead of the IBM Z Open Automation Utilities (ZOAU) team in Poughkeepsie, NY. Anthony holds a BS and MS in Computer Science from the NYU Tandon School of Engineering.
Nate Myers contributed to the editorial review of this article.