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.0

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.0
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)

Table of built distributions (wheels) for zosmfrestapi 0.2.0
File Interpreter ABI Platform Actions
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.

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