### Install zhmcclient using pip

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/README.md

Install the zhmcclient package using pip. This is the quickest way to get started.

```bash
pip install zhmcclient
```

--------------------------------

### Install zhmcclient with testutils

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Installs the zhmcclient package along with testing utilities. This is a common starting point for development or testing.

```text
$ pip install zhmcclient[testutils]
```

--------------------------------

### Start Jupyter Notebook with Downloaded Tutorial Notebooks

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/tutorial.rst

Starts Jupyter Notebook with downloaded tutorial notebooks. The '{your-notebook-dir}' placeholder should be replaced with the actual directory where the tutorial notebooks have been saved.

```text
$ jupyter notebook --notebook-dir={your-notebook-dir}
```

--------------------------------

### Install zhmcclient from source distribution

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Installs zhmcclient from a source distribution archive (.tar.gz). This method is an alternative to installing from wheel archives.

```text
# 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
```

--------------------------------

### Install zhmcclient from local repository

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Installs zhmcclient directly from the root directory of its cloned Git repository. This is useful for development or testing local changes.

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

--------------------------------

### Start Jupyter Notebook with Tutorial Notebooks

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/tutorial.rst

This command starts Jupyter Notebook with all tutorial notebooks located in the 'docs/notebooks' directory of the zhmcclient repository. It is used when the development environment for zhmcclient is already set up.

```text
$ jupyter notebook --notebook-dir=docs/notebooks
```

--------------------------------

### Example Dependency Update in Requirements

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

This example shows how a package version might be updated in requirements files, considering Python version compatibility.

```text
urllib3==2.6.0
```

--------------------------------

### Install zhmcclient with testutils extra

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Installs the zhmcclient package along with the 'testutils' extra, which includes additional Python packages required for end-to-end testing against a real HMC and for running example scripts. This is useful for development and testing purposes.

```text
pip install zhmcclient[testutils]
```

--------------------------------

### List OSA Adapters by State using list with full_properties

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/concepts.rst

Use the `list` method with `full_properties=True` and filter arguments to retrieve specific resources. This example retrieves the same OSA adapters as the `findall` example but ensures the returned resource objects have the full set of properties.

```python
osa_adapters = cpc.adapters.list(full_properties=True,
                                       filter_args=filter_args)
```

--------------------------------

### Install zhmcclient from local packages (offline)

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Installs zhmcclient and its dependencies from local files in the current directory, without accessing the internet. This is used after downloading packages on a system with internet access.

```text
[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
```

--------------------------------

### Install zhmcclient from PyPI

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Installs the latest released version of the zhmcclient package and its dependencies from PyPI into the currently active Python environment. This command provides everything needed to program against the client API.

```text
$ pip install zhmcclient
```

--------------------------------

### Download zhmcclient and dependencies

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Downloads the zhmcclient package and all its dependencies to the current directory. This is the first step for an offline installation.

```text
[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
```

--------------------------------

### Quickstart: List Permitted Partitions

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/README.md

This Python script lists partitions on CPCs in DPM mode accessible to the user. It requires HMC connection details and disables SSL certificate verification.

```python
#!/usr/bin/env python

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

# Set these variables for your environment:
host = "<IP address or hostname of the HMC>"
userid = "<userid on that HMC>"
password = "<password of that HMC userid>"
verify_cert = False

session = zhmcclient.Session(host, userid, password, verify_cert=verify_cert)
client = zhmcclient.Client(session)
console = client.consoles.console

partitions = console.list_permitted_partitions()
for part in partitions:
    cpc = part.manager.parent
    print("{} {}".format(cpc.name, part.name))
```

--------------------------------

### Clone Repository and Set Up Development Environment

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

Clone the zhmcclient Git repository and install development prerequisites using 'make develop'. Ensure a virtual Python environment is active.

```text
$ git clone git@github.com:zhmcclient/python-zhmcclient.git
$ cd python-zhmcclient
$ make develop
```

--------------------------------

### Verify zhmcclient Installation

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Verifies that the zhmcclient package and its dependencies are installed correctly by importing the package into Python.

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

