zosmfrestapi 0.2.0__py3-none-any.whl

zosmfrestapi/testing/workflows.py

@@ -0,0 +1,320 @@
+from zosmfrestapi.models.workflow import (
+    WorkflowArchivedListItem,
+    WorkflowInstance,
+    WorkflowListItem,
+)
+
+
+def make_workflow_list():
+    return [
+        WorkflowListItem(
+            instanceURI="/zosmf/workflow/rest/1.0/workflows/"
+            "8ed3a85e-6472-47eb-ba44-19e9511df450",
+            owner="FOOBAR",
+            vendor="Hooli Software",
+            workflowDefinitionFileMD5Value="c87342978ad879837a9872899cse2001",
+            workflowDescription="The Box III, Gavin Belson Signature Edition",
+            workflowID="HOOLMC",
+            workflowKey="8ed3a85e-6472-47eb-ba44-19e9511df450",
+            workflowName="HOOLIE",
+            workflowVersion="1.0",
+        ),
+    ]
+
+
+def make_workflow(steps=[], variables=[]):
+    return WorkflowInstance(
+        name="HOOLIE",
+        percentComplete=0,
+        workflowDefinitionFileMD5Value="8e8fabbd0f72c54119a3748427fc0f25",
+        workflowArchiveSAFID="FOOBAR",
+        jobStatement=None,
+        globalVariableGroup=None,
+        jobsOutputDirectory="/foo/bar/log",
+        scope="sysplex",
+        status="in-progress",
+        vendor="Hooli Software",
+        deleteCompletedJobs=False,
+        autoDeleteOnCompletion=False,
+        isInstanceVariableWithoutPrefix=False,
+        workflowVersion="1.0",
+        steps=steps,
+        access="Public",
+        productVersion=None,
+        productID=None,
+        variables=variables,
+        category="general",
+        system="TST01.TSTA",
+        workflowDescription="The Box III, Gavin Belson Signature Edition",
+        workflowID="Hoolie",
+        owner="FOOBAR",
+        accountInfo=None,
+        automationStatus=None,
+        containsParallelSteps=False,
+        isCallable=None,
+        workflowKey="fc4fc0fa-1fa3-4247-bb2d-7f5203e0c3c7",
+        productName=None,
+    )
+
+
+def make_new_workflow():
+    return WorkflowInstance(
+        name="HOOLIE",
+        owner="demouser",
+        system="TST01.TSTA (TSTA)",
+        scope="sysplex",
+        percentComplete=0,
+        workflowDefinitionFileMD5Value="aca0b684798fb2dfd49261ca4d211d93",
+        workflowArchiveSAFID="demouser",
+        jobStatement=None,
+        globalVariableGroup=None,
+        jobsOutputDirectory=None,
+        status="in-progress",
+        vendor="Hoolie Software",
+        deleteCompletedJobs=False,
+        autoDeleteOnCompletion=False,
+        isInstanceVariableWithoutPrefix=False,
+        workflowVersion="1.0",
+        steps=[],
+        access="Public",
+        productVersion=None,
+        productID=None,
+        variables=[],
+        category="general",
+        workflowDescription="The Box III, Gavin Belson Signature Edition",
+        workflowID="Hoolie",
+        accountInfo=None,
+        automationStatus=None,
+        containsParallelSteps=False,
+        isCallable=None,
+        workflowKey="fc4fc0fa-1fa3-4247-bb2d-7f5203e0c3c7",
+        productName=None,
+    )
+
+
+def make_workflow_with_steps():
+
+    step1 = """//*********************************************************************
+//*              STEP - Create temporary directory using BPXBATCH     *
+//*********************************************************************
+//*
+//CREATE   EXEC PGM=BPXBATCH
+//*
+//STDOUT   DD SYSOUT=*
+//*
+//STDERR   DD SYSOUT=*
+//*
+//STDPARM  DD *
+SH mkdir -m 700 /tmp/IZUWORKFLOW-17932912593740.328682
+/*
+//*
+//*********************************************************************
+//*              STEP - Create script in temp directory using BPXCOPY *
+//*********************************************************************
+//*
+//UXCOPY   EXEC PGM=BPXCOPY,
+//             PARM='ELEMENT(MYSCRIPT) TYPE(TEXT) PATHMODE(0,7,0,0)'
+//*
+//SYSTSPRT DD SYSOUT=*
+//*
+//SYSIN    DD DUMMY
+//*
+//SYSUT2   DD PATH='/tmp/IZUWORKFLOW-17932912593740.328682'
+//*
+//SYSUT1   DD *,DLM=$$
+/bin/echo 'HELLO WORLD 1'
+$$
+//*
+//*********************************************************************
+//*              STEP - Execute script using BPXBATCH                 *
+//*********************************************************************
+//*
+//XBATCH   EXEC PGM=BPXBATCH
+//*
+//STDOUT   DD SYSOUT=*
+//*
+//STDERR   DD SYSOUT=*
+//*
+//STDPARM  DD *
+SH /tmp/IZUWORKFLOW-17932912593740.328682/MYSCRIPT
+/*
+//*
+//*********************************************************************
+//*              STEP - Delete temporary directory using BPXBATCH     *
+//*********************************************************************
+//*
+//REMOVE   EXEC PGM=BPXBATCH
+//*
+//STDOUT   DD SYSOUT=*
+//*
+//STDERR   DD SYSOUT=*
+//*
+//STDPARM  DD *
+SH rm -r /tmp/IZUWORKFLOW-17932912593740.328682
+/*
+//*
+//*********************************************************************"""
+    step2 = """//*********************************************************************
+//*              STEP - Create temporary directory using BPXBATCH     *
+//*********************************************************************
+//*
+//CREATE   EXEC PGM=BPXBATCH
+//*
+//STDOUT   DD SYSOUT=*
+//*
+//STDERR   DD SYSOUT=*
+//*
+//STDPARM  DD *
+SH mkdir -m 700 /tmp/IZUWORKFLOW-17932912593750.432322
+/*
+//*
+//*********************************************************************
+//*              STEP - Create script in temp directory using BPXCOPY *
+//*********************************************************************
+//*
+//UXCOPY   EXEC PGM=BPXCOPY,
+//             PARM='ELEMENT(MYSCRIPT) TYPE(TEXT) PATHMODE(0,7,0,0)'
+//*
+//SYSTSPRT DD SYSOUT=*
+//*
+//SYSIN    DD DUMMY
+//*
+//SYSUT2   DD PATH='/tmp/IZUWORKFLOW-17932912593750.432322'
+//*
+//SYSUT1   DD *,DLM=$$
+/bin/echo 'HELLO WORLD 2'
+$$
+//*
+//*********************************************************************
+//*              STEP - Execute script using BPXBATCH                 *
+//*********************************************************************
+//*
+//XBATCH   EXEC PGM=BPXBATCH
+//*
+//STDOUT   DD SYSOUT=*
+//*
+//STDERR   DD SYSOUT=*
+//*
+//STDPARM  DD *
+SH /tmp/IZUWORKFLOW-17932912593750.432322/MYSCRIPT
+/*
+//*
+//*********************************************************************
+//*              STEP - Delete temporary directory using BPXBATCH     *
+//*********************************************************************
+//*
+//REMOVE   EXEC PGM=BPXBATCH
+//*
+//STDOUT   DD SYSOUT=*
+//*
+//STDERR   DD SYSOUT=*
+//*
+//STDPARM  DD *
+SH rm -r /tmp/IZUWORKFLOW-17932912593750.432322
+/*
+//*
+//*********************************************************************"""
+
+    return make_workflow(
+        steps=[
+            {
+                "template": step1,
+                "instructions": "",
+                "maxLrecl": 1024,
+                "failedPattern": [],
+                "description": "The Box III, Gavin Belson Signature Edition: because"
+                " ordinary excellence was never enough",
+                "outputVariablesPrefix": None,
+                "variable-references": None,
+                "saveAsUnixFileSub": False,
+                "procName": "IZUFPROC",
+                "title": "Infinite Scale",
+                "jobInfo": None,
+                "timeout": 0,
+                "regionSize": 0,
+                "skills": None,
+                "isRestStep": False,
+                "output": None,
+                "outputSub": False,
+                "returnCode": None,
+                "outputSysoutDD": False,
+                "successPattern": None,
+                "state": "Unassigned",
+                "templateSub": False,
+                "owner": None,
+                "autoEnable": True,
+                "submitAs": "shell-JCL",
+                "userDefined": False,
+                "weight": "1",
+                "optional": False,
+                "steps": None,
+                "scriptParameters": None,
+                "saveAsUnixFile": None,
+                "instructionsSub": False,
+                "saveAsDatasetSub": False,
+                "isConditionStep": False,
+                "prereqStep": None,
+                "hasCalledWorkflow": False,
+                "name": "step1",
+                "stepNumber": "1",
+                "saveAsDataset": None,
+            },
+            {
+                "template": step2,
+                "instructions": "",
+                "maxLrecl": 1024,
+                "failedPattern": [],
+                "description": "Engineered for those who don't follow the"
+                " future, but define it.",
+                "outputVariablesPrefix": None,
+                "variable-references": None,
+                "saveAsUnixFileSub": False,
+                "procName": "IZUFPROC",
+                "title": "Vision Engine",
+                "jobInfo": None,
+                "timeout": 0,
+                "regionSize": 0,
+                "skills": None,
+                "isRestStep": False,
+                "output": None,
+                "outputSub": False,
+                "returnCode": None,
+                "outputSysoutDD": False,
+                "successPattern": None,
+                "state": "Unassigned",
+                "templateSub": False,
+                "owner": None,
+                "autoEnable": True,
+                "submitAs": "shell-JCL",
+                "userDefined": False,
+                "weight": "1",
+                "optional": False,
+                "steps": None,
+                "scriptParameters": None,
+                "saveAsUnixFile": None,
+                "instructionsSub": False,
+                "saveAsDatasetSub": False,
+                "isConditionStep": False,
+                "prereqStep": None,
+                "hasCalledWorkflow": False,
+                "name": "step2",
+                "stepNumber": "2",
+                "saveAsDataset": None,
+            },
+        ]
+    )
+
+
+def make_workflow_with_variables():
+    return make_workflow()
+
+
+def make_archived_worfklow_list():
+    return [
+        WorkflowArchivedListItem(
+            archivedInstanceURI="/zosmf/workflow/rest/1.0/archivedworkflows/"
+            "07775b08-2dd9-4810-abb4-26f7cb05152a",
+            workflowKey="07775b08-2dd9-4810-abb4-26f7cb05152a",
+            workflowName="myworkflow",
+        )
+    ]

