From 1735ceb564f1228c8d23589d2b2724977819777c Mon Sep 17 00:00:00 2001 From: Timothy Johnson Date: Tue, 28 Nov 2023 12:09:41 -0500 Subject: [PATCH 1/2] Lock down deps and add readmes to package metadata Signed-off-by: Timothy Johnson --- README.md | 79 +++++++++++++++++++++++++--------------- src/core/setup.py | 14 ++++--- src/setup.py | 2 + src/zos_console/setup.py | 2 + src/zos_files/setup.py | 2 + src/zos_jobs/setup.py | 2 + src/zos_tso/setup.py | 2 + src/zosmf/setup.py | 2 + 8 files changed, 69 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 93723df9..b31237ac 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ![](https://img.shields.io/badge/license-EPL--2.0-blue) [![Latest Release](https://img.shields.io/github/v/release/zowe/zowe-client-python-sdk)](https://github.com/zowe/zowe-client-python-sdk/releases/latest) [![Documentation Status](https://readthedocs.org/projects/zowe-client-python-sdk/badge/?version=latest)](https://zowe-client-python-sdk.readthedocs.io/en/latest/index.html) -The Zowe Client Python SDK, is a set of Python packages designed to allow programmatic +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 @@ -18,11 +18,10 @@ When installing the Zowe Client Python SDK, you have two options: - 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. +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: ``` @@ -36,24 +35,33 @@ pip install zowe._for_zowe_sdk ``` For more information on the available sub-packages click [HERE](https://zowe-client-python-sdk.readthedocs.io/en/latest/packages/packages.html) - ## Requirements -The Zowe core package has dependencies on the below packages: +The Zowe core package has dependencies on the packages listed below: ``` -requests>=2.22 -keyring +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 zowe.core-for-zowe-sdk[secrets] +``` + ### Developer setup **Prerequisite:** The minimum supported Python version is 3.7. @@ -71,7 +79,7 @@ cd zowe-client-python-sdk/ git checkout main ``` -We recommend that developers make a virtual environment to install all required dependencies. +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: @@ -106,11 +114,9 @@ deactivate ## Quickstart - -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). +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: - ```python from zowe.zos_console_for_zowe_sdk import Console profile = { @@ -135,60 +141,67 @@ Alternatively, you can use an existing Zowe CLI profile instead: **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. - # Available options 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 +- 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. ## Console Usage of the console api: + ```python result = my_console.issue_command("") ``` + The result will be a JSON object containing the result from the console command. ## Job To retrieve the status of a job on JES + ```python result = my_jobs.get_job_status("", "") ``` To retrieve list of jobs in JES spool + ```python result = my_jobs.list_jobs(owner="", prefix="") ``` + Additional parameters available are: -* max_jobs -* user_correlator +- max_jobs +- user_correlator To submit a job from a dataset: + ```python result = my_jobs.submit_from_mainframe("") ``` To submit a job from a local file: + ```python result = my_jobs.submit_from_local_file("") ``` To submit from plain text: + ```python jcl = ''' //IEFBR14Q JOB (AUTOMATION),CLASS=A,MSGCLASS=0, @@ -203,6 +216,7 @@ result = my_jobs.submit_from_plaintext(jcl) ## TSO Starting a TSO address space + ```python session_parameters = { @@ -217,27 +231,32 @@ session_parameters = { 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 + ```python my_tso.end_tso_session("") ``` In order to issue a TSO command + ```python tso_output = my_tso.issue_command("") ``` ## z/OSMF + Usage of the z/OSMF api + ```python result = my_zosmf.get_info() ``` -The result will be a JSON object containing z/OSMF information +The result will be a JSON object containing z/OSMF information # Acknowledgments -* Make sure to check out the [Zowe project](https://github.com/zowe)! -* For further information on z/OSMF REST API, click [HERE](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.izua700/IZUHPINFO_RESTServices.htm) +- Make sure to check out the [Zowe project](https://github.com/zowe)! +- For further information on z/OSMF REST API, click [HERE](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.izua700/IZUHPINFO_RESTServices.htm) diff --git a/src/core/setup.py b/src/core/setup.py index 5919f70f..1b46e7ea 100644 --- a/src/core/setup.py +++ b/src/core/setup.py @@ -10,6 +10,8 @@ name="zowe_core_for_zowe_sdk", version=__version__, description="Zowe Python SDK - Core package", + long_description=open("README.md", 'r').read(), + long_description_content_type="text/markdown", url="https://github.com/zowe/zowe-client-python-sdk", author="Guilherme Cartier", author_email="gcartier94@gmail.com", @@ -20,12 +22,12 @@ "License :: OSI Approved :: Eclipse Public License 2.0 (EPL-2.0)", ], install_requires=[ - "commentjson", - "deepmerge", - "jsonschema", - "pyyaml", - "requests", - "urllib3", + "commentjson~=0.9.0", + "deepmerge~=1.1.0", + "jsonschema~=4.17.3", + "pyyaml~=6.0.1", + "requests~=2.31.0", + "urllib3~=1.26.18", ], extras_require={ "secrets": [resolve_sdk_dep("secrets", "~=" + __version__)] diff --git a/src/setup.py b/src/setup.py index af3527a1..5b65a608 100644 --- a/src/setup.py +++ b/src/setup.py @@ -24,6 +24,8 @@ def resolve_sdk_dep(sdk_name, version_spec): name="zowe", version=__version__, description="Zowe Python SDK", + long_description=open("../README.md", 'r').read(), + long_description_content_type="text/markdown", url="https://github.com/zowe/zowe-client-python-sdk", author="Guilherme Cartier", author_email="gcartier94@gmail.com", diff --git a/src/zos_console/setup.py b/src/zos_console/setup.py index 659f9212..864f8e4c 100644 --- a/src/zos_console/setup.py +++ b/src/zos_console/setup.py @@ -10,6 +10,8 @@ name="zowe_zos_console_for_zowe_sdk", version=__version__, description="Zowe Python SDK - z/OS Console package", + long_description=open("README.md", 'r').read(), + long_description_content_type="text/markdown", url="https://github.com/zowe/zowe-client-python-sdk", author="Guilherme Cartier", author_email="gcartier94@gmail.com", diff --git a/src/zos_files/setup.py b/src/zos_files/setup.py index f6adc7c2..3bf890a2 100644 --- a/src/zos_files/setup.py +++ b/src/zos_files/setup.py @@ -10,6 +10,8 @@ name="zowe_zos_files_for_zowe_sdk", version=__version__, description="Zowe Python SDK - z/OS Files package", + long_description=open("README.md", 'r').read(), + long_description_content_type="text/markdown", url="https://github.com/zowe/zowe-client-python-sdk", author="Guilherme Cartier", author_email="gcartier94@gmail.com", diff --git a/src/zos_jobs/setup.py b/src/zos_jobs/setup.py index 8109eaf1..8c677401 100644 --- a/src/zos_jobs/setup.py +++ b/src/zos_jobs/setup.py @@ -10,6 +10,8 @@ name="zowe_zos_jobs_for_zowe_sdk", version=__version__, description="Zowe Python SDK - z/OS Jobs package", + long_description=open("README.md", 'r').read(), + long_description_content_type="text/markdown", url="https://github.com/zowe/zowe-client-python-sdk", author="Guilherme Cartier", author_email="gcartier94@gmail.com", diff --git a/src/zos_tso/setup.py b/src/zos_tso/setup.py index 593f7a41..07e73a34 100644 --- a/src/zos_tso/setup.py +++ b/src/zos_tso/setup.py @@ -10,6 +10,8 @@ name="zowe_zos_tso_for_zowe_sdk", version=__version__, description="Zowe Python SDK - z/OS TSO package", + long_description=open("README.md", 'r').read(), + long_description_content_type="text/markdown", url="https://github.com/zowe/zowe-client-python-sdk", author="Guilherme Cartier", author_email="gcartier94@gmail.com", diff --git a/src/zosmf/setup.py b/src/zosmf/setup.py index ba830f9a..73f38107 100644 --- a/src/zosmf/setup.py +++ b/src/zosmf/setup.py @@ -10,6 +10,8 @@ name="zowe_zosmf_for_zowe_sdk", version=__version__, description="Zowe Python SDK - z/OSMF package", + long_description=open("README.md", 'r').read(), + long_description_content_type="text/markdown", url="https://github.com/zowe/zowe-client-python-sdk", author="Guilherme Cartier", author_email="gcartier94@gmail.com", From 62640c15f54b699efec84054d3566430ee145986 Mon Sep 17 00:00:00 2001 From: Timothy Johnson Date: Tue, 28 Nov 2023 12:54:20 -0500 Subject: [PATCH 2/2] Document cargo as prereq in readme Signed-off-by: Timothy Johnson --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b31237ac..5a46b26e 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,11 @@ pip install zowe.core-for-zowe-sdk[secrets] ### Developer setup -**Prerequisite:** The minimum supported Python version is 3.7. +Ensure the following prerequisites are installed and on your PATH: + +- Python >= 3.7 and `pip` +- Cargo >= 1.72 (to build Rust bindings for Secrets SDK) +- Visual Studio Build Tools >= 2015 (Windows only) Clone the repository using `git`: @@ -81,7 +85,7 @@ 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. +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: ``` @@ -90,7 +94,7 @@ 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. +Activate your virtual environment so that Python uses it to manage dependencies. Assuming that you are using Bash shell, reference the command below: ``` @@ -105,7 +109,7 @@ 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. +You can now develop the Python SDK with the installed dependencies. When you are finished with your development session, deactivate your virtual environment: ```