--------------------------------

### Get Debug Info using Python

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/changes.rst

Use this command to display debug information for the zhmcclient library when installed from PyPI. It replaces the removed zhmcclient/debuginfo.py script.

```python
python -c "import zhmcclient; print(zhmcclient.debuginfo())"
```

--------------------------------

### Install Jupyter Notebook and zhmcclient

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/tutorial.rst

Installs the Jupyter Notebook and zhmcclient packages into a Python environment. This is an alternative to setting up the full zhmcclient development environment, allowing users to download tutorial notebooks separately.

```text
$ pip install jupyter zhmcclient
```

--------------------------------

### Install latest development version from GitHub

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Installs the most recent development version of zhmcclient directly from its master branch on GitHub. Use this if you need the absolute latest features or bug fixes.

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

--------------------------------

### Example HMC Inventory File

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

A complete example of an HMC inventory file in YAML format, demonstrating the structure and possible configurations for defining HMCs and groups.

```yaml
---
all:
  hosts:
    HMC1:
      description: "Primary HMC"
      access_via: "SSH"
      ansible_host: "192.168.0.10"
      cpcs:
        CPC1:
          dpm_enabled: true
        CPC2:
          dpm_enabled: false
    HMC2:
      description: "Secondary HMC"
      access_via: "SSH"
      ansible_host: "192.168.0.11"
      cpcs:
        CPC3:
          dpm_enabled: true
  children:
    group1:
      hosts:
        HMC1:
      vars:
        test_var: "value1"
    group2:
      hosts:
        HMC2:
      vars:
        test_var: "value2"

```

--------------------------------

### Initialize FakedSession and Client

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/mocksupport.rst

Instantiate FakedSession to simulate an HMC and then create a zhmcclient.Client with it. This is the basic setup for using mock support.

```python
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()
. . .
```

--------------------------------

### List Managed CPCs with Details

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/changes.rst

This example script lists managed CPCs, including their version, status, and operational mode. It helps in monitoring and managing hardware resources.

```python
# Example script: list_cpcs.py
```

--------------------------------

### Running Example Scripts with Default HMC Nickname

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

Run example scripts using the default HMC nickname ('default') when the TESTHMC environment variable is not specified. This is convenient for general script execution.

```bash
$ examples/list_cpcs.py    # run this example script against nickname "default""
```

--------------------------------

### Connect to a single HMC

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/concepts.rst

Example of initializing a zhmcclient Session with a single HMC host.

```python
session = zhmcclient.Session(host='10.11.12.13', ...)
```

--------------------------------

### Filter OSA Adapters by State using findall

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/concepts.rst

Use the `findall` method with filter arguments to retrieve specific resources. This example filters for OSA adapters in a 'stand-by', 'reserved', or 'unknown' state within a specific cage. The returned objects have a minimal set of properties.

```python
filter_args = {
    'adapter-family': 'osa',
    'card-location': '1234-.*',
    'state': ['stand-by', 'reserved', 'unknown'],
}
osa_adapters = cpc.adapters.findall(**filter_args)
```

--------------------------------

### Running Example Scripts with a Specific HMC

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

Execute example scripts against a specific HMC by setting the TESTHMC environment variable to the desired nickname. This allows testing individual scripts against particular HMC configurations.

```bash
$ TESTHMC=HMC1 examples/list_cpcs.py    # run this example script against nickname "HMC1"
```

--------------------------------

### Dump HMC Definition to File

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/changes.rst

This example script demonstrates how to dump the resources of an HMC into a HMC definition file. This file can then be used as a mock definition for testing.

```python
# Example script: dump_hmc_definition.py
```

--------------------------------

### Connect to multiple redundant HMCs

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/concepts.rst

Example of initializing a zhmcclient Session with a list of HMC hosts for redundancy.

```python
session = zhmcclient.Session(host=['10.11.12.13', '10.11.12.14'], ...)
```

--------------------------------

### Python Script for Linux OS Console Login and Command Execution

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/general.rst

