The Zowe Client Python SDK, is a set of Python packages designed to allow programmatic interactions with z/OS REST API interfaces with minimal effort.
Python developers can leverage the Zowe SDK in order to create powerful scripts/applications that can interact with z/OS components.
When installing the Zowe Client Python SDK, you have two options:
- Install all the Zowe packages
- Install a single sub-package
The choice depends on your intentions. If you choose to install all Zowe SDK packages,
this means that you will install everything under the zowe
namespace in PyPi.
Alternatively, you can choose to install only a single subpackage for a smaller installation.
To install all Zowe SDK packages using pip:
pip install -U --pre zowe-python-sdk-bundle
Or, to install a subpackage using pip:
pip install -U --pre zowe.<subpackage>_for_zowe_sdk
For more information on the available sub-packages click HERE
The Zowe core package has dependencies on the packages listed below:
commentjson
deepmerge
jsonschema
pyyaml
requests>=2.22
urllib3
It also has an optional dependency on the Zowe Secrets SDK for storing client secrets which can be installed with the secrets
extra:
pip install -U --pre zowe.core-for-zowe-sdk[secrets]
Ensure the following prerequisites are installed and on your PATH:
- Python >= 3.8 and
pip
- Cargo >= 1.72 (to build Rust bindings for Secrets SDK)
- Visual Studio Build Tools >= 2015 (Windows only)
Clone the repository using git
:
git clone https://github.com/zowe/zowe-client-python-sdk.git
Navigate to the root of the repository and checkout the desired branch. Currently, active development is on the main
branch:
cd zowe-client-python-sdk/
git checkout main
We recommend that developers make a virtual environment to install all required dependencies.
Create a virtual environment in the root of the repository folder using the venv
module.
The command below assumes that python
is a version of Python3:
python -m venv venv
(If this isn't the case for your environment, use the appropriate command alias for Python3)
Activate your virtual environment so that Python uses it to manage dependencies. Assuming that you are using Bash shell, reference the command below:
source venv/bin/activate
Otherwise, check the table titled "Command to activate virtual environment" here to find the command that works for your shell.
Install the dependencies listed in requirements.txt
using pip
:
pip install -r requirements.txt
You can now develop the Python SDK with the installed dependencies. When you are finished with your development session, deactivate your virtual environment:
deactivate
After you install the package in your project, import the class for the required sub-package (i.e Console
class for z/OS Console commands).
Create a dictionary to handle communication with the plug-in:
from zowe.zos_console_for_zowe_sdk import Console
profile = {
"host": "example.com",
"port": 443,
"user": "<user>",
"password": "<password>"
}
my_console = Console(profile)
Alternatively, you can use an existing Zowe CLI profile instead:
from zowe.zos_core_for_zowe_sdk import ProfileManager
from zowe.zos_console_for_zowe_sdk import Console
profile = ProfileManager().load(profile_type="zosmf")
my_console = Console(profile)
Important: If your z/OSMF profile uses a credentials manager, this approach may not work depending on your operating system. Support for loading secure profiles has only been tested on Windows and Ubuntu so far.
Currently, the Zowe Python SDK supports the following interfaces:
- Console commands
- z/OSMF Information retrieval
- Submit job from a dataset
- Submit job from local file
- Submit job as plain text JCL
- Retrieve job status
- Retrieve job list from JES spool
- Start/End TSO address space
- Ping TSO address space
- Issue TSO command
Important: Notice that the below examples assume that you have already created an object for the sub-package of your preference just like in the quickstart example.
Usage of the console api:
result = my_console.issue_command("<command>")
The result will be a JSON object containing the result from the console command.
To retrieve the status of a job on JES
result = my_jobs.get_job_status("<jobname>", "<jobid>")
To retrieve list of jobs in JES spool
result = my_jobs.list_jobs(owner="<user>", prefix="<job-prefix>")
Additional parameters available are:
- max_jobs
- user_correlator
To submit a job from a dataset:
result = my_jobs.submit_from_mainframe("<dataset-name>")
To submit a job from a local file:
result = my_jobs.submit_from_local_file("<file-path>")
To submit from plain text:
jcl = '''
//IEFBR14Q JOB (AUTOMATION),CLASS=A,MSGCLASS=0,
// MSGLEVEL=(1,1),REGION=0M,NOTIFY=&SYSUID
//STEP1 EXEC PGM=IEFBR14
'''
result = my_jobs.submit_from_plaintext(jcl)
Starting a TSO address space
session_parameters = {
'proc': 'IZUFPROC',
'chset': '697',
'cpage': '1047',
'rows': '204',
'cols': '160',
'rsize': '4096',
'acct': 'DEFAULT'
}
session_key = my_tso.start_tso_session(**session_parameters)
If you don't provide any session parameter ZoweSDK will attempt to start a session with default parameters.
To end a TSO address space
my_tso.end_tso_session("<session-key>")
In order to issue a TSO command
tso_output = my_tso.issue_command("<tso-command>")
Usage of the z/OSMF api
result = my_zosmf.get_info()
The result will be a JSON object containing z/OSMF information
- Make sure to check out the Zowe project!
- For further information on z/OSMF REST API, click HERE