A Python wrapper for the z/OSMF REST API
- Website: https://sr.ht/~ocurero/zosmfrestapi/
- Repository: https://git.sr.ht/~ocurero/zosmfrestapi
- Changelog: https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/CHANGELOG.md
Key features:
- Pure Python: Package and its dependencies are 100% pure Python (no C extensions required).
- Cross-platform: Works on Windows, Linux, macOS, and z/OS UNIX System Services.
- Flexible authentication: Supports user/password, LTPA and JWT tokens, and mutual TLS (mTLS).
- Proxy ready: Full support for standard HTTP/HTTPS proxies as well as authenticated proxies.
Install
zosmfrestapi requires Python 3.12 or newer and access to a z/OSMF server.
Install the package from PyPI:
python -m pip install zosmfrestapi
If you have downloaded or cloned the source code, run this from the project's root folder instead:
python -m pip install .
Quickstart
from zosmfrestapi import ZosmfClient
with ZosmfClient("https://zosmf.example",
username="demouser", password="itsasecret") as client:
for instance in client.list_swis():
print(f"{instance.name} ({instance.system})")
The with block closes the network connection automatically, even if a request
fails. list_swis() returns Python objects; the example prints each software
instance's name and system. You can also query systems or read a data set. Put
these calls inside the with block shown above, before it ends:
systems = client.get_systems()
contents = client.read_dataset("USER.DATASET")
These calls must be made inside the with block, before the client is closed.
For a partitioned data set member, use a name such as
USER.PDS(MEMBER).
Clients
The library provides two client implementations:
ZosmfClient: The standard synchronous client for communicating with z/OSMF using username/password, tokens, or standard TLS certificate files.ZosmfZcryptoClient: A specialized client for z/OS environments that extracts mutual TLS (mTLS) client certificates directly from SAF key rings (RACF, ACF2, Top Secret).
Platform Support
| Client | Linux | macOS | Windows | z/OS USS |
|---|---|---|---|---|
ZosmfClient |
✅ | ✅ | ✅ | ✅ |
ZosmfZcryptoClient |
❌ | ❌ | ❌ | ✅ |
Using ZosmfZcryptoClient on z/OS
ZosmfZcryptoClient retrieves client certificates and private keys directly from a SAF key ring, exporting temporary PEM files and configuring mutual TLS transparently. When using a key ring owned by the current user, specify the ring name as "name". When using a key ring owned by another user, specify the ring name as "userid/name":
from zosmfrestapi import ZosmfZcryptoClient
with ZosmfZcryptoClient("https://zosmf.example",
keyring="userid/name", label="zOSMF Client Certificate") as client:
systems = client.get_systems()
Install the optional zcrypto extra:
python -m pip install "zosmfrestapi[zcrypto]"
Authentication and TLS
The client uses the server's normal TLS certificate checks by default. Keep
those checks enabled for routine use. The HTTP transport is HTTPX2; HTTPX2 uses truststore
to integrate operating-system certificate stores when it creates its default TLS context.
zosmfrestapi currently passes its own context, created with Python's
ssl.create_default_context(), so the certificates available to Python are used.
If the z/OSMF server's CA is no trusted in that environment, pass its certificate file
with cafile below.
| Situation | Client option |
|---|---|
| User ID and password | username="...", password="..." |
| Client certificate and key in separate files | cert=("client.crt", "client.key") |
| Client certificate and key in one PEM file | cert="client.pem" |
| Internal certificate authority | cafile="company-ca.pem" |
| Existing LTPA or JWT token | ltpa_token="..." or jwt_token="..." |
| Identity propagation (needs PH68412) | None |
| Network proxy | proxy="http://proxy.example.com:8080" |
For example, to trust an internal certificate authority, pass cafile when
creating the client:
with ZosmfClient("https://zosmf.example", username="demouser", password="itsasecret",
cafile="company-ca.pem") as client:
systems = client.get_systems()
The insecure=True option disables TLS certificate verification; use it only for temporary
diagnostics, never as a production fix. It cannot be combined with cert or cafile.
Supported APIs
| API Category | Description | Key Methods (examples) |
|---|---|---|
| Authentication | Basic Auth, LTPA / JWT tokens session login | authenticate() |
| Topology | Query systems and sysplex groups defined in z/OSMF | get_groups(), get_systems() |
| Datasets | Sequential and partitioned dataset retrieval | read_dataset() |
| Software Management | SMP/E software instances, CSI queries, and datasets | list_swis(), get_swi_by_name(), query_csi_by_name() |
| Software Updates | Search, inspect, start, monitor, and cancel update processes | search_sw_updates_by_name(), start_sw_update_by_name(), check_sw_update_status() |
| Workflows | List, create, inspect, execute, monitor, and archive workflows | get_workflows(), create_workflow(), start_workflow(), wait_for_workflow() |
Some operations change z/OSMF state. Check the method documentation and make sure your account has the required permissions before using them.
Troubleshooting
- Python version error: install Python 3.12 or newer, then recreate the virtual environment with that interpreter.
- 401 / unauthorized: check the server URL, user ID, password or token, and whether the account is authorized for the requested API.
- Certificate verification error: ask your z/OSMF administrator for the
correct CA certificate and pass its path with
cafile. - Connection or timeout error: check that the server and port are reachable from your machine and that any required proxy is configured.
- PowerShell will not activate the virtual environment: use the Python
executable inside
.venv\Scripts\python.exeto run commands, or follow your organization's PowerShell policy guidance. Do not change the machine-wide execution policy just to install this package.
For the complete API, parameters, and return types, see the docstrings in the package source and the project website.
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines on development, testing, and submitting patches.
Issues and Feedback
If you encounter any bugs or have feature requests, please report them on the SourceHut issue tracker.
License
The MIT License. See LICENSE.
Trademarks
IBM, the IBM logo, z/OS, MVS, and Z/OSMF are trademarks or are registered trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available at https://www.ibm.com/legal/copytrade.
This project is an independent community effort. It is not affiliated with, endorsed by, or sponsored by IBM.
Metadata
Release files for zosmfrestapi 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| zosmfrestapi-0.3.0.tar.gz | 33.5 kB | Without provenance | Details for zosmfrestapi-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zosmfrestapi-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for zosmfrestapi-0.3.0-py3-none-any.whl |
Total release size: 74.9 kB
Release files / zosmfrestapi-0.3.0.tar.gz
| Download URL | zosmfrestapi-0.3.0.tar.gz |
|---|---|
| Size | 33.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1dcb01ad4e6a5ed5f930574cf7524f7e1b5a45ede27c3d75588aa7cf469e0152
|
|
BLAKE2b-256 checksum How to use checksums |
8afcd43c8bd948b374e170f3d4344489493023e5517624c40f125b2a3e17be3c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.12.16 Linux/6.18.60-0-lts
|
Release files / zosmfrestapi-0.3.0-py3-none-any.whl
| Download URL | zosmfrestapi-0.3.0-py3-none-any.whl |
|---|---|
| Size | 41.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b26999e71ba8b4559b8867870dfb97291b116d21c9a11d7ee68e457ff82fe64d
|
|
BLAKE2b-256 checksum How to use checksums |
ae7a7848bb6324c48b960296e24a5de1037fabd9a2bfc5fd55389e2e51cd9a6d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.12.16 Linux/6.18.60-0-lts
|
Security for zosmfrestapi 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.