This script demonstrates how to use the 'websocket-client' library to connect to a partition's OS console, log in to a Linux user, and execute the 'uname -a' command. Ensure you have the 'websocket-client', 'certifi', and 'zhmcclient' packages installed. Replace placeholder values for HMC and Linux credentials.

```python
#!/usr/bin/env python
# Use WebSocket to console of a partition, login to Linux and execute 'uname'

import sys
import re
import ssl
import time
import websocket
import certifi
import requests.packages.urllib3
import zhmcclient

WS_TIMEOUT = 5  # WebSocket receive timeout in seconds

HMC_HOST = '...'  # HMC IP address
HMC_USERID = '...'  # HMC user name
HMC_PASSWORD = '...'  # HMC password
HMC_VERIFY_CERT = False  # or path to CA certificate file/dir

CPC_NAME = '...'  # CPC name
PARTITION_NAME = '...'  # partition name

LINUX_USERNAME = '...'  # Linux user name for the partition
LINUX_PASSWORD = '...'  # Linux password for the partition


def recv_all(ws):
    """Receive all lines on console"""
    lines = []
    while True:
        try:
            line = ws.recv()
        except websocket.WebSocketTimeoutException:
            return ''.join(lines)
        lines.append(line)


def linux_login(ws, username, password):
    """Login to a Linux OS"""
    while True:
        lines = recv_all(ws)
        if lines and re.search(r"loginః$", lines.strip(), flags=re.I+re.M):
            ws.send(username + '\n')
            lines = recv_all(ws)
            if lines and re.search(r"passwordః$", lines.strip(), flags=re.I+re.M):
                ws.send(password + '\n')
                lines = recv_all(ws)
                if lines and re.search(r"login incorrect", lines, flags=re.I+re.M):
                    msg = lines.replace('\r\n', '\n')
                    msg = re.sub(r"\n+", "\n", msg, flags=re.M)
                    msg = re.sub(r"\n[^\n]*loginః", "", msg, flags=re.I+re.M)
                    msg = msg.strip().replace('\n', ' ')
                    raise Exception(msg)
                break
        else:
            # Sending empty line to get to login prompt
            ws.send('\n')


def main():

    requests.packages.urllib3.disable_warnings()

    session = zhmcclient.Session(
        host=HMC_HOST,
        userid=HMC_USERID,
        password=HMC_PASSWORD,
        verify_cert=HMC_VERIFY_CERT)

    client = zhmcclient.Client(session)
    cpc = client.cpcs.find(name=CPC_NAME)
    partition = cpc.partitions.find(name=PARTITION_NAME)

    session = partition.manager.session
    sslopt = {}
    if isinstance(session.verify_cert, str):
        sslopt["cert_reqs"] = ssl.CERT_REQUIRED
        sslopt["ca_cert_path"] = session.verify_cert
    elif session.verify_cert is True:
        sslopt["cert_reqs"] = ssl.CERT_REQUIRED
        sslopt["ca_cert_path"] = certifi.where()
    else:
        sslopt["cert_reqs"] = ssl.CERT_NONE

    ws_uri = partition.create_os_websocket()

    ws = websocket.WebSocket(sslopt=sslopt)

    try:
        print(f"Connecting to WebSocket for partition {cpc.name}.{partition.name}")
        ws.connect(f"wss://{session.actual_host}:6794{ws_uri}", timeout=WS_TIMEOUT)

        print("Logging in to Linux")
        try:
            linux_login(ws, LINUX_USERNAME, LINUX_PASSWORD)
        except Exception as exc:
            print(f"Error: Cannot login: {exc}")
            return 1

        print("Executing 'uname -a' command")
        try:
            ws.send('uname -a\n')
            uname_out = recv_all(ws)
        except Exception as exc:
            print(f"Error: Cannot execute uname: {exc}")
            return 1

        print(f"Output: {uname_out}")

    finally:
        print("Closing WebSocket")
        ws.close()
        return 0


if __name__ == '__main__':
    rc = main()
    sys.exit(rc)

```

--------------------------------

