A Python wrapper for the z/OSMF© REST API
- Open Source: MIT License.
- Website: https://sr.ht/~ocurero/zosmfrestapi/
- Pypi: https://pypi.org/project/zosmfrestapi/
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.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 .
First request
Save this as example.py and run it with python example.py. Enter the base
URL of your z/OSMF server when prompted (for example,
https://zosmf.example.com:443). The URL should include https:// and any
required port, but not an API path such as /zosmf.
The password is requested without displaying it and is not stored in the script. Replace the sample operation with one your z/OSMF user is authorized to perform.
from getpass import getpass
from zosmfrestapi import ZosmfClient, ZosmfError
server = input("z/OSMF server URL: ").strip().rstrip("/")
username = input("User ID: ").strip()
password = getpass("Password: ")
try:
with ZosmfClient(server, username=username, password=password) as client:
for instance in client.list_swis():
print(f"{instance.name} ({instance.system})")
except ZosmfError as error:
print(f"The z/OSMF request failed: {error}")
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).
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, a fork of
HTTPX; HTTPX2 uses truststore to integrate operating-system certificate
stores when it creates its default TLS context. This package 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 not
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="..." |
| Network proxy | proxy="http://proxy.example.com:8080" |
For example, to trust an internal certificate authority, pass cafile when
creating the client:
with ZosmfClient(server, username=username, password=password,
cafile="company-ca.pem") as client:
systems = client.get_systems()
Avoid putting passwords or tokens directly in scripts, committing them to
version control, or sharing them in logs. 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.
What you can do
The client provides synchronous methods for:
- Authentication (
authenticate). - z/OSMF groups and systems (
get_groups,get_systems). - Data sets (
read_dataset). - Software instances and SMP/E information (
list_swis,get_swi_by_name,get_swi_by_uuid, and related query methods). - Workflows (list, inspect, create, start, wait for, cancel, and archive).
- Software updates (search, inspect, start, monitor, and cancel).
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.
Metadata
Release files for zosmfrestapi 0.2.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.2.0.tar.gz | 31.8 kB | Without provenance | Details for zosmfrestapi-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zosmfrestapi-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for zosmfrestapi-0.2.0-py3-none-any.whl |
Total release size: 72.1 kB
Release files / zosmfrestapi-0.2.0.tar.gz
| Download URL | zosmfrestapi-0.2.0.tar.gz |
|---|---|
| Size | 31.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
493eeb1535fae25b7efc532536c7c3f7f57d8d60f53b75cbc1157d4ee7487d75
|
|
BLAKE2b-256 checksum How to use checksums |
488cee097b7a927ff583f59215be4877efbfd770c3e5ae72780fdcb65cfb11a1
|
| 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.2.0-py3-none-any.whl
| Download URL | zosmfrestapi-0.2.0-py3-none-any.whl |
|---|---|
| Size | 40.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d138b08605f9c84166eaba663d0dbaa6014440345a12c5c6ed24e2084c895b2a
|
|
BLAKE2b-256 checksum How to use checksums |
9659a8a99c1b103fe1649ce1e6ddf7d9452ecaffd2fb69f7f364cbec8710c64f
|
| 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.2.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.