zosmfrestapi/utils.py

@@ -0,0 +1,76 @@
+from dataclasses import fields, is_dataclass
+from typing import Any
+
+import pendulum
+
+
+def _parse_datetime(value: str) -> pendulum.DateTime:
+    """Parse a string and require a Pendulum ``DateTime`` result.
+
+    Args:
+        value: Date/time string accepted by :func:`pendulum.parse`.
+
+    Returns:
+        The parsed timezone-aware or naive Pendulum ``DateTime`` value.
+
+    Raises:
+        TypeError: If Pendulum parses the input as a date, time, duration, or
+            another non-``DateTime`` value.
+    """
+    result = pendulum.parse(value)
+
+    if not isinstance(result, pendulum.DateTime):
+        raise TypeError(f"Expected DateTime, got {type(result)}")
+
+    return result
+
+
+def remap(data: dict[str, Any], cls: type[Any]) -> dict[str, Any]:
+    """Translate JSON field aliases to the names used by a dataclass.
+
+    Dataclass fields with ``metadata={"json_name": ...}`` are mapped from
+    their external JSON key back to the Python field name. Other keys and
+    values are preserved.
+
+    Args:
+        data: Mapping-like dictionary received from an API response.
+        cls: Dataclass type whose field metadata defines the aliases.
+
+    Returns:
+        A new dictionary with aliased keys remapped; ``data`` is not modified.
+    """
+    aliases = {
+        f.metadata["json_name"]: f.name for f in fields(cls) if "json_name" in f.metadata
+    }
+
+    return {aliases.get(k, k): v for k, v in data.items()}
+
+
+def to_dict(obj: object) -> Any:
+    """Recursively convert dataclasses and containers to JSON payload values.
+
+    Dataclass fields are converted to dictionaries, respecting each field's
+    ``json_name`` metadata. Lists and dictionaries are converted recursively;
+    other values are returned unchanged.
+
+    Args:
+        obj: Dataclass instance, list, dictionary, or scalar value to convert.
+
+    Returns:
+        The recursively converted value. Leaves are preserved, so callers
+        should supply JSON-compatible scalar values when using the result as an
+        HTTP JSON body.
+    """
+    if is_dataclass(obj):
+        return {
+            f.metadata.get("json_name", f.name): to_dict(getattr(obj, f.name))
+            for f in fields(obj)
+        }
+
+    if isinstance(obj, list):
+        return [to_dict(item) for item in obj]
+
+    if isinstance(obj, dict):
+        return {key: to_dict(value) for key, value in obj.items()}
+
+    return obj