### Fake HMC Resource Structure Example

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/design/fake-client.rst

Defines the nested dictionary structure for preloading a fake HMC's resource state, including properties and child resources like adapters and ports.

```python
resources = {
    'cpcs': [
        {
            'properties': {
                'name': 'cpc_1',
                . . .  # more properties
            },
            'adapters': [
                {
                    'properties': {
                        'name': 'ad_1',
                        . . .  # more properties
                    },
                    'ports': [
                        {
                            'properties': {
                                'name': 'port_1',
                                . . .  # more properties
                            }
                        },
                        . . .  # more Ports
                    ],
                },
                . . .  # more Adapters
            ],
            . . .  # more CPC child resources
        },
        . . .  # more CPCs
    ]
}
```

--------------------------------

### Import zhmcclient

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/notebooks/02_connections.ipynb

Import the zhmcclient library to begin using its functionalities. Ensure the package is installed in your Python environment.

```python
import zhmcclient
```

--------------------------------

### Handling specific zhmcclient exceptions for fallback

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/notebooks/04_error_handling.ipynb

This example shows how to handle a specific zhmcclient exception, zhmcclient.NotFound, to implement a fallback mechanism. If the primary CPC is not found, it attempts to use a backup CPC.

```python
try:
    cpc = client.consoles.get_primary_cpc()
except zhmcclient.NotFound:
    # Primary CPC not found, try backup CPC
    cpc = client.consoles.get_backup_cpc()
    print("Primary CPC not found, using backup CPC.")

# Proceed with operations using 'cpc'
```

--------------------------------

### Initialize zhmcclient Session and Client

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Initializes a zhmcclient session and client to interact with the HMC. Ensure you replace placeholder variables with your actual HMC details. SSL certificate verification is disabled for simplicity in this example.

```python
#!/usr/bin/env python

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

# Set these variables for your environment:
host = "<IP address or hostname of the HMC>"
userid = "<userid on that HMC>"
password = "<password of that HMC userid>"
verify_cert = False

session = zhmcclient.Session(host, userid, password, verify_cert=verify_cert)
client = zhmcclient.Client(session)
console = client.consoles.console

```

--------------------------------

### Example Commit Message

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

A commit message must start with a short summary line, followed by a blank line, and end with a DCO sign-off. All lines must not exceed 80 characters.

```text
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>
```

--------------------------------

### Improved Mock Support for Create Partition

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/changes.rst

Mock support for 'Create Partition' has been improved with more input validation and the setting of all default properties on new partitions. This enhances the accuracy of mock partition creation.

```python
# Improved mock support for Create Partition with validation and defaults.
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

Build the project documentation locally using the 'make builddoc' command. The generated HTML files can be found in 'build_doc/html/docs/index.html'.

```text
$ make builddoc
```

--------------------------------

### Call Flow for HTTP GET Request and Response in zhmcclient

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/design/network-errors.rst

Traces the sequence of calls made during an HTTP GET request and response, showing the interaction between different layers of the networking stack.

```text
    -> zhmcclient/_session.py(392): Session.get()
      -> requests/sessions.py(501): Session.get()
         -> requests/sessions.py(488)request()
            -> requests/sessions.py(609)send()
               -> requests/adapters.py(423)send()
                  -> requests/packages/urllib3/connectionpool.py(600)urlopen()
                     -> requests/packages/urllib3/connectionpool.py(356)_make_request()
                        -> httplib.py(1022): HTTPConnection.request()
                           -> httplib.py(1056): HTTPConnection._send_request()
                              -> httplib.py(1018): HTTPConnection.endheaders()
                                 -> httplib.py(869): HTTPConnection._send_output()
                                    -> httplib.py(829): HTTPConnection.send()
                                       -> _socketmodule.so: socket.connect(), if needed (not used by urllib3)
                                       -> _socketmodule.so: socket.sendall()
                     -> requests/packages/urllib3/connectionpool.py(379)_make_request()
                        -> httplib.py(1089): HTTPConnection.getresponse()
                           -> httplib.py(444): HTTPResponse.begin()
                              -> httplib.py(400): HTTPResponse._read_status()
                                 -> socket.py(424): _fileobject.readline()
                                    -> _socketmodule.so: socket.recv()
            -> requests/sessions.py(641)send()
               -> requests/models.py(797)content()
                  -> requests/models.py(719)generate()
                     -> requests/packages/urllib3/response.py(432)stream()
                        -> requests/packages/urllib3/response.py(380)read()
                           -> httplib.py(602): HTTPResponse.read()
                              -> socket.py(355): _fileobject.read()
                                 -> _socketmodule.so: socket.recv()
                           -> httplib.py(610): HTTPResponse.read()
                              -> httplib.py(555): HTTPResponse.close()
                                 -> socket.py(284): _fileobject.close()
                                    -> socket.py(300): _fileobject.flush()
                                       -> _socketmodule.so: socket.sendall(), if anything remaining
                                    -> _socketmodule.so: socket.close()
