Skip to main content

A Python wrapper for the z/OSMF© REST API

Project Status: Active – The project has reached a stable, usable state and is being actively developed. builds.sr.ht status z/OS License: MIT Code style: black

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.exe to 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.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zosmfrestapi 0.2.1
File Size Uploaded Provenance Actions
zosmfrestapi-0.2.1.tar.gz 31.9 kB Without provenance Details for zosmfrestapi-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zosmfrestapi 0.2.1
File Interpreter ABI Platform Actions
zosmfrestapi-0.2.1-py3-none-any.whl Python 3 none any Details for zosmfrestapi-0.2.1-py3-none-any.whl

Total release size: 72.3 kB

Release files / zosmfrestapi-0.2.1.tar.gz

Download URL zosmfrestapi-0.2.1.tar.gz
Size 31.9 kB
Tags Source
SHA-256 checksum
How to use checksums
85cc339c6492dbebf41919aed969a4fde34d77509a073976eec6f78774345c38
BLAKE2b-256 checksum
How to use checksums
2b1e7d06cb4736307e444745f471970509e7b61def2061616e4ec7bfdef19273
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.1-py3-none-any.whl

Download URL zosmfrestapi-0.2.1-py3-none-any.whl
Size 40.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b14165c8b30e159c51091ced3a9307cee0e28a7fccf3faaa91f3ab9cce219230
BLAKE2b-256 checksum
How to use checksums
07ee532115a225f7a9e4a1daf9d9ee6e62de806497d1d9c26f7798d0f4a36a8c
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.1

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page