zosmfrestapi/zcrypto.py

@@ -0,0 +1,55 @@
+# pyright: reportMissingImports=false
+
+
+import cryptography
+from cryptography.hazmat.primitives import serialization
+
+USE_MODERN_CRYPTOGRAPHY = cryptography.__version__ != "3.3.2"
+
+
+def _extract_key_from_pkcs12(
+    p12_data: bytes,
+    password: str,
+):
+    if USE_MODERN_CRYPTOGRAPHY:
+        # Use cryptography.pkcs12.load_key_and_certificates() whenever
+        # a modern cryptography release is available.
+        #
+        from cryptography.hazmat.primitives.serialization import pkcs12
+
+        private_key, _, _ = pkcs12.load_key_and_certificates(
+            p12_data,
+            password.encode(),
+        )
+        if private_key is None:
+            raise ValueError("PKCS#12 does not contain a private key")
+
+        return private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.BestAvailableEncryption(password.encode()),
+        ).decode("utf-8")
+
+    else:  # pragma: no cover
+        # Fallback to OpenSSL.crypto.load_pkcs12() on legacy z/OS
+        # environments where only older cryptography versions are
+        # available.
+        #
+        # This fallback exists for two reasons:
+        #   - Older z/OS environments could not easily use modern
+        #     cryptography releases due to the Rust dependency.
+        #   - cryptography 3.3.2 showed extremely poor PKCS#12
+        #     performance on z/OS (~15 seconds versus <1 second
+        #     with PyOpenSSL).
+        #
+        # Note that OpenSSL.crypto.load_pkcs12() was removed from
+        # PyOpenSSL 23.3.0 (2023-10-25). This code path is therefore
+        # intended solely for legacy environments.
+        from OpenSSL import crypto
+
+        return crypto.dump_privatekey(
+            crypto.FILETYPE_PEM,
+            crypto.load_pkcs12(p12_data, password.encode()).get_privatekey(),
+            cipher="aes-256-cbc",
+            passphrase=password.encode(),
+        ).decode("utf-8")