```

--------------------------------

### Example HMC Vault File

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

This is an example of an HMC vault file in YAML format. Note that in the current release, HMC vault files cannot be encrypted. Set restrictive file permissions to mitigate this.

```yaml
# Example HMC vault file
# This file is compatible with Ansible vault files in YAML format.
# In the current release, HMC vault files cannot be encrypted.
# To mitigate that, set restrictive file permissions on the HMC vault files.

hmc_vault:
  - hmc_host: "hmc1.example.com"
    username: "user1"
    password: "password_for_user1"
  - hmc_host: "hmc2.example.com"
    username: "user2"
    password: "password_for_user2"

```

--------------------------------

### Run Unit Tests

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

Execute unit tests using 'make test'. This command imports zhmcclient modules from the local directory. The 'TESTCASES' environment variable can filter test execution.

```text
$ make test
```

--------------------------------

### Build Draft Changelog

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

Run this command to preview how your changes will appear in the release changelog.

```sh
towncrier build --draft
```

--------------------------------

### Improved Waiting for Asynchronous Job Operations

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/changes.rst

The wait time between 'Get Job Properties' operations has been increased from 1 to 10 seconds to reduce stress on the HMC. Failures during 'Get Job Properties' are now logged, and the original message in `urllib3.exceptions.MaxRetryError` is no longer removed.

```python
# Increased wait time for async job operations to 10 seconds.
```

--------------------------------

### Added Lpar.nvme_load() and Lpar.nvme_dump() Methods

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/changes.rst

New methods, Lpar.nvme_load() and Lpar.nvme_dump(), have been added along with their corresponding tests. These methods support NVMe operations for Logical Partitions.

```python
# Added Lpar.nvme_load() and Lpar.nvme_dump() methods with tests.
```

--------------------------------

### Start New Version Branch

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

Creates and pushes a new branch for starting development of a new version. The default branch used depends on the VERSION variable; 'master' for M.N.0 and 'stable_M.N' otherwise. A specific stable branch can be specified using the BRANCH variable.

```sh
VERSION=M.N.U make start_branch
```

```sh
VERSION=M.N.0 BRANCH=stable_M.N make start_branch
```

--------------------------------

### Added Mock Support for Lpar.nvme_load() and Lpar.nvme_dump()

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/changes.rst

Mock support and tests have been added for Lpar.nvme_load() and Lpar.nvme_dump(). This enables testing of NVMe operations in a simulated environment.

```python
# Added mock support and tests for Lpar.nvme_load() and Lpar.nvme_dump().
```

--------------------------------

### Create and Log On zhmcclient Client

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/notebooks/03_datamodel.ipynb

Creates a logged-on zhmcclient client for the specified HMC. The `make_client` function handles user ID and password prompts and storage.

```python
import tututils
zhmc = '9.152.150.65'  # edit this to your HMC's IP address or host name
user = 'ensadmin'      # edit this to the userid on that HMC
client = tututils.make_client(zhmc, user)
```

--------------------------------

### Get HMC API version

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/notebooks/02_connections.ipynb

Retrieve and print the API version of the HMC. This operation can be performed without being logged in.

```python
vi = client.version_info()
print("HMC API version: {}.{}".format(vi[0], vi[1]))
```

--------------------------------

### Client

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/general.rst

Documentation for the main Client class used to interact with the z/VM HMC.

```APIDOC
## Client

