zhmcclient - A pure Python client library for the IBM Z HMC Web Services API¶

Introduction¶

What this package provides¶

The zhmcclient package (also known as python-zhmcclient) is a client library written in pure Python that interacts with the Web Services API of the Hardware Management Console (HMC) of IBM Z or LinuxONE machines. The goal of this package is to make the HMC Web Services API easily consumable for Python programmers.

The HMC Web Services API is the access point for any external tools to manage the IBM Z or LinuxONE platform. It supports management of the lifecycle and configuration of various platform resources, such as partitions, CPU, memory, virtual switches, I/O adapters, and more.

The zhmcclient package encapsulates both protocols supported by the HMC Web Services API:

REST over HTTPS for request/response-style operations driven by the client. Most of these operations complete synchronously, but some long-running tasks complete asynchronously.
JMS (Java Messaging Services) for notifications from the HMC to the client. This is used for notification about changes in the system, or about completion of asynchronous tasks started using REST.

zhmc CLI¶

Before version 0.18.0 of the zhmcclient package, it contained the zhmc CLI. Starting with zhmcclient version 0.18.0, the zhmc CLI has been moved from this project into the new zhmccli project.

If your project uses the zhmc CLI, and you are upgrading the zhmcclient package from before 0.18.0 to 0.18.0 or later, your project will need to add the zhmccli package to its dependencies.

Supported environments¶

The zhmcclient package is supported in these environments:

Operating systems: Linux, Windows (native, and with UNIX-like environments), OS-X

Python versions: 2.7, 3.4, and higher 3.x
HMC versions: 2.11.1 and higher

The following table shows for each HMC version the supported HMC API version and the supported IBM Z machine generations. The corresponding LinuxONE machine generations are listed in the notes below the table:

HMC version	HMC API version	HMC API book	Machine generations
2.11.1	1.1 - 1.2	HMC API 2.11.1	z196 and z114
2.12.0	1.3	HMC API 2.12.0	z196 to zEC12 and z114
2.12.1	1.4 - 1.5	HMC API 2.12.1	z196 to zEC12 and z114 to zBC12
2.13.0	1.6	HMC API 2.13.0	z196 to z13 (1) and z114 to zBC12
2.13.1	1.7, 2.1 - 2.2	HMC API 2.13.1	z196 to z13 (1) and z114 to z13s (2)
2.14.0	2.20 - 2.25	HMC API 2.14.0	z196 to z14 (3) and z114 to z13s (2)
2.14.1	2.35 - 2.37	HMC API 2.14.1	z196 to z14 (3) and z114 to z14-ZR1 (4)

Notes:

Supported for z13 and LinuxONE Emperor
Supported for z13s and LinuxONE Rockhopper
Supported for z14 and LinuxONE Emperor II
Supported for z14-ZR1 and LinuxONE Rockhopper II

Installation¶

The easiest way to install the zhmcclient package is by using Pip. Pip ensures that any dependent Python packages also get installed.

With Pip, there are three options for where to install a Python package and its dependent packages:

Into a virtual Python environment. This is done by having the virtual Python environment active, and running the Pip install commands as shown in the following sections.

This option is recommended if you intend to develop programs using the zhmcclient API, because the packages you install do not interfere with other Python projects you may have.
Into the system Python, just for the current user. This is done by not having a virtual Python environment active, and by using the --user option on the Pip install commands shown in the following sections.

This option is recommended if you intend to only use the zhmc CLI, or if you are not concerned about interfering with other Python projects you may have.
Into the system Python, for all users of the system. This is done by not having a virtual Python environment active, and by using sudo on the Pip install commands shown in the following sections.

Be aware that this option will replace the content of existing Python packages, e.g. when a package version is updated. Such updated packages as well as any newly installed Python packages are not known by your operating system installer, so the knowledge of your operating system installer is now out of sync with the actual set of packages in the system Python.

Therefore, this approach is not recommended and you should apply this approach only after you have thought about how you would maintain these Python packages in the future.

Installation of latest released version¶

The following command installs the latest released version of the zhmcclient package from Pypi into the currently active Python environment:

$ pip install zhmcclient

Installation of latest development version¶

If you want to install the latest development level of the zhmcclient package instead for some reason, you can install directly from the master branch of its Git repository:

$ pip install git+https://github.com/zhmcclient/python-zhmcclient.git@master#egg=zhmcclient

Installation on a system without Internet access¶

In both cases described above, Internet access is needed to access these repositories.

If you want to install the zhmcclient package on a system that does not have Internet access, you can do this by first downloading the zhmcclient package and its dependent packages on a download system that does have Internet access, transferring these packages to the target system, and installing them on the target system from the downloaded packages:

On a system with Internet access, download the zhmcclient package and its dependent packages:

[download-system]$ mkdir packages

[download-system]$ cd packages

[download-system]$ pip download zhmcclient
Collecting zhmcclient
  Using cached https://files.pythonhosted.org/packages/c3/29/7f0acab22b27ff29453ac87c92a2cbec2b16014b0d32c36fcce1ca285be7/zhmcclient-0.19.0-py2.py3-none-any.whl
  Saved ./zhmcclient-0.19.0-py2.py3-none-any.whl
Collecting stomp.py>=4.1.15 (from zhmcclient)
. . .
Successfully downloaded zhmcclient decorator pytz stomp.py six requests docopt urllib3 certifi chardet idna

[download-system]$ ls -1
certifi-2019.11.28-py2.py3-none-any.whl
chardet-3.0.4-py2.py3-none-any.whl
decorator-4.4.1-py2.py3-none-any.whl
docopt-0.6.2.tar.gz
idna-2.8-py2.py3-none-any.whl
pytz-2019.3-py2.py3-none-any.whl
requests-2.22.0-py2.py3-none-any.whl
six-1.13.0-py2.py3-none-any.whl
stomp.py-4.1.22.tar.gz
urllib3-1.25.7-py2.py3-none-any.whl
zhmcclient-0.25.1-py2.py3-none-any.whl

Transfer all downloaded package files to the target system. Note that the package files are binary files.

The actual files you see in your directory may not be the same ones shown in this section, because new package versions may have been released meanwhile, and new versions may even have different dependent packages.

On the target system, install the zhmcclient package in a way that causes Pip not to go out to the Pypi repository on the Internet, and instead resolves its dependencies by using the packages you transferred from the download system into the current directory:

[target-system]$ ls -1
certifi-2019.11.28-py2.py3-none-any.whl
chardet-3.0.4-py2.py3-none-any.whl
decorator-4.4.1-py2.py3-none-any.whl
docopt-0.6.2.tar.gz
idna-2.8-py2.py3-none-any.whl
pytz-2019.3-py2.py3-none-any.whl
requests-2.22.0-py2.py3-none-any.whl
six-1.13.0-py2.py3-none-any.whl
stomp.py-4.1.22.tar.gz
urllib3-1.25.7-py2.py3-none-any.whl
zhmcclient-0.25.1-py2.py3-none-any.whl

[target-system]$ pip install -f . --no-index --upgrade zhmcclient-*.whl
Looking in links: .
. . .
Installing collected packages: decorator, pytz, docopt, stomp.py, six,
  urllib3, certifi, chardet, idna, requests, zhmcclient
Successfully installed certifi-2019.11.28 chardet-3.0.4 decorator-4.4.1
  docopt-0.6.2 idna-2.8 pytz-2019.3 requests-2.22.0 six-1.13.0
  stomp.py-4.1.22 urllib3-1.25.7 zhmcclient-0.25.1

Alternative installation methods and sources¶

The installation using Pip as shown in the previous sections uses the wheel distribution archive from Pypi. This is the fastest installation method and source and does not normally need to be changed.

In case you have a need to install from alternative sources, or cannot use Pip for some reason, here are some alternative installation methods and sources:

Pip install from wheel distribution archive (the normal case discussed earlier):
```
$ pip install zhmcclient
```

Pip install from source distribution archive:

# Download the source dist archive (you can also use any other means to get it):
$ pip download zhmcclient --no-binary zhmcclient

# Install from the source dist archive:
$ pip install zhmcclient-0.26.1.tar.gz  # adjust version

setup.py install from unpacked source distribution archive:

# Download the source dist archive (you can also use any other means to get it):
$ pip download zhmcclient --no-binary zhmcclient

# Install from the source dist archive:
$ tar -xf zhmcclient-0.26.1.tar.gz  # adjust version
$ python setup.py install

Pip install from repo root directory:

$ git clone https://github.com/zhmcclient/python-zhmcclient
$ cd python-zhmcclient
$ pip install .

setup.py install from repo root directory:

$ git clone https://github.com/zhmcclient/python-zhmcclient
$ cd python-zhmcclient
$ python setup.py install

Verification of the installation¶

You can verify that the zhmcclient package and its dependent packages are installed correctly by importing the package into Python:

$ python -c "import zhmcclient; print('ok')"
ok

Considerations for Windows¶

On Windows, you can run your Python scripts on native Windows or in a UNIX-like environment (such as CygWin, MSYS2, Babun, or Gow).

Running Python scripts on native Windows means they run in the Windows command processor, and use a Python installed on Windows.

Running Python scripts in a UNIX-like environment means they run in the shell of the UNIX-like environment, and use the Python of the UNIX-like environment.

The zhmcclient package can be used in any of these scenarios. It is tested on the Appveyor CI on native Windows, with CygWin and with MSYS2.

Setting up the HMC¶

Usage of the zhmcclient package requires that the HMC in question is prepared accordingly:

The Web Services API must be enabled on the HMC.
To use all functionality provided in the zhmcclient package, the HMC user ID that will be used by the zhmcclient must be authorized for the following tasks. The description of each method of the zhmcclient package will mention its specific authorization requirements.
- “Remote Restart” must be enabled on the HMC
- Use of the Web Services API
- Shutdown/Restart
- Manage Alternate HMC
- Audit and Log Management
- View Security Logs
- Manage LDAP Server Definitions
- Manage Password Rules
- Manage Users
- Manage User Patterns
- Manage User Roles
- Manage User Templates
When using CPCs in DPM mode:
- Start (a CPC in DPM mode)
- Stop (a CPC in DPM mode)
- New Partition
- Delete Partition
- Partition Details
- Start Partition
- Stop Partition
- Dump Partition
- PSW Restart (a Partition)
- Create HiperSockets Adapter
- Delete HiperSockets Adapter
- Adapter Details
- Manage Adapters
- Export WWPNs
When using CPCs in classic mode (or ensemble mode):
- Activate (an LPAR)
- Deactivate (an LPAR)
- Load (an LPAR)
- Customize/Delete Activation Profiles
- CIM Actions ExportSettingsData
(Optional) If desired, the HMC user ID that will be used by the zhmcclient can be restricted to accessing only certain resources managed by the HMC. To establish such a restriction, create a custom HMC user role, limit resource access for that role accordingly, and associate the HMC user ID with that role.

The zhmcclient needs object-access permission for the following resources:
- CPCs to be accessed
For CPCs in DPM mode:
- Partitions to be accessed
- Adapters to be accessed
For CPCs in classic mode (or ensemble mode):
- LPARs to be accessed

For details, see the HMC Operations Guide.

A step-by-step description for a similar use case can be found in chapter 11, section “Enabling the System z HMC to work the Pacemaker STONITH Agent”, in the KVM for IBM z Systems V1.1.2 System Administration book.

Examples¶

The following example code lists the machines (CPCs) managed by an HMC:

#!/usr/bin/env python

import zhmcclient
import requests.packages.urllib3
requests.packages.urllib3.disable_warnings()

# Set these variables for your environment:
hmc_host = "<IP address or hostname of the HMC>"
hmc_userid = "<userid on that HMC>"
hmc_password = "<password of that HMC userid>"

session = zhmcclient.Session(hmc_host, hmc_userid, hmc_password)
client = zhmcclient.Client(session)

cpcs = client.cpcs.list()
for cpc in cpcs:
    print(cpc)

Possible output when running the script:

Cpc(name=P000S67B, object-uri=/api/cpcs/fa1f2466-12df-311a-804c-4ed2cc1d6564, status=service-required)

For more example code, see the Python scripts in the examples directory of the Git repository, or the Tutorials section of this documentation.

Versioning¶

This documentation applies to version 0.27.1.dev1 of the zhmcclient package. You can also see that version in the top left corner of this page.

The zhmcclient package uses the rules of Semantic Versioning 2.0.0 for its version.

The package version can be accessed by programs using the zhmcclient.__version__ variable [1]:

zhmcclient._version.__version__ = '0.27.1.dev1'¶

The full version of this package including any development levels, as a string.

Possible formats for this version string are:

“M.N.P.dev1”: A not yet released version M.N.P
“M.N.P”: A released version M.N.P

This documentation may have been built from a development level of the package. You can recognize a development version of this package by the presence of a “.devD” suffix in the version string. Development versions are pre-versions of the next assumed version that is not yet released. For example, version 0.1.2.dev25 is development pre-version #25 of the next version to be released after 0.1.1. Version 1.1.2 is an assumed next version, because the actually released next version might be 0.2.0 or even 1.0.0.

[1]	For tooling reasons, that variable is shown as `zhmcclient._version.__version__` in this documentation, but it should be accessed as `zhmcclient.__version__`.

Compatibility¶

In this package, compatibility is always seen from the perspective of the user of the package. Thus, a backwards compatible new version of this package means that the user can safely upgrade to that new version without encountering compatibility issues.

This package uses the rules of Semantic Versioning 2.0.0 for compatibility between package versions, and for deprecations.

The public API of this package that is subject to the semantic versioning rules (and specificically to its compatibility rules) is the API described in this documentation.

Violations of these compatibility rules are described in section Change log.

Deprecations¶

Deprecated functionality is marked accordingly in this documentation and in the Change log, and is made visible at runtime by issuing Python warnings of type exceptions.DeprecationWarning (see warnings for details).

Since Python 2.7, exceptions.DeprecationWarning warnings are suppressed by default. They can be shown for example in any of these ways:

by specifying the Python command line option:

-W default
by invoking Python with the environment variable:

PYTHONWARNINGS=default

by issuing in your Python program:

warnings.filterwarnings(action='default', category=DeprecationWarning)

It is recommended that users of this package run their test code with exceptions.DeprecationWarning warnings being shown, so they become aware of any use of deprecated functionality.

It is even possible to raise an exception instead of issuing a warning message upon the use of deprecated functionality, by setting the action to 'error' instead of 'default'.

Reporting issues¶

If you encounter any problem with this package, or if you have questions of any kind related to this package (even when they are not about a problem), please open an issue in the zhmcclient issue tracker.

It is helpful if you include debug information in the issue, that can be printed as in the following example:

$ python -m zhmcclient.debuginfo
Operating system: Darwin 18.7.0 on x86_64
Python implementation: CPython 3.8.2 (64 bit, wide unicode)
Python version: 3.8.2
zhmcclient version: 0.27.0.dev1

License¶

This package is licensed under the Apache 2.0 License.

Tutorials¶

This section contains tutorials explaining the use of the zhmcclient package.

Each tutorial is a Jupyter Notebook (formerly known as IPython Notebook). In order to view a tutorial, just click on a link in the table below. This will show the tutorial in the online Jupyter Notebook Viewer.

Tutorial	Short description
01_notebook_basics.ipynb	1: Basics about Jupyter notebooks
02_connections.ipynb	2: Connecting to an HMC
03_datamodel.ipynb	3: Basics about working with HMC resources
04_error_handling.ipynb	4: Error handling

Executing code in the tutorials¶

In order to execute and also modify the code in the tutorials, Jupyter Notebook needs to be installed in a Python environment, preferrably in a virtual Python environment, and you need to have the notebook files locally.

There are two options on how to do that:

Set up the development environment for zhmcclient (see Setting up the development environment). This will provide you with an installation of Jupyter Notebook and with all the tutorial notebooks in directory docs/notebooks.

To start Jupyter Notebook with all tutorial notebooks, issue from the repo work directory:
```
$ jupyter notebook --notebook-dir=docs/notebooks
```
If you intend to keep your changes locally, you may want to work on a copy of the docs/notebooks directory that is outside of the repo work directory.
Install Jupyter Notebook and the zhmcclient package into a Python environment (preferrably virtual):
```
$ pip install jupyter zhmcclient
```
and download the tutorial notebooks using the download button in the Jupyter Notebook Viewer (following the links in the table above).

To start Jupyter Notebook with the downloaded tutorial notebooks, issue:
```
$ jupyter notebook --notebook-dir={your-notebook-dir}
```

Concepts¶

This section presents some concepts that are helpful to understand when using the zhmcclient package.

Topology¶

The following figure shows the topology of Python applications using the zhmcclient package with an HMC and the CPCs managed by that HMC:

+----------------------------------------+  +--------------------+
|                  Node 1                |  |       Node 2       |
|                                        |  |                    |
|  +----------------+  +--------------+  |  |  +--------------+  |
|  |  Python app 1  |  | Python app 2 |  |  |  | Python app 3 |  |
|  +----------------+  +--------------+  |  |  +--------------+  |
|  |   zhmcclient   |  |  zhmcclient  |  |  |  |  zhmcclient  |  |
|  | S      S   NR  |  |    S  NR     |  |  |  |     S        |  |
|  +-v------v---^---+  +----v--^------+  |  |  +-----v--------+  |
+----|------|---|-----------|--|---------+  +--------|-----------+
     |      |   |           |  |                     |
 REST|  REST|   |JMS    REST|  |JMS              REST|
     |      |   |           |  |                     |
+----v------v---^-----------v--^---------------------v-----------+
|                                                                |
|                             HMC                                |
|                                                                |
|                      ... resources ...                         |
|                                                                |
+-------------+------------------------------------+-------------+
              |                                    |
              |                                    |
+-------------+------------+         +-------------+-------------+
|                          |         |                           |
|           CPC 1          |         |          CPC 2            |
|                          |         |                           |
|     ... resources ...    |         |    ... resources ...      |
|                          |         |                           |
+--------------------------+         +---------------------------+

The Python applications can be for example the zhmc CLI (provided in the zhmccli project), your own Python scripts using the zhmcclient API, or long-lived services that perform some function. In any case, each Python application in the figure runs in the runtime of exactly one Python process.

In that Python process, exactly one instance of the zhmcclient Python package is loaded. Performing HMC operations on a particular HMC requires a Session object (shown as S in the figure). Receiving notifications from a particular HMC requires a NotificationReceiver object (shown as NR in the figure).

For example, Python app 1 in the figure has two sessions and one notification receiver. For simplicity, the two sessions go to the same HMC in this example, but they could also go to different HMCs. Similarly, a Python app could receive notifications from more than one HMC.

Multi-threading considerations¶

The zhmcclient package supports the use of multi-threading in Python processes, but each Session, Client, and NotificationReceiver object can be used by only one thread at a time. However, this is not verified or enforced by the zhmcclient package, so ensuring this is a responsibility of the user of the zhmcclient package.

If your Python app is multi-threaded, it is recommended that each thread with a need to perform HMC operations has its own Session object and its own Client object, and that each thread with a need to receive HMC notifications has its own NotificationReceiver object. These different objects can very well target the same HMC.

Resource model concepts¶

The zhmcclient package provides a resource model at its API that represents exactly the resource model described in the HMC API book. Some of these resources are located on the HMC (for example HMC users), and some on the CPCs managed by the HMC (for example the CPC itself, or partitions on the CPC).

The entry points for a user of the zhmcclient API are two objects that need to be created by the user:

a Session object. A session object represents a REST session with exactly one HMC and handles all aspects of the session, such as the credentials for automatic logon and re-logon, the retry and timeout configuration, or the logging configuration.
a Client object. A client object is the top of the resource tree and is initialized with a Session object (if connecting to a real HMC) or with a FakedSession object (in unit tests that work against a mocked HMC). Despite its classname, a client object really represents the HMC (real or mocked).

A session that is logged on is always in the context of the HMC userid that was used for the session. That HMC userid determines what the Python application using that session object can see and what it is allowed to do. See Setting up the HMC for a list of access rights that are needed in order to see all resources and to perform all tasks supported by the zhmcclient package. The HMC API book details for each HMC operation which access rights are needed in order to perform the operation.

A client object is the top of the resource tree exposed by an HMC. Resources located on the HMC (e.g. HMC userids) are direct or indirect children of the client object. The CPCs managed by the HMC are direct children of the client object, and the resources located on each CPC are direct or indirect children of the Cpc object representing the CPC. There is a strict parent-child relationship in the resource model, so that the resource model is a strict tree without any shared children.

For each actual managed resource on the HMC or its managed CPCs, the zhmcclient package may provide more than one Python object representing that resource. For example, the child resources of a resource can be listed by using the list() method. Each time that method is invoked, it returns a new list of Python objects representing the state of the child resources at the time the call was made.

This is an important principle in the design of the zhmcclient API: Whenever a Python object representing a resource (i.e. objects of subclasses of BaseResource) is returned to the caller of the zhmcclient API, its state represents the state of the actual managed resource at the time the call was made, but the state of the Python resource object is not automatically being updated when the state of the actual managed resource changes.

As a consequence, there are multiple Python resource objects for the same actual managed resource.

All Python resource objects provided by the zhmcclient package can be asked to update their state to match the current state of the actual managed resource, via the pull_full_properties() method. Alternatively, a new Python resource object with the current state of the actual managed resource can be retrieved using the find() method using filters on name or object ID so that only the desired single resource is returned. See Filtering for details.

With the exception of the Client object, Python resource objects are never created by the user of the zhmcclient package. Instead, they are always returned back to the user. Most of the time, resource objects are returned from methods such as list(), find() or findall(). They are methods on a manager object that handles the set of child resources of a particular type within a parent resource. For example, the Client object has a cpcs instance attribute of type CpcManager which handles the CPCs managed by the HMC. Invoking list() returns the CPCs managed by the HMC as Cpc resource objects. Each Cpc object has again instance attributes for its child resources, for example its partitions instance attribute of type PartitionManager handles the set of partitions of that CPC (but not the partitions of other CPCs managed by this HMC).

See Reference: Resources for a description of the resource model supported by the zhmcclient package.

Error handling¶

Errors are returned to the user by raising exceptions. All exception classes defined in the zhmcclient package are derived from zhmcclient.Error.

Exceptions may be raised that are not derived from Error. In all cases where this is possible, this is very likely caused by programming errors of the user (incorrect type passed in, invalid value passed in, etc.).

Some HTTP status code / reason code combinations returned from the HMC are silently handled by the zhmcclient package:

GET, POST, or DELETE with status 403 and reason 5: This combination means that the HMC session token has expired. It is handled by re-logon, creating a new session token, and retrying the original HMC operation.
POST with status 202: This status code means that the operation is being performed asynchronously. There are two cases for that:
- If there is a response body, an asynchronous job has been started on the HMC that performs the actual operation. If wait_for_completion is True in the method that invoked the HMC operation, the method waits for completion of the job (via polling with GET on the job URI), gathering success or failure from the job results. In case of success, the job results are returned from the method. In case of failure, an HTTPError is raised based upon the error information in the job results.
- If there is no response body, the operation is performed asynchronously on the HMC, but there is no job resource that can be used to poll for completion status. This is used only for operations such as restarting the HMC.

The other HTTP status / reason code combinations are forwarded to the user by means of raising HTTPError. That exception class is modeled after the error information described in section “Error response bodies” of the HMC API book.

The exception classes defined in the zhmcclient package are described in section Exceptions.

Filtering¶

The resource lookup methods on manager objects support the concept of resource filtering. This concept allows narrowing the set of returned resources based upon the matching of filter arguments.

The methods that support resource filtering, are:

A resource is included in the result only if it matches all filter arguments (i.e. this is a logical AND between the filter arguments).

A filter argument specifies a property name and a match value.

Any resource property may be specified in a filter argument. The zhmcclient implementation handles them in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.

For the findall() and find() methods, an additional optimization is implemented: If the “name” property is specified as the only filter argument, an optimized lookup is performed that uses a name-to-URI cache in this manager object.

The match value specifies how the corresponding resource property matches:

For resource properties of type String (as per the resource’s data model in the HMC API), the match value is interpreted as a regular expression that must match the actual resource property value. The regular expression syntax used is the same as that used by the Java programming language, as specified for the java.util.regex.Pattern class (see http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html).
For resource properties of type String Enum, the match value is interpreted as an exact string that must be equal to the actual resource property value.
For resource properties of other types, the match value is interpreted as an exact value that must be equal to the actual resource property value.
If the match value is a list or a tuple, a resource matches if any item in the list or tuple matches (i.e. this is a logical OR between the list items).

If a property that is specified in filter arguments does not exist on all resources that are subject to be searched, those resources that do not have the property are treated as non-matching. An example for this situation is the “card-location” property of the Adapter resource which does not exist for Hipersocket adapters.

Examples:

This example uses the findall() method to return those OSA adapters in cage ‘1234’ of a given CPC, whose state is ‘stand-by’, ‘reserved’, or ‘unknown’:
```
filter_args = {
    'adapter-family': 'osa',
    'card-location': '1234-.*',
    'state': ['stand-by', 'reserved', 'unknown'],
}
osa_adapters = cpc.adapters.findall(**filter_args)
```
The returned resource objects will have only a minimal set of properties.
This example uses the list() method to return the same set of OSA adapters as the previous example, but the returned resource objects have the full set of properties:
```
osa_adapters = cpc.adapters.list(full_properties=True,
                                 filter_args=filter_args)
```
This example uses the find() method to return the adapter with a given adapter name:
```
adapter1 = cpc.adapters.find(name='OSA-1')
```
The returned resource object will have only a minimal set of properties.
This example uses the find() method to return the adapter with a given object ID:
```
oid = '12345-abc...-def-67890'
adapter1 = cpc.adapters.find(**{'object-id':oid})
```
The returned resource object will have only a minimal set of properties.

Reference: General features¶

Session¶

Session class: A session to the HMC, optionally in context of an HMC user.

class zhmcclient.Session(host, userid=None, password=None, session_id=None, get_password=None, retry_timeout_config=None, port=6794)[source]¶

A session to the HMC, optionally in context of an HMC user.

The session supports operations that require to be authenticated, as well as operations that don’t (e.g. obtaining the API version).

The session can keep statistics about the elapsed time for issuing HTTP requests against the HMC API. Instance variable time_stats_keeper is used to enable/disable the measurements, and to print the statistics.

Creating a session object will not immediately cause a logon to be attempted; the logon is deferred until needed.

There are several alternatives for specifying the authentication related parameters:

userid/password only: The session is initially in a logged-off state and subsequent operations that require logon will use the specified userid and password to automatically log on. The returned session-id will be stored in this session object. Subsequent operations that require logon will use that session-id. Once the HMC expires that session-id, subsequent operations that require logon will cause a re-logon with the specified userid and password.
userid/password and session_id: The specified session-id will be stored in this session object, so that the session is initially in a logged-on state. Subsequent operations that require logon will use that session-id. Once the HMC expires that session-id, subsequent operations that require logon will cause a re-logon with the specified userid/password.
session_id only: The specified session-id will be stored in this session object, so that the session is initially in a logged-on state. Subsequent operations that require logon will use the stored session-id. Once the HMC expires the session-id, subsequent operations that require logon will cause an ServerAuthError to be raised (because userid/password have not been specified, so an automatic re-logon is not possible).
Neither userid/password nor session_id: Only operations that do not require logon, are possible.

Parameters:

host (string) – HMC host. For valid formats, see the host property. Must not be None.
userid (string) – Userid of the HMC user to be used, or None.
password (string) – Password of the HMC user to be used, if userid was specified.
session_id (string) – Session-id to be used for this session, or None.
get_password (callable) –
A password retrieval function, or None.

If provided, this function will be called if a password is needed but not provided. This mechanism can be used for example by command line interfaces for prompting for the password.

The password retrieval function must follow the interface defined in get_password_interface().
retry_timeout_config (RetryTimeoutConfig) –
The retry/timeout configuration for this session for use by any of its HMC operations, overriding any defaults.

None for an attribute in that configuration object means that the default value will be used for that attribute.

None for the entire retry_timeout_config parameter means that a default configuration will be used with the default values for all of its attributes.

See Constants for the default values.
port (integer) – HMC TCP port. Defaults to DEFAULT_HMC_PORT. For details, see the port property.

Methods

`delete`	Perform the HTTP DELETE method against the resource identified by a URI.
`get`	Perform the HTTP GET method against the resource identified by a URI.
`get_notification_topics`	The ‘Get Notification Topics’ operation returns a structure that describes the JMS notification topics associated with the API session.
`is_logon`	Return a boolean indicating whether the session is currently logged on to the HMC.
`logoff`	Make sure the session is logged off from the HMC.
`logon`	Make sure the session is logged on to the HMC.
`post`	Perform the HTTP POST method against the resource identified by a URI, using a provided request body.

Attributes

`base_url`	Base URL of the HMC in this session.
`default_rt_config`
`get_password`	The password retrieval function, or None.
`headers`	HTTP headers to be used in each request.
`host`	HMC host, in one of the following formats:
`port`	HMC TCP port to be used.
`retry_timeout_config`	The effective retry/timeout configuration for this session for use by any of its HMC operations, taking into account the defaults and the session-specific overrides.
`session`	`requests.Session` object for this session.
`session_id`	Session ID for this session, returned by the HMC.
`time_stats_keeper`	The time statistics keeper (for a usage example, see section Time Statistics).
`userid`	Userid of the HMC user to be used.

Details

__repr__()[source]¶: Return a string with the state of this session, for debug purposes.

host¶

HMC host, in one of the following formats:

a short or fully qualified DNS hostname
a literal (= dotted) IPv4 address
a literal IPv6 address, formatted as defined in RFC3986 with the extensions for zone identifiers as defined in RFC6874, supporting - (minus) for the delimiter before the zone ID string, as an additional choice to %25

Type:	string

port¶

HMC TCP port to be used.

Type:	integer

userid¶

Userid of the HMC user to be used.

If None, only operations that do not require authentication, can be performed.

Type:	string

get_password¶

The password retrieval function, or None.

The password retrieval function must follow the interface defined in get_password_interface().

retry_timeout_config¶

The effective retry/timeout configuration for this session for use by any of its HMC operations, taking into account the defaults and the session-specific overrides.

Type:	`RetryTimeoutConfig`

base_url¶

Base URL of the HMC in this session.

Example:

https://myhmc.acme.com:6794

Type:	string

headers¶

HTTP headers to be used in each request.

Initially, this is the following set of headers:

Content-type: application/json
Accept: */*

When the session is logged on to the HMC, the session token is added to these headers:

X-API-Session: ...

Type:	header dict

time_stats_keeper¶: The time statistics keeper (for a usage example, see section Time Statistics).

session_id¶

Session ID for this session, returned by the HMC.

Type:	string

session¶

requests.Session object for this session.

Type:	string

logon(verify=False)[source]¶

Make sure the session is logged on to the HMC.

By default, this method checks whether there is a session-id set and considers that sufficient for determining that the session is logged on. The verify parameter can be used to verify the validity of a session-id that is already set, by issuing a dummy operation (“Get Console Properties”) to the HMC.

After successful logon to the HMC, the following is stored in this session object for reuse in subsequent operations:

the HMC session-id, in order to avoid extra userid authentications,
a requests.Session object, in order to enable connection pooling. Connection pooling avoids repetitive SSL/TLS handshakes.

Parameters:	verify (bool) – If a session-id is already set, verify its validity.
Raises:	`HTTPError` `ParseError` `ClientAuthError` `ServerAuthError` `ConnectionError`

logoff(verify=False)[source]¶

Make sure the session is logged off from the HMC.

After successful logoff, the HMC session-id and requests.Session object stored in this object are reset.

Parameters:	verify (bool) – If a session-id is already set, verify its validity.
Raises:	`HTTPError` `ParseError` `ServerAuthError` `ConnectionError`

is_logon(verify=False)[source]¶

Return a boolean indicating whether the session is currently logged on to the HMC.

By default, this method checks whether there is a session-id set and considers that sufficient for determining that the session is logged on. The verify parameter can be used to verify the validity of a session-id that is already set, by issuing a dummy operation (“Get Console Properties”) to the HMC.

Parameters:	verify (bool) – If a session-id is already set, verify its validity.

get(uri, logon_required=True)[source]¶

Perform the HTTP GET method against the resource identified by a URI.

A set of standard HTTP headers is automatically part of the request.

If the HMC session token is expired, this method re-logs on and retries the operation.

Parameters:	uri (string) – Relative URI path of the resource, e.g. “/api/session”. This URI is relative to the base URL of the session (see the `base_url` property). Must not be None. logon_required (bool) – Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, the API version retrieval operation does not require that.
Returns:	json object with the operation result.
Raises:	`HTTPError` `ParseError` `ClientAuthError` `ServerAuthError` `ConnectionError`

post(uri, body=None, logon_required=True, wait_for_completion=False, operation_timeout=None)[source]¶

Perform the HTTP POST method against the resource identified by a URI, using a provided request body.

A set of standard HTTP headers is automatically part of the request.

HMC operations using HTTP POST are either synchronous or asynchronous. Asynchronous operations return the URI of an asynchronously executing job that can be queried for status and result.

Examples for synchronous operations:

With no result: “Logon”, “Update CPC Properties”
With a result: “Create Partition”

Examples for asynchronous operations:

With no result: “Start Partition”

The wait_for_completion parameter of this method can be used to deal with asynchronous HMC operations in a synchronous way.

If executing the operation reveals that the HMC session token is expired, this method re-logs on and retries the operation.

The timeout and retry

Parameters:

uri (string) – Relative URI path of the resource, e.g. “/api/session”. This URI is relative to the base URL of the session (see the base_url property). Must not be None.
body (json object) – JSON object to be used as the HTTP request body (payload). None means the same as an empty dictionary, namely that no HTTP body is included in the request.
logon_required (bool) – Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, the “Logon” operation does not require that.
wait_for_completion (bool) –
Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation.

A value of True will cause an additional entry in the time statistics to be created that represents the entire asynchronous operation including the waiting for its completion. That time statistics entry will have a URI that is the targeted URI, appended with “+completion”.

For synchronous HMC operations, this parameter has no effect on the operation execution or on the return value of this method, but it should still be set (or defaulted) to False in order to avoid the additional entry in the time statistics.
operation_timeout (number) –
Timeout in seconds, when waiting for completion of an asynchronous operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used.

For wait_for_completion=True, a OperationTimeout is raised when the timeout expires.

For wait_for_completion=False, this parameter has no effect.

Returns:

A json object or None or a Job object, as follows:

For synchronous HMC operations, and for asynchronous HMC operations with wait_for_completion=True:

If this method returns, the HMC operation has completed successfully (otherwise, an exception is raised). For asynchronous HMC operations, the associated job has been deleted.

The return value is the result of the HMC operation as a json object, or None if the operation has no result. See the section in the HMC API book about the specific HMC operation for a description of the members of the returned JSON object.
For asynchronous HMC operations with wait_for_completion=False:

If this method returns, the asynchronous execution of the HMC operation has been started successfully as a job on the HMC (if the operation could not be started, an exception is raised).

The return value is a Job object representing the job on the HMC.

Raises:

HTTPError
ParseError
ClientAuthError
ServerAuthError
ConnectionError
OperationTimeout – The timeout expired while waiting for completion of the asynchronous operation.
TypeError – Body has invalid type.

delete(uri, logon_required=True)[source]¶

Perform the HTTP DELETE method against the resource identified by a URI.

A set of standard HTTP headers is automatically part of the request.

If the HMC session token is expired, this method re-logs on and retries the operation.

Parameters:	uri (string) – Relative URI path of the resource, e.g. “/api/session/{session-id}”. This URI is relative to the base URL of the session (see the `base_url` property). Must not be None. logon_required (bool) – Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, for the logoff operation, it does not make sense to first log on.
Raises:	`HTTPError` `ParseError` `ClientAuthError` `ServerAuthError` `ConnectionError`

get_notification_topics()[source]¶

The ‘Get Notification Topics’ operation returns a structure that describes the JMS notification topics associated with the API session.

Returns:

A list with one item for each notification topic. Each item is a dictionary with the following keys:

"topic-type" (string): Topic type, e.g. “job-notification”.
"topic-name" (string): Topic name; can be used for subscriptions.
"object-uri" (string): When topic-type is “os-message-notification”, this item is the canonical URI path of the Partition for which this topic exists. This field does not exist for the other topic types.
"include-refresh-messages" (bool): When the topic-type is “os-message-notification”, this item indicates whether refresh operating system messages will be sent on this topic.

class zhmcclient.Job(session, uri, op_method, op_uri)[source]¶

A job on the HMC that performs an asynchronous HMC operation.

This class supports checking the job for completion, and waiting for job completion.

Parameters:

session (Session) – Session with the HMC. Must not be None.
uri (string) –
Canonical URI of the job on the HMC. Must not be None.

Example: "/api/jobs/{job-id}"
op_method (string) –
Name of the HTTP method of the operation that is executing asynchronously on the HMC. Must not be None.

Example: "POST"
op_uri (string) –
Canonical URI of the operation that is executing asynchronously on the HMC. Must not be None.

Example: "/api/partitions/{partition-id}/stop"

Methods

`check_for_completion`	Check once for completion of the job and return completion status and result if it has completed.
`wait_for_completion`	Wait for completion of the job, then delete the job on the HMC and return the result of the original asynchronous HMC operation, if it completed successfully.

Attributes

`op_method`	Name of the HTTP method of the operation that is executing asynchronously on the HMC.
`op_uri`	Canonical URI of the operation that is executing asynchronously on the HMC.
`session`	Session with the HMC.
`uri`	Canonical URI of the job on the HMC.

Details

session¶

Session with the HMC.

Type:	`Session`

uri¶

Canonical URI of the job on the HMC.

Example: "/api/jobs/{job-id}"

Type:	string

op_method¶

Name of the HTTP method of the operation that is executing asynchronously on the HMC.

Example: "POST"

Type:	string

op_uri¶

Canonical URI of the operation that is executing asynchronously on the HMC.

Example: "/api/partitions/{partition-id}/stop"

Type:	string

check_for_completion()[source]¶

Check once for completion of the job and return completion status and result if it has completed.

If the job completed in error, an HTTPError exception is raised.

Returns:

A tuple (status, result) with:

status (string): Completion status of the job, as returned in the status field of the response body of the “Query Job Status” HMC operation, as follows:
- "complete": Job completed (successfully).
- any other value: Job is not yet complete.
result (json object or None): None for incomplete jobs. For completed jobs, the result of the original asynchronous operation that was performed by the job, from the job-results field of the response body of the “Query Job Status” HMC operation. That result is a json object as described for the asynchronous operation, or None if the operation has no result.

Raises:

HTTPError – The job completed in error, or the job status cannot be retrieved, or the job cannot be deleted.
ParseError
ClientAuthError
ServerAuthError
ConnectionError

wait_for_completion(operation_timeout=None)[source]¶

Wait for completion of the job, then delete the job on the HMC and return the result of the original asynchronous HMC operation, if it completed successfully.

If the job completed in error, an HTTPError exception is raised.

Parameters:	operation_timeout (number) – Timeout in seconds, when waiting for completion of the job. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires, a `OperationTimeout` is raised. This method gives completion of the job priority over strictly achieving the timeout. This may cause a slightly longer duration of the method than prescribed by the timeout.
Returns:	The result of the original asynchronous operation that was performed by the job, from the `job-results` field of the response body of the “Query Job Status” HMC operation. That result is a json object as described for the asynchronous operation, or None if the operation has no result.
Return type:	json object or None
Raises:	`HTTPError` – The job completed in error, or the job status cannot be retrieved, or the job cannot be deleted. `ParseError` `ClientAuthError` `ServerAuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for job completion.

zhmcclient.get_password_interface(host, userid)[source]¶

Interface to the password retrieval function that is invoked by Session if no password is provided.

Parameters:	host (string) – Hostname or IP address of the HMC userid (string) – Userid on the HMC
Returns:	Password of the userid on the HMC
Return type:	string

Retry / timeout configuration¶

class zhmcclient.RetryTimeoutConfig(connect_timeout=None, connect_retries=None, read_timeout=None, read_retries=None, max_redirects=None, operation_timeout=None, status_timeout=None, name_uri_cache_timetolive=None)[source]¶

A configuration setting that specifies verious retry counts and timeout durations.

For all parameters, None means that this object does not specify a value for the parameter, and that a default value should be used (see Constants).

All parameters are available as instance attributes.

Parameters:

connect_timeout (number) – Connect timeout in seconds. This timeout applies to making a connection at the socket level. The same socket connection is used for sending an HTTP request to the HMC and for receiving its HTTP response. The special value 0 means that no timeout is set.
connect_retries (integer) – Number of retries (after the initial attempt) for connection-related issues. These retries are performed for failed DNS lookups, failed socket connections, and socket connection timeouts.
read_timeout (number) – Read timeout in seconds. This timeout applies to reading at the socket level, when receiving an HTTP response. The special value 0 means that no timeout is set.
read_retries (integer) – Number of retries (after the initial attempt) for read-related issues. These retries are performed for failed socket reads and socket read timeouts. A retry consists of resending the original HTTP request. The zhmcclient restricts these retries to just the HTTP GET method. For other HTTP methods, no retry will be performed.
max_redirects (integer) – Maximum number of HTTP redirects.
operation_timeout (number) – Asynchronous operation timeout in seconds. This timeout applies when waiting for the completion of asynchronous HMC operations. The special value 0 means that no timeout is set.
status_timeout (number) – Resource status timeout in seconds. This timeout applies when waiting for the transition of the status of a resource to a desired status. The special value 0 means that no timeout is set.
name_uri_cache_timetolive (number) – Time to the next automatic invalidation of the Name-URI cache of manager objects, in seconds since the last invalidation. The special value 0 means that no Name-URI cache is maintained (i.e. the caching is disabled).

Methods

override_with Return a new configuration object that represents the configuration from this configuration object acting as a default, and the specified configuration object overriding that default.

Attributes

Details

override_with(override_config)[source]¶

Return a new configuration object that represents the configuration from this configuration object acting as a default, and the specified configuration object overriding that default.

Parameters:	override_config (`RetryTimeoutConfig`) – The configuration object overriding the defaults defined in this configuration object.
Returns:	A new configuration object representing this configuration object, overridden by the specified configuration object.
Return type:	`RetryTimeoutConfig`

Client¶

Client class: A client to an HMC.

class zhmcclient.Client(session)[source]¶

A client to an HMC.

This is the main class for users of this package.

Parameters:	session (`Session`) – Session with the HMC.

Methods

`get_inventory`	Returns a JSON object with the requested resources and their properties, that are managed by the HMC.
`query_api_version`	The Query API Version operation returns information about the level of Web Services API supported by the HMC.
`version_info`	Returns API version information for the HMC.
`wait_for_available`	Wait for the Console (HMC) this client is connected to, to become available.

Attributes

`consoles`	Manager object for the (one) Console representing the HMC this client is connected to.
`cpcs`	Manager object for the CPCs in scope of this client.
`metrics_contexts`	Manager object for the Metrics Contexts in scope of this client (i.e.
`session`	Session with the HMC.

Details

session¶

Session with the HMC.

Type:	`Session`

cpcs¶

Manager object for the CPCs in scope of this client. This includes managed and unmanaged CPCs.

Type:	`CpcManager`

consoles¶

Manager object for the (one) Console representing the HMC this client is connected to.

Type:	`ConsoleManager`

metrics_contexts¶

Manager object for the Metrics Contexts in scope of this client (i.e. in scope of its HMC).

Type:	`MetricsContextManager`

version_info()[source]¶

Returns API version information for the HMC.

This operation does not require authentication.

Returns:	The HMC API version supported by the HMC.
Return type:	HMC API version
Raises:	`HTTPError` `ParseError` `ConnectionError`

query_api_version()[source]¶

The Query API Version operation returns information about the level of Web Services API supported by the HMC.

This operation does not require authentication.

Returns:	A JSON object with members `api-major-version`, `api-minor-version`, `hmc-version` and `hmc-name`. For details about these properties, see section ‘Response body contents’ in section ‘Query API Version’ in the HMC API book.
Return type:	json object
Raises:	`HTTPError` `ParseError` `ConnectionError`

get_inventory(resources)[source]¶

Returns a JSON object with the requested resources and their properties, that are managed by the HMC.

This method performs the ‘Get Inventory’ HMC operation.

Parameters:

resources (iterable of string) –

Resource classes and/or resource classifiers specifying the types of resources that should be included in the result. For valid values, see the ‘Get Inventory’ operation in the HMC API book.

Element resources of the specified resource types are automatically included as children (for example, requesting ‘partition’ includes all of its ‘hba’, ‘nic’ and ‘virtual-function’ element resources).

Must not be None.

Returns: The resources with their properties, for the requested resource classes and resource classifiers.

Return type: JSON object

Example

resource_classes = [‘partition’, ‘adapter’] result_dict = client.get_inventory(resource_classes)

Raises:	`HTTPError` `ParseError` `ConnectionError`

wait_for_available(operation_timeout=None)[source]¶

Wait for the Console (HMC) this client is connected to, to become available. The Console is considered available if the query_api_version() method succeeds.

If the Console does not become available within the operation timeout, an OperationTimeout exception is raised.

Parameters:

operation_timeout (number) –

Timeout in seconds, when waiting for the Console to become available. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used.

If the timeout expires, a OperationTimeout is raised.

Raises: OperationTimeout – The timeout expired while waiting for the Console to become available.

Time Statistics¶

The TimeStatsKeeper class allows measuring the elapsed time of accordingly instrumented code and keeps a statistics of these times.

The Session class uses this class for keeping statistics about the time to issue HTTP requests against the HMC API (see its time_stats_keeper property).

The TimeStats class is a helper class that contains the actual measurement data for all invocations of a particular HTTP request. Its objects are under control of the TimeStatsKeeper class.

Example:

import zhmcclient

session = zhmcclient.Session(hmc, userid, password)
session.time_stats_keeper.enable()

# Some operations that are being measured
client = zhmcclient.Client(session)
cpcs = client.cpcs.list()

print(session.time_stats_keeper)

class zhmcclient.TimeStatsKeeper[source]¶

Statistics keeper for elapsed times.

The statistics keeper can hold multiple time statistics (see TimeStats), that are identified by a name.

The statistics keeper can be in a state of enabled or disabled. If enabled, it accumulates the elapsed times between subsequent calls to the begin() and end() methods of class TimeStats. If disabled, calls to these methods do not accumulate any time.

Initially, the statistics keeper is disabled.

Methods

`disable`	Disable the statistics keeper.
`enable`	Enable the statistics keeper.
`get_stats`	Get the time statistics for a name.
`snapshot`	Return a snapshot of the time statistics of this keeper.

Attributes

enabled Indicates whether the statistics keeper is enabled.

Details

enabled¶: Indicates whether the statistics keeper is enabled.

enable()[source]¶: Enable the statistics keeper.

disable()[source]¶: Disable the statistics keeper.

get_stats(name)[source]¶

Get the time statistics for a name. If a time statistics for that name does not exist yet, create one.

Parameters:	name (string) – Name of the time statistics.
Returns:	The time statistics for the specified name. If the statistics keeper is disabled, a dummy time statistics object is returned, in order to save resources.
Return type:	TimeStats

snapshot()[source]¶

Return a snapshot of the time statistics of this keeper.

The snapshot represents the statistics data at the time this method is called, and remains unchanged even if the statistics of this keeper continues to be updated.

Returns:	A dictionary of the time statistics by operation, where: key (string): Name of the operation value (`TimeStats`): Time statistics for the operation
Return type:	dict

__str__()[source]¶

Return a human readable string with the time statistics for this keeper. The operations are sorted by decreasing average time.

Example result, if keeper is enabled:

Time statistics (times in seconds):
Count  Average  Minimum  Maximum  Operation name
    1  0.024    0.024    0.024    get /api/cpcs
    1  0.009    0.009    0.009    get /api/version

class zhmcclient.TimeStats(keeper, name)[source]¶

Elapsed time statistics for all invocations of a particular named operation.

All invocations of the operation will be accumulated into the statistics data kept by an object of this class.

Objects of this class don’t need to (and in fact, are not supposed to) be created by the user. Instead, the zhmcclient.TimeStatsKeeper.get_stats() method should be used to create objects of this class.

Parameters:	keeper (TimeStatsKeeper) – The statistics keeper that holds this time statistics. name (string) – Name of the operation.

Methods

`begin`	This method must be called before invoking the operation.
`end`	This method must be called after the operation returns.
`reset`	Reset the time statistics data for the operation.

Attributes

`avg_time`	The average elapsed time for invoking the operation, in seconds.
`count`	The number of invocations of the operation.
`keeper`	The time statistics keeper holding this time statistics.
`max_time`	The maximum elapsed time for invoking the operation, in seconds.
`min_time`	The minimum elapsed time for invoking the operation, in seconds.
`name`	Name of the operation this time statistics has data for.

Details

name¶

Name of the operation this time statistics has data for.

This name is used by the TimeStatsKeeper object holding this time statistics as a key.

Type:	string

keeper¶

The time statistics keeper holding this time statistics.

Type:	`TimeStatsKeeper`

count¶

The number of invocations of the operation.

Type:	integer

avg_time¶

The average elapsed time for invoking the operation, in seconds.

Type:	float

min_time¶

The minimum elapsed time for invoking the operation, in seconds.

Type:	float

max_time¶

The maximum elapsed time for invoking the operation, in seconds.

Type:	float

reset()[source]¶: Reset the time statistics data for the operation.

begin()[source]¶

This method must be called before invoking the operation. Note that this method is not to be invoked by the user; it is invoked by the implementation of the Session class.

If the statistics keeper holding this time statistics is enabled, this method takes the current time, so that end() can calculate the elapsed time between the two method calls.

If the statistics keeper holding this time statistics is disabled, this method does nothing, in order to save resources.

end()[source]¶

This method must be called after the operation returns. Note that this method is not to be invoked by the user; it is invoked by the implementation of the Session class.

If the statistics keeper holding this time statistics is enabled, this method takes the current time, calculates the duration of the operation since the last call to begin(), and updates the time statistics to reflect the new operation.

If the statistics keeper holding this time statistics is disabled, this method does nothing, in order to save resources.

If this method is called without a preceding call to begin(), a RuntimeError is raised.

Raises:	`RuntimeError`

__str__()[source]¶

Return a human readable string with the time statistics for this operation.

Example result:

TimeStats: count=1 avg=1.000s min=1.000s max=1.000s get /api/cpcs

Metrics¶

The HMC supports the retrieval of metrics values for resources of a IBM Z or LinuxONE computer. This section describes the zhmcclient API for retrieving such metrics from the HMC.

A resource termed Metrics Context is associated with any metrics retrieval. These resources are user-created definitions of the kinds of metrics that are intended to be retrieved. A metrics context mostly defines the names of the metric groups to be retrieved. The available metric groups are described in section ‘Metric Groups’ in the HMC API book.

The zhmcclient API for metrics provides access to the metric values and to their definitions, so that clients using the metric values do not need to have intimate knowledge about the specific metric values when just displaying them.

The basic usage of the metrics API is shown in this example:

# Create a Metrics Context for the desired metric groups:
metric_groups = ['dpm-system-usage-overview', 'partition-usage']
mc = client.metrics_contexts.create(
    {'anticipated-frequency-seconds': 15,
     'metric-groups': metric_groups})

# Retrieve the current metric values:
mr_str = mc.get_metrics()

# Display the metric values:
print("Current metric values:")
mr = zhmcclient.MetricsResponse(mc, mr_str)
for mg in mr.metric_groups:
    mg_name = mg.name
    mg_def = mc.metric_group_definitions[mg_name]
    print("  Metric group: {}".format(mg_name))
    for ov in mg.object_values:
        print("    Resource: {}".format(ov.resource_uri))
        print("    Timestamp: {}".format(ov.timestamp))
        print("    Metric values:")
        for m_name in ov.metrics:
            m_value = ov.metrics[m_name]
            m_def = mg_def.metric_definitions[m_name]
            m_unit = m_def.unit
            m_type = m_def.type
            print("      {:30}  {} {}".
                  format(m_name, m_value, m_unit.encode('utf-8')))

# Delete the Metrics Context:
mc.delete()

class zhmcclient.MetricsContextManager(client)[source]¶

Manager providing access to the Metrics Context resources that were created through this manager object.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the metrics_contexts attribute of the Client object connected to the HMC.

Methods

`create`	Create a Metrics Context resource in the HMC this client is connected to.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the Metrics Context resources that were created through this manager object.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`client`	The client defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

__repr__()[source]¶: Return a string with the state of this manager object, for debug purposes.

client¶

The client defining the scope for this manager.

Type:	`Client`

list(full_properties=False)[source]¶

List the Metrics Context resources that were created through this manager object.

Note that the HMC does not provide a way to enumerate the existing Metrics Context resources. Therefore, this method will only list the Metrics Context resources that were created through this manager object. For example, Metrics Context resources created through a second Client object will not be listed.

Parameters:	full_properties (bool) – This parameter exists for compatibility with other resource classes, but for this class, it has no effect on the result.
Returns:	A list of `MetricsContext` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create a Metrics Context resource in the HMC this client is connected to.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Metrics Context’ in the HMC API book.
Returns:	The resource object for the new Metrics Context resource.
Return type:	`MetricsContext`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.MetricsContext(manager, uri, name=None, properties=None)[source]¶

Representation of a Metrics Context resource.

A Metrics Context resource specifies a list of metrics groups for which the current metric values can be retrieved using the get_metrics() method.

The properties of this resource are the response fields described for the ‘Create Metrics Context’ operation in the HMC API book.

This class is derived from BaseResource; see there for common methods and attributes.

Objects of this class can be created by the user with the zhmcclient.MetricsContextManager.create() method.

Methods

`delete`	Delete this Metrics Context resource.
`get_metrics`	Retrieve the current metric values for this Metrics Context resource from the HMC.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`metric_group_definitions`	The metric definitions for the metric groups of this Metrics Context resource, as a dictionary of `MetricGroupDefinition` objects, by metric group name.
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

metric_group_definitions¶

The metric definitions for the metric groups of this Metrics Context resource, as a dictionary of MetricGroupDefinition objects, by metric group name.

Type:	dict

get_metrics()[source]¶

Retrieve the current metric values for this Metrics Context resource from the HMC.

The metric values are returned by this method as a string in the MetricsResponse format described with the ‘Get Metrics’ operation in the HMC API book.

The MetricsResponse class can be used to process the MetricsResponse string returned by this method, and provides structured access to the metrics values.

Returns:	The current metric values, in the MetricsResponse string format.
Return type:	string
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

delete()[source]¶

Delete this Metrics Context resource.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.MetricGroupDefinition[source]¶

A namedtuple representing definitional information for a metric group.

Parameters:

name (string) – Metric group name, as defined in section ‘Metric groups’ in the HMC API book.
resource_class (string) – A string identifying the resource class to which this metric group belongs, using the values from the ‘class’ property of resource objects.
metric_definitions (dict) – Metric definitions for the metrics in this metric group, as a dictionary where the key is the metric name and the value is the MetricDefinition object for the metric.

All these parameters are also available as same-named attributes.

class zhmcclient.MetricDefinition[source]¶

A namedtuple representing definitional information for a single metric.

Parameters:

index (integer) – 0-based index (=position) of the metric in a MetricsResponse value row.
name (string) – Metric field name, as shown in the tables defining the metric groups in section ‘Metric groups’ in the HMC API book.
type (callable) –
Python type for the metric value. The type must be a constructor (callable) that takes the metrics value from the MetricsResponse string as its only argument, using the following Python types for the metric group description types shown in the HMC API book:

Description type Python type

Boolean bool

Byte integer

Short integer

Integer integer

Long integer

Double float

String, String Enum unicode string
unit (string) – Unit of the metric value.

All these parameters are also available as same-named attributes.

class zhmcclient.MetricsResponse(metrics_context, metrics_response_str)[source]¶

Represents the metric values returned by one call to the get_metrics() method, and provides structured access to the data.

Parameters:	metrics_context (`MetricsContext`) – The `MetricsContext` object that was used to retrieve the metrics response string. It defines the structure of the metric values in the metrics response string. metrics_response_str (string) – The metrics response string, as returned by the `get_metrics()` method.

Methods

Attributes

`metric_group_values`	The list of `MetricGroupValues` objects representing the metric groups in this metric response.
`metrics_context`	`MetricsContext` object for this metric response.

Details

metrics_context¶: MetricsContext object for this metric response. This can be used to access the metric definitions for this response.

metric_group_values¶

The list of MetricGroupValues objects representing the metric groups in this metric response.

Each MetricGroupValues object contains a list of MetricObjectValues objects representing the metric values in this group (each for a single resource and point in time).

Type:	`list`

class zhmcclient.MetricGroupValues(name, object_values)[source]¶

Represents the metric values for a metric group in a MetricsResponse string.

Parameters:	name (string) – Metric group name. object_values (`list`) – The `MetricObjectValues` objects in this metric group. Each of them represents the metric values for a single resource at a single point in time.

Methods

Attributes

`name`	The metric group name.
`object_values`	The `MetricObjectValues` objects in this metric group.

Details

name¶

The metric group name.

Type:	string

object_values¶

The MetricObjectValues objects in this metric group. Each of them represents the metric values for a single resource at a single point in time.

Type:	`list`

class zhmcclient.MetricObjectValues(client, metric_group_definition, resource_uri, timestamp, metrics)[source]¶

Represents the metric values for a single resource at a single point in time.

Parameters:

client (Client) – Client object, for retrieving the actual resource.
metric_group_definition (MetricGroupDefinition) – Metric group definition for this set of metric values.
resource_uri (string) – Resource URI of the resource these metric values apply to.
timestamp (datetime.datetime) – Point in time when the HMC captured these metric values (as a timezone-aware datetime object).
metrics (dict) – The metric values, as a dictionary of the (Python typed) metric values, by metric name.

Methods

Attributes

`client`	Client object, for retrieving the actual resource.
`metric_group_definition`	Metric group definition for this set of metric values.
`metrics`	The metric values, as a dictionary of the (Python typed) metric values, by metric name.
`resource`	The Python resource object of the
`resource_uri`	The canonical URI path of the resource these metric values apply to.
`timestamp`	Point in time when the HMC captured these metric values (as a timezone-aware datetime object).

Details

client¶

Client object, for retrieving the actual resource.

Type:	`Client`

metric_group_definition¶

Metric group definition for this set of metric values.

Type:	`MetricGroupDefinition`

resource_uri¶

The canonical URI path of the resource these metric values apply to.

Example: /api/cpcs/12345

Type:	string

timestamp¶

Point in time when the HMC captured these metric values (as a timezone-aware datetime object).

Type:	`datetime.datetime`

metrics¶

The metric values, as a dictionary of the (Python typed) metric values, by metric name.

Type:	dict

resource¶

The Python resource object of the: resource these metric values apply to.

Raises:	`NotFound` – No resource found for this URI in the management scope of the HMC.
Type:	`BaseResource`

Logging¶

The zhmcclient supports logging using the standard Python logging module, using standard Python Logger objects with these names:

‘zhmcclient.api’ for user-issued calls to zhmcclient API functions, at the debug level. Internal calls to API functions are not logged.
‘zhmcclient.hmc’ for interactions between zhmcclient and the HMC, at the debug level.

For HMC operations and API calls that contain the HMC password or HMC session tokens, the password is hidden in the log message by replacing it with a few ‘*’ characters.

All these loggers have a null-handler (see NullHandler) and have no log formatter (see Formatter).

As a result, the loggers are silent by default. If you want to turn on logging, add a log handler (see addHandler(), and logging.handlers for the handlers included with Python) and set the log level (see setLevel(), and Logging Levels for the defined levels).

If you want to change the default log message format, use setFormatter(). Its form parameter is a format string with %-style placeholders for the log record attributes (see Python section LogRecord attributes).

Examples:

To output the log records for all HMC operations to stdout in a particular format, do this:

import logging

handler = logging.StreamHandler()
format_string = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
handler.setFormatter(logging.Formatter(format_string))
logger = logging.getLogger('zhmcclient.hmc')
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)

This example uses the basicConfig() convenience function that sets the same format and level as in the previous example, but for the root logger. Therefore, it will output all log records, not just from this package:
```
import logging

format_string = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
logging.basicConfig(format=format_string, level=logging.DEBUG)
```

Exceptions¶

Exceptions that can be raised by the client.

class zhmcclient.Error[source]¶

Abstract base class for exceptions specific to this package.

Exceptions of this class are not raised; only derived exceptions are raised.

Derived from exceptions.Exception.

Details

str_def()[source]¶

Interface definition for the corresponding method derived exception classes.

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts.

For the exact format returned by derived exception classes, see the same-named methods there.

class zhmcclient.ConnectionError(msg, details)[source]¶

This exception indicates a problem with the connection to the HMC, below the HTTP level. HTTP errors are indicated via HTTPError.

A retry by the user code is not likely to be successful, unless connect or read retries had been disabled when creating the session (see Session).

Even though this class has exceptions derived from it, exceptions of this class may also be raised (if no other derived class matches the circumstances).

Derived from Error.

Parameters:	msg (string) – A human readable message describing the problem. details (Exception) – The original exception describing details about the error.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`details`	The original exception caught by this package, providing more information about the problem.
`message`

Details

details¶

The original exception caught by this package, providing more information about the problem.

This will be one of the following exceptions:

Any exception derived from requests.exceptions.RequestException.

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; message={};

class zhmcclient.ConnectTimeout(msg, details, connect_timeout, connect_retries)[source]¶

This exception indicates that a connection to the HMC timed out after exhausting the connect retries (see zhmcclient.RetryTimeoutConfig.connect_retries).

Further retrying by the user code is not likely to be successful, unless connect retries had been disabled when creating the session (see Session).

Derived from ConnectionError.

Parameters:	msg (string) – A human readable message describing the problem. details (Exception) – The original exception describing details about the error. connect_timeout (integer) – The connect timeout in seconds. connect_retries (integer) – The number of connect retries.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`connect_retries`	The number of connect retries.
`connect_timeout`	The connect timeout in seconds.
`details`	The original exception caught by this package, providing more information about the problem.
`message`

Details

connect_timeout¶

The connect timeout in seconds.

Type:	integer

connect_retries¶

The number of connect retries.

Type:	integer

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; connect_timeout={}; connect_retries={}; message={};

class zhmcclient.ReadTimeout(msg, details, read_timeout, read_retries)[source]¶

This exception indicates that reading an HTTP response from the HMC timed out after exhausting the read retries (see zhmcclient.RetryTimeoutConfig.read_retries).

Further retrying by the user code is not likely to be successful, unless read retries had been disabled when creating the session (see Session).

Derived from ConnectionError.

Parameters:	msg (string) – A human readable message describing the problem. details (Exception) – The original exception describing details about the error. read_timeout (integer) – The read timeout in seconds. read_retries (integer) – The number of read retries.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`details`	The original exception caught by this package, providing more information about the problem.
`message`
`read_retries`	The number of read retries.
`read_timeout`	The read timeout in seconds.

Details

read_timeout¶

The read timeout in seconds.

Type:	integer

read_retries¶

The number of read retries.

Type:	integer

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; read_timeout={}; read_retries={}; message={};

class zhmcclient.RetriesExceeded(msg, details, connect_retries)[source]¶

This exception indicates that the maximum number of retries for connecting to the HMC, sending HTTP requests or reading HTTP responses was exceeded, for reasons other than connect timeouts (see ConnectTimeout) or read timeouts (see ReadTimeout).

Further retrying by the user code is not likely to be successful, unless connect or read retries had been disabled when creating the session (see Session).

Derived from ConnectionError.

Parameters:	msg (string) – A human readable message describing the problem. details (Exception) – The original exception describing details about the error. connect_retries (integer) – The number of connect retries.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`connect_retries`	The number of connect retries.
`details`	The original exception caught by this package, providing more information about the problem.
`message`

Details

connect_retries¶

The number of connect retries.

Type:	integer

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; connect_retries={}; message={};

class zhmcclient.AuthError[source]¶

This exception indicates erors related to authentication.

Exceptions of this class are not raised; only derived exceptions are raised.

Derived from Error.

Methods

str_def Interface definition for the corresponding method derived exception classes.

Attributes

`args`
`message`

Details

class zhmcclient.ClientAuthError(msg)[source]¶

This exception indicates an authentication related problem detected on the client side.

Derived from AuthError.

Parameters:	msg (string) – A human readable message describing the problem.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`message`

Details

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; message={};

class zhmcclient.ServerAuthError(msg, details)[source]¶

This exception indicates an authentication error with the HMC.

Derived from AuthError.

Parameters:	msg (string) – A human readable message describing the problem. details (Exception) – The `HTTPError` exception describing the error returned by the HMC.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`details`	The original exception describing details about the error.
`message`

Details

details¶

The original exception describing details about the error.

This may be one of the following exceptions:

HTTPError

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; request_method={}; request_uri={}; http_status={}; reason={}; message={};

class zhmcclient.ParseError(msg)[source]¶

This exception indicates a parsing error while processing the JSON payload in a response from the HMC.

Derived from Error.

The error location within the payload is automatically determined by parsing the error message for the pattern:

: line {line} column {column}

Parameters:

msg (string) –

A human readable message describing the problem.

This should be the message of the ValueError exception raised by methods of the json.JSONDecoder class.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`column`	The 1-based column number of the error location within the JSON payload.
`line`	The 1-based line number of the error location within the JSON payload.
`message`

Details

line¶

The 1-based line number of the error location within the JSON payload.

None indicates that the error location is not available.

Type:	integer

column¶

The 1-based column number of the error location within the JSON payload.

None indicates that the error location is not available.

Type:	integer

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; line={}; column={}; message={};

class zhmcclient.VersionError(msg, min_api_version, api_version)[source]¶

This exception indicates that a function of the client requires a minimum HMC API version which is not supported by the HMC.

Derived from Error.

Parameters:	msg (string) – A human readable message describing the problem. min_api_version (HMC API version) – The minimum HMC API version required to perform the function that raised this exception. api_version (HMC API version) – The actual HMC API version supported by the HMC.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`api_version`	The actual HMC API version supported by the HMC.
`args`
`message`
`min_api_version`	The minimum HMC API version required to perform the function that raised this exception.

Details

min_api_version¶

The minimum HMC API version required to perform the function that raised this exception.

Type:	HMC API version

api_version¶

The actual HMC API version supported by the HMC.

Type:	HMC API version

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; min_api_version={}; api_version={}; message={};

class zhmcclient.HTTPError(body)[source]¶

This exception indicates that the HMC returned an HTTP response with a bad HTTP status code.

Derived from Error.

Parameters:	body (json object) – Body of the HTTP error response.

args[0] will be set to the ‘message’ item of the body, or to None if not present.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`error_details`	A nested object that provides additional operation-specific error information.
`http_status`	Numeric HTTP status code (e.g.
`message`	Message describing the error.
`reason`	Numeric HMC reason code.
`request_authenticated_as`	Name of the HMC user associated with the API session under which the request was issued.
`request_body`	The request body, in the form of a JSON document.
`request_body_as_string`	The complete request body, or some portion of the request body, exactly as it was submitted by the API client program, if the `request_body` property is None.
`request_body_as_string_partial`	Indicates whether the `request_body_as_string` property contains only part of the request body (True) or the entire request body (False).
`request_headers`	HTTP headers specified on the request.
`request_method`	The HTTP method (DELETE, GET, POST, PUT) that caused this error response.
`request_query_parms`	URI query parameters specified on the request.
`request_uri`	The URI that caused this error response.
`stack`	Internal HMC diagnostic information for the error.

Details

http_status¶

Numeric HTTP status code (e.g. 500).

See RFC2616 for a list of HTTP status codes and reason phrases.

Type:	integer

reason¶

Numeric HMC reason code.

HMC reason codes provide more details as to the nature of the error than is provided by the HTTP status code. This HMC reason code is treated as a sub-code of the HTTP status code and thus must be used in conjunction with the HTTP status code to determine the error condition.

Standard HMC reason codes that apply across the entire API are described in section ‘Common request validation reason codes’ in the HMC API book. Additional operation-specific reason codes may also be documented in the description of specific API operations in the HMC API book.

The articial reason code 999 is used when the response from the HMC contains an HTML-formatted error message.

Type:	integer

message¶

Message describing the error.

This message is not currently localized.

Type:	string

request_method¶

The HTTP method (DELETE, GET, POST, PUT) that caused this error response.

Type:	string

request_uri¶

The URI that caused this error response.

Type:	string

request_query_parms¶

URI query parameters specified on the request.

Each query-parm-info object identifies a single query parameter by its name and includes its value(s).

An empty list, if the request did not specify any query parameters.

Type:	List of query-parm-info objects

request_headers¶

HTTP headers specified on the request.

An empty list, if the request did not specify any HTTP headers.

Type:	header-info object

request_authenticated_as¶

Name of the HMC user associated with the API session under which the request was issued.

None, if the request was issued without an established session or there is no HMC user bound to the session.

Type:	string

request_body¶

The request body, in the form of a JSON document. Note that, since it is in the form of a JSON document, this may not be exactly what was submitted by the API client program, but it is semantically equivalent.

If the request body could not be parsed or some other error prevented the creation of a JSON document from the request body, this property is None and the request body is instead available in the request_body_as_string property.

request_body_as_string¶

The complete request body, or some portion of the request body, exactly as it was submitted by the API client program, if the request_body property is None. Otherwise, None.

The request_body_as_string_partial property indicates whether the complete request body is provided in this property.

Type:	string

request_body_as_string_partial¶

Indicates whether the request_body_as_string property contains only part of the request body (True) or the entire request body (False). None, if the request_body_as_string property is None.

Type:	`bool`

stack¶

Internal HMC diagnostic information for the error.

This field is supplied only on selected 5xx HTTP status codes. None, if not supplied.

Type:	string

error_details¶

A nested object that provides additional operation-specific error information. This field is provided by selected operations, and the format of the nested object is as described by that operation.

Type:	string

__str__()[source]¶: Return a human readable string representation of this exception object.

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; request_method={}; request_uri={}; http_status={}; reason={}; message={};

class zhmcclient.OperationTimeout(msg, operation_timeout)[source]¶

This exception indicates that the waiting for completion of an asynchronous HMC operation has timed out.

Derived from Error.

Parameters:	msg (string) – A human readable message describing the problem. operation_timeout (integer) – The operation timeout in seconds.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`message`
`operation_timeout`	The operation timeout in seconds.

Details

operation_timeout¶

The operation timeout in seconds.

Type:	integer

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; operation_timeout={}; message={};

class zhmcclient.StatusTimeout(msg, actual_status, desired_statuses, status_timeout)[source]¶

This exception indicates that the waiting for reaching a desired LPAR or Partition status has timed out.

The possible status values for an LPAR are:

"not-activated" - The LPAR is not active.
"not-operating" - The LPAR is active but no operating system is running in the LPAR.
"operating" - The LPAR is active and an operating system is running in the LPAR.
"exceptions" - The LPAR or its CPC has one or more unusual conditions.

The possible status values for a Partition are described in the ‘status’ property of the data model for the partition resource in the HMC API book.

Derived from Error.

Parameters:	msg (string) – A human readable message describing the problem. actual_status (string) – The actual status (at the point in time when the status timeout expired). desired_statuses (iterable of string) – The desired status values that were supposed to be reached. status_timeout (number) – The status timeout (in seconds) that has expired.

args[0] will be set to the msg parameter.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`actual_status`	The actual status (at the point in time when the status timeout expired).
`args`
`desired_statuses`	The desired status values that were supposed to be reached.
`message`
`status_timeout`	The status timeout (in seconds) that has expired.

Details

actual_status¶

The actual status (at the point in time when the status timeout expired).

Type:	string

desired_statuses¶

The desired status values that were supposed to be reached.

Type:	iterable of string

status_timeout¶

The status timeout (in seconds) that has expired.

Type:	number

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; actual_status={}; desired_statuses={}; status_timeout={}; message={};

class zhmcclient.NotFound(filter_args, manager)[source]¶

This exception indicates that a resource was not found.

Derived from Error.

Parameters:	filter_args (dict) – Dictionary of filter arguments by which the resource was attempted to be found. Keys are the resource property names, values are the match values for that property. manager (`BaseManager`) – The manager of the resource, in whose scope the resource was attempted to be found. Must not be None.

args[0] will be set to an exception message that is automatically constructed from the input parameters.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`filter_args`	Dictionary of filter arguments by which the resource was attempted to be found.
`manager`	The manager of the resource, in whose scope the resource was attempted to be found.
`message`

Details

filter_args¶

Dictionary of filter arguments by which the resource was attempted to be found. Keys are the resource property names, values are the match values for that property.

Type:	dict

manager¶

The manager of the resource, in whose scope the resource was attempted to be found.

Type:	`BaseManager`

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; resource_classname={}; filter_args={}; parent_classname={}; parent_name={}; message={};

class zhmcclient.NoUniqueMatch(filter_args, manager, resources)[source]¶

This exception indicates that more than one resource matched the filter arguments.

Derived from Error.

Parameters:

filter_args (dict) – Dictionary of filter arguments by which the resource was attempted to be found. Keys are the resource property names, values are the match values for that property.
manager (BaseManager) –
The manager of the resource, in whose scope the resource was attempted to be found.

Must not be None.
resources (iterable of BaseResource) –
The resources that did match the filter.

Must not be None.

args[0] will be set to an exception message that is automatically constructed from the input parameters.

Methods

str_def string: The exception as a string in a Python definition-style format, e.g.

Attributes

`args`
`filter_args`	Dictionary of filter arguments by which the resource was attempted to be found.
`manager`	The manager of the resource, in whose scope the resource was attempted to be found.
`message`
`resource_uris`	List of URIs of the resources that matched the filter.
`resources`	The resources that matched the filter.

Details

filter_args¶

Dictionary of filter arguments by which the resource was attempted to be found. Keys are the resource property names, values are the match values for that property.

Type:	dict

manager¶

The manager of the resource, in whose scope the resource was attempted to be found.

Type:	`BaseManager`

resources¶

The resources that matched the filter.

Type:	List of `BaseResource`

resource_uris¶: List of URIs of the resources that matched the filter.

__repr__()[source]¶: Return a string with the state of this exception object, for debug purposes.

str_def()[source]¶

string: The exception as a string in a Python definition-style format, e.g. for parsing by scripts:

classname={}; resource_classname={}; filter_args={}; parent_classname={}; manager_name={}; message={}; resource_uris={}

Constants¶

Public constants.

These constants are not meant to be changed by the user, they are made available for inspection and documentation purposes only.

For technical reasons, the online documentation shows these constants in the zhmcclient._constants namespace, but they are also available in the zhmcclient namespace and should be used from there.

zhmcclient._constants.DEFAULT_CONNECT_TIMEOUT = 30¶: Default HTTP connect timeout in seconds, if not specified in the retry_timeout_config init argument to Session.

zhmcclient._constants.DEFAULT_CONNECT_RETRIES = 3¶: Default number of HTTP connect retries, if not specified in the retry_timeout_config init argument to Session.

zhmcclient._constants.DEFAULT_HMC_PORT = 6794¶: Default HMC port number

zhmcclient._constants.DEFAULT_READ_TIMEOUT = 3600¶

Default HTTP read timeout in seconds, if not specified in the retry_timeout_config init argument to Session.

Note: The default value for this parameter has been increased to a large value in order to mitigate the behavior of the ‘requests’ module to retry HTTP methods even if they are not idempotent (e.g. DELETE). See zhmcclient issue #249.

zhmcclient._constants.DEFAULT_STOMP_PORT = 61612¶: Default port on which the HMC issues JMS over STOMP messages.

zhmcclient._constants.DEFAULT_READ_RETRIES = 0¶

Default number of HTTP read retries, if not specified in the retry_timeout_config init argument to Session.

Note: The default value for this parameter has been set to 0 in order to mitigate the behavior of the ‘requests’ module to retry HTTP methods even if they are not idempotent (e.g. DELETE). See zhmcclient issue #249.

zhmcclient._constants.DEFAULT_MAX_REDIRECTS = 30¶: Default max. number of HTTP redirects, if not specified in the retry_timeout_config init argument to Session.

zhmcclient._constants.DEFAULT_OPERATION_TIMEOUT = 3600¶

Default timeout in seconds for waiting for completion of an asynchronous HMC operation, if not specified in the retry_timeout_config init argument to Session.

This is used as a default value in asynchronous methods on resource objects (e.g. zhmcclient.Partition.start()), in the zhmcclient.Job.wait_for_completion() method, and in the low level method zhmcclient.Session.post().

zhmcclient._constants.DEFAULT_STATUS_TIMEOUT = 900¶

Default timeout in seconds for waiting for completion of deferred status changes for LPARs, if not specified in the retry_timeout_config init argument to Session.

This is used as a default value in asynchronous methods of the Lpar class that change its status (e.g. zhmcclient.Lpar.activate())).

zhmcclient._constants.DEFAULT_NAME_URI_CACHE_TIMETOLIVE = 300¶

Default time to the next automatic invalidation of the Name-URI cache of manager objects, in seconds since the last invalidation, if not specified in the retry_timeout_config init argument to Session.

The special value 0 means that no Name-URI cache is maintained (i.e. the caching is disabled).

zhmcclient._constants.HMC_LOGGER_NAME = 'zhmcclient.hmc'¶: Name of the Python logger that logs HMC operations.

zhmcclient._constants.API_LOGGER_NAME = 'zhmcclient.api'¶: Name of the Python logger that logs zhmcclient API calls made by the user.

zhmcclient._constants.HTML_REASON_WEB_SERVICES_DISABLED = 900¶

Web Services API is not enabled on the HMC.

Type:	HTTP reason code

zhmcclient._constants.HTML_REASON_OTHER = 999¶

Other HTML-formatted error response. Note that over time, there may be more specific reason codes introduced for such situations.

Type:	HTTP reason code

Utilities¶

Utility functions.

zhmcclient.datetime_from_timestamp(ts, tzinfo=<UTC>)[source]¶

Convert an HMC timestamp number into a datetime object. The resulting object will be timezone-aware and will be represented in the specified timezone, defaulting to UTC.

The HMC timestamp number must be non-negative. This means the special timestamp value -1 cannot be represented as datetime and will cause ValueError to be raised.

The date and time range supported by this function has the following bounds:

The upper bounds is determined by datetime.datetime.max and additional limitations, as follows:
- 9999-12-31 23:59:59 UTC, for 32-bit and 64-bit CPython on Linux and OS-X.
- 3001-01-01 07:59:59 UTC, for 32-bit and 64-bit CPython on Windows, due to a limitation in gmtime() in Visual C++.
- 2038-01-19 03:14:07 UTC, for some 32-bit Python implementations, due to the Year 2038 problem.
The lower bounds is the UNIX epoch: 1970-01-01 00:00:00 UTC.

Parameters:	ts (timestamp) – Point in time as an HMC timestamp number. Must not be None. tzinfo (`datetime.tzinfo`) – Timezone in which the returned object will be represented. This may be any object derived from `datetime.tzinfo`, including but not limited to objects returned by `pytz.timezone()`. Note that this parameter does not affect how the HMC timestamp value is interpreted; i.e. the effective point in time represented by the returned object is not affected. What is affected by this parameter is for example the timezone in which the point in time is shown when printing the returned object. Must not be None.
Returns:	Point in time as a timezone-aware Python datetime object for the specified timezone.
Return type:	`datetime`
Raises:	`ValueError`

zhmcclient.timestamp_from_datetime(dt)[source]¶

Convert a datetime object into an HMC timestamp number.

The date and time range supported by this function has the following bounds:

The upper bounds is datetime.datetime.max, as follows:
- 9999-12-31 23:59:59 UTC, for 32-bit and 64-bit CPython on Linux and OS-X.
- 2038-01-19 03:14:07 UTC, for some 32-bit Python implementations, due to the Year 2038 problem.
The lower bounds is the UNIX epoch: 1970-01-01 00:00:00 UTC.

Parameters:	dt (`datetime`) – Point in time as a Python datetime object. The datetime object may be timezone-aware or timezone-naive. If timezone-naive, the UTC timezone is assumed. Must not be None.
Returns:	Point in time as an HMC timestamp number.
Return type:	timestamp
Raises:	`ValueError`

Reference: Resources¶

This section describes the resource model supported by the zhmcclient package.

Note that the zhmcclient package supports only a subset of the resources described in the HMC API book. We will grow the implemented subset over time, and if you find that a particular resource you need is missing, please open an issue in the zhmcclient issue tracker.

See Resource model concepts for a description of the concepts used in representing the resource model.

The resource descriptions in this section do not detail the resource properties. The description of the resource properties of a particular HMC resource type can be found in its “Data model” section in the HMC API book. Each Python resource class mentions the corresponding HMC resource type.

The data types used in these “Data model” sections are represented in Python data types according to the mapping shown in the following table:

HMC API data type	Python data type
Boolean	`bool`
Byte, Integer, Long, Short	integer
Float	`float`
String, String Enum	unicode string
timestamp	integer
Array	`list`
Object	`dict`

CPCs¶

A CPC (Central Processor Complex) is a physical IBM Z or LinuxONE computer.

A particular HMC can manage multiple CPCs and can discover other CPCs that are not managed by that HMC. Such other CPCs are called “unmanaged CPCs” and they may or may not be managed by another HMC.

This section describes the interface for managed CPCs using resource class Cpc and the corresponding manager class CpcManager.

The HMC can manage a range of old and new CPC generations. Some older CPC generations are not capable of supporting the HMC Web Services API; these older CPCs can be managed using the GUI of the HMC, but not through its Web Services API. Therefore, such older CPCs will not be exposed at the HMC Web Services API, and thus will not show up in the API of this Python package.

TODO: List earliest CPC generation that supports the HMC Web Services API.

A CPC can be in any of the following three modes:

DPM mode: Dynamic Partition Manager is enabled for the CPC.
Classic mode: The CPC does not have Dynamic Partition Manager enabled, and is not member of an ensemble.
Ensemble mode: The CPC is member of an ensemble. This Python client does not support the functionality that is specific to ensemble mode.

The functionality supported at the HMC API and thus also for users of this Python client, depends on the mode in which the CPC currently is. If a particular functionality is available only in a specific mode, that is indicated in the description of the functionality.

class zhmcclient.CpcManager(client)[source]¶

Manager providing access to the managed CPCs exposed by the HMC this client is connected to.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Client object:

cpcs

Methods

`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the CPCs managed by the HMC this client is connected to.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`client`	The client defining the scope for this manager.
`console`	The Console representing the HMC this CPC is managed by.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

client¶

The client defining the scope for this manager.

Type:	`Client`

console¶

The Console representing the HMC this CPC is managed by.

The returned object is cached, so it is looked up only upon first access to this property.

The returned object has only the following properties set:

‘object-uri’

Use get_property() or prop() to access any properties regardless of whether they are already set or first need to be retrieved.

Type:	`Console`

list(full_properties=False, filter_args=None)[source]¶

List the CPCs managed by the HMC this client is connected to.

Authorization requirements:

Object-access permission to any CPC to be included in the result.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `Cpc` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.Cpc(manager, uri, name=None, properties=None)[source]¶

Representation of a managed CPC.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, CpcManager).

Methods

`export_profiles`	Export activation profiles and/or system activity profiles from this CPC to the SE hard drive using the HMC operation “Export Profiles”.
`feature_enabled`	Indicates whether the specified feature is enabled for this CPC.
`feature_info`	Returns information about the features available for this CPC.
`get_energy_management_properties`	Return the energy management properties of the CPC.
`get_free_crypto_domains`	Return a list of crypto domains that are free for usage on a list of crypto adapters in this CPC.
`get_property`	Return the value of a resource property.
`get_wwpns`	Return the WWPNs of the host ports (of the HBAs) of the specified Partitions of this CPC.
`import_profiles`	Import activation profiles and/or system activity profiles for this CPC from the SE hard drive into the CPC using the HMC operation “Import Profiles”.
`list_associated_storage_groups`	Return the storage groups that are associated to this CPC.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`set_power_capping`	Set the power capping settings of this CPC.
`set_power_save`	Set the power save setting of this CPC.
`start`	Start this CPC, using the HMC operation “Start CPC”.
`stop`	Stop this CPC, using the HMC operation “Stop CPC”.
`update_properties`	Update writeable properties of this CPC.
`validate_lun_path`	Validate if an FCP storage volume on an actual storage subsystem is reachable from this CPC, through a specified host port and using a specified host WWPN.

Attributes

`adapters`	Access to the Adapters in this CPC.
`dpm_enabled`	Indicates whether this CPC is currently in DPM mode (Dynamic Partition Manager mode).
`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`image_activation_profiles`	Access to the Image Activation Profiles in this CPC.
`load_activation_profiles`	Access to the Load Activation Profiles in this CPC.
`lpars`	Access to the LPARs in this CPC.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`maximum_active_partitions`	The maximum number of active logical partitions or partitions of this CPC.
`name`	The name of the resource.
`partitions`	Access to the Partitions in this CPC.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`reset_activation_profiles`	Access to the Reset Activation Profiles in this CPC.
`uri`	The canonical URI path of the resource.
`virtual_switches`	Access to the Virtual Switches in this CPC.
`vswitches`	Access to the Virtual Switches in this CPC.

Details

lpars¶

Access to the LPARs in this CPC.

Type:	`LparManager`

partitions¶

Access to the Partitions in this CPC.

Type:	`PartitionManager`

adapters¶

Access to the Adapters in this CPC.

Type:	`AdapterManager`

virtual_switches¶

Access to the Virtual Switches in this CPC.

Type:	`VirtualSwitchManager`

vswitches¶

Access to the Virtual Switches in this CPC.

Deprecated: This attribute is deprecated and using it will cause a exceptions.DeprecationWarning to be issued. Use virtual_switches instead.

Type:	`VirtualSwitchManager`

reset_activation_profiles¶

Access to the Reset Activation Profiles in this CPC.

Type:	`ActivationProfileManager`

image_activation_profiles¶

Access to the Image Activation Profiles in this CPC.

Type:	`ActivationProfileManager`

load_activation_profiles¶

Access to the Load Activation Profiles in this CPC.

Type:	`ActivationProfileManager`

dpm_enabled¶

Indicates whether this CPC is currently in DPM mode (Dynamic Partition Manager mode).

If the CPC is not currently in DPM mode, or if the CPC does not support DPM mode (i.e. before z13), False is returned.

Authorization requirements:

Object-access permission to this CPC.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`
Type:	bool

maximum_active_partitions¶

The maximum number of active logical partitions or partitions of this CPC.

The following table shows the maximum number of active logical partitions or partitions by machine generations supported at the HMC API:

Machine generation	Maximum partitions
z196	60
z114	30
zEC12	60
zBC12	30
z13 / Emperor	85
z13s / Rockhopper	40
z14 / Emperor II	85
z14-ZR1 / -LR1	40
z15-T01 / -LT1 / -GT2	85
z15-T02 / -LT2	40

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `ValueError` – Unknown machine type
Type:	Integer

feature_enabled(feature_name)[source]¶

Indicates whether the specified feature is enabled for this CPC.

The HMC must generally support features, and the specified feature must be available for the CPC.

For a list of available features, see section “Features” in the HMC API, or use the feature_info() method.

Authorization requirements:

Object-access permission to this CPC.

Parameters:	feature_name (string) – The name of the feature.
Returns:	True if the feature is enabled, or False if the feature is disabled (but available).
Return type:	bool
Raises:	`ValueError` – Features are not supported on the HMC. `ValueError` – The specified feature is not available for the CPC. `HTTPError` `ParseError` `AuthError` `ConnectionError`

feature_info()[source]¶

Returns information about the features available for this CPC.

Authorization requirements:

Object-access permission to this CPC.

Returns:

An iterable where each item represents one feature that is available for this CPC.

Each item is a dictionary with the following items:

name (unicode string): Name of the feature.
description (unicode string): Short description of the feature.
state (bool): Enablement state of the feature (True if the enabled, False if disabled).

Return type:

iterable

Raises:

ValueError – Features are not supported on the HMC.
HTTPError
ParseError
AuthError
ConnectionError

update_properties(properties)[source]¶

Update writeable properties of this CPC.

Authorization requirements:

Object-access permission to this CPC.
Task permission for the “CPC Details” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘CPC’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

start(wait_for_completion=True, operation_timeout=None)[source]¶

Start this CPC, using the HMC operation “Start CPC”.

Authorization requirements:

Object-access permission to this CPC.
Task permission for the “Start (start a single DPM system)” task.

Parameters:	wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

stop(wait_for_completion=True, operation_timeout=None)[source]¶

Stop this CPC, using the HMC operation “Stop CPC”.

Authorization requirements:

Object-access permission to this CPC.
Task permission for the “Stop (stop a single DPM system)” task.

Parameters:	wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

import_profiles(profile_area, wait_for_completion=True, operation_timeout=None)[source]¶

Import activation profiles and/or system activity profiles for this CPC from the SE hard drive into the CPC using the HMC operation “Import Profiles”.

This operation is not permitted when the CPC is in DPM mode.

Authorization requirements:

Object-access permission to this CPC.
Task permission for the “CIM Actions ExportSettingsData” task.

Parameters:	profile_area (int) – The numbered hard drive area (1-4) from which the profiles are imported. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

export_profiles(profile_area, wait_for_completion=True, operation_timeout=None)[source]¶

Export activation profiles and/or system activity profiles from this CPC to the SE hard drive using the HMC operation “Export Profiles”.

This operation is not permitted when the CPC is in DPM mode.

Authorization requirements:

Object-access permission to this CPC.
Task permission for the “CIM Actions ExportSettingsData” task.

Parameters:	profile_area (int) – The numbered hard drive area (1-4) to which the profiles are exported. Any existing data is overwritten. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

get_wwpns(partitions)[source]¶

Return the WWPNs of the host ports (of the HBAs) of the specified Partitions of this CPC.

This method performs the HMC operation “Export WWPN List”.

Authorization requirements:

Object-access permission to this CPC.
Object-access permission to the Partitions designated by the “partitions” parameter.
Task permission for the “Export WWPNs” task.

Parameters:

partitions (iterable of Partition) – Partitions to be used.

Returns:

A list of items for each WWPN, where each item is a dict with the following keys:

’partition-name’ (string): Name of the Partition.
’adapter-id’ (string): ID of the FCP Adapter.
’device-number’ (string): Virtual device number of the HBA.
’wwpn’ (string): WWPN of the HBA.

Raises:

HTTPError – See the HTTP status and reason codes of operation “Export WWPN List” in the HMC API book.
ParseError
AuthError
ConnectionError

get_free_crypto_domains(crypto_adapters=None)[source]¶

Return a list of crypto domains that are free for usage on a list of crypto adapters in this CPC.

A crypto domain is considered free for usage if it is not assigned to any defined partition of this CPC in access mode ‘control-usage’ on any of the specified crypto adapters.

For this test, all currently defined partitions of this CPC are checked, regardless of whether or not they are active. This ensures that a crypto domain that is found to be free for usage can be assigned to a partition for ‘control-usage’ access to the specified crypto adapters, without causing a crypto domain conflict when activating that partition.

Note that a similar notion of free domains does not exist for access mode ‘control’, because a crypto domain on a crypto adapter can be in control access by multiple active partitions.

This method requires the CPC to be in DPM mode.

Example:

            crypto domains
adapters     0   1   2   3
           +---+---+---+---+
  c1       |A,c|a,c|   | C |
           +---+---+---+---+
  c2       |b,c|B,c| B | C |
           +---+---+---+---+
In this example, the CPC has two crypto adapters c1 and c2. For simplicity of the example, we assume these crypto adapters support only 4 crypto domains.

Partition A uses only adapter c1 and has domain 0 in ‘control-usage’ access (indicated by an upper case letter ‘A’ in the corresponding cell) and has domain 1 in ‘control’ access (indicated by a lower case letter ‘a’ in the corresponding cell).

Partition B uses only adapter c2 and has domain 0 in ‘control’ access and domains 1 and 2 in ‘control-usage’ access.

Partition C uses both adapters, and has domains 0 and 1 in ‘control’ access and domain 3 in ‘control-usage’ access.

The domains free for usage in this example are shown in the following table, for each combination of crypto adapters to be investigated:

crypto_adapters domains free for usage

c1 1, 2

c2 0

c1, c2 (empty list)

Experimental: This method has been added in v0.14.0 and is currently considered experimental. Its interface may change incompatibly. Once the interface remains stable, this experimental marker will be removed.

Authorization requirements:

Object-access permission to this CPC.
Object-access permission to all of its Partitions.
Object-access permission to all of its crypto Adapters.

Parameters:

crypto_adapters (iterable of Adapter) –

The crypto Adapters to be investigated.

None means to investigate all crypto adapters of this CPC.

Returns:

A sorted list of domain index numbers (integers) of the crypto domains that are free for usage on the specified crypto adapters.

Returns None, if crypto_adapters was an empty list or if crypto_adapters was None and the CPC has no crypto adapters.

Raises:

set_power_save(power_saving, wait_for_completion=True, operation_timeout=None)[source]¶

Set the power save setting of this CPC.

The current power save setting in effect for a CPC is described in the “cpc-power-saving” property of the CPC.

This method performs the HMC operation “Set CPC Power Save”. It requires that the feature “Automate/advanced management suite” (FC 0020) is installed and enabled, and fails otherwise.

This method will also fail if the CPC is under group control.

Whether a CPC currently allows this method is described in the “cpc-power-save-allowed” property of the CPC.

Authorization requirements:

Object-access permission to this CPC.
Task permission for the “Power Save” task.

Parameters:	power_saving (string) – The new power save setting, with the possible values: ”high-performance” - The power consumption and performance of the CPC are not reduced. This is the default setting. ”low-power” - Low power consumption for all components of the CPC enabled for power saving. ”custom” - Components may have their own settings changed individually. No component settings are actually changed when this mode is entered. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` – See the HTTP status and reason codes of operation “Set CPC Power Save” in the HMC API book. `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

set_power_capping(power_capping_state, power_cap=None, wait_for_completion=True, operation_timeout=None)[source]¶

Set the power capping settings of this CPC. The power capping settings of a CPC define whether or not the power consumption of the CPC is limited and if so, what the limit is. Use this method to limit the peak power consumption of a CPC, or to remove a power consumption limit for a CPC.

The current power capping settings in effect for a CPC are described in the “cpc-power-capping-state” and “cpc-power-cap-current” properties of the CPC.

This method performs the HMC operation “Set CPC Power Capping”. It requires that the feature “Automate/advanced management suite” (FC 0020) is installed and enabled, and fails otherwise.

This method will also fail if the CPC is under group control.

Whether a CPC currently allows this method is described in the “cpc-power-cap-allowed” property of the CPC.

Authorization requirements:

Object-access permission to this CPC.
Task permission for the “Power Capping” task.

Parameters:	power_capping_state (string) – The power capping state to be set, with the possible values: ”disabled” - The power cap of the CPC is not set and the peak power consumption is not limited. This is the default setting. ”enabled” - The peak power consumption of the CPC is limited to the specified power cap value. ”custom” - Individually configure the components for power capping. No component settings are actually changed when this mode is entered. power_cap (integer) – The power cap value to be set, as a power consumption in Watt. This parameter is required not to be None if power_capping_state=”enabled”. The specified value must be between the values of the CPC properties “cpc-power-cap-minimum” and “cpc-power-cap-maximum”. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` – See the HTTP status and reason codes of operation “Set CPC Power Save” in the HMC API book. `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

get_energy_management_properties()[source]¶

Return the energy management properties of the CPC.

The returned energy management properties are a subset of the properties of the CPC resource, and are also available as normal properties of the CPC resource. In so far, there is no new data provided by this method. However, because only a subset of the properties is returned, this method is faster than retrieving the complete set of CPC properties (e.g. via pull_full_properties()).

This method performs the HMC operation “Get CPC Energy Management Data”, and returns only the energy management properties for this CPC from the operation result. Note that in non-ensemble mode of a CPC, the HMC operation result will only contain data for the CPC alone.

It requires that the feature “Automate/advanced management suite” (FC 0020) is installed and enabled, and returns empty values for most properties, otherwise.

Authorization requirements:

Object-access permission to this CPC.

Returns:	A dictionary of properties of the CPC that are related to energy management. For details, see section “Energy management related additional properties” in the data model for the CPC resource in the HMC API book.
Return type:	dict
Raises:	`HTTPError` – See the HTTP status and reason codes of operation “Get CPC Energy Management Data” in the HMC API book. `ParseError` – Also raised by this method when the JSON response could be parsed but contains inconsistent data. `AuthError` `ConnectionError`

list_associated_storage_groups(full_properties=False, filter_args=None)[source]¶

Return the storage groups that are associated to this CPC.

If the CPC does not support the “dpm-storage-management” feature, or does not have it enabled, an empty list is returned.

Storage groups for which the authenticated user does not have object-access permission are not included.

Authorization requirements:

Object-access permission to any storage groups to be included in the result.

Parameters:	full_properties (bool) – Controls that the full set of resource properties for each returned storage group is being retrieved, vs. only the following short set: “object-uri”, “cpc-uri”, “name”, “fulfillment-state”, and “type”. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen. The ‘cpc-uri’ property is automatically added to the filter arguments and must not be specified in this parameter.
Returns:	A list of `StorageGroup` objects.
Raises:	`ValueError` – The filter_args parameter specifies the ‘cpc-uri’ property `HTTPError` `ParseError` `AuthError` `ConnectionError`

validate_lun_path(host_wwpn, host_port, wwpn, lun)[source]¶

Validate if an FCP storage volume on an actual storage subsystem is reachable from this CPC, through a specified host port and using a specified host WWPN.

This method performs the “Validate LUN Path” HMC operation.

If the volume is reachable, the method returns. If the volume is not reachable (and no other errors occur), an HTTPError is raised, and its reason property indicates the reason as follows:

484: Target WWPN cannot be reached.
485: Target WWPN can be reached, but LUN cannot be reached.

The CPC must have the “dpm-storage-management” feature enabled.

Parameters:

host_wwpn (string) –
World wide port name (WWPN) of the host (CPC), as a hexadecimal number of up to 16 characters in any lexical case.

This may be the WWPN of the physical storage port, or a WWPN of a virtual HBA. In any case, it must be the kind of WWPN that is used for zoning and LUN masking in the SAN.
host_port (Port) – Storage port on the CPC that will be used for validating reachability.
wwpn (string) – World wide port name (WWPN) of the FCP storage subsystem containing the storage volume, as a hexadecimal number of up to 16 characters in any lexical case.
lun (string) – Logical Unit Number (LUN) of the storage volume within its FCP storage subsystem, as a hexadecimal number of up to 16 characters in any lexical case.

Authorization requirements:

Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - Storage Administrator” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Unmanaged CPCs¶

A CPC (Central Processor Complex) is a physical IBM Z or LinuxONE computer.

A particular HMC can manage multiple CPCs and can discover other CPCs that are not managed by that HMC. Such other CPCs are called “unmanaged CPCs” and they may or may not be managed by another HMC.

This section describes the interface for unmanaged CPCs using resource class UnmanagedCpc and the corresponding manager class UnmanagedCpcManager.

class zhmcclient.UnmanagedCpcManager(console)[source]¶

Manager providing access to the CPCs that have been discovered by the HMC this client is connected to, but are not managed by it. They may or may not be managed by another HMC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Console object:

unmanaged_cpcs

Methods

`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the unmanaged CPCs exposed by the HMC this client is connected to.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`console`	Console defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

console¶

Console defining the scope for this manager.

Type:	`Console`

list(full_properties=False, filter_args=None)[source]¶

List the unmanaged CPCs exposed by the HMC this client is connected to.

Because the CPCs are unmanaged, the returned UnmanagedCpc objects cannot perform any operations and will have only the following properties:

object-uri
name

Authorization requirements:

None

Parameters:	full_properties (bool) – Ignored (exists for consistency with other list() methods). filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `UnmanagedCpc` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.UnmanagedCpc(manager, uri, name=None, properties=None)[source]¶

Representation of an unmanaged CPC.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, UnmanagedCpcManager).

Methods

`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

Activation profiles¶

An Activation Profile controls the activation of a CPC or LPAR. They are used to tailor the operation of a CPC and are stored in the Support Element associated with the CPC.

Activation Profile resources are contained in CPC resources.

Activation Profile resources only exist in CPCs that are not in DPM mode.

TODO: If Reset Activation Profiles are used to determine the CPC mode,: should they not exist in all CPC modes?

There are three types of Activation Profiles:

Reset: The Reset Activation Profile defines for a CPC the mode in which the CPC licensed internal code will be loaded (e.g. DPM mode or classic mode) and how much central storage and expanded storage will be used.
Image: For CPCs in classic mode, each LPAR can have an Image Activation Profile. The Image Activation Profile determines the number of CPs that the LPAR will use and whether these CPs will be dedicated to the LPAR or shared. It also allows assigning the amount of central storage and expanded storage that will be used by each LPAR.
Load: For CPCs in classic mode, each LPAR can have a Load Activation Profile. The Load Activation Profile defines the channel address of the device that the operating system for that LPAR will be loaded (booted) from.

class zhmcclient.ActivationProfileManager(cpc, profile_type)[source]¶

Manager providing access to the Activation Profiles of a particular type in a particular CPC (the scoping CPC).

Possible types of activation profiles are:

Reset Activation Profile
Image Activation Profile
Load Activation Profile

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variables of a Cpc object (in classic mode or ensemble mode):

reset_activation_profiles
image_activation_profiles
load_activation_profiles

Methods

`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the Activation Profiles of this CPC, of the profile type managed by this object.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`cpc`	CPC defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`profile_type`	Type of the Activation Profiles managed by this object:
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

cpc¶

CPC defining the scope for this manager.

Type:	`Cpc`

profile_type¶

Type of the Activation Profiles managed by this object:

'reset' - Reset Activation Profiles
'image' - Image Activation Profiles
'load' - Load Activation Profiles

Type:	string

list(full_properties=False, filter_args=None)[source]¶

List the Activation Profiles of this CPC, of the profile type managed by this object.

Authorization requirements:

Object-access permission to this CPC.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `ActivationProfile` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.ActivationProfile(manager, uri, name=None, properties=None)[source]¶

Representation of an Activation Profile of a particular type.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, ActivationProfileManager).

Methods

`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`update_properties`	Update writeable properties of this Activation Profile.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

update_properties(properties)[source]¶

Update writeable properties of this Activation Profile.

Authorization requirements:

Object-access permission to the CPC of this Activation Profile.
Task permission for the “Customize/Delete Activation Profiles” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘<profile_type> activation profile’ in the HMC API book, where <profile_type> is the profile type of this object (e.g. Reset, Load, Image).
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

LPARs¶

A LPAR (Logical Partition) is a subset of the hardware resources of a CPC in classic mode (or ensemble mode), virtualized as a separate computer.

LPARs cannot be created or deleted by the user; they can only be listed.

LPAR resources are contained in CPC resources.

LPAR resources only exist in CPCs that are in classic mode (or ensemble mode). CPCs in DPM mode have Partition resources, instead.

class zhmcclient.LparManager(cpc)[source]¶

Manager providing access to the LPARs in a particular CPC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Cpc object (in DPM mode):

lpars

Methods

`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the LPARs in this CPC.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`cpc`	CPC defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

cpc¶

CPC defining the scope for this manager.

Type:	`Cpc`

list(full_properties=False, filter_args=None)[source]¶

List the LPARs in this CPC.

Authorization requirements:

Object-access permission to this CPC.
Object-access permission to any LPAR to be included in the result.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `Lpar` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.Lpar(manager, uri, name=None, properties=None)[source]¶

Representation of an LPAR.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, LparManager).

Methods

`activate`	Activate (start) this LPAR, using the HMC operation “Activate Logical Partition”.
`deactivate`	De-activate (stop) this LPAR, using the HMC operation “Deactivate Logical Partition”.
`get_property`	Return the value of a resource property.
`load`	Load (boot) this LPAR from a load address (boot device), using the HMC operation “Load Logical Partition”.
`open_os_message_channel`	Open a JMS message channel to this LPAR’s operating system, returning the string “topic” representing the message channel.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`psw_restart`	Restart this LPAR, using the HMC operation “PSW Restart”.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`reset_clear`	Initialize this LPAR by clearing its pending interruptions, resetting its channel subsystem, and resetting its processors, using the HMC operation “Reset Clear”.
`scsi_dump`	Load a standalone dump program from a designated SCSI device in this LPAR, using the HMC operation “SCSI Dump”.
`scsi_load`	Load (boot) this LPAR from a designated SCSI device, using the HMC operation “SCSI Load”.
`send_os_command`	Send a command to the operating system running in this LPAR.
`stop`	Stop this LPAR, using the HMC operation “Stop Logical Partition”.
`update_properties`	Update writeable properties of this LPAR.
`wait_for_status`	Wait until the status of this LPAR has a desired value.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

update_properties(properties)[source]¶

Update writeable properties of this LPAR.

Authorization requirements:

Object-access permission to this LPAR.
Task permission for the “Change Object Definition” task.
Object-access permission to the CPC of this LPAR.
For an LPAR whose activation-mode is “zaware”, task permission for the “Firmware Details” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘Logical Partition object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

activate(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, activation_profile_name=None, force=False)[source]¶

Activate (start) this LPAR, using the HMC operation “Activate Logical Partition”.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “not-operating” (which indicates that the LPAR is active but no operating system is running), or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

Object-access permission to the CPC containing this LPAR.
Object-access permission to this LPAR.
Task permission for the “Activate” task.

Parameters:	wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “not-operating” (or in addition “exceptions”, if allow_status_exceptions was set. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised. status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `StatusTimeout` is raised. allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set. activation_profile_name (string) – Name of the image `ActivationProfile` to use for activation. None means that the activation profile specified in the next-activation-profile-name property of the LPAR is used. force (bool) – Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status. TBD: What will happen with the LPAR in that case (deactivated then activated? nothing?)
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation. `StatusTimeout` – The timeout expired while waiting for the desired LPAR status.

deactivate(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, force=False)[source]¶

De-activate (stop) this LPAR, using the HMC operation “Deactivate Logical Partition”.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “not-activated”, or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

Object-access permission to the CPC containing this LPAR.
Object-access permission to this LPAR.
Task permission for the “Deactivate” task.

Parameters:	wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “non-activated” (or in addition “exceptions”, if allow_status_exceptions was set. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised. status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `StatusTimeout` is raised. allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set. force (bool) – Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status. TBD: What will happen with the LPAR in that case (deactivated then activated? nothing?)
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation. `StatusTimeout` – The timeout expired while waiting for the desired LPAR status.

scsi_load(load_address, wwpn, lun, load_parameter=None, disk_partition_id=None, operating_system_specific_load_parameters=None, boot_record_logical_block_address=None, force=False, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]¶

Load (boot) this LPAR from a designated SCSI device, using the HMC operation “SCSI Load”.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

Object-access permission to the CPC containing this LPAR.
Object-access permission to this LPAR.
Task permission for the “SCSI Load” task.

Parameters:	load_address (string) – Device number of the boot device. wwpn (string) – Worldwide port name (WWPN) of the target SCSI device to be used for this operation, in hexadecimal. lun (string) – Hexadecimal logical unit number (LUN) to be used for the SCSI Load. load_parameter (string) – Optional load control string. If empty string or None, it is not passed to the HMC. disk_partition_id (integer) – Optional disk-partition-id (also called the boot program selector) to be used for the SCSI Load. If None, it is not passed to the HMC. operating_system_specific_load_parameters (string) – Optional operating system specific load parameters to be used for the SCSI Load. boot_record_logical_block_address (string) – Optional hexadecimal boot record logical block address to be used for the SCSI Load. force (bool) – Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status. The default value is True. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised. status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `StatusTimeout` is raised. allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation. `StatusTimeout` – The timeout expired while waiting for the desired LPAR status.

scsi_dump(load_address, wwpn, lun, load_parameter=None, disk_partition_id=None, operating_system_specific_load_parameters=None, boot_record_logical_block_address=None, os_ipl_token=None, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]¶

Load a standalone dump program from a designated SCSI device in this LPAR, using the HMC operation “SCSI Dump”.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

Object-access permission to the CPC containing this LPAR.
Object-access permission to this LPAR.
Task permission for the “SCSI Dump” task.

Parameters:	load_address (string) – Device number of the boot device. wwpn (string) – Worldwide port name (WWPN) of the target SCSI device to be used for this operation, in hexadecimal. lun (string) – Hexadecimal logical unit number (LUN) to be used for the SCSI Load. load_parameter (string) – Optional load control string. If empty string or None, it is not passed to the HMC. disk_partition_id (integer) – Optional disk-partition-id (also called the boot program selector) to be used for the SCSI Load. If None, it is not passed to the HMC. operating_system_specific_load_parameters (string) – Optional operating system specific load parameters to be used for the SCSI Load. boot_record_logical_block_address (string) – Optional hexadecimal boot record logical block address to be used for the SCSI Load. os_ipl_token (string) – Optional hexadecimal value to be used for the SCSI dump. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised. status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `StatusTimeout` is raised. allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation. `StatusTimeout` – The timeout expired while waiting for the desired LPAR status.

load(load_address=None, load_parameter=None, clear_indicator=True, store_status_indicator=False, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False, force=False)[source]¶

Load (boot) this LPAR from a load address (boot device), using the HMC operation “Load Logical Partition”.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

Object-access permission to the CPC containing this LPAR.
Object-access permission to this LPAR.
Task permission for the “Load” task.

Parameters:	load_address (string) – Device number of the boot device. Up to z13, this parameter is required. Starting with z14, this parameter is optional and defaults to the load address specified in the ‘last-used-load-address’ property of the Lpar. load_parameter (string) – Optional load control string. If empty string or None, it is not passed to the HMC. clear_indicator (bool) – Optional boolean controlling whether the memory should be cleared before performing the load or not cleared. The default value is True. store_status_indicator (bool) – Optional boolean controlling whether the status should be stored before performing the Load. The default value is False. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised. status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `StatusTimeout` is raised. allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set. force (bool) – Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status. TBD: What will happen with the LPAR in that case (deactivated then activated? nothing?)
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation. `StatusTimeout` – The timeout expired while waiting for the desired LPAR status.

stop(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]¶

Stop this LPAR, using the HMC operation “Stop Logical Partition”. The stop operation stops the processors from processing instructions.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

Object-access permission to the CPC containing this LPAR.
Object-access permission to this LPAR.
Task permission for the “Stop” task.

Parameters:	wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised. status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `StatusTimeout` is raised. allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation. `StatusTimeout` – The timeout expired while waiting for the desired LPAR status.

reset_clear(force=False, wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]¶

Initialize this LPAR by clearing its pending interruptions, resetting its channel subsystem, and resetting its processors, using the HMC operation “Reset Clear”.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

Object-access permission to the CPC containing this LPAR.
Object-access permission to this LPAR.
Task permission for the “Reset Clear” task.

Parameters:	force (bool) – Boolean controlling whether this operation is permitted when the LPAR is in the “operating” status. The default is False. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised. status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `StatusTimeout` is raised. allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation. `StatusTimeout` – The timeout expired while waiting for the desired LPAR status.

open_os_message_channel(include_refresh_messages=True)[source]¶

Open a JMS message channel to this LPAR’s operating system, returning the string “topic” representing the message channel.

Parameters:	include_refresh_messages (bool) – Boolean controlling whether refresh operating systems messages should be sent, as follows: If True, refresh messages will be recieved when the user connects to the topic. The default. If False, refresh messages will not be recieved when the user connects to the topic.
Returns:	Returns a string representing the os-message-notification JMS topic. The user can connect to this topic to start the flow of operating system messages.
Return type:	string
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

send_os_command(os_command_text, is_priority=False)[source]¶

Send a command to the operating system running in this LPAR.

Parameters:	os_command_text (string) – The text of the operating system command. is_priority (bool) – Boolean controlling whether this is a priority operating system command, as follows: If True, this message is treated as a priority operating system command. If False, this message is not treated as a priority operating system command. The default.
Returns:	None
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

psw_restart(wait_for_completion=True, operation_timeout=None, status_timeout=None, allow_status_exceptions=False)[source]¶

Restart this LPAR, using the HMC operation “PSW Restart”.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the LPAR status has reached the desired value. If wait_for_completion=True, this method repeatedly checks the status of the LPAR after the HMC operation has completed, and waits until the status is in the desired state “operating”, or if allow_status_exceptions was set additionally in the state “exceptions”.

Authorization requirements:

Object-access permission to the CPC containing this LPAR.
Object-access permission to this LPAR.
Task permission for the “PSW Restart” task.

Parameters:	wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation, and for the status becoming “operating” (or in addition “exceptions”, if allow_status_exceptions was set. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised. status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `StatusTimeout` is raised. allow_status_exceptions (bool) – Boolean controlling whether LPAR status “exceptions” is considered an additional acceptable end status when wait_for_completion is set.
Returns:	If wait_for_completion is True, returns None. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation. `StatusTimeout` – The timeout expired while waiting for the desired LPAR status.

wait_for_status(status, status_timeout=None)[source]¶

Wait until the status of this LPAR has a desired value.

Parameters:

status (string or iterable of string) –
Desired LPAR status or set of status values to reach; one or more of the following values:
- "not-activated" - The LPAR is not active.
- "not-operating" - The LPAR is active but no operating system is running in the LPAR.
- "operating" - The LPAR is active and an operating system is running in the LPAR.
- "exceptions" - The LPAR or its CPC has one or more unusual conditions.
Note that the description of LPAR status values in the HMC API book (as of its version 2.13.1) is partly confusing.
status_timeout (number) – Timeout in seconds, for waiting that the status of the LPAR has reached one of the desired status values. The special value 0 means that no timeout is set. None means that the default status timeout will be used. If the timeout expires , a StatusTimeout is raised.

Raises:

HTTPError
ParseError
AuthError
ConnectionError
StatusTimeout – The timeout expired while waiting for the desired LPAR status.

Partitions¶

A Partition is a subset of the hardware resources of a CPC in DPM mode, virtualized as a separate computer.

Partitions can be created and deleted dynamically, and their resources such as CPU, memory or I/O devices can be configured dynamically. You can create as many partition definitions as you want, but only a specific number of partitions can be active at any given time.

TODO: How can a user find out what the maximum is, before it is reached?

Partition resources are contained in CPC resources.

Partition resources only exist in CPCs that are in DPM mode. CPCs in classic mode (or ensemble mode) have LPAR resources, instead.

class zhmcclient.PartitionManager(cpc)[source]¶

Manager providing access to the Partitions in a particular CPC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Cpc object (in DPM mode):

partitions

Methods

`create`	Create and configure a Partition in this CPC.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the Partitions in this CPC.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`cpc`	CPC defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

cpc¶

CPC defining the scope for this manager.

Type:	`Cpc`

list(full_properties=False, filter_args=None)[source]¶

List the Partitions in this CPC.

Authorization requirements:

Object-access permission to this CPC.
Object-access permission to any Partition to be included in the result.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `Partition` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create and configure a Partition in this CPC.

Authorization requirements:

Object-access permission to this CPC.
Task permission to the “New Partition” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Partition’ in the HMC API book.
Returns:	The resource object for the new Partition. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	Partition
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.Partition(manager, uri, name=None, properties=None)[source]¶

Representation of a Partition.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, PartitionManager).

Methods

`attach_storage_group`	Attach a storage group to this partition.
`change_crypto_domain_config`	Change the access mode for a crypto domain that is currently included in the crypto configuration of this partition.
`decrease_crypto_config`	Remove crypto adapters and/or crypto domains from the crypto configuration of this partition.
`delete`	Delete this Partition.
`detach_storage_group`	Detach a storage group from this partition.
`dump_partition`	Dump this Partition, by loading a standalone dump program from a SCSI device and starting its execution, using the HMC operation ‘Dump Partition’.
`feature_enabled`	Indicates whether the specified feature is enabled for the CPC of this partition.
`feature_info`	Returns information about the features available for the CPC of this partition.
`get_property`	Return the value of a resource property.
`increase_crypto_config`	Add crypto adapters and/or crypto domains to the crypto configuration of this partition.
`list_attached_storage_groups`	Return the storage groups that are attached to this partition.
`mount_iso_image`	Upload an ISO image and associate it to this Partition using the HMC operation ‘Mount ISO Image’.
`open_os_message_channel`	Open a JMS message channel to this partition’s operating system, returning the string “topic” representing the message channel.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`psw_restart`	Initiates a PSW restart for this Partition, using the HMC operation ‘Perform PSW Restart’.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`send_os_command`	Send a command to the operating system running in this partition.
`start`	Start (activate) this Partition, using the HMC operation “Start Partition”.
`stop`	Stop (deactivate) this Partition, using the HMC operation “Stop Partition”.
`unmount_iso_image`	Unmount the currently mounted ISO from this Partition using the HMC operation ‘Unmount ISO Image’.
`update_properties`	Update writeable properties of this Partition.
`wait_for_status`	Wait until the status of this partition has a desired value.
`zeroize_crypto_domain`	Zeroize a single crypto domain on a crypto adapter.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`hbas`	Access to the HBAs in this Partition.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`nics`	Access to the NICs in this Partition.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.
`virtual_functions`	Access to the Virtual Functions in this Partition.

Details

nics¶

Access to the NICs in this Partition.

Type:	`NicManager`

hbas¶

Access to the HBAs in this Partition.

If the “dpm-storage-management” feature is enabled, this property is None.

Type:	`HbaManager`

virtual_functions¶

Access to the Virtual Functions in this Partition.

Type:	`VirtualFunctionManager`

feature_enabled(feature_name)[source]¶

Indicates whether the specified feature is enabled for the CPC of this partition.

The HMC must generally support features, and the specified feature must be available for the CPC.

For a list of available features, see section “Features” in the HMC API, or use the feature_info() method.

Authorization requirements:

Object-access permission to this partition.

Parameters:	feature_name (string) – The name of the feature.
Returns:	True if the feature is enabled, or False if the feature is disabled (but available).
Return type:	bool
Raises:	`ValueError` – Features are not supported on the HMC. `ValueError` – The specified feature is not available for the CPC. `HTTPError` `ParseError` `AuthError` `ConnectionError`

feature_info()[source]¶

Returns information about the features available for the CPC of this partition.

Authorization requirements:

Object-access permission to this partition.

Returns:

An iterable where each item represents one feature that is available for the CPC of this partition.

Each item is a dictionary with the following items:

name (unicode string): Name of the feature.
description (unicode string): Short description of the feature.
state (bool): Enablement state of the feature (True if the enabled, False if disabled).

Return type:

iterable

Raises:

ValueError – Features are not supported on the HMC.
HTTPError
ParseError
AuthError
ConnectionError

start(wait_for_completion=True, operation_timeout=None, status_timeout=None)[source]¶

Start (activate) this Partition, using the HMC operation “Start Partition”.

This HMC operation has deferred status behavior: If the asynchronous job on the HMC is complete, it takes a few seconds until the partition status has reached the desired value (it still may show status “paused”). If wait_for_completion=True, this method repeatedly checks the status of the partition after the HMC operation has completed, and waits until the status is in one of the desired states “active” or “degraded”.

TODO: Describe what happens if the maximum number of active partitions is exceeded.

Authorization requirements:

Object-access permission to this Partition.
Object-access permission to the CPC containing this Partition.
Task permission to the “Start Partition” task.

Parameters:	wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised. status_timeout (number) – Timeout in seconds, for waiting that the status of the partition has reached the desired status, after the HMC operation has completed. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `StatusTimeout` is raised.
Returns:	If wait_for_completion is True, returns an empty `dict` object. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	`dict` or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation. `StatusTimeout` – The timeout expired while waiting for the desired partition status.

stop(wait_for_completion=True, operation_timeout=None)[source]¶

Stop (deactivate) this Partition, using the HMC operation “Stop Partition”.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Stop Partition” task.

Parameters:	wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns an empty `dict` object. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	`dict` or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

delete()[source]¶

Delete this Partition.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Delete Partition” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this Partition.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Partition Details” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘Partition object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

dump_partition(parameters, wait_for_completion=True, operation_timeout=None)[source]¶

Dump this Partition, by loading a standalone dump program from a SCSI device and starting its execution, using the HMC operation ‘Dump Partition’.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Dump Partition” task.

Parameters:	parameters (dict) – Input parameters for the operation. Allowable input parameters are defined in section ‘Request body contents’ in section ‘Dump Partition’ in the HMC API book. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns an empty `dict` object. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	`dict` or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

psw_restart(wait_for_completion=True, operation_timeout=None)[source]¶

Initiates a PSW restart for this Partition, using the HMC operation ‘Perform PSW Restart’.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “PSW Restart” task.

Parameters:	wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested asynchronous HMC operation, as follows: If True, this method will wait for completion of the asynchronous job performing the operation. If False, this method will return immediately once the HMC has accepted the request to perform the operation. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns an empty `dict` object. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	`dict` or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

mount_iso_image(image, image_name, ins_file_name)[source]¶

Upload an ISO image and associate it to this Partition using the HMC operation ‘Mount ISO Image’.

When the partition already has an ISO image associated, the newly uploaded image replaces the current one.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Partition Details” task.

Parameters:

image (byte string or file-like object) –
The content of the ISO image.

Images larger than 2GB cannot be specified as a Byte string; they must be specified as a file-like object.

File-like objects must have opened the file in binary mode.
image_name (string) –
The displayable name of the image.

This value must be a valid Linux file name without directories, must not contain blanks, and must end with ‘.iso’ in lower case.

This value will be shown in the ‘boot-iso-image-name’ property of this partition.
ins_file_name (string) –
The path name of the INS file within the file system of the ISO image.

This value will be shown in the ‘boot-iso-ins-file’ property of this partition.

Raises:

unmount_iso_image()[source]¶

Unmount the currently mounted ISO from this Partition using the HMC operation ‘Unmount ISO Image’. This operation sets the partition’s ‘boot-iso-image-name’ and ‘boot-iso-ins-file’ properties to null.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Partition Details” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

open_os_message_channel(include_refresh_messages=True)[source]¶

Open a JMS message channel to this partition’s operating system, returning the string “topic” representing the message channel.

Parameters:	include_refresh_messages (bool) – Boolean controlling whether refresh operating systems messages should be sent, as follows: If True, refresh messages will be recieved when the user connects to the topic. The default. If False, refresh messages will not be recieved when the user connects to the topic.
Returns:	Returns a string representing the os-message-notification JMS topic. The user can connect to this topic to start the flow of operating system messages.
Return type:	string
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

send_os_command(os_command_text, is_priority=False)[source]¶

Send a command to the operating system running in this partition.

Parameters:	os_command_text (string) – The text of the operating system command. is_priority (bool) – Boolean controlling whether this is a priority operating system command, as follows: If True, this message is treated as a priority operating system command. If False, this message is not treated as a priority operating system command. The default.
Returns:	None
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

wait_for_status(status, status_timeout=None)[source]¶

Wait until the status of this partition has a desired value.

Parameters:

status (string or iterable of string) – Desired partition status or set of status values to reach; one or more of the values defined for the ‘status’ property in the data model for partitions in the HMC API book.
status_timeout (number) – Timeout in seconds, for waiting that the status of the partition has reached one of the desired status values. The special value 0 means that no timeout is set. None means that the default status timeout will be used. If the timeout expires, a StatusTimeout is raised.

Raises:

HTTPError
ParseError
AuthError
ConnectionError
StatusTimeout – The status timeout expired while waiting for the desired partition status.

increase_crypto_config(crypto_adapters, crypto_domain_configurations)[source]¶

Add crypto adapters and/or crypto domains to the crypto configuration of this partition.

The general principle for maintaining crypto configurations of partitions is as follows: Each adapter included in the crypto configuration of a partition has all crypto domains included in the crypto configuration. Each crypto domain included in the crypto configuration has the same access mode on all adapters included in the crypto configuration.

Example: Assume that the current crypto configuration of a partition includes crypto adapter A and crypto domains 0 and 1. When this method is called to add adapter B and domain configurations for domains 1 and 2, the resulting crypto configuration of the partition will include domains 0, 1, and 2 on each of the adapters A and B.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Partition Details” task.

Parameters:

crypto_adapters (iterable of Adapter) – Crypto adapters that should be added to the crypto configuration of this partition.
crypto_domain_configurations (iterable of domain_config) –
Crypto domain configurations that should be added to the crypto configuration of this partition.

A crypto domain configuration (domain_config) is a dictionary with the following keys:
- "domain-index" (integer): Domain index of the crypto domain.
  The domain index is a number in the range of 0 to a maximum that depends on the model of the crypto adapter and the CPC model. For the Crypto Express 5S adapter in a z13, the maximum domain index is 84.
- "access-mode" (string): Access mode for the crypto domain.
  The access mode specifies the way the partition can use the crypto domain on the crypto adapter(s), using one of the following string values:
  - "control" - The partition can load cryptographic keys into the domain, but it may not use the domain to perform cryptographic operations.
  - "control-usage" - The partition can load cryptographic keys into the domain, and it can use the domain to perform cryptographic operations.

Raises:

decrease_crypto_config(crypto_adapters, crypto_domain_indexes)[source]¶

Remove crypto adapters and/or crypto domains from the crypto configuration of this partition.

For the general principle for maintaining crypto configurations of partitions, see increase_crypto_config().

Example: Assume that the current crypto configuration of a partition includes crypto adapters A, B and C and crypto domains 0, 1, and 2 (on each of the adapters). When this method is called to remove adapter C and domain 2, the resulting crypto configuration of the partition will include domains 0 and 1 on each of the adapters A and B.

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Partition Details” task.

Parameters:	crypto_adapters (iterable of `Adapter`) – Crypto adapters that should be removed from the crypto configuration of this partition. crypto_domain_indexes (iterable of integer) – Domain indexes of the crypto domains that should be removed from the crypto configuration of this partition. For values, see `increase_crypto_config()`.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

change_crypto_domain_config(crypto_domain_index, access_mode)[source]¶

Change the access mode for a crypto domain that is currently included in the crypto configuration of this partition.

The access mode will be changed for the specified crypto domain on all crypto adapters currently included in the crypto configuration of this partition.

For the general principle for maintaining crypto configurations of partitions, see increase_crypto_config().

Authorization requirements:

Object-access permission to this Partition.
Task permission to the “Partition Details” task.

Parameters:	crypto_domain_index (integer) – Domain index of the crypto domain to be changed. For values, see `increase_crypto_config()`. access_mode (string) – The new access mode for the crypto domain. For values, see `increase_crypto_config()`.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

zeroize_crypto_domain(crypto_adapter, crypto_domain_index)[source]¶

Zeroize a single crypto domain on a crypto adapter.

Zeroizing a crypto domain clears the cryptographic keys and non-compliance mode settings in the crypto domain.

The crypto domain must be attached to this partition in “control-usage” access mode.

Supported CPC versions: z14 GA2 and above, and the corresponding LinuxOne systems.

Authorization requirements:

Object-access permission to this Partition and to the Crypto Adapter.
Task permission to the “Zeroize Crypto Domain” task.

Parameters:	crypto_adapter (`Adapter`) – Crypto adapter with the crypto domain to be zeroized. crypto_domain_index (integer) – Domain index of the crypto domain to be zeroized.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

attach_storage_group(storage_group)[source]¶

Attach a storage group to this partition.

This will cause the storage volumes of the storage group to be attached to the partition, instantiating any necessary virtual storage resource objects.

A storage group can be attached to a partition regardless of its fulfillment state. The fulfillment state of its storage volumes and thus of the entire storage group changes as volumes are discovered by DPM, and will eventually reach “complete”.

The CPC must have the “dpm-storage-management” feature enabled.

Authorization requirements:

Object-access permission to this partition.
Object-access permission to the specified storage group.
Task permission to the “Partition Details” task.

Parameters:	storage_group (`StorageGroup`) – Storage group to be attached. The storage group must not currently be attached to this partition.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

detach_storage_group(storage_group)[source]¶

Detach a storage group from this partition.

This will cause the storage volumes of the storage group to be detached from the partition, removing any virtual storage resource objects that had been created upon attachment.

A storage group can be detached from a partition regardless of its fulfillment state. The fulfillment state of its storage volumes changes as volumes are discovered by DPM.

The CPC must have the “dpm-storage-management” feature enabled.

Authorization requirements:

Object-access permission to this partition.
Task permission to the “Partition Details” task.

Parameters:	storage_group (`StorageGroup`) – Storage group to be detached. The storage group must currently be attached to this partition.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

list_attached_storage_groups(full_properties=False)[source]¶

Return the storage groups that are attached to this partition.

The CPC must have the “dpm-storage-management” feature enabled.

Authorization requirements:

Object-access permission to this partition.
Task permission to the “Partition Details” task.

Parameters:

full_properties (bool) –

Controls that the full set of resource properties for each returned storage group is being retrieved, vs. only the following short set: “object-uri”, “object-id”, “class”, “parent”.

TODO: Verify short list of properties.

Returns:

List of StorageGroup objects representing the storage groups that are attached to this partition.

Raises:

Adapters¶

An Adapter is a physical adapter card (e.g. OSA-Express adapter, Crypto adapter) or a logical adapter (e.g. HiperSockets switch).

Adapter resources are contained in CPC resources.

Adapters only exist in CPCs that are in DPM mode.

There are four types of Adapters:

Network Adapters: Network adapters enable communication through different networking transport protocols. These network adapters are OSA-Express, HiperSockets and RoCE-Express. DPM automatically discovers OSA-Express and RoCE-Express adapters because they are physical cards that are installed on the CPC. In contrast, HiperSockets are logical adapters and must be created and configured by an administrator using the ‘Create Hipersocket’ operation (see create_hipersocket()). Network Interface Cards (NICs) provide a partition with access to networks. Each NIC represents a unique connection between the partition and a specific network adapter.
Storage Adapters: Fibre Channel connections provide high-speed connections between CPCs and storage devices. DPM automatically discovers any storage adapters installed on the CPC. Host bus adapters (HBAs) provide a partition with access to external storage area networks (SANs) and devices that are connected to a CPC. Each HBA represents a unique connection between the partition and a specific storage adapter.
Accelerator Adapters: Accelerator adapters provide specialized functions to improve performance or use of computer resource like the IBM System z Enterprise Data Compression (zEDC) feature. DPM automatically discovers accelerators that are installed on the CPC. An accelerator virtual function provides a partition with access to zEDC features that are installed on a CPC. Each virtual function represents a unique connection between the partition and a physical feature card.
Crypto Adapters: Crypto adapters provide cryptographic processing functions. DPM automatically discovers cryptographic features that are installed on the CPC.

class zhmcclient.AdapterManager(cpc)[source]¶

Manager providing access to the Adapters in a particular CPC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Cpc object (in DPM mode):

adapters

Methods

`create_hipersocket`	Create and configure a HiperSockets Adapter in this CPC.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the Adapters in this CPC.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`cpc`	CPC defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

cpc¶

CPC defining the scope for this manager.

Type:	`Cpc`

list(full_properties=False, filter_args=None)[source]¶

List the Adapters in this CPC.

Authorization requirements:

Object-access permission to this CPC.
Object-access permission to any Adapter to be included in the result.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `Adapter` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create_hipersocket(properties)[source]¶

Create and configure a HiperSockets Adapter in this CPC.

Authorization requirements:

Object-access permission to the scoping CPC.
Task permission to the “Create HiperSockets Adapter” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Hipersocket’ in the HMC API book.
Returns:	The resource object for the new HiperSockets Adapter. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	`Adapter`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.Adapter(manager, uri, name=None, properties=None)[source]¶

Representation of an Adapter.

Derived from BaseResource; see there for common methods and attributes.

For the properties of an Adapter, see section ‘Data model’ in section ‘Adapter object’ in the HMC API book.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, AdapterManager).

Methods

`change_adapter_type`	Reconfigures an adapter from one type to another, or to ungonfigured.
`change_crypto_type`	Reconfigures a cryptographic adapter to a different crypto type.
`delete`	Delete this Adapter.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`update_properties`	Update writeable properties of this Adapter.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`maximum_crypto_domains`	The maximum number of crypto domains on this crypto adapter.
`name`	The name of the resource.
`port_type_by_family`
`port_uri_segment`	Adapter type specific URI segment for adapter port URIs, or the empty string (‘’) for adapters without ports.
`port_uri_segment_by_family`
`port_uris_prop`	Name of adapter property that specifies the adapter port URIs, or the empty string (‘’) for adapters without ports.
`port_uris_prop_by_family`
`ports`	Access to the Ports of this Adapter.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

ports¶

Access to the Ports of this Adapter.

Type:	`PortManager`

port_uris_prop¶

Name of adapter property that specifies the adapter port URIs, or the empty string (‘’) for adapters without ports.

For example, ‘network-port-uris’ for a network adapter.

Type:	string

port_uri_segment¶

Adapter type specific URI segment for adapter port URIs, or the empty string (‘’) for adapters without ports.

For example, ‘network-ports’ for a network adapter.

Type:	string

maximum_crypto_domains¶

The maximum number of crypto domains on this crypto adapter.

The following table shows the maximum number of crypto domains for crypto adapters supported on IBM Z machine generations in DPM mode. The corresponding LinuxONE machine generations are listed in the notes below the table:

Adapter type	Machine generations	Maximum domains
Crypto Express 5S	z14 (3) / z13 (1)	85
Crypto Express 5S	z14-ZR1 (4) / z13s (2)	40
Crypto Express 6S	z14 (3)	85
Crypto Express 6S	z14-ZR1 (4)	40

Notes:

Supported for z13 and LinuxONE Emperor
Supported for z13s and LinuxONE Rockhopper
Supported for z14 and LinuxONE Emperor II
Supported for z14-ZR1 and LinuxONE Rockhopper II

If this adapter is not a crypto adapter, None is returned.

If the crypto adapter card type is not known, ValueError is raised.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `ValueError` – Unknown crypto card type
Type:	Integer

delete()[source]¶

Delete this Adapter.

The Adapter must be a HiperSockets Adapter.

Authorization requirements:

Object-access permission to the HiperSockets Adapter to be deleted.
Task permission to the “Delete HiperSockets Adapter” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this Adapter.

Authorization requirements:

Object-access permission to the Adapter.
Task permission for the “Adapter Details” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘Adapter object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

__repr__()[source]¶: Return a string with the state of this Adapter, for debug purposes.

change_crypto_type(crypto_type, zeroize=None)[source]¶

Reconfigures a cryptographic adapter to a different crypto type. This operation is only supported for cryptographic adapters.

The cryptographic adapter must be varied offline before its crypto type can be reconfigured.

Authorization requirements:

Object-access permission to this Adapter.
Task permission to the “Adapter Details” task.

Parameters:

crypto_type (string) –
- "accelerator": Crypto Express5S Accelerator
- "cca-coprocessor": Crypto Express5S CCA Coprocessor
- "ep11-coprocessor": Crypto Express5S EP11 Coprocessor
zeroize (bool) – Specifies whether the cryptographic adapter will be zeroized when it is reconfigured to a crypto type of "accelerator". None means that the HMC-implemented default of True will be used.

Raises:

change_adapter_type(adapter_type)[source]¶

Reconfigures an adapter from one type to another, or to ungonfigured. Currently, only storage adapters can be reconfigured, and their adapter type is the supported storage protocol (FCP vs. FICON).

Storage adapter instances (i.e. Adapter objects) represent daughter cards on a physical storage card. Current storage cards require both daughter cards to be configured to the same protocol, so changing the type of the targeted adapter will also change the type of the adapter instance that represents the other daughter card on the same physical card. Zhmcclient users that need to determine the related adapter instance can do so by finding the storage adapter with a matching first 9 characters (card ID and slot ID) of their card-location property values.

The targeted adapter and its related adapter on the same storage card must not already have the desired adapter type, they must not be attached to any partition, and they must not have an adapter status of ‘exceptions’.

Authorization requirements:

Object-access permission to this Adapter.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:

adapter_type (string) –

"fcp": FCP (Fibre Channel Protocol)
"fc": FICON (Fibre Connection) protocol
"not-configured": No adapter type configured

Raises:

Ports¶

A Port is a physical connector port (jack) of an Adapter.

Port resources are contained in Adapter resources.

Ports only exist in CPCs that are in DPM mode.

class zhmcclient.PortManager(adapter, port_type)[source]¶

Manager providing access to the Ports of a particular Adapter.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible as properties in higher level resources (in this case, the Adapter object).

Methods

`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the Ports of this Adapter.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`adapter`	Adapter defining the scope for this manager.
`class_name`	The resource class name
`parent`	Parent resource defining the scope for this manager.
`port_type`	Type of the Ports managed by this object:
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

adapter¶

Adapter defining the scope for this manager.

Type:	`Adapter`

port_type¶

Type of the Ports managed by this object:

'network' - Ports of a network adapter
'storage' - Ports of a storage adapter
None - Adapter family without ports

Type:	string

list(full_properties=False, filter_args=None)[source]¶

List the Ports of this Adapter.

If the adapter does not have any ports, an empty list is returned.

Authorization requirements:

Object-access permission to this Adapter.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `Port` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.Port(manager, uri, name=None, properties=None)[source]¶

Representation of a Port.

Derived from BaseResource; see there for common methods and attributes.

For the properties of a Port, see section ‘Data model - Port Element Object’ in section ‘Adapter object’ in the HMC API book.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, PortManager).

Methods

`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`update_properties`	Update writeable properties of this Port.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

update_properties(properties)[source]¶

Update writeable properties of this Port.

Authorization requirements:

Object-access permission to the Adapter of this Port.
Task permission to the “Adapter Details” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model - Port Element Object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

NICs¶

A NIC (Network Interface Card) is a logical entity that provides a Partition with access to external communication networks through a Network Adapter. More specifically, a NIC connects a Partition with a Network Port, or with a Virtual Switch which then connects to the Network Port.

NIC resources are contained in Partition resources.

NICs only exist in CPCs that are in DPM mode.

class zhmcclient.NicManager(partition)[source]¶

Manager providing access to the NICs in a particular Partition.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Partition object (in DPM mode):

nics

Methods

`create`	Create and configure a NIC in this Partition.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the NICs in this Partition.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`parent`	Parent resource defining the scope for this manager.
`partition`	Partition defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

partition¶

Partition defining the scope for this manager.

Type:	`Partition`

list(full_properties=False, filter_args=None)[source]¶

List the NICs in this Partition.

Authorization requirements:

Object-access permission to this Partition.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `Nic` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create and configure a NIC in this Partition.

The NIC must be backed by an adapter port (on an OSA, ROCE, or Hipersockets adapter).

The way the backing adapter port is specified in the “properties” parameter of this method depends on the adapter type, as follows:

For OSA and Hipersockets adapters, the “virtual-switch-uri” property is used to specify the URI of the virtual switch that is associated with the backing adapter port.

This virtual switch is a resource that automatically exists as soon as the adapter resource exists. Note that these virtual switches do not show up in the HMC GUI; but they do show up at the HMC REST API and thus also at the zhmcclient API as the VirtualSwitch class.

The value for the “virtual-switch-uri” property can be determined from a given adapter name and port index as shown in the following example code (omitting any error handling):
```
partition = ...  # Partition object for the new NIC

adapter_name = 'OSA #1'  # name of adapter with backing port
adapter_port_index = 0   # port index of backing port

adapter = partition.manager.cpc.adapters.find(name=adapter_name)

vswitches = partition.manager.cpc.virtual_switches.findall(
    **{'backing-adapter-uri': adapter.uri})

vswitch = None
for vs in vswitches:
    if vs.get_property('port') == adapter_port_index:
        vswitch = vs
        break

properties['virtual-switch-uri'] = vswitch.uri
```

For RoCE adapters, the “network-adapter-port-uri” property is used to specify the URI of the backing adapter port, directly.

The value for the “network-adapter-port-uri” property can be determined from a given adapter name and port index as shown in the following example code (omitting any error handling):

partition = ...  # Partition object for the new NIC

adapter_name = 'ROCE #1'  # name of adapter with backing port
adapter_port_index = 0   # port index of backing port

adapter = partition.manager.cpc.adapters.find(name=adapter_name)

port = adapter.ports.find(index=adapter_port_index)

properties['network-adapter-port-uri'] = port.uri

Authorization requirements:

Object-access permission to this Partition.
Object-access permission to the backing Adapter for the new NIC.
Task permission to the “Partition Details” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create NIC’ in the HMC API book.
Returns:	The resource object for the new NIC. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	Nic
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.Nic(manager, uri, name=None, properties=None)[source]¶

Representation of a NIC.

Derived from BaseResource; see there for common methods and attributes.

For the properties of a NIC resource, see section ‘Data model - NIC Element Object’ in section ‘Partition object’ in the HMC API book.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, NicManager).

Methods

`delete`	Delete this NIC.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`update_properties`	Update writeable properties of this NIC.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

delete()[source]¶

Delete this NIC.

Authorization requirements:

Object-access permission to the Partition containing this HBA.
Task permission to the “Partition Details” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this NIC.

Authorization requirements:

Object-access permission to the Partition containing this NIC.
Object-access permission to the backing Adapter for this NIC.
Task permission to the “Partition Details” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model - NIC Element Object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

HBAs¶

A HBA (Host Bus Adapter) is a logical entity that provides a Partition with access to external storage area networks (SANs) through an FCP Adapter. More specifically, an HBA connects a Partition with an Adapter Port on an FCP Adapter.

HBA resources are contained in Partition resources.

HBA resources only exist in CPCs that are in DPM mode and when the “dpm-storage-management” feature is not enabled. See section Storage Groups for details. When the “dpm-storage-management” feature is enabled, virtual HBAs are represented as Virtual Storage Resource resources.

class zhmcclient.HbaManager(partition)[source]¶

Manager providing access to the HBAs in a particular Partition.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Partition object (in DPM mode):

hbas

Note that this instance variable will be None if the “dpm-storage-management” feature is enabled.

Methods

`create`	Create and configure an HBA in this Partition.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the HBAs in this Partition.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`parent`	Parent resource defining the scope for this manager.
`partition`	Partition defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

partition¶

Partition defining the scope for this manager.

Type:	`Partition`

list(full_properties=False, filter_args=None)[source]¶

List the HBAs in this Partition.

The returned HBAs have only the ‘element-uri’ property set.

Filtering is supported only for the ‘element-uri’ property.

Authorization requirements:

Object-access permission to this Partition.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `Hba` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create and configure an HBA in this Partition.

The HBA must be backed by an adapter port on an FCP adapter.

The backing adapter port is specified in the “properties” parameter of this method by setting the “adapter-port-uri” property to the URI of the backing adapter port.

The value for the “adapter-port-uri” property can be determined from a given adapter name and port index as shown in the following example code (omitting any error handling):

partition = ...  # Partition object for the new HBA

adapter_name = 'FCP #1'  # name of adapter with backing port
adapter_port_index = 0   # port index of backing port

adapter = partition.manager.cpc.adapters.find(name=adapter_name)

port = adapter.ports.find(index=adapter_port_index)

properties['adapter-port-uri'] = port.uri

Authorization requirements:

Object-access permission to this Partition.
Object-access permission to the backing Adapter for the new HBA.
Task permission to the “Partition Details” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create HBA’ in the HMC API book.
Returns:	The resource object for the new HBA. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	Hba
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.Hba(manager, uri, name=None, properties=None)[source]¶

Representation of an HBA.

Derived from BaseResource; see there for common methods and attributes.

For the properties of an HBA resource, see section ‘Data model - HBA Element Object’ in section ‘Partition object’ in the HMC API book.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, HbaManager).

Methods

`delete`	Delete this HBA.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`reassign_port`	Reassign this HBA to a new underlying FCP port.
`update_properties`	Update writeable properties of this HBA.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

delete()[source]¶

Delete this HBA.

Authorization requirements:

Object-access permission to the Partition containing this HBA.
Task permission to the “Partition Details” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this HBA.

Authorization requirements:

Object-access permission to the Partition containing this HBA.
TBD: Verify: Object-access permission to the backing Adapter for this HBA.
Task permission to the “Partition Details” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model - HBA Element Object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

reassign_port(port)[source]¶

Reassign this HBA to a new underlying FCP port.

This method performs the HMC operation “Reassign Storage Adapter Port”.

Authorization requirements:

Object-access permission to the Partition containing this HBA.
Object-access permission to the Adapter with the new Port.
Task permission to the “Partition Details” task.

Parameters:	port (`Port`) – FCP port to be used.
Raises:	`HTTPError` – See the HTTP status and reason codes of operation “Reassign Storage Adapter Port” in the HMC API book. `ParseError` `AuthError` `ConnectionError`

Virtual Functions¶

A Virtual Function is a logical entity that provides a Partition with access to Accelerator Adapters.

Virtual Function resources are contained in Partition resources.

Virtual Functions only exist in CPCs that are in DPM mode.

class zhmcclient.VirtualFunctionManager(partition)[source]¶

Manager providing access to the Virtual Functions in a particular Partition.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Partition object (in DPM mode):

virtual_functions

Methods

`create`	Create a Virtual Function in this Partition.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the Virtual Functions of this Partition.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`parent`	Parent resource defining the scope for this manager.
`partition`	Partition defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

partition¶

Partition defining the scope for this manager.

Type:	`Partition`

list(full_properties=False, filter_args=None)[source]¶

List the Virtual Functions of this Partition.

Authorization requirements:

Object-access permission to this Partition.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `VirtualFunction` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create a Virtual Function in this Partition.

Authorization requirements:

Object-access permission to this Partition.
Object-access permission to the backing accelerator Adapter.
Task permission for the “Partition Details” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Virtual Function’ in the HMC API book.
Returns:	The resource object for the new Virtual Function. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	VirtualFunction
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.VirtualFunction(manager, uri, name=None, properties=None)[source]¶

Representation of a Virtual Function.

Derived from BaseResource; see there for common methods and attributes.

For the properties of a Virtual Function, see section ‘Data model - Virtual Function Element Object’ in section ‘Partition object’ in the HMC API book.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, VirtualFunctionManager).

Methods

`delete`	Delete this Virtual Function.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`update_properties`	Update writeable properties of this Virtual Function.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

delete()[source]¶

Delete this Virtual Function.

Authorization requirements:

Object-access permission to the Partition of this Virtual Function.
Task permission for the “Partition Details” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this Virtual Function.

Authorization requirements:

Object-access permission to the Partition of this Virtual Function.
When updating the “adapter-uri” property, object-access permission to the Adapter identified in that URI.
Task permission for the “Partition Details” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model - Virtual Function element object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Virtual Switches¶

A Virtual Switch is a virtualized networking switch connecting NICs with a Network Port.

Virtual Switches are generated automatically every time a new Network Adapter is detected and configured.

Virtual Switch resources are contained in CPC resources.

Virtual Switches only exist in CPCs that are in DPM mode.

class zhmcclient.VirtualSwitchManager(cpc)[source]¶

Manager providing access to the Virtual Switches in a particular CPC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Cpc object (in DPM mode):

virtual_switches

Methods

`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the Virtual Switches in this CPC.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`cpc`	CPC defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

cpc¶

CPC defining the scope for this manager.

Type:	`Cpc`

list(full_properties=False, filter_args=None)[source]¶

List the Virtual Switches in this CPC.

Authorization requirements:

Object-access permission to this CPC.
Object-access permission to the backing Adapters of any Virtual Switches to be included in the result.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `VirtualSwitch` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.VirtualSwitch(manager, uri, name=None, properties=None)[source]¶

Representation of a Virtual Switch.

Derived from BaseResource; see there for common methods and attributes.

For the properties of a Virtual Switch, see section ‘Data model’ in section ‘Virtual Switch object’ in the HMC API book.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, VirtualSwitchManager).

Methods

`get_connected_nics`	List the NICs connected to this Virtual Switch.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`update_properties`	Update writeable properties of this Virtual Switch.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

get_connected_nics()[source]¶

List the NICs connected to this Virtual Switch.

This method performs the “Get Connected VNICs of a Virtual Switch” HMC operation.

Authorization requirements:

Object-access permission to this CPC.
Object-access permission to the backing Adapter of this Virtual Switch.

Returns:

A list of Nic objects. These objects will be connected in the resource tree (i.e. have a parent Partition object, etc.) and will have the following properties set:

element-uri
element-id
parent
class

Raises:

update_properties(properties)[source]¶

Update writeable properties of this Virtual Switch.

Authorization requirements:

Object-access permission to the backing Adapter of this Virtual Switch.
Task permission for the “Manage Adapters” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘Virtual Switch object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Storage Groups¶

Starting with the z14-ZR1 and LinuxONE Rockhopper II machine generations, the “dpm-storage-management” firmware feature has been introduced to support a simpler management of FCP and FICON (=ECKD) storage for DPM mode. If machines of these generations are in DPM mode, the feature is always enabled and cannot be disabled.

When the “dpm-storage-management” feature is enabled, storage group and storage volume resources can be defined on the HMC, and can cause fulfillment requests to be sent via email to storage administrators. Once these requests are satisfied on the actual storage subsystem and possibly SAN switches, the changes are automatically discovered by DPM and reflected in the state of these resources. Thus, the allocation of actual storage volumes on the storage subsystem is not performed by DPM.

The sending of email is optional, and if the changes are done by some automation tool, they will also be discovered automatically. That way, the whole process of allocating and attaching volumes can be fully automated, if so desired.

The top level resource objects are storage groups. Storage groups are defined globally at the HMC level, and are associated with a CPC. They can only be associated with one CPC at a time. In the zhmcclient, the StorageGroup objects are accessible via the storage_groups property.

Storage groups are a grouping mechanism for storage volumes. An FCP-type storage group can contain only FCP type storage volumes, and a FICON-type storage group can contain only FICON/ECKD type storage volumes.

Attachment and detachment of volumes to a partition happens at the level of storage groups, and always applies to all volumes defined in the storage group.

The storage-related z/Architecture devices that are visible to a partition are different for the two storage architectures: For FCP, the virtualized HBA is visible as a device, and the storage volumes (LUNs) are not represented as devices. For FICON, each ECKD volume is visible as a device, but the virtualized FICON adapter port is not represented as a device. When the “dpm-storage-management” feature is enabled, each storage-related z/Architecture device that is visible to a partition is represented as a virtual storage resource object. The virtual storage resource objects are instantiated automatically when a storage group is attached to a partition. The HBA resource objects known from DPM mode before the introduction of the “dpm-storage-management” feature are not exposed anymore (their equivalent are now the virtual storage resource objects).

Single storage volumes cannot be attached to partitions, only entire storage groups can be. In fact, storage volume objects do not even exist outside the scope of storage groups. A particular storage volume can be contained in only one storage group.

Storage groups can be listed, created, deleted, and updated, and their storage volumes can also be listed, created, deleted, and updated.

Storage groups can be attached to zero or more partitions. Attachment to multiple partitions at the same time is possible for storage groups that are defined to be shareable. In case of multiple attachments of a storage group, it contains the storage volume objects only once for all attachments, but the virtual storage resource objects are instantiated separately for each attachment.

Storage groups can only be associated with CPCs that have the “dpm-storage-management” feature enabled.

class zhmcclient.StorageGroupManager(console)[source]¶

Manager providing access to the storage groups of the HMC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable:

storage_groups of a Console object.

console¶

The Console object representing the HMC.

Type:	`Console`

list(full_properties=False, filter_args=None)[source]¶

List the storage groups defined in the HMC.

Storage groups for which the authenticated user does not have object-access permission are not included.

Authorization requirements:

Object-access permission to any storage groups to be included in the result.

Parameters:	full_properties (bool) – Controls that the full set of resource properties for each returned storage volume is being retrieved, vs. only the following short set: “object-uri”, “cpc-uri”, “name”, “fulfillment-state”, and “type”. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen.
Returns:	A list of `StorageGroup` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties=None, template=None)[source]¶

Create and configure a storage group either from input properties or from a storage group template.

The input properties may specify initial storage volumes for the new storage group via the storage-volumes property. Additional storage volumes can be added with update_properties().

A storage group template can also specify initial storage volumes for the new storage group. For details, see StorageGroupTemplate.

The new storage group will be associated with the CPC identified by the cpc-uri input property.

Authorization requirements:

Object-access permission to the CPC that will be associated with the new storage group.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Storage Group’ in the HMC API book. The ‘cpc-uri’ property identifies the CPC to which the new storage group will be associated, and is required to be specified in this parameter. The ‘template-uri’ property is not allowed. If you want to create a storage group from a storage template, specify the template parameter. The properties and template parameters are mutually exclusive. template (`StorageGroupTemplate`) – storage group template defining the initial property values for the storage group, including its initial storage volumes.
Returns:	The resource object for the new storage group. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	`StorageGroup`
Raises:	`ValueError` - Property ‘template-uri’ is not permitted `HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.StorageGroup(manager, uri, name=None, properties=None)[source]¶

Representation of a storage group.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, StorageGroupManager).

storage_volumes¶

Access to the storage volumes in this storage group.

Type:	`StorageVolumeManager`

virtual_storage_resources¶

Access to the virtual storage resources in this storage group.

Type:	`VirtualStorageResourceManager`

cpc¶

The CPC to which this storage group is associated.

The returned Cpc has only a minimal set of properties populated.

Type:	`Cpc`

list_attached_partitions(name=None, status=None)[source]¶

Return the partitions to which this storage group is currently attached, optionally filtered by partition name and status.

Authorization requirements:

Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	name (string) – Filter pattern (regular expression) to limit returned partitions to those that have a matching name. If None, no filtering for the partition name takes place. status (string) – Filter string to limit returned partitions to those that have a matching status. The value must be a valid partition status property value. If None, no filtering for the partition status takes place.
Returns:	List of `Partition` objects representing the partitions to whivch this storage group is currently attached, with a minimal set of properties (‘object-id’, ‘name’, ‘status’).
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

delete(email_to_addresses=None, email_cc_addresses=None, email_insert=None)[source]¶

Delete this storage group and its storage volume resources on the HMC, and optionally send emails to storage administrators requesting deletion of the storage volumes on the storage subsystem and cleanup of any resources related to the storage group (e.g. zones on a SAN switch, or host objects on a storage subsystem).

Authorization requirements:

Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:

email_to_addresses (iterable of string) – Email addresses of one or more storage administrator to be notified. If None or empty, no email will be sent.
email_cc_addresses (iterable of string) – Email addresses of one or more storage administrator to be copied on the notification email. If None or empty, nobody will be copied on the email. Must be None or empty if email_to_addresses is None or empty.
email_insert (string) – Additional text to be inserted in the notification email. The text can include HTML formatting tags. If None, no additional text will be inserted. Must be None or empty if email_to_addresses is None or empty.

Raises:

HTTPError
ParseError
AuthError
ConnectionError
ValueError – Incorrect input arguments

update_properties(properties)[source]¶

Update writeable properties of this storage group.

This includes the storage-volumes property which contains requests for creations, deletions and updates of StorageVolume resources of this storage group. As an alternative to this bulk approach for managing storage volumes, each StorageVolume resource can individually be created, deleted and updated using the respective methods on storage_volumes.

Authorization requirements:

Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are listed for operation ‘Modify Storage Group Properties’ in section ‘Storage Group object’ in the HMC API book. This includes the email addresses of the storage administrators.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

add_candidate_adapter_ports(ports)[source]¶

Add a list of storage adapter ports to this storage group’s candidate adapter ports list.

This operation only applies to storage groups of type “fcp”.

These adapter ports become candidates for use as backing adapters when creating virtual storage resources when the storage group is attached to a partition. The adapter ports should have connectivity to the storage area network (SAN).

Candidate adapter ports may only be added before the CPC discovers a working communications path, indicated by a “verified” status on at least one of this storage group’s WWPNs. After that point, all adapter ports in the storage group are automatically detected and manually adding them is no longer possible.

Because the CPC discovers working communications paths automatically, candidate adapter ports do not need to be added by the user. Any ports that are added, are validated by the CPC during discovery, and may or may not actually be used.

Authorization requirements:

Object-access permission to this storage group.
Object-access permission to the adapter of each specified port.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	ports (`list`) – List of `Port` objects representing the ports to be added. All specified ports must not already be members of this storage group’s candidate adapter ports list.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

remove_candidate_adapter_ports(ports)[source]¶

Remove a list of storage adapter ports from this storage group’s candidate adapter ports list.

This operation only applies to storage groups of type “fcp”.

Because the CPC discovers working communications paths automatically, candidate adapter ports do not need to be managed by the user. Any ports that are removed using this function, might actually be added again by the CPC dependent on the results of discovery.

Authorization requirements:

Object-access permission to this storage group.
Object-access permission to the adapter of each specified port.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	ports (`list`) – List of `Port` objects representing the ports to be removed. All specified ports must currently be members of this storage group’s candidate adapter ports list and must not be referenced by any of the group’s virtual storage resources.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

list_candidate_adapter_ports(full_properties=False)[source]¶

Return the current candidate storage adapter port list of this storage group.

The result reflects the actual list of ports used by the CPC, including any changes that have been made during discovery. The source for this information is the ‘candidate-adapter-port-uris’ property of the storage group object.

Parameters:

full_properties (bool) –

Controls that the full set of resource properties for each returned candidate storage adapter port is being retrieved, vs. only the following short set: “element-uri”, “element-id”, “class”, “parent”.

TODO: Verify short list of properties.

Returns:

List of Port objects representing the current candidate storage adapter ports of this storage group.

Raises:

discover_fcp(force_restart=False, wait_for_completion=True, operation_timeout=None)[source]¶

Perform Logical Unit Number (LUN) discovery for this FCP storage group. The corresponding HMC operation is “Start FCP Storage Discovery”.

This operation only applies to storage groups of type “fcp”.

The HMC performs the LUN discovery in an asynchronous job. This method supports waiting for completion of the job and thus the LUN discovery, or returning immediately after the HMC has started the asynchronous job.

When the LUN discovery is completed, a connection report will have been created that reflects the results of the discovery. The connection report can be retrieved with get_connection_report(). It is recommended to retrieve the connection report and verify that it reports correct volumes.

Authorization requirements:

Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task or to the “Configure Storage - Storage Administrator” task.

Parameters:	force_restart (bool) – Indicates if there is an in-progress discovery operation for the specified storage group, it should be terminated and started again. If False or there is no in-progress discovery operation for the specified storage group, a new one is started. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the asynchronous job performing the LUN discovery. operation_timeout (number) – Timeout in seconds, for waiting for completion of the asynchronous job performing the LUN discovery. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_completion=True, a `OperationTimeout` is raised.
Returns:	If wait_for_completion is True, returns nothing. If wait_for_completion is False, returns a `Job` object representing the asynchronously executing job on the HMC.
Return type:	None or `Job`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError` `OperationTimeout` – The timeout expired while waiting for completion of the operation.

get_connection_report()[source]¶

Get the latest connection report for this storage group.

The corresponding HMC operation is “Get Connection Report”.

The connection report is updated when LUN discovery is performed. LUN discovery for FCP storage groups is performed automatically based on certain triggers, and regularly every 10 minutes, and can additionally be triggered with discover_fcp().

To verify that the correct volumes are reported for an FCP storage group, verify that the property volumes-configuration-status has a value of “correct-volumes” for all WWPNs in all FCP subsystems:

report = storage_group.get_connection_report()
for subsys in report['fcp-storage-subsystems']:
    for config in subsys['storage-configurations']:
        if config['volumes-configuration-status'] != "correct-volumes":
            # report incorrect volumes

Authorization requirements:

Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task or to the “Configure Storage - Storage Administrator” task.

Returns:	A JSON object with the connection report. For details about the items in the JSON object, see section ‘Response body contents’ in section ‘Get Connection Report’ in the HMC API book.
Return type:	json object
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Storage Volumes¶

A StorageVolume object represents an FCP or FICON (ECKD) storage volume that is defined in a storage group.

Storage volume objects can be created, but what is created is the definition of a storage volume in the HMC and CPC. This does not include the act of actually allocating the volume on a storage subsystem. That is performed by a storage administrator who fulfills the volumes.

In order to represent that, storage volume objects have a fulfillment state that is available in their ‘fulfillment-state’ property.

When a storage group is attached to a partition, the group’s storage volumes are attached to the partition and any virtual storage resource objects are instantiated.

Storage volumes are contained in storage groups.

You can create as many storage volumes as you want in a storage group.

Storage groups and storage volumes only can be defined in CPCs that are in DPM mode and that have the “dpm-storage-management” feature enabled.

class zhmcclient.StorageVolumeManager(storage_group)[source]¶

Manager providing access to the storage volumes in a particular storage group.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a StorageGroup object:

storage_volumes

storage_group¶

Storage group defining the scope for this manager.

Type:	`StorageGroup`

list(full_properties=False, filter_args=None)[source]¶

List the storage volumes in this storage group.

Authorization requirements:

Object-access permission to this storage group.

Parameters:	full_properties (bool) – Controls that the full set of resource properties for each returned storage volume is being retrieved, vs. only the following short set: “element-uri”, “name”, “fulfillment-state”, “size”, and “usage”. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `StorageVolume` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties, email_to_addresses=None, email_cc_addresses=None, email_insert=None)[source]¶

Create a storage volume in this storage group on the HMC, and optionally send emails to storage administrators requesting creation of the storage volume on the storage subsystem and setup of any resources related to the storage volume (e.g. LUN mask definition on the storage subsystem).

This method performs the “Modify Storage Group Properties” operation, requesting creation of the volume.

Authorization requirements:

Object-access permission to this storage group.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	properties (dict) – Initial property values for the new volume. Allowable properties are the fields defined in the “storage-volume-request-info” nested object described for operation “Modify Storage Group Properties” in the HMC API book. The valid fields are those for the “create” operation. The operation field must not be provided; it is set automatically to the value “create”. The properties provided in this parameter will be copied and then amended with the operation=”create” field, and then used as a single array item for the storage-volumes field in the request body of the “Modify Storage Group Properties” operation. Note that for storage volumes, the HMC does auto-generate a value for the “name” property, but that auto-generated name is not unique within the parent storage group. If you depend on a unique name, you need to specify a “name” property accordingly. email_to_addresses (iterable of string) – Email addresses of one or more storage administrator to be notified. If None or empty, no email will be sent. email_cc_addresses (iterable of string) – Email addresses of one or more storage administrator to be copied on the notification email. If None or empty, nobody will be copied on the email. Must be None or empty if email_to_addresses is None or empty. email_insert (string) – Additional text to be inserted in the notification email. The text can include HTML formatting tags. If None, no additional text will be inserted. Must be None or empty if email_to_addresses is None or empty.
Returns:	The resource object for the new storage volume. The object will have the following properties set: ’element-uri’ as returned by the HMC ’element-id’ as determined from the ‘element-uri’ property ’class’ and ‘parent’ additional properties as specified in the input properties
Return type:	StorageVolume
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Example:

stovol1 = fcp_stogrp.storage_volumes.create(
    properties=dict(
        name='vol1',
        size=30,  # GiB
))

class zhmcclient.StorageVolume(manager, uri, name=None, properties=None)[source]¶

Representation of a storage volume.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, StorageVolumeManager).

oid¶

term unicode string: The object ID of this storage volume. The object ID is unique within the parent storage group.

Note that for storage volumes, the ‘name’ property is not unique and therefore cannot be used to identify a storage volume. Therefore, storage volumes provide easy access to the object ID, as a means to identify the storage volume in CLIs and other string-based tooling.

delete(email_to_addresses=None, email_cc_addresses=None, email_insert=None)[source]¶

Delete this storage volume on the HMC, and optionally send emails to storage administrators requesting deletion of the storage volume on the storage subsystem and cleanup of any resources related to the storage volume (e.g. LUN mask definitions on a storage subsystem).

This method performs the “Modify Storage Group Properties” operation, requesting deletion of the volume.

Authorization requirements:

Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:

email_to_addresses (iterable of string) – Email addresses of one or more storage administrator to be notified. If None or empty, no email will be sent.
email_cc_addresses (iterable of string) – Email addresses of one or more storage administrator to be copied on the notification email. If None or empty, nobody will be copied on the email. Must be None or empty if email_to_addresses is None or empty.
email_insert (string) – Additional text to be inserted in the notification email. The text can include HTML formatting tags. If None, no additional text will be inserted. Must be None or empty if email_to_addresses is None or empty.

Raises:

update_properties(properties, email_to_addresses=None, email_cc_addresses=None, email_insert=None)[source]¶

Update writeable properties of this storage volume on the HMC, and optionally send emails to storage administrators requesting modification of the storage volume on the storage subsystem and of any resources related to the storage volume.

This method performs the “Modify Storage Group Properties” operation, requesting modification of the volume.

Authorization requirements:

Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:

properties (dict) –
New property values for the volume. Allowable properties are the fields defined in the “storage-volume-request-info” nested object for the “modify” operation. That nested object is described in section “Request body contents” for operation “Modify Storage Group Properties” in the HMC API book.

The properties provided in this parameter will be copied and then amended with the operation=”modify” and element-uri properties, and then used as a single array item for the storage-volumes field in the request body of the “Modify Storage Group Properties” operation.
email_to_addresses (iterable of string) – Email addresses of one or more storage administrator to be notified. If None or empty, no email will be sent.
email_cc_addresses (iterable of string) – Email addresses of one or more storage administrator to be copied on the notification email. If None or empty, nobody will be copied on the email. Must be None or empty if email_to_addresses is None or empty.
email_insert (string) – Additional text to be inserted in the notification email. The text can include HTML formatting tags. If None, no additional text will be inserted. Must be None or empty if email_to_addresses is None or empty.

Raises:

indicate_fulfillment_ficon(control_unit, unit_address)[source]¶

TODO: Add ControlUnit objects etc for FICON support.

Indicate completion of fulfillment for this ECKD (=FICON) storage volume and provide identifying information (control unit and unit address) about the actual storage volume on the storage subsystem.

Manually indicating fulfillment is required for all ECKD volumes, because they are not auto-discovered by the CPC.

This method performs the “Fulfill FICON Storage Volume” HMC operation.

Upon successful completion of this operation, the “fulfillment-state” property of this storage volume object will have been set to “complete”. That is necessary for the CPC to be able to address and connect to the volume.

If the “fulfillment-state” properties of all storage volumes in the owning storage group are “complete”, the owning storage group’s “fulfillment-state” property will also be set to “complete”.

Parameters:	control_unit (`ControlUnit`) – Logical control unit (LCU) in which the backing ECKD volume is defined. unit_address (string) – Unit address of the backing ECKD volume within its logical control unit, as a hexadecimal number of up to 2 characters in any lexical case.

Authorization requirements:

Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - Storage Administrator” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

indicate_fulfillment_fcp(wwpn, lun, host_port)[source]¶

Indicate completion of fulfillment for this FCP storage volume and provide identifying information (WWPN and LUN) about the actual storage volume on the storage subsystem.

Manually indicating fulfillment is required for storage volumes that will be used as boot devices for a partition. The specified host port will be used to access the storage volume during boot of the partition.

Because the CPC discovers storage volumes automatically, the fulfillment of non-boot volumes does not need to be manually indicated using this function (it may be indicated though before the CPC discovers a working communications path to the volume, but the role of the specified host port is not clear in this case).

This method performs the “Fulfill FCP Storage Volume” HMC operation.

Upon successful completion of this operation, the “fulfillment-state” property of this storage volume object will have been set to “complete”. That is necessary for the CPC to be able to address and connect to the volume.

If the “fulfillment-state” properties of all storage volumes in the owning storage group are “complete”, the owning storage group’s “fulfillment-state” property will also be set to “complete”.

Parameters:

wwpn (string) – World wide port name (WWPN) of the FCP storage subsystem containing the storage volume, as a hexadecimal number of up to 16 characters in any lexical case.
lun (string) – Logical Unit Number (LUN) of the storage volume within its FCP storage subsystem, as a hexadecimal number of up to 16 characters in any lexical case.
host_port (Port) – Storage port on the CPC that will be used to boot from.

Authorization requirements:

Object-access permission to the storage group owning this storage volume.
Task permission to the “Configure Storage - Storage Administrator” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Virtual Storage Resources¶

A virtual storage resource object represents a storage-related z/Architecture device that is visible to a partition and that provides access for that partition to a storage volume.

The storage-related z/Architecture devices that are visible to a partition are different for the two storage architectures: For FCP, the virtualized HBA is visible as a device, and the storage volumes (LUNs) are not represented as devices. For FICON, each ECKD volume is visible as a device, but the virtualized FICON adapter port is not represented as a device.

What the virtual storage resource objects represent, therefore depends on the storage architecture of the storage volume they are used for:

For FCP, a virtual storage resource object represents the virtualized HBA in the partition that is used to access the LUN. However, each usage of the virtual HBA in context of a storage group has its own virtual storage resource object.
For FICON, a virtual storage resource object represents the ECKD volume.

Virtual storage resource objects are instantiated automatically when a storage group is attached to a partition, and are removed automatically upon detachment.

The HBA resource objects known from DPM mode before introduction of the “dpm-storage-management” feature are no longer exposed.

Virtual storage resource objects are contained in storage group objects.

Storage groups and storage volumes only can be defined in CPCs that are in DPM mode and that have the “dpm-storage-management” feature enabled.

class zhmcclient.VirtualStorageResourceManager(storage_group)[source]¶

Manager providing access to the virtual storage resources in a particular storage group.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a StorageGroup object:

virtual_storage_resources

storage_group¶

Storage group defining the scope for this manager.

Type:	`StorageGroup`

list(full_properties=False, filter_args=None)[source]¶

List the virtual storage resources in this storage group.

Authorization requirements:

Object-access permission to this storage group.

Parameters:	full_properties (bool) – Controls that the full set of resource properties for each returned storage volume is being retrieved, vs. only the following short set: “element-uri”, “name”, “device-number”, “adapter-port-uri”, and “partition-uri”. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `VirtualStorageResource` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.VirtualStorageResource(manager, uri, name=None, properties=None)[source]¶

Representation of a virtual storage resource.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, VirtualStorageResourceManager).

attached_partition¶

The partition to which this virtual storage resource is attached.

The returned partition object has only a minimal set of properties set (‘object-id’, ‘object-uri’, ‘class’, ‘parent’).

Note that a virtual storage resource is always attached to a partition, as long as it exists.

Authorization requirements:

Object-access permission to the storage group owning this virtual storage resource.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`
Type:	`Partition`

adapter_port¶

The storage adapter port associated with this virtual storage resource, once discovery has determined which port to use for this virtual storage resource.

This applies to both, FCP and FICON/ECKD typed storage groups.

The returned adapter port object has only a minimal set of properties set (‘object-id’, ‘object-uri’, ‘class’, ‘parent’).

Authorization requirements:

Object-access permission to the storage group owning this virtual storage resource.
Object-access permission to the CPC of the storage adapter.
Object-access permission to the storage adapter.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`
Type:	`Port`

update_properties(properties)[source]¶

Update writeable properties of this virtual storage resource.

Authorization requirements:

Object-access permission to the storage group owning this virtual storage resource.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘Virtual Storage Resource object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Storage Group Templates¶

A StorageGroupTemplate object represents a storage group template object and can be used to create storage group objects with the properties of the template, including an initial set of storage volumes, using the zhmcclient.StorageGroupTemplateManager.create() method.

Storage group template objects can be created, updated and deleted.

Storage group template objects can only be defined in CPCs that are in DPM mode and that have the “dpm-storage-management” feature enabled.

class zhmcclient.StorageGroupTemplateManager(console)[source]¶

Manager providing access to the storage group templates of the HMC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable:

storage_group_templates of a Console object.

console¶

The Console object representing the HMC.

Type:	`Console`

list(full_properties=False, filter_args=None)[source]¶

List the storage group templates defined in the HMC.

Storage group templates for which the authenticated user does not have object-access permission are not included.

Authorization requirements:

Object-access permission to any storage group templates to be included in the result.

Parameters:	full_properties (bool) – Controls that the full set of resource properties for each returned storage group template is being retrieved, vs. only the following short set: “object-uri”, “cpc-uri”, “name”, and “type”. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen.
Returns:	A list of `StorageGroupTemplate` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create a storage group template.

The new storage group will be associated with the CPC identified by the cpc-uri input property.

Authorization requirements:

Object-access permission to the CPC that will be associated with the new storage group template.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Storage Template’ in the HMC API book. The ‘cpc-uri’ property identifies the CPC to which the new storage group template will be associated, and is required to be specified in this parameter.
Returns:	The resource object for the new storage group template. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	`StorageGroupTemplate`
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.StorageGroupTemplate(manager, uri, name=None, properties=None)[source]¶

Representation of a storage group template.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, StorageGroupTemplateManager).

storage_volume_templates¶

Access to the storage volumes in this storage group.

Type:	`StorageVolumeManager`

cpc¶

The CPC to which this storage group template is associated.

The returned Cpc has only a minimal set of properties populated.

Type:	`Cpc`

delete()[source]¶

Delete this storage group template and its storage volume template resources on the HMC.

Storage groups and their volumes that have been created from the template that is deleted, are not affected.

Authorization requirements:

Object-access permission to this storage group template.
Task permission to the “Configure Storage - System Programmer” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this storage group template.

This includes the storage-template-volumes property which contains requests for creations, deletions and updates of StorageVolumeTemplate resources of this storage group template.

As an alternative to this bulk approach for managing storage volume templates, each StorageVolumeTemplate resource can individually be created, deleted and updated using the respective methods on storage_volume_templates.

Authorization requirements:

Object-access permission to this storage group template.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are listed for operation ‘Modify Storage Template Properties’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Storage Volume Templates¶

A StorageVolumeTemplate object represents a storage volume template for FCP or FICON (ECKD) that is defined in a storage group template.

Storage volume template objects can be created, updated and deleted.

Storage volume templates are contained in storage group templates.

You can create as many storage volume templates as you want in a storage group template. When creating a storage group from the storage group template, each storage volume template will cause a storage volume to be created in the new storage group.

Storage group templates and storage volume templates only can be defined in CPCs that are in DPM mode and that have the “dpm-storage-management” feature enabled.

class zhmcclient.StorageVolumeTemplateManager(storage_group_template)[source]¶

Manager providing access to the storage volume templates in a particular storage group template.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a StorageGroupTemplate object:

storage_volume_templates

storage_group_template¶

Storage group template defining the scope for this manager.

Type:	`StorageGroupTemplate`

list(full_properties=False, filter_args=None)[source]¶

List the storage volume templates in this storage group template.

Authorization requirements:

Object-access permission to this storage group template.

Parameters:	full_properties (bool) – Controls that the full set of resource properties for each returned storage volume template is being retrieved, vs. only the following short set: “element-uri”, “name”, “size”, and “usage”. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `StorageVolumeTemplate` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create a storage volume template in this storage group template on the HMC.

This method performs the “Modify Storage Template Properties” operation, requesting creation of the volume.

Authorization requirements:

Object-access permission to this storage group template.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:	properties (dict) – Initial property values for the new volume template. Allowable properties are the fields defined in the “storage-template-volume-request-info” nested object described for operation “Modify Storage Template Properties” in the HMC API book. The valid fields are those for the “create” operation. The operation field must not be provided; it is set automatically to the value “create”. The properties provided in this parameter will be copied and then amended with the operation=”create” field, and then used as a single array item for the storage-template-volumes field in the request body of the “Modify Storage Template Properties” operation.
Returns:	The resource object for the new storage volume template. The object will have the following properties set: ’element-uri’ as returned by the HMC ’element-id’ as determined from the ‘element-uri’ property ’class’ and ‘parent’ additional properties as specified in the input properties
Return type:	StorageVolumeTemplate
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Example:

stovol1 = fcp_stogrp.storage_volume_templates.create(
    properties=dict(
        name='vol1',
        size=30,  # GiB
))

class zhmcclient.StorageVolumeTemplate(manager, uri, name=None, properties=None)[source]¶

Representation of a storage volume template.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, StorageVolumeTemplateManager).

delete()[source]¶

Delete this storage volume template on the HMC.

This method performs the “Modify Storage Template Properties” operation, requesting deletion of the volume template.

Authorization requirements:

Object-access permission to the storage group template owning this storage volume template.
Task permission to the “Configure Storage - System Programmer” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this storage volume template on the HMC.

This method performs the “Modify Storage Template Properties” operation, requesting modification of the volume.

Authorization requirements:

Object-access permission to the storage group template owning this storage volume template.
Task permission to the “Configure Storage - System Programmer” task.

Parameters:

properties (dict) –

New property values for the volume. Allowable properties are the fields defined in the “storage-template-volume-request-info” nested object for the “modify” operation. That nested object is described in operation “Modify Storage Template Properties” in the HMC API book.

The properties provided in this parameter will be copied and then amended with the operation=”modify” and element-uri properties, and then used as a single array item for the storage-template-volumes field in the request body of the “Modify Storage Template Properties” operation.

Raises:

Console¶

A Console resource represents an HMC.

In a paired setup with primary and alternate HMC, each HMC is represented as a separate Console resource.

class zhmcclient.ConsoleManager(client)[source]¶

Manager providing access to the Console representing the HMC this client is connected to.

In a paired setup with primary and alternate HMC, each HMC is represented as a separate Console resource.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Client object:

zhmcclient.Client.consoles

Methods

`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the (one) Console representing the HMC this client is connected to.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`client`	The client defining the scope for this manager.
`console`	The Console representing the HMC this client is connected to.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

client¶

The client defining the scope for this manager.

Type:	`Client`

console¶

The Console representing the HMC this client is connected to.

The returned object is cached, so it is looked up only upon first access to this property.

The returned object has only the following properties set:

‘object-uri’

Use get_property() or prop() to access any properties regardless of whether they are already set or first need to be retrieved.

Type:	`Console`

list(full_properties=True, filter_args=None)[source]¶

List the (one) Console representing the HMC this client is connected to.

Authorization requirements:

None

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only a short set consisting of ‘object-uri’. filter_args (dict) – This parameter exists for consistency with other list() methods and will be ignored.
Returns:	A list of `Console` objects, containing the one Console representing the HMC this client is connected to.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.Console(manager, uri, name=None, properties=None)[source]¶

Representation of a Console.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, ConsoleManager).

Methods

`get_audit_log`	Return the console audit log entries, optionally filtered by their creation time.
`get_property`	Return the value of a resource property.
`get_security_log`	Return the console security log entries, optionally filtered by their creation time.
`list_unmanaged_cpcs`	List the unmanaged CPCs of this HMC.
`make_primary`	Change the role of the alternate HMC represented by this Console object to become the primary HMC.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`restart`	Restart the HMC represented by this Console object.
`shutdown`	Shut down and power off the HMC represented by this Console object.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`ldap_server_definitions`	Access to the LDAP Server Definitions in this Console.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`password_rules`	Access to the Password Rules in this Console.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`storage_group_templates`	Manager object for the Storage Group Templates in scope of this Console.
`storage_groups`	Manager object for the Storage Groups in scope of this Console.
`tasks`	Access to the Tasks in this Console.
`unmanaged_cpcs`	Access to the unmanaged CPCs in this Console.
`uri`	The canonical URI path of the resource.
`user_patterns`	Access to the User Patterns in this Console.
`user_roles`	Access to the User Roles in this Console.
`users`	Access to the Users in this Console.

Details

storage_groups¶

Manager object for the Storage Groups in scope of this Console.

Type:	`StorageGroupManager`

storage_group_templates¶

Manager object for the Storage Group Templates in scope of this Console.

Type:	`StorageGroupTemplateManager`

users¶

Access to the Users in this Console.

Type:	`UserManager`

user_roles¶

Access to the User Roles in this Console.

Type:	`UserRoleManager`

user_patterns¶

Access to the User Patterns in this Console.

Type:	`UserPatternManager`

password_rules¶

Access to the Password Rules in this Console.

Type:	`PasswordRuleManager`

tasks¶

Access to the Tasks in this Console.

Type:	`TaskManager`

ldap_server_definitions¶

Access to the LDAP Server Definitions in this Console.

Type:	`LdapServerDefinitionManager`

unmanaged_cpcs¶

Access to the unmanaged CPCs in this Console.

Type:	`UnmanagedCpcManager`

restart(force=False, wait_for_available=True, operation_timeout=None)[source]¶

Restart the HMC represented by this Console object.

Once the HMC is online again, this Console object, as well as any other resource objects accessed through this HMC, can continue to be used. An automatic re-logon will be performed under the covers, because the HMC restart invalidates the currently used HMC session.

Authorization requirements:

Task permission for the “Shutdown/Restart” task.
“Remote Restart” must be enabled on the HMC.

Parameters:

force (bool) – Boolean controlling whether the restart operation is processed when users are connected (True) or not (False). Users in this sense are local or remote GUI users. HMC WS API clients do not count as users for this purpose.
wait_for_available (bool) –
Boolean controlling whether this method should wait for the HMC to become available again after the restart, as follows:
- If True, this method will wait until the HMC has restarted and is available again. The query_api_version() method will be used to check for availability of the HMC.
- If False, this method will return immediately once the HMC has accepted the request to be restarted.
operation_timeout (number) – Timeout in seconds, for waiting for HMC availability after the restart. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. If the timeout expires when wait_for_available=True, a OperationTimeout is raised.

Raises:

HTTPError
ParseError
AuthError
ConnectionError
OperationTimeout – The timeout expired while waiting for the HMC to become available again after the restart.

shutdown(force=False)[source]¶

Shut down and power off the HMC represented by this Console object.

While the HMC is powered off, any Python resource objects retrieved from this HMC may raise exceptions upon further use.

In order to continue using Python resource objects retrieved from this HMC, the HMC needs to be started again (e.g. by powering it on locally). Once the HMC is available again, Python resource objects retrieved from that HMC can continue to be used. An automatic re-logon will be performed under the covers, because the HMC startup invalidates the currently used HMC session.

Authorization requirements:

Task permission for the “Shutdown/Restart” task.
“Remote Shutdown” must be enabled on the HMC.

Parameters:	force (bool) – Boolean controlling whether the shutdown operation is processed when users are connected (True) or not (False). Users in this sense are local or remote GUI users. HMC WS API clients do not count as users for this purpose.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

make_primary()[source]¶

Change the role of the alternate HMC represented by this Console object to become the primary HMC.

If that HMC is already the primary HMC, this method does not change its rols and succeeds.

The HMC represented by this Console object must participate in a {primary, alternate} pairing.

Authorization requirements:

Task permission for the “Manage Alternate HMC” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

get_audit_log(begin_time=None, end_time=None)[source]¶

Return the console audit log entries, optionally filtered by their creation time.

Authorization requirements:

Task permission to the “Audit and Log Management” task.

Parameters:	begin_time (`datetime`) – Begin time for filtering. Log entries with a creation time older than the begin time will be omitted from the results. If None, no such filtering is performed (and the oldest available log entries will be included). end_time (`datetime`) – End time for filtering. Log entries with a creation time newer than the end time will be omitted from the results. If None, no such filtering is performed (and the newest available log entries will be included).
Returns:	A JSON object with the log entries, as described in section ‘Response body contents’ of operation ‘Get Console Audit Log’ in the HMC API book.
Return type:	json object
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

get_security_log(begin_time=None, end_time=None)[source]¶

Return the console security log entries, optionally filtered by their creation time.

Authorization requirements:

Task permission to the “View Security Logs” task.

Parameters:	begin_time (`datetime`) – Begin time for filtering. Log entries with a creation time older than the begin time will be omitted from the results. If None, no such filtering is performed (and the oldest available log entries will be included). end_time (`datetime`) – End time for filtering. Log entries with a creation time newer than the end time will be omitted from the results. If None, no such filtering is performed (and the newest available log entries will be included).
Returns:	A JSON object with the log entries, as described in section ‘Response body contents’ of operation ‘Get Console Security Log’ in the HMC API book.
Return type:	json object
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

list_unmanaged_cpcs(name=None)[source]¶

List the unmanaged CPCs of this HMC.

For details, see list().

Authorization requirements:

None

Parameters:

name (string) –

Regular expression pattern for the CPC name, as a filter that narrows the list of returned CPCs to those whose name property matches the specified pattern.

None causes no filtering to happen, i.e. all unmanaged CPCs discovered by the HMC are returned.

Returns:

A list of UnmanagedCpc objects.

Raises:

User¶

A User resource represents a user configured in the HMC.

class zhmcclient.UserManager(console)[source]¶

Manager providing access to the User resources of a HMC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Console object:

zhmcclient.Console.users

Methods

`create`	Create a new User in this HMC.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the User resources representing the users defined in this HMC.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`console`	Console defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

console¶

Console defining the scope for this manager.

Type:	`Console`

list(full_properties=True, filter_args=None)[source]¶

List the User resources representing the users defined in this HMC.

Authorization requirements:

User-related-access permission to the User object included in the result, or, depending on the type of User object, task permission to the “Manage Users” task or the “Manage User Templates” task.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `User` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create a new User in this HMC.

Authorization requirements:

Task permission to the “Manage Users” task to create a standard user or the “Manage User Templates” task to create a template user.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create User’ in the HMC API book.
Returns:	The resource object for the new User. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	User
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.User(manager, uri, name=None, properties=None)[source]¶

Representation of a User.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, UserManager).

Methods

`add_user_role`	Add the specified User Role to this User.
`delete`	Delete this User.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`remove_user_role`	Remove the specified User Role from this User.
`update_properties`	Update writeable properties of this User.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

delete()[source]¶

Delete this User.

Authorization requirements:

Task permission to the “Manage Users” task to delete a non-template user, or the “Manage User Templates” task to delete a template user.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this User.

Authorization requirements:

Task permission to the “Manage Users” task to update a non-template user, or the “Manage User Templates” task to update a template user.
For a user to update their own password or default-group-uri property, user-related-access permission to the user represented by this User object, or task permission to the “Manage Users” task is required.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘User object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

add_user_role(user_role)[source]¶

Add the specified User Role to this User.

This User must not be a system-defined or pattern-based user.

Authorization requirements:

Task permission to the “Manage Users” task to modify a standard user or the “Manage User Templates” task to modify a template user.

Parameters:	user_role (`UserRole`) – User Role to be added. Must not be None.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

remove_user_role(user_role)[source]¶

Remove the specified User Role from this User.

This User must not be a system-defined or pattern-based user.

Authorization requirements:

Task permission to the “Manage Users” task to modify a standard user or the “Manage User Templates” task to modify a template user.

Parameters:	user_role (`UserRole`) – User Role to be removed. Must not be None.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

User Role¶

A User Role resource represents an authority role which can be assigned to one or more HMC users.

A User Role may allow access to specific managed objects, classes of managed objects, groups and/or tasks. There are two types of User Roles: user-defined and system-defined. User-defined User Roles are created by an HMC user, whereas the system-defined User Roles are pre-defined, standard User Roles supplied with the HMC.

class zhmcclient.UserRoleManager(console)[source]¶

Manager providing access to the User Role resources of a HMC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Console object:

zhmcclient.Console.user_roles

Methods

`create`	Create a new (user-defined) User Role in this HMC.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the User Role resources representing the user roles defined in this HMC.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`console`	Console defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

console¶

Console defining the scope for this manager.

Type:	`Console`

list(full_properties=True, filter_args=None)[source]¶

List the User Role resources representing the user roles defined in this HMC.

Authorization requirements:

User-related-access permission to the User Role objects included in the result, or task permission to the “Manage User Roles” task.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `UserRole` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create a new (user-defined) User Role in this HMC.

Authorization requirements:

Task permission to the “Manage User Roles” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create User Role’ in the HMC API book.
Returns:	The resource object for the new User Role. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	UserRole
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.UserRole(manager, uri, name=None, properties=None)[source]¶

Representation of a User Role.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, UserRoleManager).

Methods

`add_permission`	Add permission for the specified permitted object(s) to this User Role, thereby granting that permission to all users that have this User Role.
`delete`	Delete this User Role.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`remove_permission`	Remove permission for the specified permitted object(s) from this User Role, thereby no longer granting that permission to all users that have this User Role.
`update_properties`	Update writeable properties of this User Role.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

delete()[source]¶

Delete this User Role.

The User Role must be user-defined. System-defined User Roles cannot be deleted.

Authorization requirements:

Task permission to the “Manage User Roles” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this User Role.

The User Role must be user-defined. System-defined User Roles cannot be updated.

Authorization requirements:

Task permission to the “Manage User Roles” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘User Role object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

add_permission(permitted_object, include_members=False, view_only=True)[source]¶

Add permission for the specified permitted object(s) to this User Role, thereby granting that permission to all users that have this User Role.

The granted permission depends on the resource class of the permitted object(s):

For Task resources, the granted permission is task permission for that task.
For Group resources, the granted permission is object access permission for the group resource, and optionally also for the group members.
For any other resources, the granted permission is object access permission for these resources.

The User Role must be user-defined.

Authorization requirements:

Task permission to the “Manage User Roles” task.

Parameters:

permitted_object (BaseResource or string) –
Permitted object(s), either as a Python resource object (e.g. Partition), or as a resource class string (e.g. ‘partition’).

Must not be None.
include_members (bool) –
Controls whether for Group resources, the operation applies additionally to its group member resources.

This parameter will be ignored when the permitted object does not specify Group resources.
view_only (bool) –
Controls whether for Task resources, the operation aplies to the view-only version of the task (if True), or to the full version of the task (if False). Only certain tasks support a view-only version.

This parameter will be ignored when the permitted object does not specify Task resources.

Raises:

remove_permission(permitted_object, include_members=False, view_only=True)[source]¶

Remove permission for the specified permitted object(s) from this User Role, thereby no longer granting that permission to all users that have this User Role.

The granted permission depends on the resource class of the permitted object(s):

For Task resources, the granted permission is task permission for that task.
For Group resources, the granted permission is object access permission for the group resource, and optionally also for the group members.
For any other resources, the granted permission is object access permission for these resources.

The User Role must be user-defined.

Authorization requirements:

Task permission to the “Manage User Roles” task.

Parameters:

permitted_object (BaseResource or string) –
Permitted object(s), either as a Python resource object (e.g. Partition), or as a resource class string (e.g. ‘partition’).

Must not be None.
include_members (bool) –
Controls whether for Group resources, the operation applies additionally to its group member resources.

This parameter will be ignored when the permitted object does not specify Group resources.
view_only (bool) –
Controls whether for Task resources, the operation aplies to the view-only version of the task (if True), or to the full version of the task (if False). Only certain tasks support a view-only version.

This parameter will be ignored when the permitted object does not specify Task resources.

Raises:

User Pattern¶

A User Pattern resource represents a pattern for HMC user IDs that are not defined on the HMC but can be verified by an LDAP server for user authentication.

User Patterns and user templates allow a system administrator to define a group of HMC users at once whose user IDs all match a certain pattern (for example, a regular expression) and who have a certain set of attributes. Each pattern identifies a template User object which defines many characteristics of such users. A successful logon with a user ID that matches a User Pattern results in the creation of a pattern-based user, with many of its attributes coming from the associated template.

User Patterns are searched in a defined order during logon processing. That order can be customized through the reorder() method.

class zhmcclient.UserPatternManager(console)[source]¶

Manager providing access to the User Pattern resources of a HMC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Console object:

zhmcclient.Console.user_patterns

Methods

`create`	Create a new User Pattern in this HMC.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the User Pattern resources representing the user patterns defined in this HMC.
`reorder`	Reorder the User Patterns of the HMC as specified.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`console`	Console defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

console¶

Console defining the scope for this manager.

Type:	`Console`

list(full_properties=True, filter_args=None)[source]¶

List the User Pattern resources representing the user patterns defined in this HMC.

Authorization requirements:

User-related-access permission to the User Pattern objects included in the result, or task permission to the “Manage User Patterns” task.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `UserPattern` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create a new User Pattern in this HMC.

Authorization requirements:

Task permission to the “Manage User Patterns” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create User Pattern’ in the HMC API book.
Returns:	The resource object for the new User Pattern. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	UserPattern
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

reorder(user_patterns)[source]¶

Reorder the User Patterns of the HMC as specified.

The order of User Patterns determines the search order during logon processing.

Authorization requirements:

Task permission to the “Manage User Patterns” task.

Parameters:

user_patterns (list of UserPattern) –

The User Patterns in the desired order.

Must not be None.

Raises:

class zhmcclient.UserPattern(manager, uri, name=None, properties=None)[source]¶

Representation of a User Pattern.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, UserPatternManager).

Methods

`delete`	Delete this User Pattern.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`update_properties`	Update writeable properties of this UserPattern.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

delete()[source]¶

Delete this User Pattern.

Authorization requirements:

Task permission to the “Manage User Patterns” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this UserPattern.

Authorization requirements:

Task permission to the “Manage User Patterns” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘User Pattern object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Password Rule¶

A Password Rule resource represents a rule which an HMC user must follow when creating a HMC logon password. Each HMC user using local authentication (i.e. not LDAP) is assigned a password rule. There are certain system-defined password rules available for use.

class zhmcclient.PasswordRuleManager(console)[source]¶

Manager providing access to the Password Rule resources of a HMC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Console object:

zhmcclient.Console.password_rules

Methods

`create`	Create a new Password Rule in this HMC.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the Password Rule resources representing the password rules defined in this HMC.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`console`	Console defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

console¶

Console defining the scope for this manager.

Type:	`Console`

list(full_properties=True, filter_args=None)[source]¶

List the Password Rule resources representing the password rules defined in this HMC.

Authorization requirements:

User-related-access permission to the Password Rule objects included in the result, or task permission to the “Manage Password Rules” task.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `PasswordRule` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create a new Password Rule in this HMC.

Authorization requirements:

Task permission to the “Manage Password Rules” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create Password Rule’ in the HMC API book.
Returns:	The resource object for the new Password Rule. The object will have its ‘element-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	PasswordRule
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.PasswordRule(manager, uri, name=None, properties=None)[source]¶

Representation of a Password Rule.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, PasswordRuleManager).

Methods

`delete`	Delete this Password Rule.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`update_properties`	Update writeable properties of this PasswordRule.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

delete()[source]¶

Delete this Password Rule.

The Password Rule must be user-defined. System-defined Password Rules cannot be deleted.

Authorization requirements:

Task permission to the “Manage Password Rules” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this PasswordRule.

The Password Rule must be user-defined. System-defined Password Rules cannot be updated.

Authorization requirements:

Task permission to the “Manage Password Rules” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘Password Rule object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Task¶

A Task resource represents an action that an HMC user with appropriate authority can perform. These actions could be available via the HMC’s graphical user interface, the Web Services APIs or both.

Tasks are predefined by the HMC and cannot be created, modified or deleted.

class zhmcclient.TaskManager(console)[source]¶

Manager providing access to the Task resources of a HMC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Console object:

zhmcclient.Console.tasks

Methods

`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the Task resources representing the tasks defined in this HMC.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`console`	Console defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

console¶

Console defining the scope for this manager.

Type:	`Console`

list(full_properties=True, filter_args=None)[source]¶

List the Task resources representing the tasks defined in this HMC.

Authorization requirements:

None

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `Task` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.Task(manager, uri, name=None, properties=None)[source]¶

Representation of a Task.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, TaskManager).

Methods

`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

LDAP Server Definition¶

A LDAP Server Definition resource represents a definition that contains information about an LDAP server that may be used for HMC user authentication purposes.

class zhmcclient.LdapServerDefinitionManager(console)[source]¶

Manager providing access to the LDAP Server Definition resources of a HMC.

Derived from BaseManager; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are accessible via the following instance variable of a Console object:

zhmcclient.Console.ldap_server_definitions

Methods

`create`	Create a new LDAP Server Definition in this HMC.
`find`	Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g.
`find_by_name`	Find a resource by name (i.e.
`findall`	Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g.
`flush`	Invalidate the Name-URI cache of this manager.
`invalidate_cache`	Invalidate the Name-URI cache of this manager.
`list`	List the LDAP Server Definition resources representing the definitions of LDAp servers in this HMC.
`resource_object`	Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

Attributes

`class_name`	The resource class name
`console`	Console defining the scope for this manager.
`parent`	Parent resource defining the scope for this manager.
`resource_class`	The Python class of the parent resource of this manager.
`session`	Session with the HMC.

Details

console¶

Console defining the scope for this manager.

Type:	`Console`

list(full_properties=True, filter_args=None)[source]¶

List the LDAP Server Definition resources representing the definitions of LDAp servers in this HMC.

Authorization requirements:

User-related-access permission to the LDAP Server Definition objects included in the result, or task permission to the “Manage LDAP Server Definitions” task.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only the short set as returned by the list operation. filter_args (dict) – Filter arguments that narrow the list of returned resources to those that match the specified filter arguments. For details, see Filtering. None causes no filtering to happen, i.e. all resources are returned.
Returns:	A list of `LdapServerDefinition` objects.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

create(properties)[source]¶

Create a new LDAP Server Definition in this HMC.

Authorization requirements:

Task permission to the “Manage LDAP Server Definitions” task.

Parameters:	properties (dict) – Initial property values. Allowable properties are defined in section ‘Request body contents’ in section ‘Create LDAP Server Definition’ in the HMC API book.
Returns:	The resource object for the new LDAP Server Definition. The object will have its ‘object-uri’ property set as returned by the HMC, and will also have the input properties set.
Return type:	LdapServerDefinition
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

class zhmcclient.LdapServerDefinition(manager, uri, name=None, properties=None)[source]¶

Representation of a LDAP Server Definition.

Derived from BaseResource; see there for common methods and attributes.

Objects of this class are not directly created by the user; they are returned from creation or list functions on their manager object (in this case, LdapServerDefinitionManager).

Methods

`delete`	Delete this LDAP Server Definition.
`get_property`	Return the value of a resource property.
`prop`	Return the value of a resource property, applying a default if it does not exist.
`pull_full_properties`	Retrieve the full set of resource properties and cache them in this object.
`update_properties`	Update writeable properties of this LDAP Server Definitions.

Attributes

`full_properties`	A boolean indicating whether or not the resource properties in this object are the full set of resource properties.
`manager`	Manager object for this resource (and for all resources of the same type in the scope of that manager).
`name`	The name of the resource.
`properties`	The properties of this resource that are currently present in this
`properties_timestamp`	The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).
`uri`	The canonical URI path of the resource.

Details

delete()[source]¶

Delete this LDAP Server Definition.

Authorization requirements:

Task permission to the “Manage LDAP Server Definitions” task.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

update_properties(properties)[source]¶

Update writeable properties of this LDAP Server Definitions.

Authorization requirements:

Task permission to the “Manage LDAP Server Definitions” task.

Parameters:	properties (dict) – New values for the properties to be updated. Properties not to be updated are omitted. Allowable properties are the properties with qualifier (w) in section ‘Data model’ in section ‘LDAP Server Definition object’ in the HMC API book.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

Notifications¶

The HMC supports the publishing of notifications for specific topics. This includes for example asynchronous job completion, property or status changes, and operating system messages issued in an LPAR or DPM partition.

The zhmcclient package supports receiving HMC notifications in an easy-to-use way, as shown in the following example that receives and displays OS messages for a DPM partition:

import zhmcclient

hmc = ...
userid = ...
password = ...

session = zhmcclient.Session(hmc, userid, password)
client = zhmcclient.Client(session)
cpc = client.cpcs.find(name=cpcname)
partition = cpc.partitions.find(name=partname)

topic = partition.open_os_message_channel(include_refresh_messages=True)

print("Subscribing for OS messages for partition %s on CPC %s using "
      "notifications..." % (partition.name, cpc.name))

receiver = zhmcclient.NotificationReceiver(topic, hmc, userid, password)

try:
    for headers, message in receiver.notifications():
        print("HMC notification #%s:" % headers['session-sequence-nr'])
        os_msg_list = message['os-messages']
        for os_msg in os_msg_list:
            msg_txt = os_msg['message-text'].strip('\n')
            msg_id = os_msg['message-id']
            print("OS message #%s:\n%s" % (msg_id, msg_txt))
except KeyboardInterrupt:
    print("Keyboard Interrupt - Leaving notification receiver loop...")
finally:
    print("Closing notification receiver...")
    receiver.close()

When running this example code in one terminal, and stopping or starting the partition in another terminal, one can monitor the shutdown or boot messages issued by the operating system. The following commands use the zhmc CLI provided in the zhmccli project to do that:

$ zhmc partition stop {cpc-name} {partition-name}
$ zhmc partition start {cpc-name} {partition-name}

class zhmcclient.NotificationReceiver(topic_names, host, userid, password, port=61612)[source]¶

A class for receiving HMC notifications that are published to particular HMC notification topics.

Experimental: This class is considered experimental at this point, and its API may change incompatibly as long as it is experimental.

Creating an object of this class establishes a JMS session with the HMC and subscribes for the specified HMC notification topic(s).

Notification topic strings are created by the HMC in context of a particular client session (i.e. Session object). However, these topic strings can be used by any JMS message listener that knows the topic string and that authenticates under some valid HMC userid. The HMC userid used by the JMS listener does not need to be the one that was used for the client session in which the notification topic was originally created.

Parameters:

topic_names (string or list/tuple thereof) – Name(s) of the HMC notification topic(s). Must not be None.
host (string) – HMC host. For valid formats, see the host property. Must not be None.
userid (string) – Userid of the HMC user to be used. Must not be None.
password (string) – Password of the HMC user to be used. Must not be None.
port (integer) – STOMP TCP port. Defaults to DEFAULT_STOMP_PORT.

notifications()[source]¶

Generator method that yields all HMC notifications (= JMS messages) received by this notification receiver.

Example:

desired_topic_types = ('security-notification',
                       'audit-notification')
topics = session.get_notification_topics()
topic_names = [t['topic-name']
               for t in topics
               if t['topic-type'] in desired_topic_types]

receiver = zhmcclient.NotificationReceiver(
    topic_names, hmc, userid, password)

for headers, message in receiver.notifications():
    . . . # processing of topic-specific message format

Yields:

A tuple (headers, message) representing one HMC notification, with:

headers (dict): The notification header fields.

Some important header fields (dict items) are:
- ‘notification-type’ (string): The HMC notification type (e.g. ‘os-message’, ‘job-completion’, or others).
- ‘session-sequence-nr’ (string): The sequence number of this HMC notification within the session created by this notification receiver object. This number starts at 0 when this receiver object is created, and is incremented each time an HMC notification is published to this receiver.
- ‘class’ (string): The class name of the HMC resource publishing the HMC notification (e.g. ‘partition’).
- ‘object-id’ (string) or ‘element-id’ (string): The ID of the HMC resource publishing the HMC notification.
For a complete list of notification header fields, see section “Message format” in chapter 4. “Asynchronous notification” in the HMC API book.
message (JSON object): Body of the HMC notification, converted into a JSON object.

The properties of the JSON object vary by notification type.

For a description of the JSON properties, see the sub-sections for each notification type within section “Notification message formats” in chapter 4. “Asynchronous notification” in the HMC API book.

close()[source]¶

Disconnect and close the JMS session with the HMC.

This implicitly unsubscribes from the notification topic this receiver was created for, and causes the notifications() method to stop its iterations.

Mock support¶

The zhmcclient PyPI package provides unit testing support for its users via its zhmcclient_mock Python package. That package allows users of zhmcclient to easily define a faked HMC that is populated with resources as needed by the test case.

The faked HMC environment is set up by creating an instance of the zhmcclient_mock.FakedSession class instead of the zhmcclient.Session class:

import zhmcclient
import zhmcclient_mock

session = zhmcclient_mock.FakedSession('fake-host', 'fake-hmc', '2.13.1',
                                       '1.8')
client = zhmcclient.Client(session)
cpcs = client.cpcs.list()
. . .

Other than using a different session class, the code operates against the same zhmcclient API as before. For example, you can see in the example above that the client object is set up from the same zhmcclient.Client class as before, and that the CPCs can be listed through the API of the client object as before.

The difference is that the faked session object contains a faked HMC and does not communicate at all with an actual HMC.

The faked HMC of the faked session object can be accessed via the hmc attribute of the faked session object in order to populate it with resources, for example to build up an initial resource environment for a test case.

The following example of a unit test case shows how an initial set of resources that is defined as a dictionary and loaded into the faked HMC using the add_resources() method:

import unittest
import zhmcclient
import zhmcclient_mock

class MyTests(unittest.TestCase):

    def setUp(self):

        self.session = zhmcclient_mock.FakedSession(
            'fake-host', 'fake-hmc', '2.13.1', '1.8')
        self.session.hmc.add_resources({
            'cpcs': [
                {
                    'properties': {
                        'name': 'cpc_1',
                        'description': 'CPC #1',
                    },
                    'adapters': [
                        {
                            'properties': {
                                'name': 'osa_1',
                                'description': 'OSA #1',
                                'adapter-family': 'osa',
                            },
                            'ports': [
                                {
                                    'properties': {
                                        'name': 'osa_1_1',
                                        'description': 'OSA #1 Port #1',
                                    },
                                },
                            ]
                        },
                    ]
                },
            ]
        })
        self.client = zhmcclient.Client(self.session)

    def test_list(self):
        cpcs = self.client.cpcs.list()
        self.assertEqual(len(cpcs), 1)
        self.assertEqual(cpcs[0].name, 'cpc_1')

In this example, the test_list() method tests the CPC list method of the zhmcclient package, but the same approach is used for testing code that uses the zhmcclient package.

As an alternative to bulk-loading resources via the input dictionary, it is also possible to add resources one by one using the add() methods of the faked resource manager classes, as shown in the following example:

class MyTests(unittest.TestCase):

    def setUp(self):

        self.session = zhmcclient_mock.FakedSession(
            'fake-host', 'fake-hmc', '2.13.1', '1.8')

        cpc1 = self.session.hmc.cpcs.add({
            'name': 'cpc_1',
            'description': 'CPC #1',
        })
        adapter1 = cpc1.adapters.add({
            'name': 'osa_1',
            'description': 'OSA #1',
            'adapter-family': 'osa',
        })
        port1 = adapter1.ports.add({
            'name': 'osa_1_1',
            'description': 'OSA #1 Port #1',
        })

        self.client = zhmcclient.Client(self.session)

As you can see, the resources need to be added from top to bottom in the resource tree, starting at the hmc attribute of the faked session object.

Section Faked HMC describes all faked resource and manager classes that you can use to add resources that way.

Section Faked session describes the faked session class.

Faked session¶

A faked Session class for the zhmcclient package.

class zhmcclient_mock.FakedSession(host, hmc_name, hmc_version, api_version)[source]¶

A faked Session class for the zhmcclient package, that can be used as a replacement for the zhmcclient.Session class.

This class is derived from zhmcclient.Session.

This class can be used by projects using the zhmcclient package for their unit testing. It can also be used by unit tests of the zhmcclient package itself.

This class provides a faked HMC with all of its resources that are relevant for the zhmcclient.

The faked HMC provided by this class maintains its resource state in memory as Python objects, and no communication happens to any real HMC. The faked HMC implements all HMC operations that are relevant for the zhmcclient package in a successful manner.

It is possible to populate the faked HMC with an initial resource state (see add_resources()).

Parameters:	host (string) – HMC host. hmc_name (string) – HMC name. Used for result of Query Version Info operation. hmc_version (string) – HMC version string (e.g. ‘2.13.1’). Used for result of Query Version Info operation. api_version (string) – HMC API version string (e.g. ‘1.8’). Used for result of Query Version Info operation.

__repr__()[source]¶: Return a string with the state of this faked session, for debug purposes.

hmc¶

The faked HMC provided by this faked session.

The faked HMC supports being populated with initial resource state, for example using its zhmcclient_mock.FakedHmc.add_resources() method.

As an alternative to providing an entire resource tree, the resources can also be added one by one, from top to bottom, using the zhmcclient_mock.FakedBaseManager.add() methods of the respective managers (the top-level manager for CPCs can be accessed via hmc.cpcs).

Type:	`FakedHmc`

get(uri, logon_required=True)[source]¶

Perform the HTTP GET method against the resource identified by a URI, on the faked HMC.

Parameters:	uri (string) – Relative URI path of the resource, e.g. “/api/session”. This URI is relative to the base URL of the session (see the `base_url` property). Must not be None. logon_required (bool) – Boolean indicating whether the operation requires that the session is logged on to the HMC. Because this is a faked HMC, this does not perform a real logon, but it is still used to update the state in the faked HMC.
Returns:	json object with the operation result.
Raises:	`HTTPError` `ParseError` (not implemented) `AuthError` (not implemented) `ConnectionError`

post(uri, body=None, logon_required=True, wait_for_completion=True, operation_timeout=None)[source]¶

Perform the HTTP POST method against the resource identified by a URI, using a provided request body, on the faked HMC.

HMC operations using HTTP POST are either synchronous or asynchronous. Asynchronous operations return the URI of an asynchronously executing job that can be queried for status and result.

Examples for synchronous operations:

With no response body: “Logon”, “Update CPC Properties”
With a response body: “Create Partition”

Examples for asynchronous operations:

With no job-results field in the completed job status response: “Start Partition”
With a job-results field in the completed job status response (under certain conditions): “Activate a Blade”, or “Set CPC Power Save”

The wait_for_completion parameter of this method can be used to deal with asynchronous HMC operations in a synchronous way.

Parameters:	uri (string) – Relative URI path of the resource, e.g. “/api/session”. This URI is relative to the base URL of the session (see the `base_url` property). Must not be None. body (json object) – JSON object to be used as the HTTP request body (payload). None means the same as an empty dictionary, namely that no HTTP body is included in the request. logon_required (bool) – Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, the “Logon” operation does not require that. Because this is a faked HMC, this does not perform a real logon, but it is still used to update the state in the faked HMC. wait_for_completion (bool) – Boolean controlling whether this method should wait for completion of the requested HMC operation, as follows: If True, this method will wait for completion of the requested operation, regardless of whether the operation is synchronous or asynchronous. This will cause an additional entry in the time statistics to be created for the asynchronous operation and waiting for its completion. This entry will have a URI that is the targeted URI, appended with “+completion”. If False, this method will immediately return the result of the HTTP POST method, regardless of whether the operation is synchronous or asynchronous. operation_timeout (number) – Timeout in seconds, when waiting for completion of an asynchronous operation. The special value 0 means that no timeout is set. None means that the default async operation timeout of the session is used. For wait_for_completion=True, a `OperationTimeout` is raised when the timeout expires. For wait_for_completion=False, this parameter has no effect.
Returns:	If wait_for_completion is True, returns a JSON object representing the response body of the synchronous operation, or the response body of the completed job that performed the asynchronous operation. If a synchronous operation has no response body, None is returned. If wait_for_completion is False, returns a JSON object representing the response body of the synchronous or asynchronous operation. In case of an asynchronous operation, the JSON object will have a member named `job-uri`, whose value can be used with the `query_job_status()` method to determine the status of the job and the result of the original operation, once the job has completed. See the section in the HMC API book about the specific HMC operation and about the ‘Query Job Status’ operation, for a description of the members of the returned JSON objects.
Return type:	json object
Raises:	`HTTPError` `ParseError` (not implemented) `AuthError` (not implemented) `ConnectionError`

delete(uri, logon_required=True)[source]¶

Perform the HTTP DELETE method against the resource identified by a URI, on the faked HMC.

Parameters:

uri (string) – Relative URI path of the resource, e.g. “/api/session/{session-id}”. This URI is relative to the base URL of the session (see the base_url property). Must not be None.
logon_required (bool) –
Boolean indicating whether the operation requires that the session is logged on to the HMC. For example, for the logoff operation, it does not make sense to first log on.

Because this is a faked HMC, this does not perform a real logon, but it is still used to update the state in the faked HMC.

Raises:

HTTPError
ParseError (not implemented)
AuthError (not implemented)
ConnectionError

Faked HMC¶

The zhmcclient_mock package provides a faked HMC with all resources that are relevant for the zhmcclient package. The faked HMC is implemented as a local Python object and maintains its resource state across operations.

class zhmcclient_mock.InputError(message)[source]¶

An error that is raised by the faked resource classes and indicates that the input is invalid in some way.

args[0] will be set to a message detailing the issue.

class zhmcclient_mock.FakedHmc(hmc_name, hmc_version, api_version)[source]¶

A faked HMC.

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

An object of this class represents a faked HMC that can have all faked resources that are relevant for the zhmcclient package.

The Python API to this class and its child resource classes is not compatible with the zhmcclient API. Instead, these classes serve as an in-memory backend for a faked session class (see zhmcclient_mock.FakedSession) that replaces the normal zhmcclient.Session class.

Objects of this class should not be created by the user. Instead, access the zhmcclient_mock.FakedSession.hmc attribute.

__repr__()[source]¶: Return a string with the state of this faked HMC, for debug purposes.

enabled¶: Return whether the faked HMC is enabled.

enable()[source]¶: Enable the faked HMC.

disable()[source]¶: Disable the faked HMC. This will cause an error to be raised when a faked session attempts to communicate with the disabled HMC.

lookup_by_uri(uri)[source]¶

Look up a faked resource by its object URI, within this faked HMC.

Parameters:	uri (string) – The object URI of the faked resource (e.g. value of the ‘object-uri’ property).
Returns:	The faked resource.
Return type:	`FakedBaseResource`
Raises:	`KeyError` – No resource found for this object ID.

class zhmcclient_mock.FakedActivationProfileManager(hmc, cpc, profile_type)[source]¶

A manager for faked Activation Profile resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked Activation Profile resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’name’ (the OID property for this resource type!) will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the OID (‘name’) property, if not specified.
’class’ will be auto-generated to ‘{profile_type}’-activation-profile’, if not specified.

Returns:

The faked: Activation Profile resource.

Return type: FakedActivationProfile

profile_type¶: Type of the activation profile (‘reset’, ‘image’, ‘load’).

class zhmcclient_mock.FakedActivationProfile(manager, properties)[source]¶

A faked Activation Profile resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedAdapterManager(hmc, cpc)[source]¶

A manager for faked Adapter resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked Adapter resource.

Parameters:	properties (dict) – Resource properties. Special handling and requirements for certain properties: ’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified. ’object-uri’ will be auto-generated based upon the object ID, if not specified. ’class’ will be auto-generated to ‘adapter’, if not specified. ’status’ is auto-set to ‘active’, if not specified. ’adapter-family’ or ‘type’ is required to be specified, in order to determine whether the adapter is a network or storage adapter. ’adapter-family’ is auto-set based upon ‘type’, if not specified. For network adapters, ‘network-port-uris’ is auto-set to an empty list, if not specified. For storage adapters, ‘storage-port-uris’ is auto-set to an empty list, if not specified.
Returns:	The faked Adapter resource.
Return type:	`FakedAdapter`
Raises:	`zhmcclient_mock.InputError` – Some issue with the input properties.

class zhmcclient_mock.FakedAdapter(manager, properties)[source]¶

A faked Adapter resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

__repr__()[source]¶: Return a string with the state of this faked Adapter resource, for debug purposes.

ports¶

The Port resources of this Adapter.

If the kind of adapter does not have ports, this is None.

Type:	`FakedPort`

adapter_kind¶

The kind of adapter, determined from the ‘adapter-family’ or ‘type’ properties. This is currently used to distinguish storage and network adapters.

Possible values are: * ‘network’ - A network adapter (OSA, ROCE, Hipersockets) * ‘storage’ - A storage adapter (FICON, FCP) * ‘other’ - Another adapter (zEDC, Crypto)

Type:	string

class zhmcclient_mock.FakedConsoleManager(hmc, client)[source]¶

A manager for faked Console resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

console¶: The faked Console representing the faked HMC (an object of FakedConsole). The object is cached.

add(properties)[source]¶

Add a faked Console resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’object-uri’ will be auto-generated to ‘/api/console’, if not specified.
’class’ will be auto-generated to ‘console’, if not specified.

Returns: The faked Console resource.

Return type: FakedConsole

class zhmcclient_mock.FakedConsole(manager, properties)[source]¶

A faked Console resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

__repr__()[source]¶: Return a string with the state of this faked Console resource, for debug purposes.

storage_groups¶

Access to the faked Storage Group resources of this Console.

Type:	`FakedStorageGroupManager`

users¶

Access to the faked User resources of this Console.

Type:	`FakedUserManager`

user_roles¶

Access to the faked User Role resources of this Console.

Type:	`FakedUserRoleManager`

user_patterns¶

Access to the faked User Pattern resources of this Console.

Type:	`FakedUserPatternManager`

password_rules¶

Access to the faked Password Rule resources of this Console.

Type:	`FakedPasswordRulesManager`

tasks¶

Access to the faked Task resources of this Console.

Type:	`FakedTaskManager`

ldap_server_definitions¶

Access to the faked LDAP Server Definition resources of this Console.

Type:	`FakedLdapServerDefinitionManager`

unmanaged_cpcs¶

Access to the faked unmanaged CPC resources of this Console.

Type:	`FakedUnmanagedCpcManager`

class zhmcclient_mock.FakedCpcManager(hmc, client)[source]¶

A manager for faked managed CPC resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked CPC resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘cpc’, if not specified.
’dpm-enabled’ is auto-set to False, if not specified.
’is-ensemble-member’ is auto-set to False, if not specified.
’status’ is auto-set, if not specified, as follows: If the ‘dpm-enabled’ property is True, it is set to ‘active’; otherwise it is set to ‘operating’.

Returns: The faked CPC resource.

Return type: FakedCpc

class zhmcclient_mock.FakedCpc(manager, properties)[source]¶

A faked managed CPC resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

__repr__()[source]¶: Return a string with the state of this faked Cpc resource, for debug purposes.

dpm_enabled¶

Indicates whether this CPC is in DPM mode.

This returns the value of the ‘dpm-enabled’ property.

Type:	bool

lpars¶

Access to the faked LPAR resources of this CPC.

Type:	`FakedLparManager`

partitions¶

Access to the faked Partition resources of this CPC.

Type:	`FakedPartitionManager`

adapters¶

Access to the faked Adapter resources of this CPC.

Type:	`FakedAdapterManager`

virtual_switches¶

Access to the faked Virtual Switch resources of this CPC.

Type:	`FakedVirtualSwitchManager`

reset_activation_profiles¶

Access to the faked Reset Activation Profile resources of this CPC.

Type:	`FakedActivationProfileManager`

image_activation_profiles¶

Access to the faked Image Activation Profile resources of this CPC.

Type:	`FakedActivationProfileManager`

load_activation_profiles¶

Access to the faked Load Activation Profile resources of this CPC.

Type:	`FakedActivationProfileManager`

class zhmcclient_mock.FakedHbaManager(hmc, partition)[source]¶

A manager for faked HBA resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked HBA resource.

Parameters:	properties (dict) – Resource properties. Special handling and requirements for certain properties: ’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified. ’element-uri’ will be auto-generated based upon the element ID, if not specified. ’class’ will be auto-generated to ‘hba’, if not specified. ’adapter-port-uri’ identifies the backing FCP port for this HBA and is required to be specified. ’device-number’ will be auto-generated with a unique value within the partition in the range 0x8000 to 0xFFFF, if not specified. This method also updates the ‘hba-uris’ property in the parent faked Partition resource, by adding the URI for the faked HBA resource.
Returns:	The faked HBA resource.
Return type:	`FakedHba`
Raises:	`zhmcclient_mock.InputError` – Some issue with the input properties.

remove(oid)[source]¶

Remove a faked HBA resource.

This method also updates the ‘hba-uris’ property in the parent Partition resource, by removing the URI for the faked HBA resource.

Parameters:	oid (string) – The object ID of the faked HBA resource.

class zhmcclient_mock.FakedHba(manager, properties)[source]¶

A faked HBA resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedLdapServerDefinitionManager(hmc, console)[source]¶

A manager for faked LDAP Server Definition resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked LDAP Server Definition resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘ldap-server-definition’, if not specified.

Returns: The faked LdapServerDefinition resource.

Return type: FakedLdapServerDefinition

class zhmcclient_mock.FakedLdapServerDefinition(manager, properties)[source]¶

A faked LDAP Server Definition resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedLparManager(hmc, cpc)[source]¶

A manager for faked LPAR resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked LPAR resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘logical-partition’, if not specified.
’status’ is auto-set to ‘not-activated’, if not specified.

Returns: The faked LPAR resource.

Return type: FakedLpar

class zhmcclient_mock.FakedLpar(manager, properties)[source]¶

A faked LPAR resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedNicManager(hmc, partition)[source]¶

A manager for faked NIC resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked NIC resource.

Parameters:	properties (dict) – Resource properties. Special handling and requirements for certain properties: ’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified. ’element-uri’ will be auto-generated based upon the element ID, if not specified. ’class’ will be auto-generated to ‘nic’, if not specified. Either ‘network-adapter-port-uri’ (for backing ROCE adapters) or ‘virtual-switch-uri’(for backing OSA or Hipersockets adapters) is required to be specified. ’device-number’ will be auto-generated with a unique value within the partition in the range 0x8000 to 0xFFFF, if not specified. This method also updates the ‘nic-uris’ property in the parent faked Partition resource, by adding the URI for the faked NIC resource. This method also updates the ‘connected-vnic-uris’ property in the virtual switch referenced by ‘virtual-switch-uri’ property, and sets it to the URI of the faked NIC resource.
Returns:	The faked NIC resource.
Return type:	`zhmcclient_mock.FakedNic`
Raises:	`zhmcclient_mock.InputError` – Some issue with the input properties.

remove(oid)[source]¶

Remove a faked NIC resource.

This method also updates the ‘nic-uris’ property in the parent Partition resource, by removing the URI for the faked NIC resource.

Parameters:	oid (string) – The object ID of the faked NIC resource.

class zhmcclient_mock.FakedNic(manager, properties)[source]¶

A faked NIC resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedPartitionManager(hmc, cpc)[source]¶

A manager for faked Partition resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked Partition resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘partition’, if not specified.
’hba-uris’ will be auto-generated as an empty array, if not specified.
’nic-uris’ will be auto-generated as an empty array, if not specified.
’virtual-function-uris’ will be auto-generated as an empty array, if not specified.
’status’ is auto-set to ‘stopped’, if not specified.

Returns:

The faked Partition: resource.

Return type: FakedPartition

class zhmcclient_mock.FakedPartition(manager, properties)[source]¶

A faked Partition resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

Each partition uses the device number range of 0x8000 to 0xFFFF for automatically assigned device numbers of HBAs, NICs and virtual functions. Users of the mock support should not use device numbers in that range (unless all of them are user-assigned for a particular partition).

__repr__()[source]¶: Return a string with the state of this faked Partition resource, for debug purposes.

nics¶

Access to the faked NIC resources of this Partition.

Type:	`FakedNicManager`

hbas¶

Access to the faked HBA resources of this Partition.

Type:	`FakedHbaManager`

virtual_functions¶

Access to the faked Virtual Function resources of this Partition.

Type:	`FakedVirtualFunctionManager`

devno_alloc()[source]¶

Allocates a device number unique to this partition, in the range of 0x8000 to 0xFFFF.

Returns:	The device number as four hexadecimal digits in upper case.
Return type:	string
Raises:	`ValueError` – No more device numbers available in that range.

devno_free(devno)[source]¶

Free a device number allocated with devno_alloc().

The device number must be allocated.

Parameters:	devno (string) – The device number as four hexadecimal digits.
Raises:	`ValueError` – Device number not in pool range or not currently allocated.

devno_free_if_allocated(devno)[source]¶

Free a device number allocated with devno_alloc().

If the device number is not currently allocated or not in the pool range, nothing happens.

Parameters:	devno (string) – The device number as four hexadecimal digits.

wwpn_alloc()[source]¶

Allocates a WWPN unique to this partition, in the range of 0xAFFEAFFE00008000 to 0xAFFEAFFE0000FFFF.

Returns:	The WWPN as 16 hexadecimal digits in upper case.
Return type:	string
Raises:	`ValueError` – No more WWPNs available in that range.

wwpn_free(wwpn)[source]¶

Free a WWPN allocated with wwpn_alloc().

The WWPN must be allocated.

Parameters:	WWPN (string) – The WWPN as 16 hexadecimal digits.
Raises:	`ValueError` – WWPN not in pool range or not currently allocated.

wwpn_free_if_allocated(wwpn)[source]¶

Free a WWPN allocated with wwpn_alloc().

If the WWPN is not currently allocated or not in the pool range, nothing happens.

Parameters:	WWPN (string) – The WWPN as 16 hexadecimal digits.

class zhmcclient_mock.FakedPasswordRuleManager(hmc, console)[source]¶

A manager for faked Password Rule resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked Password Rule resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘password-rule’, if not specified.

Returns: The faked Password Rule resource.

Return type: FakedPasswordRule

class zhmcclient_mock.FakedPasswordRule(manager, properties)[source]¶

A faked Password Rule resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedPortManager(hmc, adapter)[source]¶

A manager for faked Adapter Port resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked Port resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘network-port’ or ‘storage-port’, if not specified.

This method also updates the ‘network-port-uris’ or ‘storage-port-uris’ property in the parent Adapter resource, by adding the URI for the faked Port resource.

Returns: The faked Port resource.

Return type: zhmcclient_mock.FakedPort

remove(oid)[source]¶

Remove a faked Port resource.

This method also updates the ‘network-port-uris’ or ‘storage-port-uris’ property in the parent Adapter resource, by removing the URI for the faked Port resource.

Parameters:	oid (string) – The object ID of the faked Port resource.

class zhmcclient_mock.FakedPort(manager, properties)[source]¶

A faked Adapter Port resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedTaskManager(hmc, console)[source]¶

A manager for faked Task resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked Task resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘task’, if not specified.

Returns: The faked Task resource.

Return type: FakedTask

class zhmcclient_mock.FakedTask(manager, properties)[source]¶

A faked Task resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedUnmanagedCpcManager(hmc, console)[source]¶

A manager for faked unmanaged CPC resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked unmanaged CPC resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.

Returns: The faked unmanaged CPC resource.

Return type: FakedUnmanagedCpc

class zhmcclient_mock.FakedUnmanagedCpc(manager, properties)[source]¶

A faked unmanaged CPC resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

__repr__()[source]¶: Return a string with the state of this faked unmanaged Cpc resource, for debug purposes.

class zhmcclient_mock.FakedUserManager(hmc, console)[source]¶

A manager for faked User resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked User resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘user’, if not specified.

Returns: The faked User resource.

Return type: FakedUser

class zhmcclient_mock.FakedUser(manager, properties)[source]¶

A faked User resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedUserPatternManager(hmc, console)[source]¶

A manager for faked User Pattern resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked User Pattern resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘user-pattern’, if not specified.

Returns: The faked User Pattern resource.

Return type: FakedUserPattern

class zhmcclient_mock.FakedUserPattern(manager, properties)[source]¶

A faked User Pattern resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedUserRoleManager(hmc, console)[source]¶

A manager for faked User Role resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked User Role resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘user-role’, if not specified.

Returns: The faked User Role resource.

Return type: FakedUserRole

class zhmcclient_mock.FakedUserRole(manager, properties)[source]¶

A faked User Role resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedVirtualFunctionManager(hmc, partition)[source]¶

A manager for faked Virtual Function resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked Virtual Function resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’element-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’element-uri’ will be auto-generated based upon the element ID, if not specified.
’class’ will be auto-generated to ‘virtual-function’, if not specified.
’device-number’ will be auto-generated with a unique value within the partition in the range 0x8000 to 0xFFFF, if not specified.

This method also updates the ‘virtual-function-uris’ property in the parent Partition resource, by adding the URI for the faked Virtual Function resource.

Returns:

The faked Virtual: Function resource.

Return type: zhmcclient_mock.FakedVirtualFunction

remove(oid)[source]¶

Remove a faked Virtual Function resource.

This method also updates the ‘virtual-function-uris’ property in the parent Partition resource, by removing the URI for the faked Virtual Function resource.

Parameters:	oid (string) – The object ID of the faked Virtual Function resource.

class zhmcclient_mock.FakedVirtualFunction(manager, properties)[source]¶

A faked Virtual Function resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedVirtualSwitchManager(hmc, cpc)[source]¶

A manager for faked Virtual Switch resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

add(properties)[source]¶

Add a faked Virtual Switch resource.

Parameters:

properties (dict) –

Resource properties.

Special handling and requirements for certain properties:

’object-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’object-uri’ will be auto-generated based upon the object ID, if not specified.
’class’ will be auto-generated to ‘virtual-switch’, if not specified.
’connected-vnic-uris’ will be auto-generated as an empty array, if not specified.

Returns:

The faked Virtual: Switch resource.

Return type: FakedVirtualSwitch

class zhmcclient_mock.FakedVirtualSwitch(manager, properties)[source]¶

A faked Virtual Switch resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

class zhmcclient_mock.FakedMetricsContextManager(hmc, client)[source]¶

A manager for faked Metrics Context resources within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseManager, see there for common methods and attributes.

Example:

The following code sets up the faked data for metrics retrieval for partition usage metrics, and then retrieves the metrics:

session = FakedSession('fake-host', 'fake-hmc', '2.13.1', '1.8')
client = Client(session)

# URIs of (faked or real) Partitions the metric apply to:
part1_uri = ...
part2_uri = ...

# Add a faked metric group definition for group 'partition-usage':
session.hmc.metric_contexts.add_metric_group_definition(
    FakedMetricGroupDefinition(
        name='partition-usage',
        types=[
            ('processor-usage', 'integer-metric'),
            ('network-usage', 'integer-metric'),
            ('storage-usage', 'integer-metric'),
            ('accelerator-usage', 'integer-metric'),
            ('crypto-usage', 'integer-metric'),
        ]))

# Prepare the faked metric response for that metric group, with
# data for two partitions:
session.hmc.metric_contexts.add_metric_values(
    FakedMetricObjectValues(
        group_name='partition-usage',
        resource_uri=part1_uri,
        timestamp=datetime.now(),
        values=[
            ('processor-usage', 15),
            ('network-usage', 0),
            ('storage-usage', 1),
            ('accelerator-usage', 0),
            ('crypto-usage', 0),
        ]))
session.hmc.metric_contexts.add_metric_values(
    FakedMetricObjectValues(
        group_name='partition-usage',
        resource_uri=part2_uri,
        timestamp=datetime.now(),
        values=[
            ('processor-usage', 17),
            ('network-usage', 5),
            ('storage-usage', 2),
            ('accelerator-usage', 0),
            ('crypto-usage', 0),
        ]))

# Create a Metrics Context resource for one metric group:
mc = client.metrics_contexts.create({
    'anticipated-frequency-seconds': 15,
    'metric-groups' ['partition-usage'],
})

# Retrieve the metrics for that metric context:
metrics_response = mc.get_metrics()

add(properties)[source]¶

Add a faked Metrics Context resource.

Parameters:

properties (dict) –

Resource properties, as defined in the description of the FakedMetricsContext class.

Special handling and requirements for certain properties:

’fake-id’ will be auto-generated with a unique value across all instances of this resource type, if not specified.
’fake-uri’ will be auto-generated based upon the ‘fake-id’ property, if not specified.

Returns: The faked Metrics Context resource.

Return type: FakedMetricsContext

add_metric_group_definition(definition)[source]¶

Add a faked metric group definition.

The definition will be used:

For later addition of faked metrics responses.
For returning the metric-group-info objects in the response of the Create Metrics Context operations.

For defined metric groups, see chapter “Metric groups” in the HMC API book.

Parameters:	( (definition) – class:~zhmcclient.FakedMetricGroupDefinition`): Definition of the metric group.
Raises:	`ValueError` – A metric group definition with this name already exists.

get_metric_group_definition(group_name)[source]¶

Get a faked metric group definition by its group name.

Parameters:	group_name (string) – Name of the metric group.
Returns:	class:~zhmcclient.FakedMetricGroupDefinition`: Definition of the metric group.
Raises:	`ValueError` – A metric group definition with this name does not exist.

get_metric_group_definition_names()[source]¶

Get the group names of all faked metric group definitions.

Returns:	The group names, in the order their metric group definitions had been added.
Return type:	iterable of string

add_metric_values(values)[source]¶

Add one set of faked metric values for a particular resource to the metrics response for a particular metric group, for later retrieval.

For defined metric groups, see chapter “Metric groups” in the HMC API book.

Parameters:	values (`FakedMetricObjectValues`) – The set of metric values to be added. It specifies the resource URI and the targeted metric group name.

get_metric_values(group_name)[source]¶

Get the faked metric values for a metric group, by its metric group name.

The result includes all metric object values added earlier for that metric group name, using add_metric_object_values() i.e. the metric values for all resources and all points in time that were added.

Parameters:	group_name (string) – Name of the metric group.
Returns:	The metric values for that metric group, in the order they had been added.
Return type:	iterable of `FakedMetricObjectValues`
Raises:	`ValueError` – Metric values for this group name do not exist.

get_metric_values_group_names()[source]¶

Get the group names of metric groups for which there are faked metric values.

Returns:	The group names, in the order their metric values had been added.
Return type:	iterable of string

class zhmcclient_mock.FakedMetricsContext(manager, properties)[source]¶

A faked Metrics Context resource within a faked HMC (see zhmcclient_mock.FakedHmc).

Derived from zhmcclient_mock.FakedBaseResource, see there for common methods and attributes.

The Metrics Context “resource” is really a service and therefore does not have a data model defined in the HMC API book. In order to fit into the zhmcclient mock framework, the faked Metrics Context in the zhmcclient mock framework is treated like all other faked resources and does have a data model.

Data Model:

‘fake-id’ (string): Object ID of the resource.

Initialization: Optional. If omitted, it will be auto-generated.

‘fake-uri’ (string): Resource URI of the resource (used for Get

Metrics operation).

Initialization: Optional. If omitted, it will be auto-generated from the Object ID.

‘anticipated-frequency-seconds’ (integer):

The number of seconds the client anticipates will elapse between metrics retrievals using this context. The minimum accepted value is 15.

Initialization: Required.

‘metric-groups’ (list of string):

The metric group names to be returned by a metric retrieval using this context.

Initialization: Optional. If omitted or the empty list, all metric groups that are valid for the operational mode of each CPC will be returned.

get_metric_group_definitions()[source]¶

Get the faked metric group definitions for this context object that are to be returned from its create operation.

If a ‘metric-groups’ property had been specified for this context, only those faked metric group definitions of its manager object that are in that list, are included in the result. Otherwise, all metric group definitions of its manager are included in the result.

Returns:	class:~zhmcclient.FakedMetricGroupDefinition`: The faked metric group definitions, in the order they had been added.
Return type:	iterable of

get_metric_group_infos()[source]¶

Get the faked metric group definitions for this context object that are to be returned from its create operation, in the format needed for the “Create Metrics Context” operation response.

Returns:	“metric-group-infos” JSON object as described for the “Create Metrics Context “operation response.

get_metric_values()[source]¶

Get the faked metrics, for all metric groups and all resources that have been prepared on the manager object of this context object.

Returns:	The faked metrics, in the order they had been added, where: group_name (string): Metric group name. values (:class:~zhmcclient.FakedMetricObjectValues`): The metric values for one resource at one point in time.
Return type:	iterable of tuple (group_name, iterable of values)

get_metric_values_response()[source]¶

Get the faked metrics, for all metric groups and all resources that have been prepared on the manager object of this context object, as a string in the format needed for the “Get Metrics” operation response.

Returns:	“MetricsResponse” string as described for the “Get Metrics” operation response.

class zhmcclient_mock.FakedBaseManager(hmc, parent, resource_class, base_uri, oid_prop, uri_prop, class_value)[source]¶

A base class for manager classes for faked resources in the faked HMC.

__repr__()[source]¶: Return a string with the state of this faked manager, for debug purposes.

hmc¶: The faked HMC this manager is part of (an object of FakedHmc).

parent¶: The parent (scoping resource) for this manager (an object of a derived class of FakedBaseResource).

resource_class¶: The resource class managed by this manager (a derived class of FakedBaseResource).

base_uri¶: The base URI for URIs of resources managed by this manager.

oid_prop¶: The name of the resource property for the object ID (‘object-id’ or ‘element-id’ or ‘name’).

uri_prop¶: The name of the resource property for the object URI (‘object-uri’ or ‘element-uri’).

class_value¶: The value for the “class” property of resources managed by this manager, as defined in the data model for the resource. For example, for LPAR resources this is set to ‘logical-partition’.

add(properties)[source]¶

Add a faked resource to this manager.

For URI-based lookup, the resource is also added to the faked HMC.

Parameters:	properties (dict) – Resource properties. If the URI property (e.g. ‘object-uri’) or the object ID property (e.g. ‘object-id’) are not specified, they will be auto-generated.
Returns:	The faked resource object.
Return type:	FakedBaseResource

remove(oid)[source]¶

Remove a faked resource from this manager.

Parameters:	oid (string) – The object ID of the resource (e.g. value of the ‘object-uri’ property).

list(filter_args=None)[source]¶

List the faked resources of this manager.

Parameters:	filter_args (dict) – Filter arguments. None causes no filtering to happen. See `list()` for details.
Returns:	The faked resource objects of this manager.
Return type:	list of FakedBaseResource

lookup_by_oid(oid)[source]¶

Look up a faked resource by its object ID, in the scope of this manager.

Parameters:	oid (string) – The object ID of the faked resource (e.g. value of the ‘object-id’ property).
Returns:	The faked resource object.
Return type:	FakedBaseResource
Raises:	`KeyError` – No resource found for this object ID.

class zhmcclient_mock.FakedBaseResource(manager, properties)[source]¶

A base class for faked resource classes in the faked HMC.

__repr__()[source]¶

Return a string with the state of this faked resource, for debug purposes.

Note that the derived faked resource classes that have child resources have their own __repr__() methods, because only they know which child resources they have.

manager¶: The manager for this resource (a derived class of FakedBaseManager).

properties¶: The properties of this resource (a dictionary).

oid¶: The object ID (property ‘object-id’ or ‘element-id’) of this resource.

uri¶: The object URI (property ‘object-uri’ or ‘element-uri’) of this resource.

name¶

The name (property ‘name’) of this resource.

Raises:	`KeyError` – Resource does not have a ‘name’ property.

update(properties)[source]¶

update the properties of this resource.

Parameters:	properties (dict) – Resource properties to be updated. Any other properties remain unchanged.

add_resources(resources)[source]¶

Add faked child resources to this resource, from the provided resource definitions.

Duplicate resource names in the same scope are not permitted.

Although this method is typically used to initially load the faked HMC with resource state just once, it can be invoked multiple times and can also be invoked on faked resources (e.g. on a faked CPC).

Parameters:

resources (dict) –

resource dictionary with definitions of faked child resources to be added. For an explanation of how the resource dictionary is set up, see the examples below.

For requirements on and auto-generation of certain resource properties, see the add() methods of the various faked resource managers (e.g. zhmcclient_mock.FakedCpcManager.add()). For example, the object-id or element-id properties and the corresponding uri properties are always auto-generated.

The resource dictionary specifies a tree of resource managers and resources, in an alternating manner. It starts with the resource managers of child resources of the target resource, which contains a list of those child resources. For an HMC, the CPCs managed by the HMC would be its child resources.

Each resource specifies its own properties (properties key) and the resource managers for its child resources. For example, the CPC resource specifies its adapter child resources using the adapters key. The keys for the child resource managers are the attribute names of these resource managers in the parent resource. For example, the adapters key is named after the zhmcclient.Cpc.adapters attribute (which has the same name as in its corresponding faked CPC resource: zhmcclient_mock.FakedCpc.adapters).

Raises: zhmcclient_mock.InputError – Some issue with the input resources.

Examples

Example for targeting a faked HMC for adding a CPC with one adapter:

resources = {
    'cpcs': [  # name of manager attribute for this resource
        {
            'properties': {
                'name': 'cpc_1',
            },
            'adapters': [  # name of manager attribute for this
                           # resource
                {
                    'properties': {
                        'object-id': '12',
                        'name': 'ad_1',
                    },
                    'ports': [
                        {
                            'properties': {
                                'name': 'port_1',
                            }
                        },
                    ],
                },
            ],
        },
    ],
}

Example for targeting a faked CPC for adding an LPAR and a load activation profile:

resources = {
    'lpars': [  # name of manager attribute for this resource
        {
            'properties': {
                # object-id is not provided -> auto-generated
                # object-uri is not provided -> auto-generated
                'name': 'lpar_1',
            },
        },
    ],
    'load_activation_profiles': [  # name of manager attribute
        {
            'properties': {
                # object-id is not provided -> auto-generated
                # object-uri is not provided -> auto-generated
                'name': 'lpar_1',
            },
        },
    ],
}

URI handler¶

A module with various handler classes for the HTTP methods against HMC URIs, based on the faked HMC.

Most handler classes do not need to be documented, but some of them have methods that can be mocked in order to provoke non-standard behavior in the handling of the HTTP methods.

class zhmcclient_mock.LparActivateHandler[source]¶

A handler class for the “Activate Logical Partition” operation.

static get_status()[source]¶

Status retrieval method that returns the status the faked Lpar will have after completion of the the “Activate Logical Partition” operation.

This method returns the successful status ‘not-operating’, and can be mocked by testcases to return a different status (e.g. ‘exceptions’).

static post(method, hmc, uri, uri_parms, body, logon_required, wait_for_completion)[source]¶: Operation: Activate Logical Partition (requires classic mode).

class zhmcclient_mock.LparDeactivateHandler[source]¶

A handler class for the “Deactivate Logical Partition” operation.

static get_status()[source]¶

Status retrieval method that returns the status the faked Lpar will have after completion of the the “Deactivate Logical Partition” operation.

This method returns the successful status ‘not-activated’, and can be mocked by testcases to return a different status (e.g. ‘exceptions’).

static post(method, hmc, uri, uri_parms, body, logon_required, wait_for_completion)[source]¶: Operation: Deactivate Logical Partition (requires classic mode).

class zhmcclient_mock.LparLoadHandler[source]¶

A handler class for the “Load Logical Partition” operation.

static get_status()[source]¶

Status retrieval method that returns the status the faked Lpar will have after completion of the “Load Logical Partition” operation.

This method returns the successful status ‘operating’, and can be mocked by testcases to return a different status (e.g. ‘exceptions’).

static post(method, hmc, uri, uri_parms, body, logon_required, wait_for_completion)[source]¶: Operation: Load Logical Partition (requires classic mode).

Development¶

This section only needs to be read by developers of the zhmcclient package. People that want to make a fix or develop some extension, and people that want to test the project are also considered developers for the purpose of this section.

Code of Conduct¶

Help us keep zhmcclient open and inclusive. Please read and follow our Code of Conduct.

Repository¶

The repository for zhmcclient is on GitHub:

https://github.com/zhmcclient/python-zhmcclient

Setting up the development environment¶

The development environment is pretty easy to set up.

Besides having a supported operating system with a supported Python version (see Supported environments), it is recommended that you set up a virtual Python environment.

Then, with a virtual Python environment active, clone the Git repo of this project and prepare the development environment with make develop:

$ git clone git@github.com:zhmcclient/python-zhmcclient.git
$ cd python-zhmcclient
$ make develop

This will install all prerequisites the package needs to run, as well as all prerequisites that you need for development.

Generally, this project uses Make to do things in the currently active Python environment. The command make help (or just make) displays a list of valid Make targets and a short description of what each target does.

Building the documentation¶

The ReadTheDocs (RTD) site is used to publish the documentation for the zhmcclient package at http://python-zhmcclient.readthedocs.io/

This page automatically gets updated whenever the master branch of the Git repo for this package changes.

In order to build the documentation locally from the Git work directory, issue:

$ make builddoc

The top-level document to open with a web browser will be build_doc/html/docs/index.html.

Testing¶

To run unit tests in the currently active Python environment, issue one of these example variants of make test:

$ make test                                  # Run all unit tests
$ TESTCASES=test_resource.py make test       # Run only this test source file
$ TESTCASES=TestInit make test               # Run only this test class
$ TESTCASES="TestInit or TestSet" make test  # py.test -k expressions are possible

To run the unit tests and some more commands that verify the project is in good shape in all supported Python environments, use Tox:

$ tox                              # Run all tests on all supported Python versions
$ tox -e py27                      # Run all tests on Python 2.7
$ tox -e py27 test_resource.py     # Run only this test source file on Python 2.7
$ tox -e py27 TestInit             # Run only this test class on Python 2.7
$ tox -e py27 TestInit or TestSet  # py.test -k expressions are possible

The positional arguments of the tox command are passed to py.test using its -k option. Invoke py.test --help for details on the expression syntax of its -k option.

Running function tests against a real HMC and CPC¶

The function tests (in tests/function/test_*.py) can be run against a faked HMC/CPC (using the zhmcclient mock support), or against a real HMC/CPC.

By default, the function tests are run against the faked HMC/CPC. To run them against a real HMC/CPC, you must:

Specify the name of the target CPC in the ZHMC_TEST_CPC environment variable. This environment variable is the control point that decides between using a real HMC/CPC and using the faked environment:
```
export ZHMC_TEST_CPC=S67B
```

Have an HMC credentials file at location examples/hmccreds.yaml that specifies the target CPC (among possibly further CPCs) in its cpcs item:

cpcs:

  S67B:
    description: "z13s in DPM mode"
    contact: "Joe"
    hmc_host: "10.11.12.13"
    hmc_userid: myuserid
    hmc_password: mypassword

  # ... more CPCs

There is an example HMC credentials file in the repo, at examples/example_hmccreds.yaml. For a description of its format, see Format of the HMC credentials file.

Enabling logging for function tests¶

The function tests always log to stderr. What can be logged are the following two components:

api: Calls to and returns from zhmcclient API functions (at debug level).
hmc: Interactions with the HMC (i.e. HTTP requests and responses, at debug level).

By default, the log component and level is set to:

all=warning

meaning that all components log at warning level or higher.

To set different log levels for the log components, set the ZHMC_LOG environment variable as follows:

export ZHMC_LOG=COMP=LEVEL[,COMP=LEVEL[,...]]

Where:

COMP is one of: all, api, hmc.
LEVEL is one of: error, warning, info, debug.

For example, to enable logging of the zhmcclient API calls and the interactions with the HMC, use:

export ZHMC_LOG=api=debug,hmc=debug

or, shorter:

export ZHMC_LOG=all=debug

Format of the HMC credentials file¶

The HMC credentials file is used for specifying real HMCs/CPCs to be used by function tests. Its syntax is YAML, and the cpcs item relevant for function testing has the following structure:

cpcs:

  "CPC1":
    description: "z13 test system"
    contact: "Amy"
    hmc_host: "10.10.10.11"           # required
    hmc_userid: "myuser1"             # required
    hmc_password: "mypassword1"       # required

  "CPC2":
    description: "z14 development system"
    contact: "Bob"
    hmc_host: "10.10.10.12"
    hmc_userid: "myuser2"
    hmc_password: "mypassword2"

In the example above, any words in double quotes are data and can change, and any words without double quotes are considered keywords and must be specified as shown.

“CPC1” and “CPC2” are CPC names that are used to select an entry in the file. The entry for a CPC contains data about the HMC managing that CPC, with its host, userid and password. If two CPCs are managed by the same HMC, there would be two CPC entries with the same HMC data.

Contributing¶

Third party contributions to this project are welcome!

In order to contribute, create a Git pull request, considering this:

Test is required.
Each commit should only contain one “logical” change.
A “logical” change should be put into one commit, and not split over multiple commits.
Large new features should be split into stages.
The commit message should not only summarize what you have done, but explain why the change is useful.
The commit message must follow the format explained below.

What comprises a “logical” change is subject to sound judgement. Sometimes, it makes sense to produce a set of commits for a feature (even if not large). For example, a first commit may introduce a (presumably) compatible API change without exploitation of that feature. With only this commit applied, it should be demonstrable that everything is still working as before. The next commit may be the exploitation of the feature in other components.

For further discussion of good and bad practices regarding commits, see:

Format of commit messages¶

A commit message must start with a short summary line, followed by a blank line.

Optionally, the summary line may start with an identifier that helps identifying the type of change or the component that is affected, followed by a colon.

It can include a more detailed description after the summary line. This is where you explain why the change was done, and summarize what was done.

It must end with the DCO (Developer Certificate of Origin) sign-off line in the format shown in the example below, using your name and a valid email address of yours. The DCO sign-off line certifies that you followed the rules stated in DCO 1.1. In short, you certify that you wrote the patch or otherwise have the right to pass it on as an open-source patch.

We use GitCop during creation of a pull request to check whether the commit messages in the pull request comply to this format. If the commit messages do not comply, GitCop will add a comment to the pull request with a description of what was wrong.

Example commit message:

cookies: Add support for delivering cookies

Cookies are important for many people. This change adds a pluggable API for
delivering cookies to the user, and provides a default implementation.

Signed-off-by: Random J Developer <random@developer.org>

Use git commit --amend to edit the commit message, if you need to.

Use the --signoff (-s) option of git commit to append a sign-off line to the commit message with your name and email as known by Git.

If you like filling out the commit message in an editor instead of using the -m option of git commit, you can automate the presence of the sign-off line by using a commit template file:

Create a file outside of the repo (say, ~/.git-signoff.template) that contains, for example:

<one-line subject>

<detailed description>

Signed-off-by: Random J Developer <random@developer.org>

Configure Git to use that file as a commit template for your repo:
```
git config commit.template ~/.git-signoff.template
```

Releasing a version¶

This section shows the steps for releasing a version to PyPI.

It covers all variants of versions that can be released:

Releasing the master branch as a new major or minor version (M+1.0.0 or M.N+1.0)
Releasing a stable branch as a new update (= fix) version (M.N.U+1)

This description assumes that you are authorized to push to the upstream repo at https://github.com/zhmcclient/python-zhmcclient and that the upstream repo has the remote name origin in your local clone.

Switch to your work directory of your local clone of the python-zhmcclient Git repo and perform the following steps in that directory.
Set shell variables for the version and branch to be released:
- MNU - Full version number M.N.U this release should have
- MN - Major and minor version numbers M.N of that full version
- BRANCH - Name of the branch to be released
When releasing the master branch as a new major or minor version (e.g. 0.19.0):
```
MNU=0.19.0
MN=0.19
BRANCH=master
```
When releasing a stable branch as a new update (=fix) version (e.g. 0.18.1):
```
MNU=0.18.1
MN=0.18
BRANCH=stable_$MN
```
Check out the branch to be released, make sure it is up to date with upstream, and create a topic branch for the version to be released:
```
git status  # Double check the work directory is clean
git checkout $BRANCH
git pull
git checkout -b release_$MNU
```
Edit the version file and set the version to be released:
```
vi zhmcclient/_version.py
```
__version__ = 'M.N.U'

Where M.N.U is the version to be released, e.g. 0.18.1.

You can verify that this version is picked up by setup.py as follows:
```
./setup.py --version
0.18.1
```
Edit the change log:
```
vi docs/changes.rst
```
and make the following changes in the section of the version to be released:
- Finalize the version to the version to be released.
- Remove the statement that the version is in development.
- Change the release date to today´s date.
- Make sure that all changes are described.
- Make sure the items shown in the change log are relevant for and understandable by users.
- In the “Known issues” list item, remove the link to the issue tracker and add text for any known issues you want users to know about.
- Remove all empty list items in that section.

Commit your changes and push them upstream:

git add docs/changes.rst
git commit -sm "Release $MNU"
git push --set-upstream origin release_$MNU

On GitHub, create a Pull Request for branch release_$MNU. This will trigger the CI runs in Travis and Appveyor.

Important: When creating Pull Requests, GitHub by default targets the master branch. If you are releasing a stable branch, you need to change the target branch of the Pull Request to stable_M.N.
On GitHub, close milestone M.N.U.
On GitHub, once the checks for this Pull Request succeed:
- Merge the Pull Request (no review is needed).
- Delete the branch of the Pull Request (release_M.N.U)
Checkout the branch you are releasing, update it from upstream, and delete the local topic branch you created:
```
git checkout $BRANCH
git pull
git branch -d release_$MNU
```
Tag the version:

Create a tag for the new version and push the tag addition upstream:
```
git status    # Double check the branch to be released is checked out
git tag $MNU
git push --tags
```
The pushing of the tag triggers an RTD docs build of its stable version.

If the previous commands fail because this tag already exists for some reason, delete the tag locally and remotely:
```
git tag --delete $MNU
git push --delete origin $MNU
```
and try again.
On GitHub, edit the new tag M.N.U, and create a release description on it. This will cause it to appear in the Release tab.

You can see the tags in GitHub via Code -> Releases -> Tags.
Upload the package to PyPI:
```
make upload
```
This will show the package version and will ask for confirmation.

Important: Double check that the correct package version (M.N.U, without any development suffix) is shown.

Attention!! This only works once for each version. You cannot re-release the same version to PyPI, or otherwise update it.

Verify that the released version arrived on PyPI: https://pypi.python.org/pypi/zhmcclient/
On RTD, verify that it shows the version to be released as its stable version:

RTD stable version: https://python-zhmcclient.readthedocs.io/en/stable.

If it does not, trigger a build of RTD version “stable” on the RTD project page:

RTD build page: https://readthedocs.org/projects/python-zhmcclient/builds/

Once that build is complete, verify again.
If you released the master branch, it needs a new fix stream.

Create a branch for its fix stream and push it upstream:
```
git status    # Double check the branch to be released is checked out
git checkout -b stable_$MN
git push --set-upstream origin stable_$MN
```
Log on to the RTD project python-zhmcclient and activate the new version (=branch) stable_M.N as a version to be built.
If you released the master branch, a new version should be started as described in Starting a new version.

This may be a new minor version on the same major version, or a new major version.

Starting a new version¶

This section shows the steps for starting development of a new version.

These steps may be performed right after the steps for Releasing a version, or independently.

This section covers all variants of new versions:

A new major or minor version for new development based upon the master branch.
A new update (=fix) version based on a stable branch.

This description assumes that you are authorized to push to the upstream repo at https://github.com/zhmcclient/python-zhmcclient and that the upstream repo has the remote name origin in your local clone.

Switch to your work directory of your local clone of the python-zhmcclient Git repo and perform the following steps in that directory.
Set shell variables for the version to be started and its base branch:
- MNU - Full version number M.N.U of the new version to be started
- MN - Major and minor version numbers M.N of that full version
- BRANCH - Name of the branch the new version is based upon
When starting a (major or minor) version (e.g. 0.20.0) based on the master branch:
```
MNU=0.20.0
MN=0.20
BRANCH=master
```
When starting an update (=fix) version (e.g. 0.19.1) based on a stable branch:
```
MNU=0.19.1
MN=0.19
BRANCH=stable_$MN
```
Check out the branch the new version is based on, make sure it is up to date with upstream, and create a topic branch for the new version:
```
git status  # Double check the work directory is clean
git checkout $BRANCH
git pull
git checkout -b start_$MNU
```
Edit the version file and set the version to the new version and to development:
```
vi zhmcclient/_version.py
```
__version__ = 'M.N.U.dev1'

Where M.N.U is the version to be started.

You can verify that this version is picked up by setup.py as follows:
```
./setup.py --version
0.20.0.dev1
```

Edit the change log:

vi docs/changes.rst

and insert the following section before the top-most section:

Version 0.20.0
^^^^^^^^^^^^^^

Released: not yet

**Incompatible changes:**

**Deprecations:**

**Bug fixes:**

**Enhancements:**

**Known issues:**

* See `list of open issues`_.

.. _`list of open issues`: https://github.com/zhmcclient/python-zhmcclient/issues

Commit your changes and push them upstream:

git add docs/changes.rst
git commit -sm "Start $MNU"
git push --set-upstream origin start_$MNU

On GitHub, create a Pull Request for branch start_M.N.U.

Important: When creating Pull Requests, GitHub by default targets the master branch. If you are starting based on a stable branch, you need to change the target branch of the Pull Request to stable_M.N.
On GitHub, create a milestone for the new version M.N.U.

You can create a milestone in GitHub via Issues -> Milestones -> New Milestone.
On GitHub, go through all open issues and pull requests that still have milestones for previous releases set, and either set them to the new milestone, or to have no milestone.
On GitHub, once the checks for this Pull Request succeed:
- Merge the Pull Request (no review is needed)
- Delete the branch of the Pull Request (start_M.N.U)
Checkout the branch the new version is based on, update it from upstream, and delete the local topic branch you created:
```
git checkout $BRANCH
git pull
git branch -d start_$MNU
```

Appendix¶

This section contains information that is referenced from other sections, and that does not really need to be read in sequence.

Base classes for resources¶

Base definitions for resource manager classes.

Resource manager classes exist for each resource type and are helper classes that provide functionality common for the resource type.

Resource manager objects are not necessarily singleton objects, because they have a scope of a certain set of resource objects. For example, the resource manager object for LPARs exists once for each CPC managed by the HMC, and the resource object scope of each LPAR manager object is the set of LPARs in that CPC.

class zhmcclient.BaseManager(resource_class, class_name, session, parent, base_uri, oid_prop, uri_prop, name_prop, query_props, list_has_name=True)[source]¶

Abstract base class for manager classes (e.g. CpcManager).

It defines the interface for the derived manager classes, and implements methods that have a common implementation for the derived manager classes.

Objects of derived manager classes should not be created by users of this package by simply instantiating them. Instead, such objects are created by this package as instance variables of Client and other resource objects, e.g. cpcs. For this reason, the __init__() method of this class and of its derived manager classes are considered internal interfaces and their parameters are not documented and may change incompatibly.

__repr__()[source]¶: Return a string with the state of this manager object, for debug purposes.

invalidate_cache()[source]¶

Invalidate the Name-URI cache of this manager.

The zhmcclient maintains a Name-URI cache in each manager object, which caches the mappings between resource URIs and resource names, to speed up certain zhmcclient methods.

The Name-URI cache is properly updated during changes on the resource name (e.g. via update_properties()) or changes on the resource URI (e.g. via resource creation or deletion), if these changes are performed through the same Python manager object.

However, changes performed through a different manager object (e.g. because a different session, client or parent resource object was used), or changes performed in a different Python process, or changes performed via other means than the zhmcclient library (e.g. directly on the HMC) will not automatically update the Name-URI cache of this manager.

In cases where the resource name or resource URI are effected by such changes, the Name-URI cache can be manually invalidated by the user, using this method.

Note that the Name-URI cache automatically invalidates itself after a certain time since the last invalidation. That auto invalidation time can be configured using the name_uri_cache_timetolive attribute of the RetryTimeoutConfig class.

resource_class¶: The Python class of the parent resource of this manager.

class_name¶: The resource class name

session¶

Session with the HMC.

Type:	`Session`

parent¶

Parent resource defining the scope for this manager.

None, if the manager has no parent, i.e. when it manages top-level resources.

Type:	Subclass of `BaseResource`

resource_object(uri_or_oid, props=None)[source]¶

Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

This method is an internal helper function and is not normally called by users.

The returned resource object will have the following minimal set of properties set automatically:

object-uri

object-id

parent

class

Additional properties for the Python resource object can be specified by the caller.

Parameters:	uri_or_oid (string) – object-uri or object-id of the resource. props (dict) – Property values in addition to the minimal list of properties that are set automatically (see above).
Returns:	A Python resource object for this resource class.
Return type:	Subclass of `BaseResource`

findall(**filter_args)[source]¶

Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g. for CPCs, a list of Cpc objects is returned).

Any resource property may be specified in a filter argument. For details about filter arguments, see Filtering.

The zhmcclient implementation handles the specified properties in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.

If the “name” property is specified as the only filter argument, an optimized lookup is performed that uses a name-to-URI cache in this manager object. This this optimized lookup uses the specified match value for exact matching and is not interpreted as a regular expression.

Authorization requirements:

see the list() method in the derived classes.

Parameters:	**filter_args – All keyword arguments are used as filter arguments. Specifying no keyword arguments causes no filtering to happen. See the examples for usage details.
Returns:	List of resource objects in scope of this manager object that match the filter arguments. These resource objects have a minimal set of properties.
Raises:	Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).

Examples:

The following example finds partitions in a CPC by status. Because the ‘status’ resource property is also a valid Python variable name, there are two ways for the caller to specify the filter arguments for this method:

As named parameters:
```
run_states = ['active', 'degraded']
run_parts = cpc.partitions.find(status=run_states)
```
As a parameter dictionary:
```
run_parts = cpc.partitions.find(**{'status': run_states})
```
The following example finds adapters of the OSA family in a CPC with an active status. Because the resource property for the adapter family is named ‘adapter-family’, it is not suitable as a Python variable name. Therefore, the caller can specify the filter argument only as a parameter dictionary:
```
filter_args = {'adapter-family': 'osa', 'status': 'active'}
active_osa_adapters = cpc.adapters.findall(**filter_args)
```

find(**filter_args)[source]¶

Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g. for a CPC, a Cpc object is returned).

Any resource property may be specified in a filter argument. For details about filter arguments, see Filtering.

The zhmcclient implementation handles the specified properties in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.

If the “name” property is specified as the only filter argument, an optimized lookup is performed that uses a name-to-URI cache in this manager object. This this optimized lookup uses the specified match value for exact matching and is not interpreted as a regular expression.

Authorization requirements:

see the list() method in the derived classes.

Parameters:	**filter_args – All keyword arguments are used as filter arguments. Specifying no keyword arguments causes no filtering to happen. See the examples for usage details.
Returns:	Resource object in scope of this manager object that matches the filter arguments. This resource object has a minimal set of properties.
Raises:	`NotFound` – No matching resource found. `NoUniqueMatch` – More than one matching resource found. Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).

Examples:

The following example finds a CPC by its name. Because the ‘name’ resource property is also a valid Python variable name, there are two ways for the caller to specify the filter arguments for this method:

As named parameters:
```
cpc = client.cpcs.find(name='CPC001')
```
As a parameter dictionary:
```
filter_args = {'name': 'CPC0001'}
cpc = client.cpcs.find(**filter_args)
```
The following example finds a CPC by its object ID. Because the ‘object-id’ resource property is not a valid Python variable name, the caller can specify the filter argument only as a parameter dictionary:
```
filter_args = {'object-id': '12345-abc...de-12345'}
cpc = client.cpcs.find(**filter_args)
```

list(full_properties=False, filter_args=None)[source]¶

Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g. for CPCs, a list of Cpc objects is returned).

Any resource property may be specified in a filter argument. For details about filter arguments, see Filtering.

The zhmcclient implementation handles the specified properties in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.

At the level of the BaseManager class, this method defines the interface for the list() methods implemented in the derived resource classes.

Authorization requirements:

see the list() method in the derived classes.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only a minimal set as returned by the list operation. filter_args (dict) – Filter arguments. None causes no filtering to happen. See the examples for usage details.
Returns:	List of resource objects in scope of this manager object that match the filter arguments. These resource objects have a set of properties according to the full_properties parameter.
Raises:	Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).

Examples:

The following example finds those OSA adapters in cage ‘1234’ of a given CPC, whose state is ‘stand-by’, ‘reserved’, or ‘unknown’:

filter_args = {
    'adapter-family': 'osa',
    'card-location': '1234-.*',
    'state': ['stand-by', 'reserved', 'unknown'],
}
osa_adapters = cpc.adapters.list(full_properties=True,
                                 filter_args=filter_args)

The returned resource objects will have the full set of properties.

find_by_name(name)[source]¶

Find a resource by name (i.e. value of its ‘name’ resource property) and return its Python resource object (e.g. for a CPC, a Cpc object is returned).

This method performs an optimized lookup that uses a name-to-URI mapping cached in this manager object.

This method is automatically used by the find() and findall() methods, so it does not normally need to be used directly by users.

Authorization requirements:

see the list() method in the derived classes.

Parameters:	name (string) – Name of the resource (value of its ‘name’ resource property). Regular expression matching is not supported for the name for this optimized lookup.
Returns:	Resource object in scope of this manager object that matches the filter arguments. This resource object has a minimal set of properties.
Raises:	`NotFound` – No matching resource found. Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).

Examples:

The following example finds a CPC by its name:
```
cpc = client.cpcs.find_by_name('CPC001')
```

flush()[source]¶

Invalidate the Name-URI cache of this manager.

Deprecated: This method is deprecated and using it will cause a exceptions.DeprecationWarning to be issued. Use invalidate_cache() instead.

Base definitions for resource classes.

Resource objects represent the real manageable resources in the systems managed by the HMC.

class zhmcclient.BaseResource(manager, uri, name, properties)[source]¶

Abstract base class for resource classes (e.g. Cpc) representing manageable resources.

It defines the interface for the derived resource classes, and implements methods that have a common implementation for the derived resource classes.

Objects of derived resource classes are representations of the actual manageable resources in the HMC or in systems managed by the HMC.

Objects of derived resource classes should not be created by users of this package by simply instantiating the derived resource classes. Instead, such objects are created by this package and are returned to the user as a result of methods such as find() or list(). For this reason, the __init__() method of this class and of its derived resource classes are considered internal interfaces and their parameters are not documented and may change incompatibly.

properties¶

The properties of this resource that are currently present in this Python object. Will not be None.

Key: Name of the property.

Value: Value of the property.

See the respective ‘Data model’ sections in the HMC API book for a description of the resources along with their properties.

The dictionary contains either the full set of resource properties, or a subset thereof, or can be empty in some cases.

Because the presence of properties in this dictionary depends on the situation, the purpose of this dictionary is only for iterating through the resource properties that are currently present.

Specific resource properties should be accessed via:

The resource name, via the name attribute.

The resource URI, via the uri attribute.

Any resource property, via the get_property() or prop() methods.

The properties in this dictionary are mutable. However, the properties of the actual manageable resources may or may not be mutable. Mutability for each resource property is indicated with the ‘w’ qualifier in its data model in the HMC API book.

Type:	dict

uri¶

The canonical URI path of the resource. Will not be None.

Example: /api/cpcs/12345

Type:	string

name¶

The name of the resource. Will not be None.

The resource name is unique across its sibling resources of the same type and with the same parent resource.

Accessing this property will cause the properties of this resource object to be updated from the HMC, if it does not yet contain the property for the resource name.

Type:	string

manager¶

Manager object for this resource (and for all resources of the same type in the scope of that manager). Will not be None.

Type:	Subclass of `BaseManager`

full_properties¶

A boolean indicating whether or not the resource properties in this object are the full set of resource properties.

Note that listing resources and creating new resources produces objects that have less than the full set of properties.

properties_timestamp¶: The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).

pull_full_properties()[source]¶

Retrieve the full set of resource properties and cache them in this object.

Authorization requirements:

Object-access permission to this resource.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

get_property(name)[source]¶

Return the value of a resource property.

If the resource property is not cached in this object yet, the full set of resource properties is retrieved and cached in this object, and the resource property is again attempted to be returned.

Authorization requirements:

Object-access permission to this resource.

Parameters:	name (string) – Name of the resource property, using the names defined in the respective ‘Data model’ sections in the HMC API book.
Returns:	The value of the resource property.
Raises:	`KeyError` – The resource property could not be found (also not in the full set of resource properties). `HTTPError` `ParseError` `AuthError` `ConnectionError`

prop(name, default=None)[source]¶

Return the value of a resource property, applying a default if it does not exist.

If the resource property is not cached in this object yet, the full set of resource properties is retrieved and cached in this object, and the resource property is again attempted to be returned.

Authorization requirements:

Object-access permission to this resource.

Parameters:	name (string) – Name of the resource property, using the names defined in the respective ‘Data model’ sections in the HMC API book. default – Default value to be used, if the resource property does not exist.
Returns:	The value of the resource property.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

__str__()[source]¶

Return a human readable string representation of this resource.

Example result:

Cpc(name=P0000S12,
    object-uri=/api/cpcs/f1bc49af-f71a-3467-8def-3c186b5d9352,
    status=service-required)

__repr__()[source]¶

Return a string with the state of this resource, for debug purposes.

Note that the derived resource classes that have child resources have their own __repr__() methods, because only they know which child resources they have.

Glossary¶

This documentation uses a few special terms:

HMC

Hardware Management Console; the node the zhmcclient talks to.

session-id

an opaque string returned by the HMC as the result of a successful logon, for use by subsequent operations instead of credential data. The HMC gives each newly created session-id a lifetime of 10 hours, and expires it after that.

fulfillment

The act of satisfying requests for creation, modification, or deletion of storage volumes in a storage subsystem (i.e. of the actual storage backing a storage volume object).

Storage volume objects have a fulfillment state indicating whether the volume is fulfilled, which means that the request for creation or modification has been carried out and the state of the backing volume is now in sync with the storage volume object.

Storage group objects also have a fulfillment state indicating whether all of its storage volumes are fulfilled.

Special type names¶

This documentation uses a few special terms to refer to Python types:

string

a unicode string or a byte string

unicode string

a Unicode string type (unicode in Python 2, and str in Python 3)

byte string

a byte string type (str in Python 2, and bytes in Python 3). Unless otherwise indicated, byte strings in this package are always UTF-8 encoded.

number

one of the number types int, long (Python 2 only), or float.

integer

one of the integer types int or long (Python 2 only).

timestamp

a Timestamp-typed value as used in the HMC API. This is a non-negative integer value representing a point in time as milliseconds since the UNIX epoch (1970-01-01 00:00:00 UTC), or the value -1 to indicate special treatment of the value.

json object

a dict object that is a Python representation of a valid JSON object. See py-to-json-table for details.

header dict

a dict object that specifies HTTP header fields, as follows:

key (string): Name of the header field, in any lexical case. Dictionary key lookup is case sensitive, however.

value (string): Value of the header field.

callable

a type for callable objects (e.g. a function, calling a class returns a new instance, instances are callable if they have a __call__() method).

DeprecationWarning

a standard Python warning that indicates the use of deprecated functionality. See section Deprecations for details.

HMC API version

an HMC API version, as a tuple of (api_major_version, api_minor_version), where:

api_major_version (integer): The numeric major version of the HMC API.
api_minor_version (integer): The numeric minor version of the HMC API.

Resource model¶

This section lists the resources that are available at the HMC API.

The term resource in this documentation is used to denote a managed object in the system. The result of retrieving a resource through the HMC API is termed a resource representation. Python classes for resources are termed to represent a resource.

For resources within a CPC, this section covers CPCs in DPM mode and classic mode, but omits any resources that are available only in ensemble mode. See section CPCs for a definition of the CPC modes.

Some of the items in this section are qualified as short terms. They are not separate types of resources, but specific usages of resources. For example, “storage adapter” is a short term for the resource “adapter” when used for attaching storage.

Resources scoped to the HMC¶

Console

The HMC itself.

Group

TBD - Not yet supported.

Hardware Message

TBD - Not yet supported.

Also scoped to CPCs in any mode.

Job

The execution of an asynchronous HMC operation.

LDAP Server Definition

The information in an HMC about an LDAP server that may be used for HMC user authorization purposes.

Metrics Context

A user-created definition of metrics that can be retrieved.

Password Rule

A rule which HMC users need to follow when creating a HMC logon password.

Session

A session between a client of the HMC API and the HMC.

Task

An action that an HMC user with appropriate authority can perform.

User

An HMC user.

User Pattern

A pattern for HMC user IDs that are not defined on the HMC as users but can be verified by an LDAP server for user authentication.

User Role

An authority role which can be assigned to one or more HMC users.

Resources scoped to CPCs in any mode¶

Capacity Record

TBD - Not yet supported.

CPC

Central Processor Complex, a physical IBM Z or LinuxONE computer.

For details, see section CPCs.

Resources scoped to CPCs in DPM mode¶

Accelerator Adapter

Short term for an Adapter providing accelerator functions (e.g. the z Systems Enterprise Data Compression (zEDC) adapter for data compression).

Adapter

A physical adapter card (e.g. OSA-Express adapter, Crypto adapter) or a logical adapter (e.g. HiperSockets switch).

For details, see section Adapters.

Adapter Port

Synonym for Port.

Capacity Group

TBD - Not yet supported.

Crypto Adapter

Short term for an Adapter providing cryptographic functions.

FCP Adapter

Short term for a Storage Adapter supporting FCP (Fibre Channel Protocol).

FCP Port

Short term for a Port of an FCP Adapter.

HBA

A logical entity that provides a Partition with access to external storage area networks (SANs) through an FCP Adapter.

For details, see section HBAs.

HBA resource objects only exist when the “dpm-storage-management” feature is not enabled. See section Storage Groups for details.

Network Adapter

Short term for an Adapter for attaching networks (e.g. OSA-Express adapter).

Network Port

Short term for a Port of a Network Adapter.

NIC

Network Interface Card, a logical entity that provides a Partition with access to external communication networks through a Network Adapter.

For details, see section NICs.

Partition

A subset of the hardware resources of a CPC in DPM mode, virtualized as a separate computer.

For details, see section Partitions.

Port

The physical connector port (jack) of an Adapter.

For details, see section Ports.

Storage Adapter

Short term for an Adapter for attaching storage.

Storage Group

A grouping entity for a set of FCP or ECKD (=FICON) storage volumes. A storage group can be attached to a partition which will cause its storage volumes to be attached to the partition.

Storage Group objects exist only when the “dpm-storage-management” feature is enabled on the CPC. For details, see section Storage Groups.

Storage Group Template

A template for Storage Groups.

Storage Port

Short term for a Port of a Storage Adapter.

Storage Volume

An FCP or ECKD (=FICON) storage volume defined in context of a storage group. The life cycle of a storage volume includes being defined but not fulfilled, being fulfilled but not attached, and finally being attached to a partition.

Storage Volume objects exist only when the “dpm-storage-management” feature is enabled on the CPC. For details, see section Storage Groups.

Storage Volume Template

A template for Storage Volumes.

vHBA

Synonym for HBA. In this resource model, HBAs are always virtualized because they belong to a Partition. Therefore, the terms vHBA and HBA can be used interchangeably.

Virtual Function

A logical entity that provides a Partition with access to an Accelerator Adapter.

For details, see section Virtual Functions.

Virtual Storage Resource

A representation of a storage-related z/Architecture device in a partition. For FCP type storage volumes, a Virtual Storage Resource object represents an HBA through which the attached storage volume is accessed. For FICON (ECKD) type storage volumes, a Virtual Storage Resource object represents the attached storage volume itself.

Virtual Storage Resource objects exist only when the “dpm-storage-management” feature is enabled on the CPC. For details, see section Storage Groups.

Virtual Switch

A virtualized networking switch connecting NICs with a Network Port.

For details, see section Virtual Switches.

vNIC

Synonym for NIC. In this resource model, NICs are always virtualized because they belong to a Partition. Therefore, the terms vNIC and NIC can be used interchangeably.

Resources scoped to CPCs in classic (and ensemble) mode¶

Activation Profile

A general term for specific types of activation profiles:

Reset Activation Profile
Image Activation Profile
Load Activation Profile

Group Profile

TBD

Image Activation Profile

A specific Activation Profile that defines characteristics of an LPAR.

Load Activation Profile

A specific Activation Profile that defines an operating system image that can be loaded (booted) into an LPAR.

Logical Partition

LPAR

A subset of the hardware resources of a CPC in classic mode (or ensemble mode), virtualized as a separate computer.

For details, see section LPARs.

Reset Activation Profile

A specific Activation Profile that defines characteristics of a CPC.

Bibliography¶

X.509: ITU-T X.509, Information technology - Open Systems Interconnection - The Directory: Public-key and attribute certificate frameworks
RFC2616: IETF RFC2616, Hypertext Transfer Protocol - HTTP/1.1, June 1999
RFC2617: IETF RFC2617, HTTP Authentication: Basic and Digest Access Authentication, June 1999
RFC3986: IETF RFC3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005
RFC6874: IETF RFC6874, Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers, February 2013
HMC API: The Web Services API of the z Systems Hardware Management Console, described in the following books:
HMC API 2.11.1: IBM SC27-2616, System z Hardware Management Console Web Services API (Version 2.11.1)
HMC API 2.12.0: IBM SC27-2617, System z Hardware Management Console Web Services API (Version 2.12.0)
HMC API 2.12.1: IBM SC27-2626, System z Hardware Management Console Web Services API (Version 2.12.1)
HMC API 2.13.0: IBM SC27-2627, z Systems Hardware Management Console Web Services API (Version 2.13.0)
HMC API 2.13.1: IBM SC27-2634, z Systems Hardware Management Console Web Services API (Version 2.13.1)
HMC API 2.14.0: IBM SC27-2636, IBM Z Hardware Management Console Web Services API (Version 2.14.0)
HMC API 2.14.1: IBM SC27-2637, IBM Z Hardware Management Console Web Services API (Version 2.14.1)
HMC API 2.15.0: IBM SC27-2638, IBM Z Hardware Management Console Web Services API (Version 2.15.0) (covers both GA1 and GA2)
HMC Operations Guide: The operations guide of the z Systems Hardware Management Console, in the following books (subset):
HMC Operations Guide 2.11.1: IBM SC28-6905, System z Hardware Management Console Operations Guide (Version 2.11.1)
HMC Operations Guide 2.12.1: System z Hardware Management Console Operations Guide (Version 2.12.1)
HMC Operations Guide 2.13.1: z Systems Hardware Management Console Operations Guide (Version 2.13.1)
HMC Operations Guide 2.14.1: Hardware Management Console Operations Guide (Version 2.14.1)
HMC Operations Guide 2.15.0: Hardware Management Console Operations Guide (Version 2.15.0) (covers both GA1 and GA2)

Change log¶

Version 0.27.1.dev1¶

Released: not yet

Incompatible changes:

Deprecations:

Bug fixes:

Enhancements:

Known issues:

See list of open issues.

Version 0.27.0¶

Released: 2020-09-10

This version contains all fixes up to 0.26.2.

Bug fixes:

Fixed Travis setup by removing circumventions for old issues that caused problems meanwhile.
Adjusted versions of dependent packages for development environment to fix issues on Python 3.4.
Fixed AttributeError when calling partition.list_attached_storage_groups(). (See issue #629)
Docs: Fixed description to start a new version that was missing updating the version to the new development version. (See issue #639)
Docs: Fixed description of installation from a repo branch. (See issue #638)
Test: Fixed missing ffi.h file on CygWin when testing (See issue #655)
Docs: Fixed links to HMC WS API books that have become invalid. (See issue #665)
Fixed empty port list returned by PortManager.list() for CNA adapters.
Install: Fixed the broken installation from the source distribution archive on Pypi (see issue #651)
Test: Pinned ‘pyrsistent’ package (used by jupyter notebook) to <0.16.0 on Python 2.7 and to <0.15.0 on Python 3.4.
Test: Fixed issue where virtualenv on pypy3 created env one level higher. (see issue #673)

Enhancements:

Added an easy way to print debug information for inclusion into issues, via python -m zhmcclient.debuginfo. (See issue #640)
Added discover_fcp() and get_connection_report() methods to the StorageGroup resource. Added an example discover_storage_group.py that uses the two new methods. (See issue #623)
Test: Running coveralls for all Python versions in order to cover Python version-specific code. The coveralls.io web site consolidates these runs properly into a single result.
Docs: Added links to HMC WS APi and Operations books for z15. (Related to issue #665)
Added the z15 machine types 8561 and 8562 for detecting the maximum number of partitions, and started exploiting the new ‘maximum-partitions’ property of the CPC for this purpose.

Cleanup

Docs: Removed link to “KVM for IBM z Systems - System Administration” book, because the product is no longer supported. (Related to issue #665)
Changed the theme of the documentation on RTD from classic to sphinx_rtd_theme (See issue #668)
Test: Added ‘make installtest’ to the Makefile to test installation of the package into an empty virtualenv using all supported installation methods. Added these install tests to the Travis CI tests. (related to issue #651)

Version 0.26.0¶

Released: 2020-01-24

This version contains all changes from 0.25.1.

Bug fixes:

Added the missing os_ipl_token parameter to Lpar.scsi_dump().
Migrated from using the yamlordereddictloader package to using the yamlloader package, because yamlordereddictloader got deprecated. (See issue #605)
Pinned version of PyYAML to <5.3 for Python 3.4 because 5.3 removed support for Python 3.4
Increased minimum version of stomp.py to 4.1.23 to pick up a fix for hangs during NotificationReceiver.close(). (See issue #572)

Enhancements:

Promoted the development status of the zhmcclient package on Pypi from 3 - Alpha to 4 - Beta.
Added support for Python 3.8 to the package metadata and to the Travis and Appveyor and Tox environments. (See issue #596)
Dropped the use of the pbr package. The package version is now managed in zhmcclient/_version.py. (See issue #594)
Test: Added support for TESTOPTS env var to Makefile to be able to specify py.test options when invoking make test.

Version 0.25.0¶

Released: 2019-12-18

Bug fixes:

Docs: Fixed incorrect statement about HMC version 2.14.0 supporting both GA generations of z14 machines.

Enhancements:

Docs: Added HMC version 2.14.1 in “Bibliography” and “Introduction” sections.
Added support for following LPAR operations:
- Lpar.psw_restart() (HMC: “PSW Restart”)
- Lpar.scsi_dump() (HMC: “SCSI Dump”)
Added support for Storage Template objects in DPM mode (see issue #589).

Version 0.24.0¶

Released: 2019-08-15

Incompatible changes:

Operations that resulted in HTTP status 403, reason 1 (“The user under which the API request was authenticated does not have the required authority to perform the requested action.”) so far raised ServerAuthError. However, that exception does not represent that situation properly, because the login user is actually properly authenticated. The handling of this case was changed to now raise HTTPError instead of ServerAuthError. This change is only incompatible to users of the zhmcclient API who have code handling this exception specifically.

Bug fixes:

Fixed LookupError on unknown encoding ISO-5589-1 in test_session.py test that occurred with latest requests_mock package.
Increased minimum version of flake8 to 3.7.0 due to difficulties with recognizing certain ‘noqa’ statements. This required explicitly specifying its dependent pycodestyle and pyflakes packages with their minimum versions, because the dependency management did not work with our minimum package versions.
Fixed use of incorrect HTTP method in Console.get_audit_log() and Console.get_security_log(). See issue #580.

Enhancements:

Improved end2end test support for zhmcclient and its using projects. The zhmcclient.testutils package already provides some support for end2end tests by users of the zhmcclient package. It is also used by the end2end tests of the zhmcclient package itself. This change improves that support, mainly from a perspective of projects using zhmcclient.
Improved the show_os_messages.py example.
Blanked out the session ID value in the log record for logging off.
Changed import of ‘stomp’ module used for notifications from the HMC, to be lazy, in order to speed up the import of ‘zhmcclient’ for its users. The ‘stomp’ module is now imported when the first zhmcclient.NotificationReceiver object is created. Also, only the class needed is imported now, instead of the entire module.
Added timezone support to the utility function zhmcclient.datetime_from_timestamp(). The desired timezone for the returned object can now be specified as an optional argument, defaulting to UTC for compatibility. This allows displaying HMC timestamps in local time rather than just UTC time.
Added support for specifying multiple notification topics to zhmcclient.NotificationReceiver.

Version 0.23.0¶

Released: 2019-04-04

Bug fixes:

Fixed the list_storage_groups.py example. It used a non-existing property on the Cpc class.
Passwords and session tokens are now correctly blanked out in logs. See issue #560.

Enhancements:

Added support for the new “Zeroize Crypto Domain” operation that allows zeroizing a single crypto domain on a crypto adapter. This operation is supported on z14 GA2 and higher, and the corresponding LinuxOne systems.
Changes in logging support:
- Removed the notion of module-specific loggers from the description of the logging chapter, because that was not used at all, and is not expected to be used in the future: Errors are supposed to be raised as exceptions and not logged, and warnings are supposed to be issued as Python warnings and not logged.
- Escaped newlines to blanks in log messages, so that all log messages are now on a single line.
- Changed the syntax for zhmcclient.api log messages, to start with “Called:” and “Return:” instead of “==>” and “<==”.
- Changed the syntax for zhmcclient.hmc log messages, to start with “Request:” and “Respons:” instead of “HMC request:” and “HMC response:”, in order to have the URLs column-adjusted.

Version 0.22.0¶

Released: 2019-01-07

Enhancements:

Added a mitigation for a firmware defect that causes filtering of adapters by adapter-id to return an empty result when the specified adapter-id contains hex digits (‘a’ to ‘f’). See issue #549.

Version 0.21.0¶

Released: 2018-10-31

Bug fixes:

Update Requests package to 2.20.0 to fix following vulnerability of the National Vulnerability Database: https://nvd.nist.gov/vuln/detail/CVE-2018-18074

Version 0.20.0¶

Released: 2018-10-24

Bug fixes:

Docs: Added missing support statements for the LinuxOne Emperor II machine generations to the documentation (The corresponding z14 was already listed).

Enhancements:

Docs: Streamlined, improved and fixed the description how to release a version and how to start a new version, in the development section of the documentation.
Added support for Python 3.7. This required increasing the minimum versions of several Python packages in order to pick up their Python 3.7 support:
- pyzmq from 16.0.2 to 16.0.4 (While 16.0.4 works for this, only 17.0.0 declares Python 3.6(!) support on Pypi, and Python 3.7 support is not officially declared on Pypi yet for this package).
- PyYAML from 3.12 to 3.13 (see PyYAML issue https://github.com/yaml/pyyaml/issues/126).
Docs: Added support statements for the z14-ZR1 and LinuxONE Rockhopper II machine generations to the documentation.
Added support for the z14-ZR1 and LinuxONE Rockhopper II machine generations to the Cpc.maximum_active_partitions() method.
Provided direct access to the (one) Console object, from the ConsoleManager and CpcManager objects, via a new console property. This is for convenience and avoids having to code find() or list() calls. The returned Console object is cached in the manager object.

Also, added a console property to the FakedConsoleManager class in the mock support, for the same purpose.
Added a property client to class CpcManager for navigating from a Cpc object back to the Client object which is the top of the resource tree.
Added support for the new concept of firmware features to Cpcs and Partitions, by adding methods feature_enabled() and feature_info() to classes Cpc and Partition for inspection of firmware features. The firmware feature concept was introduced starting with the z14-ZR1 and LinuxONE Rockhopper II machine generation. The DPM storage management feature is the first of these new firmware features.
Added support for the DPM storage management feature that is available starting with the z14-ZR1 and LinuxONE Rockhopper II machine generation. This includes new resources like Storage Groups, Storage Volumes, and Virtual Storage Resources. It also includes new methods for managing storage group attachment to Partitions. The new items in the documentation are:
- In 5.1. CPCs: list_associated_storage_groups(), validate_lun_path().
- In 5.5. Partitions: attach_storage_group(), detach_storage_group(), list_attached_storage_groups().
- 5.12. Storage Groups
- 5.13. Storage Volumes
- 5.14. Virtual Storage Resources
- In 5.15 Console: storage_groups
Added support for changing the type of storage adapters between FICON and FCP, via a new method Adapter.change_adapter_type(). This capability was introduced with the z14-ZR1 and LinuxONE Rockhopper II machine generation.

Version 0.19.11¶

Released: 2018-05-14

Note: The version number of this release jumped from 0.19.0 right to 0.19.11, for tooling reasons.

Enhancements:

Docs: Improved the description of installation without Internet access, and considerations on system Python vs. virtual Python environments.
Lowered the minimum version requirements for installing the zhmcclient package, for the packages: requests, pbr, decorator. Added support for tolerating decorator v3.4 in the zhmcclient _logging module.
Adjusted development environment to changes in Appveyor CI environment.

Version 0.19.0¶

Released: 2018-03-15

Incompatible changes:

The Lpar.deactivate() method is now non-forceful by default, but can be made to behave like previously by specifying the new force parameter. In force mode, the deactivation operation is permitted when the LPAR status is “operating”.

Bug fixes:

Fixed a flawed setup of setuptools in Python 2.7 on the Travis CI, where the metadata directory of setuptools existed twice, by adding a script remove_duplicate_setuptools.py that removes the moot copy of the metadata directory (issue #434).
Fixed a bug where multiple Session objects shared the same set of HTTP header fields, causing confusion in the logon status.

Enhancements:

Migrated all remaining test cases from unittest to pytest, and started improving the testcases using pytest specific features such as parametrization.
Added support for a force parameter in the Lpar.activate(), Lpar.deactivate(), and Lpar.load() methods. It controls whether the operation is permitted when the LPAR status is “operating”.

Note that this changes Lpar.deactivate() to be non-forceful by default (force=True was hard coded before this change).
Added support for an activation_profile_name option in the Lpar.activate() method, that allows specifying the activation profile to be used. The default is as before: The profile that is specified in the next-activation-profile property of the Lpar object.
Made the load_address parameter of Lpar.load() optional in order to support z14. Up to z13, the HMC now returns an error if no load address is specified. Adjusted the zhmcclient mock support accordingly.
Added LPAR status checks in the zhmcclient mock support, so that activate, deactivate and load returns the same errors as the real system when the initial LPAR status is not permitted, or when the activation profile name does not match the LPAR name, or when no load address is specified.
Improved the testcases for the Lpar and LparManager classes.
Added the ability to mock the resulting status of the faked Lpars in the zhmcclient mock support, for the Activate, Deactivate, and Load operations. Added a new chapter “URI handlers” in section “Mock support” of the documentation, to describe this new ability.
Added support for CPC energy management operations:
- Cpc.set_power_save() (HMC: “Set CPC Power Save”)
- Cpc.set_power_capping() (HMC: “Set CPC Power Capping”)
- Cpc.get_energy_management_properties() (HMC: “Get CPC Energy Management Data”)
The zhmcclient package no longer adds a NullHandler to the Python root logger (but still to the zhmcclient.api/.hmc loggers).
Added a function test concept that tests against a real HMC.

Version 0.18.0¶

Released: 2017-10-19

Incompatible changes:

Removed the zhmc CLI support from this project, moving it into a new GitHub project zhmcclient/zhmccli.

This removes the following prerequisite Python packages for the zhmcclient package:
- click
- click-repl
- click-spinner
- progressbar2
- tabulate
- prompt_toolkit (from click-repl)
- python-utils (from progressbar2)
- wcwidth (from prompt-toolkit -> click-repl)

Bug fixes:

Fixed a flawed setup of setuptools in Python 2.7 on the Travis CI, where the metadata directory of setuptools existed twice, by adding a script remove_duplicate_setuptools.py that removes the moot copy of the metadata directory (issue #434).

Version 0.17.0¶

Released: 2017-09-20

Incompatible changes:

The zhmcclient mock support for Partitions no longer allows to stop a partition when it is in status ‘degraded’ or ‘reservation-error’. That is consistent with the real HMC as described in the HMC API book.
In the HTTPError exception class, args[0] was set to the body argument, i.e. to the entore response body. Because by convention, args[0] should be a human readable message, this has been changed to now set args[0] to the ‘message’ field in the response body, or to None if not present.

Bug fixes:

Fixed the bug that aborting a confirmation question in the CLI (e.g. for “zhmc partition delete”) caused an AttributeError to be raised. It now prints “Aborted!” and in interactive mode, terminates only the current command. (issue #418).
Fixed an AttributeError when calling ‘zhmc vfunction update’. Access to a partition from nic and vfunction is done via the respective manager (issue #416).
In the zhmc CLI, fixed that creating a new session reused an existing session. This prevented switching between userids on the same HMC (issue #422).
Docs: In the “Introduction” chapter of the documentation, fixed the HMC API version shown for z14.
Docs: In the Appendix of the documentation, added IBM book number and link for the HMC API book of z14.

Enhancements:

Avoided DeprecationWarning on Python 3 for invalid escape sequences in some places.
The zhmcclient mock support for various resource classes did not always check for invalid CPC status and for invalid Partition status as described in the HMC API book. It now does.
In the mock support, invalid input to faked resource classes (mainly when adding faked resources) is now handled by raising a new exception zhmcclient_mock.InputError (instead of ValueError). The URI handler of the mock support now converts that into an HTTP error 400 (Bad Request), consistent with the HMC API book.
Added datetime_from_timestamp() and datetime_from_timestamp() functions that convert between Python datetime objects and HMC timestamp numbers.
Added mock support for Metrics resources.
Added a verify argument to Session.logoff(), consistent with Session.logon(). This was needed as part of fixing issue #422.
Added a __repr__() function to the Session class, for debug purposes.
In the ParseError exception class, a message of None is now tolerated, for consistency with the other zhmcclient exception classes.
In the NotFound exception class, a filter_args parameter of None is now tolerated, for consistency with the NoUniqueMatch exception class.
Documented for the zhmcclient exception classes how args[0] is set.
Clarified in the documentation that the manager and resources parameters of the NoUniqueMatch and NotFound exception classes must not be None.
Improved the unit test cases for the Client class and for the zhmcclient exception classes, and migrated them to py.test.
Migrated the unit tests for HBAs from unittest to py.test, and improved the test cases.
In the Hba.reassign_port() method, updated the Hba object with the changed port, consistent with other update situations.
Clarified in the description of HbaManager.list() that only the ‘element-uri’ property is returned and can be used for filtering.
The mock support for the “Create NIC” operation now performs more checking on the URIs specified in the ‘network-adapter-port’ or ‘virtual-switch-uri’ input properties, raising HTTP status 404 (Not Found) as specified in the HMC API book.
In the FakedNic.add() method of the mock support, the checking for the URIs specified in the ‘network-adapter-port’ or ‘virtual-switch-uri’ input properties was relaxed to only the minimum, in order to make the setting up of faked resources easier.
Migrated the unit tests for Nic and NicManager from unittest to py.test, and improved them.
Improved the way the named tuples MetricGroupDefinition and MetricDefinition are documented.
Added support for Console resource and its child resources User, User Role, User Pattern, Password Rule, Task, and LDAP Server Definition, both for the zhmcclient API and for the zhmcclient mock support.
As part of support for the Console resource, added a new resource class UnmanagedCpc which representd unmanaged CPCs that have been discovered by the HMC. The existing Cpc class continues to represent only managed CPCs; this has been clarified in the documentation.
As part of support for the Console resource, added a method wait_for_available() to the Client class, which waits until the HMC is available again after a restart. This method is used by Console.restart(), but it can also be used by zhmcclient users.
As part of support for the Console resource, improved Session.post() to allow for an empty response body when the operation returns with HTTP status 202 (Accepted). This status code so far was always assumed to indicate that an asynchronous job had been started, but it can happen in some Console operations as well.
Improved the error information in the ParseError exception, by adding the “Content-Type” header in cases where that is interesting.
Add CLI commmands to mount and unmount an ISO to a Partition.

Version 0.16.0¶

Released: 2017-08-29

Bug fixes:

Fixed CLI: Remove defaults for options for ‘partition update’ (issue #405).

Enhancements:

Added Code Climate support.

Version 0.15.0¶

Released: 2017-08-15

Incompatible changes:

In case the user code was specifically processing the reason code 900 used for HTML-formatted error responses with HTTP status 500: This reason code has been split up into multiple reason codes. See the corresponding item in section “Enhancements”.

Bug fixes:

Fixed a TypeError: “‘odict_values’ object does not support indexing” on Python 3.x (issue #372).
Minor fixes in the documentation (e.g. fixed name of MetricGroupValues class).
Fixed the zhmc CLI for Python 3 where multiple commands raised AttributeError: “‘dict’ object has no attribute ‘iteritems’ in zhmccli/_helper.py. (issue #396).

Enhancements:

Added support for the HMC Metric Service. For details, see section ‘Metrics’ in the zhmcclient documentation. There is an example script metrics.py demonstrating the use of the metrics support. The metrics support caused an additional package requirement for the pytz package.
Added support for a “metrics” command to the zhmc CLI.
Added support for the IBM z14 system (in internal machine type tables and in the documentation).
zhmccli: Support for ‘authorization controls’ of a Partition (issue #380)
Added CLI support for processing weights (issue #383)
The HTTPError raised at the API for HMC Web Services not enabled now has a simple error message and uses a specific reason code of 900. Previously, the returned HTML-formatted response body was used for the message and a generic reason code of 999. All other HTML-formatted error responses still use the generic reason code 999. That reason code 999 is now documented to be changed to more specific reason codes, over time. (issue #296).
Reduced the package requirements to only the direct dependencies of this package.
Changed the experimental Cpc.get_free_crypto_domains() method to test only control-usage access to the specified adapters. Improved that method by supporting None for the list of adapters which means to inspect all crypto adapters of the CPC.

Version 0.14.0¶

Released: 2017-07-07

Incompatible changes:

Changed the return value of TimeStatsKeeper.snapshot() from a list of key/value tuples to a dictionary. This is more flexible and reduces the number of data structure conversions in different scenarios. See issue #269.
Changed the arguments of Partition.mount_iso_image() incompatibly, in order to fix issue #57.

Bug fixes:

Fixed the documentation of several asynchronous Partition methods that incorrectly documented returning None in case of synchronous invocation, to now document returning an empty dictionary:
- Partition.start()
- Partition.stop()
- Partition.dump_partition()
- Partition.psw_restart()
All other asynchronous methods did not have this issue. See issue #248.
Clarified in the documentation of all exceptions that have a details instance variable, that it is never None.
Fixed using ‘–ssc-dns-servers’ option for the CLI commands ‘zhmc partition create/update’. See issue #310.
Fixed the incorrect parameters of Partition.mount_iso_image(). See issue #57.
Reads the vlan-id as a integer instead as a string for the ‘zhmc nic create/update’ cli command. See issue #337.
Fixed the AttributeError that occurred when using zhmcclient in Jupyter notebooks, or in the python interactive mode. See issue #341.

Enhancements:

Improved content of zhmcclient.ParseError message for better problem analysis.
Increased the default status timeout from 60 sec to 15 min, in order to accomodate for some large environments. The status timeout applies to waiting for reaching the desired LPAR status after the HMC operation ‘Activate LPAR’ or ‘Deactivate LPAR’ has completed.
Allow None as a value for the load_parameter argument of Lpar.load(), and changed the default to be None (the latter change does not change the behavior).
Added actual status, desired statuses and status timeout as attributes to the StatusTimeout exception, for programmatic processing by callers.
In the zhmc CLI, added a --allow-status-exceptions option for the lpar activate/deactivate/load commands. Setting this option causes the LPAR status “exceptions” to be considered an additional valid end status when waiting for completion of the operation.
Improved documentation of CLI output formats.
Simplified the message of the OperationTimeout exception.
Split the AuthError exception into ClientAuthError and ServerAuthError that are used depending on where the authentication issue is detected. Reason for the split was that the two subclasses have different instance variables. The AuthError exception class is now an abstract base class that is never raised but can be used to catch exceptions.
Made error data available as instance variables of the following exceptions: ConnectTimeout, ReadTimeout, RetriesExceeded, ClientAuthError, ServerAuthError, OperationTimeout, and StatusTimeout, NotFound, NoUniqueMatch.
Improved unit test cases for zhmcclient._exceptions module.
Added support to the zhmc CLI for an interactive session to the console of the operating system running in a partition (zhmc partition console) or LPAR (zhmc lpar console).
Added str_def() method to all exception classes, which returns a definition-style string for parsing by scripts.
In the zhmc CLI, added options -e, --error-format for controlling the format of error messages. The -e def option selects the format returned by the new str_def() methods. This format provides for easier parsing of details of error messages by invoking scripts.
Added wait_for_status() methods to the Lpar and Partition classes, in order to ease the work for users that need to ensure that a particular LPAR or partition status is reached.
Added support for crypto-related methods on the Partition and Adapter resource classes. Added zhmcclient mock support for the faked partition (not yet for the faked adapter).
Added that Partition.start() waits for reaching the desired status ‘active’ or ‘degraded’, because it transitions through status ‘paused’ when starting a partition.
Improved the NoUniqueMatch exception so that the list of resources that did match the filter, are shown with their URIs in the error message, and are available as new resources and resource_uris attributes. This change adds a required argument resources to the constructor of NoUniqueMatch. However, since this exception is only supposed to be raised by the zhmcclient implementation, this change is compatible to zhmcclient users.
Moved the invocation of PyLint from the “make check” target into its own “make pylint” target, inorder to speed up the CI testing.
Added the ability for Session.post() to support binary data as the payload. The body argument may now be a dictionary which is represented as a JSON string, a binary string which is used directly, or a unicode string which is encoded using UTF-8. This was necessary to fix issue #57.
In the zhmcclient mock support, added a Python property name to all faked resources, which returns the value of the ‘name’ resource property.
Added a Python property maximum_crypto_domains to the Adapter class, which returns the maximum number of crypto domains of a crypto adapter.
Added a Python property maximum_active_partitions to the Cpc class, which returns the maximum number of active LPARs or partitions of a CPC.
Added get_free_crypto_domains() method to the Cpc class, in order to find out free domain index numbers for a given set of crypto adapters. Note: This method is considered experimental in this version.
Added an update_properties() method to the Lpar and Cpc resource classes.
Improved the description of the Hba.create() and Nic.create() methods to describe how the backing adapter port is specified.
Extended the zhmcclient mock support by adding support for all operations thet are supported at the zhmcclient API but were not yet supported for mocking, so far.

Version 0.13.0¶

Released: 2017-05-18

Incompatible changes:

In the CLI, changed the default for number of processors for the zhmc partition create command to create 1 IFL by default, if neither IFLs nor CPs had been specified. Also, a specified number of 0 processors is now passed on to the HMC (and rejected there) instead of being removed by the CLI. This keeps the logic simpler and more understandable. See also issue #258.

Deprecations:

Deprecated the BaseManager.flush() method in favor of the new BaseManager.invalidate_cache() method.

Bug fixes:

Fixed that the defaults for memory for the zhmc partition create command were ignored (issue #246).
The default values for the retry / timeout configuration for a session has been changed to disable read retries and to set the read timeout to 1 hour. In addition, read retries are now restricted to HTTP GET methods, in case the user enabled read retries. See issue #249.
Fixed that resource creation, deletion, and resource property updating now properly updates the resource name-to-URI cache in the zhmcclient that is maintained in the *Manager objects. As part of that, the BaseManager init function got an additional required argument session, but because creation of manager objects is not part of the external API, this should not affect users. See issue #253.
In the unit testcases for the update_properties() and delete() methods of resource classes, fixed incorrect assumptions about their method return values. See issue #256.
In the unit testcases for the update_properties() and delete() methods of resource classes, fixed incorrectly returned response bodies for mocked DELETE and POST (for update), and replaced that with status 204 (no content). This came up as part of fixing issue #256.
Fixed that find(name) raised NotFound for existing resources, for resource types that are elements (i.e. NICs, HBAs, VFs, Ports) (issue #264).
Fixed that the filter arguments for find(), findall(), and list() for string properties when matched on the client side are matched using regular expressions instead of exact matching, consistent with the zhmcclient documentation, and with server-side matching on the HMC. See issue #263.
Fixed that the filter arguments for find(), findall(), and list() when used with lists of match values incorrectly applied ANDing between the list items. They now apply ORing, consistent with the zhmcclient documentation, and with server-side matching on the HMC. See issue #267.
Fixed that the Cpc.dpm_enabled property incorrectly returned True on a z13 in classic mode. See issue #277.
Fixed errors in zhmcclient mock support related to DPM mode checking.
Fixed that filter arguments specifying properties that are not on each resource, resulted in raising KeyError. An example was when the “card-location” property was specified when finding adapters; that property does not exist for Hipersocket adapters, but for all other types. This situation is now handled by treating such resources as non-matching. See issue #271.
Fix when providing ‘load-parameter’ option. See issue #273

Enhancements:

Added content to the “Concepts” chapter in the documentation.
The update_properties() method of all Python resource objects now also updates the properties of that Python resource object with the properties provided by the user (in addition to issuing the corresponding Update Properties HMC operation. This was done because that is likely the expectation of users, and we already store user-provided properties in Python resource objects when creating resources so it is now consistent with that. This came up as part of issue #253.
As part of fixing the name-to-URI cache, a new attribute name_uri_cache_timetolive was added to class RetryTimeoutConfig, which allows controlling after what time the name-to-URI cache is automatically invalidated. The default for that is set in a new DEFAULT_NAME_URI_CACHE_TIMETOLIVE constant. Also, the *Manager classes now have a new method invalidate_cache() which can be used to manually invalidate the name-to-URI cache, for cases where multiple parties (besides the current zhmcclient instance) change resources on the HMC. This came up as part of issue #253.
Improved the documentation of the lookup methods (list(), find(), findall()) and of the resource filtering concept in section ‘Filtering’. Related to issue #261.
Added zhmcclient mock support for the Create Hipersocket and Delete Hipersocket operations.
Added support for filtering in the zhmcclient mock support.
In order to improve the ability to debug the resource and manager objects at the API and the faked resource and manager objects of the mock support, the __repr()__ methods ahave been improved. Because these functions now display a lot of data, and because testing their string layout is not very interesting, all unit test cases that tested the result of __repr()__ methods have been removed.
Add basic Secure Service Container support to the CLI.

Version 0.12.0¶

Released: 2017-04-13

Incompatible changes:

The password retrieval function that can optionally be passed to Session() has changed its interface; it is now being called with host and userid. Related to issue #225.

Bug fixes:

Added WWPN support in mocking framework (issue #212).
Fixed error in mock support where the operation_timeout argument to FakedSession.post() was missing.
Fixed a bug in the unit test for the mock support, that caused incomplete expected results not to be surfaced, and fixed the incomplete testcases.
Fixed in the CLI that the spinner character was part of the output.
Improved robustness of timestats tests by measuring the actual sleep time instead of going by the requested sleep time.
Added support for ‘error’ field in ‘job-results’ (fixes issue #228).
Fixed version mismatches in CI test environment when testing with the minimum package level by consistently using the latest released packages as of zhmcclient v0.9.0 (2016-12-27). This caused an increase in versions of packages needed for the runtime.

Enhancements:

Improved the mock support by adding the typical attributes of its superclass FakedBaseResource to the FakedHmc class.
Improved the mock support by adding __repr__() methods to all Faked* classes that return an object representation suitable for debugging.
In the mock support, the following resource properties are now auto-set if not specified in the input properties:
- Cpc:
  - ‘dpm-enabled’ is auto-set to False, if not specified.
  - ‘is-ensemble-member’ is auto-set to False, if not specified.
  - ‘status’ is auto-set, if not specified, as follows: If the ‘dpm-enabled’ property is True, it is set to ‘active’; otherwise it is set to ‘operating’.
- Partition: ‘status’ is auto-set to ‘stopped’, if not specified.
- Lpar: ‘status’ is auto-set to ‘not-activated’, if not specified.
- Adapter: ‘status’ is auto-set to ‘active’, if not specified.
In the CLI, added -y as a shorter alternative to the existing --yes options, that allow skipping confirmation prompts.
Added OS-X as a test environment to the Travis CI setup.
In the CLI, added a -p / --password option for specifying the HMC password (issue #225).
Added logging support to the zhmc CLI (issue #113).
Added ‘load-parameter’ option to ‘zhmc lpar load’ (issue #226).

Version 0.11.0¶

Released: 2017-03-16

Incompatible changes:

Changed the return value of all methods on resource classes that invoke asynchronous operations (i.e. all methods that have a wait_for_completion parameter), as follows:
- For wait_for_completion=True, the JSON object in the ‘job-results’ field is now returned, or None if not present (i.e. no result data). Previously, the complete response was returned as a JSON object.
- For wait_for_completion=False, a new Job object is now returned that allows checking and waiting for completion directly on the Job object. Previously, the whole response of the ‘Query Job Status’ operation was returned as a JSON object, and the job completion was checked on the Session object, and one could not wait for completion.
Changed the default value of the wait_for_completion parameter of the Session.post() method from True to False, in order to avoid superfluos timestats entries. This method is not normally used by users of the zhmcclient package.
Removed the version strings from the args[] property of the zhmcclient.VersionError exception class. They had been available as args[1] and args[2]. args[0] continues to be the error message, and the min_api_version and api_version properties continue to provide the version strings.
Changed the names of the Python loggers as follows:
1. Logger ‘zhmcclient.api’ logs API calls made by the user of the package, at log level DEBUG. Internal calls to API functions are no longer logged.
2. Logger ‘zhmcclient.hmc’ logs HMC operations. Their log level has been changed from INFO to DEBUG.
Removed the log calls for the HMC request ID.

Bug fixes:

Added a minimum version requirement >=4.0.0 for the dependency on the “decorate” Python package (issue #199).
Increased minimum version of “click-spinner” package to 0.1.7, in order to pick up the fix for zhmcclient issue #116.
Fixed CLI help text for multiple commands, where the text was incorrectly flowed into a paragraph.

Enhancements:

Added support for retry/timeout configuration of HTTP sessions, via a new RetryTimeoutConfig class that can be specified for the Session object. The retry/timeout configuration can specify:
- HTTP connect timeout and number of retries.
- HTTP read timeout (of HTTP responses), and number of retries.
- Maximum number of HTTP redirects.
Added new exceptions zhmcclient.ConnectTimeout (for HTTP connect timeout), zhmcclient.ResponseReadTimeout (for HTTP response read timeout), and zhmcclient.RequestRetriesExceeded (for HTTP request retry exceeded). They are all derived from zhmcclient.ConnectionError.
Fixed a discrepancy between documentation and actual behavior of the return value of all methods on resource classes that invoke asynchronous operations (i.e. all methods that have a wait_for_completion parameter). See also the corresponding incompatible change (issue #178).
In the CLI, added a ‘help’ command that displays help for interactive mode, and a one-line hint that explains how to get help and how to exit interactive mode (issue #197).
In the CLI, added support for command history. The history is stored in the file ~/.zhmc_history.
In the CLI, changed the prompt of the interactive mode to zhmc>.
Added support for tolerating HTML content in the response, instead of JSON. An HTML formatted error message may be in the response for some 4xx and 5xx HTTP status codes (e.g. when the WS API is disabled). Such responses are raised as HTTPError exceptions with an artificial reason code of 999.
Fixed an incorrect use of the zhmcclient.AuthError exception and unnecessary checking of HMC behavior, i.e. when the HMC fails with “API session token expired” for an operation that does not require logon. This error should never be returned for operations that do not require logon. If it would be returned, it is now handled in the same way as when the operation does require logon, i.e. by a re-logon.
Added support for deferred status polling to the Lpar.activate/deactivate/load() methods. The HMC operations issued by these methods exhibit “deferred status” behavior, which means that it takes a few seconds after successful completion of the asynchronous job that executes the operation, until the new status can be observed in the ‘status’ property of the LPAR resource. These methods will poll the LPAR status until the desired status value is reached. A status timeout can be specified via a new status_timeout parameter to these methods, which defaults to 60 seconds. If the timeout expires, a new StatusTimeout exception is raised (issue #191).
Added operation timeout support to Session.post() and to all resource methods with a wait_for_completion parameter (i.e. the asynchronous methods). The operation timeout on the asynchronous methods can be specified via a new operation_timeout parameter, which defaults to 3600 seconds. If the timeout expires, a new OperationTimeout exception is raised (issue #6).
Added a new module that defines public constants, and that defines default timeout and retry values.
Experimental: In the CLI, added more supported table formats (plain, simple, psql, rst, mediawiki, html, LaTeX).
Improved the content of the log messages for logged API calls and HMC operations to now contain the function call arguments and return values (for API calls) and the HTTP request and response details (for HMC operations). For HMC operations and API calls that contain the HMC password, the password is hidden in the log message by replacing it with a few ‘*’ characters.

Version 0.10.0¶

Released: 2017-02-02

Incompatible changes:

The support for server-side filtering caused an incompatibility for the find() and findall() methods: For String typed resource properties, the provided filter string is now interpreted as a regular expression that is matched against the actual property value, whereby previously it was matched by exact string comparison.
The parameter signatures of the __init__() methods of BaseResource and BaseManager have changed incompatibly. These methods have always been considered internal to the package. They are now explicitly stated to be internal and their parameters are no longer documented. If users have made themselves dependent on these parameters (e.g. by writing a mock layer), they will need to adjust to the new parameter signature. See the code for details.

Bug fixes:

Fixed a bug where the CLI code tries to access ‘cpc’ from the ‘partition’ directly without going via the manager property. This caused an AttributeError (issue #161).
Fixed unrecognized field (‘adapter-port’) during ‘HBA create’ (issue #163).

Enhancements:

Added filter arguments to the list() method, and added support for processing as many filter arguments as supported on the server side via filter query parameters in the URI of the HMC List operation. The remaining filter arguments are processed on the client side in the list() method.
Changed the keyword arguments of the find() and findall() methods to be interpreted as filter arguments that are passed to the list() method.
Documented the authorization requirements for each method, and in total in a new section “Setting up the HMC”.
Added a method open_os_message_channel() on Partition and Lpar objects, that returns a notification token for receiving operating system messages as HMC notifications.
Experimental: Added a class NotificationReceiver that supports receiving and iterating through HMC notificationsi for a notification token, e.g. those produced by open_os_message_channel().

Version 0.9.0¶

Released: 2017-01-11

Bug fixes:

Fixed a bug where accessing the ‘name’ property via the properties attribute caused KeyError to be raised (issue #137). Note that there is now a recommendation to use get_property() or the name or uri attributes for accessing specific properties. The properties attribute should only be used for iterating over the currently present resource properties, but not for expecting particular properties.
Fixing regression in findall(name=..) (issue #141).

Enhancements:

Changed links to HMC API books in Bibliography to no longer require IBM ID (issue #131).
Added example shell script showing how to use the command line interface.
Improved the examples with better print messages, exception handling, access of resource properties, and refreshing of resources.
Added support for load-parameter field in lpar.load().

Version 0.8.0¶

Released: 2016-12-27

Enhancements:

Added support in CLI for remaining cmds; client improvements.
Added a tool ‘tools/cpcdata’ for gathering information about all CPCs managed by a set of HMCs. The data can optionally be appended to a CSV spreadsheet, for regular monitoring.

Version 0.7.0¶

Released: 2016-12-08

Bug fixes:

IOError during click-spinner 0.1.4 install (issue #120)

Enhancements:

Documentation for zhmc CLI

Version 0.6.0¶

Released: 2016-12-07

Bug fixes:

Fixed typo in help message of cpcinfo.
Fixed KeyError: ‘status’ when running example5.py (issue #99).
Fixed documentation of field Partition.hbas (issue #101).
Fixed new Flake8 issue E305.

Enhancements:

Started raising a ParseError exception when the JSON payload in a HTTP response cannot be parsed, and improved the definition of the ParseError exception by adding line and column information.
Improved the AuthError and ConnectionError exceptions by adding a details property that provides access to the underlying exception describing details.
For asynchronous operations that are invoked with wait_for_completion, added an entry in the time statistics for the overall operation from the start to completion of the asynchronous operation. That entry is for a URI that is the target URI, appended with “+completion”.
Added time statistics entry for overall asynchronous operations.
Improved VersionError exception class and removed number-of-args tests.
Added the option to create a session object with a given session id.
Added base implementation of a command line interface (zhmc) for the zhmcclient.

Version 0.5.0¶

Released: 2016-10-04

Incompatible changes:

In VirtualSwitch.get_connected_vnics(), renamed the method to get_connected_nics() and changed its return value to return Nic objects instead of their URIs.

Bug fixes:

Fixed that in Partition.dump_partition(), wait_for_completion was always passed on as True, ignoring the corresponding input argument.

Enhancements:

Added a script named tools/cpcinfo that displays information about CPCs. Invoke with -h for help.
Added a prop() method for resources that allows specifying a default value in case the property does not exist.
Added get_wwpns() which performs HMC operation ‘Export WWPN List’.
Added reassign_port() which performs HMC operation ‘Reassign Storage Adapter Port’.
Clarifications in the Resource model section.
Optimized dpm_enabled property to use ‘List Partitions’ and ‘List Logical Partitions’ operations, in order to avoid the ‘List CPC Properties’ operation.
Improved tutorials.

Version 0.4.0¶

Released: 2016-09-13

This is the base version for this change log.