zosmfrestapi/zcrypto_client.py

@@ -0,0 +1,68 @@
+import platform
+import secrets
+import ssl
+from tempfile import NamedTemporaryFile
+
+from zosmfrestapi.client import ZosmfClient
+from zosmfrestapi.zcrypto import _extract_key_from_pkcs12
+
+
+class ZosmfZcryptoClient(ZosmfClient):
+    """Create an HTTP client for communicating with z/OSMF using a
+    client certificate stored in a SAF key ring.
+
+    This class behaves like ``ZosmfClient`` but retrieves the client
+    certificate and private key from a SAF key ring using ``py_zcrypto``.
+    The certificate material is exported to temporary PEM files and
+    configured automatically for mutual TLS (mTLS) authentication.
+
+    Example:
+        Use a client with mTLS authentication using a certificate stored
+        in a SAF key ring:
+
+            with ZosmfClient(
+                "https://zosmf.example",
+                keyring="USERID/SAF_key_ring_name",
+                label="Certificate label",
+            ) as client:
+                systems = client.get_systems()
+
+    Additional Args:
+        keyring: SAF key ring name. The format can be either
+            ``keyring_name`` or ``USERID/keyring_name``.
+
+        label: Label of the certificate in the SAF key ring.
+
+    Notes:
+        The ``zcrypto`` optional dependency must be installed:
+
+            pip install "zosmfrestapi[zcrypto]"
+
+        All other arguments are inherited from ``ZosmfClient``.
+    """
+
+    def __init__(self, *args, **kwargs):
+        if platform.system() != "OS/390":
+            raise RuntimeError("The zcrypto backend is only available on z/OS.")
+        import py_zcrypto  # pyright: ignore[reportMissingImports]
+
+        keyring = kwargs.pop("keyring")
+        label = kwargs.pop("label")
+        zcrypto_obj = py_zcrypto.zcrypto()
+        zcrypto_obj.open_key_ring(keyring)
+        password = secrets.token_urlsafe(32)
+        with NamedTemporaryFile(mode="w") as key_pem, NamedTemporaryFile(mode="w") as cert_pem:
+
+            key = _extract_key_from_pkcs12(
+                bytes(zcrypto_obj.export_key_to_buffer(password, label)), password
+            )
+            cert = ssl.DER_cert_to_PEM_cert(bytes(zcrypto_obj.export_cert_to_buffer(label)))
+
+            key_pem.write(key)
+            cert_pem.write(cert)
+            key_pem.flush()
+            cert_pem.flush()
+
+            super().__init__(
+                *args, **kwargs, cert=(cert_pem.name, key_pem.name), key_password=password
+            )

zosmfrestapi-0.2.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: zosmfrestapi
+Version: 0.2.0
+Summary: A Python wrapper for the z/OSMF REST API
+License-Expression: MIT
+License-File: LICENSE
+Keywords: z/OSMF,IBM Z,mainframe,REST API
+Author: Oscar Curero
+Author-email: dev@curero.es
+Requires-Python: >=3.12
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Provides-Extra: zcrypto
+Requires-Dist: dacite (>=1.9.2,<2.0.0)
+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: PyPI, https://pypi.org/project/zosmfrestapi/
+Project-URL: Repository, https://sr.ht/~ocurero/zosmfrestapi/
+Description-Content-Type: text/markdown
+
+# 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/>
+* Pypi: <https://pypi.org/project/zosmfrestapi/>
+* Changelog: [CHANGELOG.md](CHANGELOG.md)
+* Contributing: [CONTRIBUTING.md](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.
+