This section covers the primary Client class.

### Class
- `zhmcclient.Client`: The main client for interacting with the HMC.
```

--------------------------------

### Get Virtual Storage Resource Properties

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/design/dpm-storage-model.rst

Retrieves the properties of a specific virtual storage resource within a storage group.

```APIDOC
## GET /api/storage-groups/{storage-group-id}/virtual-storage-resources/{virtual-storage-resource-id}

### Description
Retrieves the properties of a specific virtual storage resource within a storage group.

### Method
GET

### Endpoint
/api/storage-groups/{storage-group-id}/virtual-storage-resources/{virtual-storage-resource-id}

### Parameters
#### Path Parameters
- **storage-group-id** (string) - Required - The ID of the storage group.
- **virtual-storage-resource-id** (string) - Required - The ID of the virtual storage resource.
```

--------------------------------

### Pass Additional Pytest Options

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/development.rst

Specify additional options for the pytest command using the 'TESTOPTS' environment variable. For example, to stop after the first failure.

```text
$ TESTOPTS='-x' make test
```

--------------------------------

### Initialize zhmcclient with HMC details

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/notebooks/04_error_handling.ipynb

This snippet initializes the zhmcclient with HMC connection details. Ensure you edit the 'zhmc' and 'user' variables to match your HMC's IP address/hostname and a valid userid.

```python
import tututils
import zhmcclient
zhmc = '9.152.150.65'  # edit this to your HMC's IP address or host name
user = 'ensadmin'      # edit this to the userid on that HMC
client = tututils.make_client(zhmc, user)
```

--------------------------------

### Fixing HMCDefinition.filepath AttributeError

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/changes.rst

An AttributeError on 'HMCDefinition.filepath' when using testutils for mocked environments has been fixed. This ensures proper handling of file paths in mock setups.

```python
# Fixed AttributeError on HMCDefinition.filepath in mock environments.
```

--------------------------------

### List Permitted Partitions

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

This snippet demonstrates how to list all permitted partitions on a console and print their CPC and partition names. It requires an active console connection.

```python
partitions = console.list_permitted_partitions()
for part in partitions:
    cpc = part.manager.parent
    print("{} {}".format(cpc.name, part.name))
```

--------------------------------

### Get the current working directory in a Jupyter Notebook

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/notebooks/01_notebook_basics.ipynb

This snippet prints the current working directory of the notebook. It is typically the directory where the `jupyter notebook` command was issued.

```python
import os
print(os.getcwd())
```

--------------------------------

### Catching zhmcclient.Error exceptions

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/notebooks/04_error_handling.ipynb

This example demonstrates the basic approach to handling exceptions in zhmcclient by catching all exceptions derived from zhmcclient.Error. This ensures that HMC-specific issues are managed gracefully.

```python
try:
    # Code that might raise zhmcclient exceptions
    pass
except zhmcclient.Error as e:
    # Handle zhmcclient-specific errors
    print(f"zhmcclient error: {e}")
except Exception as e:
    # Handle other unexpected errors
    print(f"An unexpected error occurred: {e}")
```

--------------------------------

### Get zhmcclient Debug Information

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/intro.rst

Print debug information for the zhmcclient package to include in issue reports. This helps in diagnosing problems by providing system and package details.

```bash
$ python -c "import zhmcclient; print(zhmcclient.debuginfo())"
```

--------------------------------

### Pylint Configuration Update

Source: https://github.com/zhmcclient/python-zhmcclient/blob/master/docs/changes.rst

Configuration file for Pylint has been migrated to version 2.14. Pylint is no longer installed on Python 2.7. Minimum Pylint version is now 2.10.0 on Python 3.5+.

```python
# Pylint configuration updated to 2.14.
```