zosmfrestapi 0.2.1__tar.gz → 0.3.1__tar.gz

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zosmfrestapi
-Version: 0.2.1
+Version: 0.3.1
 Summary: A Python wrapper for the z/OSMF REST API
 License-Expression: MIT
 License-File: LICENSE
@@ -19,23 +19,23 @@ Requires-Dist: httpx2 (>=2.12.0,<3.0.0)
 Requires-Dist: pendulum (>=3.2.0,<4.0.0)
 Requires-Dist: py_zcrypto ; extra == "zcrypto"
 Project-URL: Homepage, https://sr.ht/~ocurero/zosmfrestapi/
+Project-URL: Issues, https://todo.sr.ht/~ocurero/zosmfrestapi
 Project-URL: PyPI, https://pypi.org/project/zosmfrestapi/
 Project-URL: Repository, https://git.sr.ht/~ocurero/zosmfrestapi
 Description-Content-Type: text/markdown
 
-# A Python wrapper for the z/OSMF© REST API
+# 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.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![builds.sr.ht status](https://builds.sr.ht/~ocurero/zosmfrestapi/commits/main/.build.yml.svg)](https://builds.sr.ht/~ocurero/zosmfrestapi/commits/main/.build.yml?)
-![z/OS](https://img.shields.io/badge/works%20on-z/OS-8A2BE2)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![100% coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://builds.sr.ht/~ocurero/zosmfrestapi/commits/main/.build.yml?)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![z/OS](https://img.shields.io/badge/works%20on-z/OS-8A2BE2)
 
-* Open Source: MIT License.
 * Website: <https://sr.ht/~ocurero/zosmfrestapi/>
 * Repository: <https://git.sr.ht/~ocurero/zosmfrestapi>
 * Changelog: <https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/CHANGELOG.md>
-* Contributing: <https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/CONTRIBUTING.md>
 
 Key features:
 * **Pure Python**: Package and its dependencies are 100% pure Python (no C extensions required).
@@ -43,6 +43,8 @@ Key features:
 * **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.
 
+![ZosmfClient demo](https://git.sr.ht/~ocurero/zosmfrestapi/blob/main/docs/ZosmfClient.gif)
+
 
 Install
 -------
@@ -62,32 +64,16 @@ 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.
+## Quickstart
 
 ```python
-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: ")
+from zosmfrestapi import ZosmfClient
 
-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}")
+with ZosmfClient("https://zosmf.example",
+                 username="demouser", password="itsasecret") as client:
+    for instance in client.list_swis():
+        print(f"{instance.name} ({instance.system})")
 ```
 
 The `with` block closes the network connection automatically, even if a request
@@ -104,15 +90,54 @@ 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)`.
 
+## Clients
+
+The library provides two client implementations:
+
+* **`ZosmfClient`**: The standard synchronous client for communicating with z/OSMF using username/password, tokens, or standard TLS certificate files.
+* **`ZosmfZcryptoClient`**: A specialized client for z/OS environments that extracts mutual TLS (mTLS) client certificates directly from SAF key rings (RACF, ACF2, Top Secret).
+
+### Platform Support
+
+| Client | Linux | macOS | Windows | z/OS USS |
+| --- | :---: | :---: | :---: | :---: |
+| `ZosmfClient` | ✅ | ✅ | ✅ | ✅ |
+| `ZosmfZcryptoClient` | ❌ | ❌ | ❌ | ✅ |
+
+### Using `ZosmfZcryptoClient` on z/OS
+
+![ZosmfZcryptoClient demo](https://git.sr.ht/~ocurero/zosmfrestapi/blob/main/docs/ZosmfZcryptoClient.gif)
+
+`ZosmfZcryptoClient` retrieves client certificates and private keys directly from a SAF key ring, exporting temporary PEM files and configuring mutual TLS transparently. When using a key ring owned by the current user, specify the ring name as "name". When using a key ring owned by another user, specify the ring name as "userid/name":
+
+```python
+from zosmfrestapi import ZosmfZcryptoClient
+
+with ZosmfZcryptoClient("https://zosmf.example",
+                        keyring="userid/name", label="zOSMF Client Certificate") as client:
+    systems = client.get_systems()
+```
+
+Install the optional `zcrypto` extra:
+
+```console
+python -m pip install "zosmfrestapi[zcrypto]"
+```
+
+> [!WARNING]
+> The `zcrypto` extra requires `py_zcrypto`, a C extension that compiles against z/OS System SSL C headers. Therefore, it can **only** be installed and executed on **z/OS** systems. Attempting to install or use `ZosmfZcryptoClient` on Linux, macOS, or Windows will raise a `RuntimeError`.
+
+
+
 ## 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.
+those checks enabled for routine use. The HTTP transport is HTTPX2; HTTPX2 uses `truststore`
+to integrate operating-system certificate stores when it creates its default TLS context.
+zosmfrestapi 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 no trusted in that environment, pass its certificate file
+with `cafile` below.
 
 | Situation | Client option |
 | --- | --- |
@@ -121,33 +146,31 @@ trusted in that environment, pass its certificate file with `cafile` below.
 | 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="..."` |
+| Identity propagation (needs [PH68412](https://www.ibm.com/support/pages/apar/PH68412))   | None |
 | Network proxy | `proxy="http://proxy.example.com:8080"` |
 
 For example, to trust an internal certificate authority, pass `cafile` when
 creating the client:
 
 ```python
-with ZosmfClient(server, username=username, password=password,
+with ZosmfClient("https://zosmf.example", username="demouser", password="itsasecret",
                  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 `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`.
 
-The client provides synchronous methods for:
+## Supported APIs
 
-* 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).
+| API Category | Description | Key Methods (examples) |
+| --- | --- | --- |
+| **Authentication** | Basic Auth, LTPA / JWT tokens session login | `authenticate()` |
+| **Topology** | Query systems and sysplex groups defined in z/OSMF | `get_groups()`, `get_systems()` |
+| **Datasets** | Sequential and partitioned dataset retrieval | `read_dataset()` |
+| **Software Management** | SMP/E software instances, CSI queries, and datasets | `list_swis()`, `get_swi_by_name()`, `query_csi_by_name()` |
+| **Software Updates** | Search, inspect, start, monitor, and cancel update processes | `search_sw_updates_by_name()`, `start_sw_update_by_name()`, `check_sw_update_status()` |
+| **Workflows** | List, create, inspect, execute, monitor, and archive workflows | `get_workflows()`, `create_workflow()`, `start_workflow()`, `wait_for_workflow()` |
 
 Some operations change z/OSMF state. Check the method documentation and make
 sure your account has the required permissions before using them.
@@ -170,3 +193,26 @@ sure your account has the required permissions before using them.
 For the complete API, parameters, and return types, see the docstrings in the
 package source and the project website.
 
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/CONTRIBUTING.md) for guidelines on development, testing, and submitting patches.
+
+## Issues and Feedback
+
+If you encounter any bugs or have feature requests, please report them on the [SourceHut issue tracker](https://todo.sr.ht/~ocurero/zosmfrestapi).
+
+## License
+
+The MIT License. See [LICENSE](https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/LICENSE).
+
+## Trademarks
+
+IBM, the IBM logo, z/OS, MVS, and Z/OSMF are trademarks or are
+registered trademarks of International Business Machines Corporation,
+registered in many jurisdictions worldwide.  Other product and service
+names might be trademarks of IBM or other companies. A current list
+of IBM trademarks is available at <https://www.ibm.com/legal/copytrade>.
+
+This project is an independent community effort. It is not affiliated
+with, endorsed by, or sponsored by IBM.
+

zosmfrestapi-0.3.1/README.md

@@ -0,0 +1,191 @@
+# 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.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![builds.sr.ht status](https://builds.sr.ht/~ocurero/zosmfrestapi/commits/main/.build.yml.svg)](https://builds.sr.ht/~ocurero/zosmfrestapi/commits/main/.build.yml?)
+[![100% coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://builds.sr.ht/~ocurero/zosmfrestapi/commits/main/.build.yml?)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![z/OS](https://img.shields.io/badge/works%20on-z/OS-8A2BE2)
+
+* Website: <https://sr.ht/~ocurero/zosmfrestapi/>
+* Repository: <https://git.sr.ht/~ocurero/zosmfrestapi>
+* Changelog: <https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/CHANGELOG.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.
+
+![ZosmfClient demo](https://git.sr.ht/~ocurero/zosmfrestapi/blob/main/docs/ZosmfClient.gif)
+
+
+Install
+-------
+
+**zosmfrestapi** requires Python 3.12 or newer and access to a z/OSMF server.
+
+Install the package from PyPI:
+
+```console
+python -m pip install zosmfrestapi
+```
+
+If you have downloaded or cloned the source code, run this from the project's
+root folder instead:
+
+```console
+python -m pip install .
+```
+
+## Quickstart
+
+```python
+
+from zosmfrestapi import ZosmfClient
+
+with ZosmfClient("https://zosmf.example",
+                 username="demouser", password="itsasecret") as client:
+    for instance in client.list_swis():
+        print(f"{instance.name} ({instance.system})")
+```
+
+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:
+
+```python
+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)`.
+
+## Clients
+
+The library provides two client implementations:
+
+* **`ZosmfClient`**: The standard synchronous client for communicating with z/OSMF using username/password, tokens, or standard TLS certificate files.
+* **`ZosmfZcryptoClient`**: A specialized client for z/OS environments that extracts mutual TLS (mTLS) client certificates directly from SAF key rings (RACF, ACF2, Top Secret).
+
+### Platform Support
+
+| Client | Linux | macOS | Windows | z/OS USS |
+| --- | :---: | :---: | :---: | :---: |
+| `ZosmfClient` | ✅ | ✅ | ✅ | ✅ |
+| `ZosmfZcryptoClient` | ❌ | ❌ | ❌ | ✅ |
+
+### Using `ZosmfZcryptoClient` on z/OS
+
+![ZosmfZcryptoClient demo](https://git.sr.ht/~ocurero/zosmfrestapi/blob/main/docs/ZosmfZcryptoClient.gif)
+
+`ZosmfZcryptoClient` retrieves client certificates and private keys directly from a SAF key ring, exporting temporary PEM files and configuring mutual TLS transparently. When using a key ring owned by the current user, specify the ring name as "name". When using a key ring owned by another user, specify the ring name as "userid/name":
+
+```python
+from zosmfrestapi import ZosmfZcryptoClient
+
+with ZosmfZcryptoClient("https://zosmf.example",
+                        keyring="userid/name", label="zOSMF Client Certificate") as client:
+    systems = client.get_systems()
+```
+
+Install the optional `zcrypto` extra:
+
+```console
+python -m pip install "zosmfrestapi[zcrypto]"
+```
+
+> [!WARNING]
+> The `zcrypto` extra requires `py_zcrypto`, a C extension that compiles against z/OS System SSL C headers. Therefore, it can **only** be installed and executed on **z/OS** systems. Attempting to install or use `ZosmfZcryptoClient` on Linux, macOS, or Windows will raise a `RuntimeError`.
+
+
+
+## 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; HTTPX2 uses `truststore`
+to integrate operating-system certificate stores when it creates its default TLS context.
+zosmfrestapi 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 no 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="..."` |
+| Identity propagation (needs [PH68412](https://www.ibm.com/support/pages/apar/PH68412))   | None |
+| Network proxy | `proxy="http://proxy.example.com:8080"` |
+
+For example, to trust an internal certificate authority, pass `cafile` when
+creating the client:
+
+```python
+with ZosmfClient("https://zosmf.example", username="demouser", password="itsasecret",
+                 cafile="company-ca.pem") as client:
+    systems = client.get_systems()
+```
+
+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`.
+
+## Supported APIs
+
+| API Category | Description | Key Methods (examples) |
+| --- | --- | --- |
+| **Authentication** | Basic Auth, LTPA / JWT tokens session login | `authenticate()` |
+| **Topology** | Query systems and sysplex groups defined in z/OSMF | `get_groups()`, `get_systems()` |
+| **Datasets** | Sequential and partitioned dataset retrieval | `read_dataset()` |
+| **Software Management** | SMP/E software instances, CSI queries, and datasets | `list_swis()`, `get_swi_by_name()`, `query_csi_by_name()` |
+| **Software Updates** | Search, inspect, start, monitor, and cancel update processes | `search_sw_updates_by_name()`, `start_sw_update_by_name()`, `check_sw_update_status()` |
+| **Workflows** | List, create, inspect, execute, monitor, and archive workflows | `get_workflows()`, `create_workflow()`, `start_workflow()`, `wait_for_workflow()` |
+
+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.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/CONTRIBUTING.md) for guidelines on development, testing, and submitting patches.
+
+## Issues and Feedback
+
+If you encounter any bugs or have feature requests, please report them on the [SourceHut issue tracker](https://todo.sr.ht/~ocurero/zosmfrestapi).
+
+## License
+
+The MIT License. See [LICENSE](https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/LICENSE).
+
+## Trademarks
+
+IBM, the IBM logo, z/OS, MVS, and Z/OSMF are trademarks or are
+registered trademarks of International Business Machines Corporation,
+registered in many jurisdictions worldwide.  Other product and service
+names might be trademarks of IBM or other companies. A current list
+of IBM trademarks is available at <https://www.ibm.com/legal/copytrade>.
+
+This project is an independent community effort. It is not affiliated
+with, endorsed by, or sponsored by IBM.

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/pyproject.toml

@@ -21,11 +21,12 @@ dependencies = [
     "dacite (>=1.9.2,<2.0.0)",
 ]
 dynamic = []
-version = "0.2.1"
+version = "0.3.1"
 
 [project.urls]
 Homepage = "https://sr.ht/~ocurero/zosmfrestapi/"
 Repository = "https://git.sr.ht/~ocurero/zosmfrestapi"
+Issues = "https://todo.sr.ht/~ocurero/zosmfrestapi"
 PyPI = "https://pypi.org/project/zosmfrestapi/"
 
 [project.optional-dependencies]
@@ -35,11 +36,11 @@ zcrypto = [
 
 [dependency-groups]
 dev = [
+    "coverage (>=7.17.3,<8.0.0)",
     "pytest (>=9.1.1,<10.0.0)",
     "black (>=26.5.1,<27.0.0)",
     "pytest-recording (>=0.14.0,<0.15.0)",
     "pytest-httpx2 (>=1.0.0,<2.0.0)",
-    "pytest-cov (>=7.1.0,<8.0.0)",
     "flake8 (>=7.5.0,<8.0.0)",
     "flake8-pyproject (>=1.2.4,<2.0.0)",
     "mypy (>=2.4.1,<3.0.0)",
@@ -60,33 +61,42 @@ per-file-ignores = "tests/*.py:E501"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = ["-ra",
-           "--record-mode=none",
-           "--cov-fail-under=100",
-           "--cov=zosmfrestapi",
-           ]
 
 
-[tool.poe.tasks]
-format = "black ."
+[tool.poe.groups.quality.tasks.format]
+help = "Format code acording to black."
+cmd = "black zosmfrestapi tests"
 
-lint = [
+[tool.poe.groups.quality.tasks.quality]
+help = "Run quality checks: black, flake8, mypy and pyright."
+sequence = [
     { cmd = "black --check ." },
-    { cmd = "flake8" },
+    { cmd = "flake8 zosmfrestapi" },
     { cmd = "mypy zosmfrestapi" },
     { cmd = "pyright --warnings" }
+]
 
+[tool.poe.groups.testing.tasks.client_tests]
+help = "Run client tests only."
+sequence = [{cmd = """coverage run --omit='tests/*,*/zcrypto*' -m 
+                   pytest --ignore=tests/test_zcrypto_client.py"""},
+            {cmd = "coverage report --fail-under=100 --show-missing"}
 ]
 
-test = "pytest"
+[tool.poe.groups.testing.tasks.zcrypto_tests]
+help = "Run zcrypto tests only."
+sequence = [{cmd = """coverage run --omit='tests/*' --include='*/zcrypto*' -m
+                   pytest tests/test_zcrypto_client.py"""},
+            {cmd = "coverage report --fail-under=100 --show-missing"}
+            ]
 
-check = [
-    { cmd = "black --check ." },
-    { cmd = "flake8 zosmfrestapi" },
-    { cmd = "pyright --warnings" },
-    { cmd = "mypy zosmfrestapi" },
-    { cmd = "pytest" }
-]
+[tool.poe.groups.testing.tasks.tests]
+help = "Run client and zcrypto tests."
+sequence = ["client_tests", "zcrypto_tests"]
+
+[tool.poe.tasks.check]
+help = "Run all checks."
+sequence = ["quality", "client_tests", "zcrypto_tests"]
 
 [[tool.mypy.overrides]]
 module = ["OpenSSL.*", "py_zcrypto.*"]
@@ -100,4 +110,3 @@ enable = false
 [build-system]
 requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
 build-backend = "poetry_dynamic_versioning.backend"
-

zosmfrestapi-0.3.1/zosmfrestapi/__init__.py

@@ -0,0 +1,11 @@
+"""Synchronous Python client for the z/OSMF REST API.
+
+The package root re-exports :class:`ZosmfClient` and :class:`ZosmfZcryptoClient`.
+Create one client per server/configuration and use it as a context manager to close
+the shared HTTP session when finished.
+"""
+
+from zosmfrestapi.client import ZosmfClient
+from zosmfrestapi.zcrypto_client import ZosmfZcryptoClient
+
+__all__ = ["ZosmfClient", "ZosmfZcryptoClient"]

zosmfrestapi-0.2.1/zosmfrestapi/utils.py → zosmfrestapi-0.3.1/zosmfrestapi/_utils.py

@@ -4,7 +4,7 @@ from typing import Any
 import pendulum
 
 
-def _parse_datetime(value: str) -> pendulum.DateTime:
+def parse_datetime(value: str) -> pendulum.DateTime:
     """Parse a string and require a Pendulum ``DateTime`` result.
 
     Args:

zosmfrestapi-0.3.1/zosmfrestapi/exceptions/__init__.py

@@ -0,0 +1,21 @@
+from zosmfrestapi.exceptions.commons import ZosmfAuthError, ZosmfError
+from zosmfrestapi.exceptions.authentication import ZosmfLoginError
+from zosmfrestapi.exceptions.dataset import ZosmfDatasetNotFoundError
+from zosmfrestapi.exceptions.software import (
+    ZosmfSoftwareInstanceNotFoundError,
+    ZosmfSoftwareManagementError,
+    ZosmfSoftwareManagementRequestError,
+)
+from zosmfrestapi.exceptions.workflow import ZosmfWorkflowBaseError, ZosmfWorkflowError
+
+__all__ = [
+    "ZosmfDatasetNotFoundError",
+    "ZosmfError",
+    "ZosmfAuthError",
+    "ZosmfLoginError",
+    "ZosmfSoftwareManagementError",
+    "ZosmfSoftwareInstanceNotFoundError",
+    "ZosmfSoftwareManagementRequestError",
+    "ZosmfWorkflowBaseError",
+    "ZosmfWorkflowError",
+]

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/zosmfrestapi/exceptions/authentication.py

@@ -1,6 +1,6 @@
 import httpx2
 
-from . import ZosmfError
+from zosmfrestapi.exceptions.commons import ZosmfError
 
 
 class ZosmfLoginError(ZosmfError):

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/zosmfrestapi/exceptions/dataset.py

@@ -1,7 +1,7 @@
 import logging
 
 import httpx2
-from zosmfrestapi.exceptions import ZosmfError
+from zosmfrestapi.exceptions.commons import ZosmfError
 
 logger = logging.getLogger(__name__)
 

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/zosmfrestapi/exceptions/software.py

@@ -1,4 +1,4 @@
-from . import ZosmfError
+from zosmfrestapi.exceptions.commons import ZosmfError
 
 
 class ZosmfSoftwareManagementError(ZosmfError):

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/zosmfrestapi/exceptions/workflow.py

@@ -1,6 +1,6 @@
 import httpx2
 
-from . import ZosmfError
+from zosmfrestapi.exceptions.commons import ZosmfError
 
 
 class ZosmfWorkflowBaseError(ZosmfError):

zosmfrestapi-0.3.1/zosmfrestapi/models/__init__.py

@@ -0,0 +1,35 @@
+from zosmfrestapi.models.authentication import LoginOk
+from zosmfrestapi.models.software import (
+    DataSet,
+    Feature,
+    Fmid,
+    NonSmpeManagedDataset,
+    Product,
+    SmpeManagedDataset,
+    SmpeManagedDatasetZoneDddef,
+    SmpeManagedUnixDataset,
+    SoftwareInstance,
+    SoftwareInstanceWorkflow,
+    WorkflowLocation,
+)
+from zosmfrestapi.models.topology import Group, System
+from zosmfrestapi.models.workflow import WorkflowInstance, WorkflowItem
+
+__all__ = [
+    "System",
+    "Group",
+    "DataSet",
+    "Feature",
+    "Fmid",
+    "LoginOk",
+    "NonSmpeManagedDataset",
+    "Product",
+    "SmpeManagedDataset",
+    "SmpeManagedDatasetZoneDddef",
+    "SmpeManagedUnixDataset",
+    "SoftwareInstance",
+    "SoftwareInstanceWorkflow",
+    "WorkflowLocation",
+    "WorkflowInstance",
+    "WorkflowItem",
+]

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/zosmfrestapi/services/software.py

@@ -1,11 +1,11 @@
 import logging
 import time
-from typing import Any
 from dataclasses import asdict
+from typing import Any
 
 import pendulum
 from dacite import Config, from_dict
-
+from zosmfrestapi import _utils
 from zosmfrestapi.exceptions.software import (
     ZosmfSoftwareInstanceNotFoundError,
     ZosmfSoftwareManagementError,
@@ -25,7 +25,6 @@ from zosmfrestapi.models.software import (
     SoftwareInstance,
     SoftwareInstanceWorkflow,
 )
-from zosmfrestapi.utils import _parse_datetime, remap
 
 from . import ZosmfBase
 
@@ -52,10 +51,10 @@ class SoftwareServices(ZosmfBase):
         return [
             from_dict(
                 data_class=SoftwareInstance,
-                data=remap(swi, SoftwareInstance),
+                data=_utils.remap(swi, SoftwareInstance),
                 config=Config(
                     type_hooks={
-                        pendulum.DateTime: _parse_datetime,
+                        pendulum.DateTime: _utils.parse_datetime,
                     }
                 ),
             )
@@ -69,10 +68,10 @@ class SoftwareServices(ZosmfBase):
         self._raise_for_status(resp, exc_handler=ZosmfSoftwareManagementError)
         return from_dict(
             data_class=SoftwareInstance,
-            data=remap(resp.json(), SoftwareInstance),
+            data=_utils.remap(resp.json(), SoftwareInstance),
             config=Config(
                 type_hooks={
-                    pendulum.DateTime: _parse_datetime,
+                    pendulum.DateTime: _utils.parse_datetime,
                     list[DataSet]: lambda v: [] if v is None else v,
                     list[Product]: lambda v: [] if v is None else v,
                     list[NonSmpeProduct]: lambda v: [] if v is None else v,

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/zosmfrestapi/services/software_updates.py

@@ -3,6 +3,12 @@ from typing import Any
 
 import pendulum
 from dacite import Config, from_dict
+from zosmfrestapi import _utils
+from zosmfrestapi.exceptions.software import (
+    ZosmfSoftwareInstanceNotFoundError,
+    ZosmfSoftwareManagementError,
+    ZosmfSoftwareManagementRequestError,
+)
 from zosmfrestapi.models.software_updates import (
     MissingFixcat,
     MissingUpdate,
@@ -10,13 +16,6 @@ from zosmfrestapi.models.software_updates import (
     UpdateProcess,
 )
 
-from zosmfrestapi.exceptions.software import (
-    ZosmfSoftwareManagementError,
-    ZosmfSoftwareInstanceNotFoundError,
-    ZosmfSoftwareManagementRequestError,
-)
-from zosmfrestapi.utils import _parse_datetime
-
 from . import ZosmfBase
 
 
@@ -39,7 +38,7 @@ class SoftwareUpdatesServices(ZosmfBase):
                 data=upd,
                 config=Config(
                     type_hooks={
-                        pendulum.DateTime: _parse_datetime,
+                        pendulum.DateTime: _utils.parse_datetime,
                     },
                     convert_key=lambda k: k.replace("_", "-"),
                 ),
@@ -128,7 +127,7 @@ class SoftwareUpdatesServices(ZosmfBase):
                 data=process,
                 config=Config(
                     type_hooks={
-                        pendulum.DateTime: _parse_datetime,
+                        pendulum.DateTime: _utils.parse_datetime,
                     },
                     convert_key=lambda k: k.replace("_", "-"),
                 ),
@@ -397,7 +396,7 @@ class SoftwareUpdatesServices(ZosmfBase):
                 data=sw_upd,
                 config=Config(
                     type_hooks={
-                        pendulum.DateTime: _parse_datetime,
+                        pendulum.DateTime: _utils.parse_datetime,
                     }
                 ),
             )
@@ -864,7 +863,7 @@ class SoftwareUpdatesServices(ZosmfBase):
                 data=process,
                 config=Config(
                     type_hooks={
-                        pendulum.DateTime: _parse_datetime,
+                        pendulum.DateTime: _utils.parse_datetime,
                     },
                     convert_key=lambda k: k.replace("_", "-"),
                 ),

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/zosmfrestapi/services/topology.py

@@ -1,7 +1,7 @@
 import logging
 from . import ZosmfBase
 from dacite import from_dict
-from zosmfrestapi.utils import remap
+from zosmfrestapi import _utils
 from zosmfrestapi.models.topology import Group, System
 
 logger = logging.getLogger(__name__)
@@ -25,7 +25,7 @@ class TopologyServices(ZosmfBase):
         resp = self.http.get("/zosmf/resttopology/groups")
         self._raise_for_status(resp)
         return {
-            item["name"]: from_dict(Group, data=remap(item, Group))
+            item["name"]: from_dict(Group, data=_utils.remap(item, Group))
             for item in resp.json()["items"]
         }
 
@@ -44,6 +44,6 @@ class TopologyServices(ZosmfBase):
         resp = self.http.get("/zosmf/resttopology/systems")
         self._raise_for_status(resp)
         return {
-            item["systemName"]: from_dict(System, data=remap(item, System))
+            item["systemName"]: from_dict(System, data=_utils.remap(item, System))
             for item in resp.json()["items"]
         }

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/zosmfrestapi/services/workflow.py

@@ -2,18 +2,14 @@ import time
 from typing import Any, Iterator, Literal, overload
 
 from dacite import from_dict
-
-from zosmfrestapi.exceptions.workflow import (
-    ZosmfWorkflowBaseError,
-    ZosmfWorkflowError,
-)
+from zosmfrestapi import _utils
+from zosmfrestapi.exceptions.workflow import ZosmfWorkflowBaseError, ZosmfWorkflowError
 from zosmfrestapi.models.workflow import (
     WorkflowArchivedListItem,
     WorkflowInstance,
     WorkflowItem,
     WorkflowListItem,
 )
-from zosmfrestapi.utils import remap, to_dict
 
 from . import ZosmfBase
 
@@ -67,7 +63,7 @@ class WorkflowServices(ZosmfBase):
         """
         return from_dict(
             WorkflowInstance,
-            data=remap(
+            data=_utils.remap(
                 self._get_workflow(workflow_id, steps=steps, variables=variables),
                 WorkflowInstance,
             ),
@@ -134,7 +130,7 @@ class WorkflowServices(ZosmfBase):
         return [
             from_dict(
                 WorkflowListItem,
-                data=remap(workflow, WorkflowListItem),
+                data=_utils.remap(workflow, WorkflowListItem),
             )
             for workflow in resp.json()["workflows"]
         ]
@@ -159,7 +155,7 @@ class WorkflowServices(ZosmfBase):
         return [
             from_dict(
                 WorkflowArchivedListItem,
-                data=remap(archived_workflow, WorkflowArchivedListItem),
+                data=_utils.remap(archived_workflow, WorkflowArchivedListItem),
             )
             for archived_workflow in resp.json()["archivedWorkflows"]
         ]
@@ -185,7 +181,9 @@ class WorkflowServices(ZosmfBase):
             httpx2.RequestError: If either request fails before an HTTP response
                 is received.
         """
-        resp = self.http.post("/zosmf/workflow/rest/1.0/workflows", json=to_dict(workflow))
+        resp = self.http.post(
+            "/zosmf/workflow/rest/1.0/workflows", json=_utils.to_dict(workflow)
+        )
         self._raise_for_status(resp, exc_handler=ZosmfWorkflowError)
         return self.get_workflow(resp.json()["workflowKey"])
 

{zosmfrestapi-0.2.1 → zosmfrestapi-0.3.1}/zosmfrestapi/zcrypto_client.py

@@ -4,7 +4,6 @@ import ssl
 from tempfile import NamedTemporaryFile
 
 from zosmfrestapi.client import ZosmfClient
-from zosmfrestapi.zcrypto import _extract_key_from_pkcs12
 
 
 class ZosmfZcryptoClient(ZosmfClient):
@@ -46,6 +45,8 @@ class ZosmfZcryptoClient(ZosmfClient):
             raise RuntimeError("The zcrypto backend is only available on z/OS.")
         import py_zcrypto  # pyright: ignore[reportMissingImports]
 
+        from zosmfrestapi.zcrypto import _extract_key_from_pkcs12
+
         keyring = kwargs.pop("keyring")
         label = kwargs.pop("label")
         zcrypto_obj = py_zcrypto.zcrypto()

zosmfrestapi-0.2.1/README.md

@@ -1,146 +0,0 @@
-# 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.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
-[![builds.sr.ht status](https://builds.sr.ht/~ocurero/zosmfrestapi/commits/main/.build.yml.svg)](https://builds.sr.ht/~ocurero/zosmfrestapi/commits/main/.build.yml?)
-![z/OS](https://img.shields.io/badge/works%20on-z/OS-8A2BE2)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
-* Open Source: MIT License.
-* Website: <https://sr.ht/~ocurero/zosmfrestapi/>
-* Repository: <https://git.sr.ht/~ocurero/zosmfrestapi>
-* Changelog: <https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/CHANGELOG.md>
-* Contributing: <https://git.sr.ht/~ocurero/zosmfrestapi/tree/main/item/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:
-
-```console
-python -m pip install zosmfrestapi
-```
-
-If you have downloaded or cloned the source code, run this from the project's
-root folder instead:
-
-```console
-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.
-
-```python
-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:
-
-```python
-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:
-
-```python
-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.

zosmfrestapi-0.2.1/zosmfrestapi/__init__.py

@@ -1,93 +0,0 @@
-"""Synchronous Python client for the z/OSMF REST API.
-
-The package root re-exports :class:`ZosmfClient`, :class:`ZosmfZcryptoClient`,
-response models, and public exceptions. Create one client per server/configuration and
-use it as a context manager to close the shared HTTP session when finished.
-"""
-
-from zosmfrestapi.client import ZosmfClient
-from zosmfrestapi.exceptions import ZosmfAuthError, ZosmfError
-from zosmfrestapi.exceptions.authentication import ZosmfLoginError
-from zosmfrestapi.exceptions.dataset import ZosmfDatasetNotFoundError
-from zosmfrestapi.exceptions.software import (
-    ZosmfSoftwareInstanceNotFoundError,
-    ZosmfSoftwareManagementError,
-    ZosmfSoftwareManagementRequestError,
-)
-from zosmfrestapi.exceptions.workflow import ZosmfWorkflowBaseError, ZosmfWorkflowError
-from zosmfrestapi.models.authentication import LoginOk
-from zosmfrestapi.models.software import (
-    CsiEntry,
-    DataSet,
-    Feature,
-    Fmid,
-    NonSmpeManagedDataset,
-    Product,
-    SmpeManagedDataset,
-    SmpeManagedDatasetZoneDddef,
-    SmpeManagedUnixDataset,
-    SoftwareInstance,
-    SoftwareInstanceWorkflow,
-    WorkflowLocation,
-)
-from zosmfrestapi.models.software_updates import (
-    MissingFixcat,
-    MissingUpdate,
-    MissingUpdateResolver,
-    SoftwareUpdate,
-    SoftwareUpdateZone,
-    UpdateErrorResults,
-    UpdateProcess,
-    UpdateResult,
-    UpdateSelection,
-)
-from zosmfrestapi.models.topology import Group, System
-from zosmfrestapi.models.workflow import (
-    WorkflowArchivedListItem,
-    WorkflowInstance,
-    WorkflowItem,
-    WorkflowListItem,
-)
-from zosmfrestapi.zcrypto_client import ZosmfZcryptoClient
-
-__all__ = [
-    "ZosmfClient",
-    "ZosmfZcryptoClient",
-    "LoginOk",
-    "ZosmfDatasetNotFoundError",
-    "ZosmfError",
-    "ZosmfAuthError",
-    "ZosmfLoginError",
-    "System",
-    "Group",
-    "CsiEntry",
-    "DataSet",
-    "Feature",
-    "Fmid",
-    "NonSmpeManagedDataset",
-    "Product",
-    "SmpeManagedDataset",
-    "SmpeManagedDatasetZoneDddef",
-    "SmpeManagedUnixDataset",
-    "SoftwareInstance",
-    "SoftwareInstanceWorkflow",
-    "WorkflowLocation",
-    "ZosmfSoftwareManagementError",
-    "ZosmfSoftwareInstanceNotFoundError",
-    "ZosmfSoftwareManagementRequestError",
-    "MissingFixcat",
-    "MissingUpdate",
-    "MissingUpdateResolver",
-    "SoftwareUpdate",
-    "SoftwareUpdateZone",
-    "UpdateErrorResults",
-    "UpdateProcess",
-    "UpdateResult",
-    "UpdateSelection",
-    "WorkflowArchivedListItem",
-    "WorkflowInstance",
-    "WorkflowItem",
-    "WorkflowListItem",
-    "ZosmfWorkflowBaseError",
-    "ZosmfWorkflowError",
-]