Public access to zhmcclient.Session password

Note that there are legitimate reasons to get the session password in a Python
program, including the zhmcclient package itself.

Details:

* Changed the protected '_password' attribute in the 'zhmcclient.Session' class
  to be available via a new public 'password' attribute, which is gettable and
  settable.

* Access via the protected attribute '_password' is still possible, but that
  attribute has been deprecated and getting or setting it now causes an according
  Python DeprecationWarning to be issued.

Signed-off-by: Andreas Maier <maiera@de.ibm.com>

Author: andy-maier

.pylintrc

@@ -528,7 +528,7 @@ argument-rgx=([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{1,29})_{0,1}$
 # Note: The expression below allows "lower_case_with_underscores" and
 #       "mixedCaseWithoutUnderscores"; leading underscores for privacy are allowed.
 #       Names matching this expression are compatible with PEP-8.
-attr-rgx=(_{0,1}([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{1,39})|__[a-z_]+__)$
+attr-rgx=(_{0,2}([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{1,39})|__[a-z_]+__)$
 
 # Bad variable names which should always be refused, separated by a comma.
 bad-names=foo,
@@ -574,7 +574,7 @@ class-attribute-rgx=_{0,2}([A-Z][A-Z0-9_]{0,38}[A-Z0-9]|[a-z][a-z0-9_]{0,38}[a-z
 #       allows that class names for callable classes can use function name syntax.
 #       This is not reflected in this regexp; callable classes that follow that
 #       convention should disable PyLint message C0103.
-class-rgx=_{0,1}[A-Z][a-zA-Z0-9]{1,39}$
+class-rgx=_{0,2}[A-Z][a-zA-Z0-9]{1,39}$
 
 # Naming style matching correct constant names.
 #const-naming-style=UPPER_CASE
@@ -585,7 +585,7 @@ class-rgx=_{0,1}[A-Z][a-zA-Z0-9]{1,39}$
 # Note: The expression below allows "UPPER_CASE_WITH_UNDERSCORES"; leading
 #       underscores for privacy are allowed.
 #       Names matching this expression are compatible with PEP-8.
-const-rgx=(_{0,1}[A-Z][A-Z0-9_]{0,48}[A-Z0-9]|__[a-z_]+__)$
+const-rgx=(_{0,2}[A-Z][A-Z0-9_]{0,48}[A-Z0-9]|__[a-z_]+__)$
 
 # Minimum line length for functions/classes that require docstrings, shorter
 # ones are exempt.
@@ -601,7 +601,7 @@ docstring-min-length=-1
 #       "mixedCaseWithoutUnderscores"; leading underscores for privacy as well as
 #       double trailing underscores are allowed.
 #       Names matching this expression are compatible with PEP-8.
-function-rgx=(_{0,1}([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{1,39})|__[a-z_]+__)$
+function-rgx=(_{0,2}([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{1,39})|__[a-z_]+__)$
 # TODO AM: Verify whether two leading underscores are allowed / supported with name mangling.
 
 # Good variable names which should always be accepted, separated by a comma.
@@ -622,7 +622,7 @@ include-naming-hint=no
 # with the set naming style.
 # Note: The expression below allows "lower_case_with_underscores" and
 #       "mixedCaseWithoutUnderscores"; leading underscores for privacy are allowed.
-inlinevar-rgx=_{0,1}([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{0,39})$
+inlinevar-rgx=_{0,2}([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{0,39})$
 
 # Naming style matching correct method names.
 #method-naming-style=snake_case
@@ -633,15 +633,15 @@ inlinevar-rgx=_{0,1}([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{0,39})$
 #       "mixedCaseWithoutUnderscores"; leading underscores for privacy as well as
 #       double trailing underscores are allowed.
 #       Names matching this expression are compatible with PEP-8.
-method-rgx=(_{0,1}([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{1,39})|__[a-z_]+__)$
+method-rgx=(_{0,2}([a-z][a-z0-9_]{0,38}[a-z0-9]|[a-z][a-zA-Z0-9]{1,39})|__[a-z_]+__)$
 
 # Naming style matching correct module names.
 #module-naming-style=snake_case
 
 # Regular expression matching correct module names. Overrides module-naming-
 # style. If left empty, module names will be checked with the set naming style.
 # Note: Names matching this expression are compatible with PEP-8.
-module-rgx=(_{0,1}[a-z][a-z0-9_]{0,38}[a-z0-9]|__[a-z_]+__)$
+module-rgx=(_{0,2}[a-z][a-z0-9_]{0,38}[a-z0-9]|__[a-z_]+__)$
 
 # Colon-delimited sets of names that determine each other's naming style when
 # the name regexes allow several styles.
@@ -671,4 +671,4 @@ property-classes=abc.abstractproperty
 #       other variables; one leading underscore is allowed, and one trailing
 #       underscore is allowed to avoid conflists with built-in names.
 #       Names matching this expression are compatible with PEP-8.
-variable-rgx=_{0,1}([A-Z]([A-Z0-9_]{0,38}[A-Z0-9])?|[a-z]([a-z0-9_]{0,38}[a-z0-9])?|[a-z]([a-zA-Z0-9]{1,39})?)_{0,1}$
+variable-rgx=_{0,2}([A-Z]([A-Z0-9_]{0,38}[A-Z0-9])?|[a-z]([a-z0-9_]{0,38}[a-z0-9])?|[a-z]([a-zA-Z0-9]{1,39})?)_{0,1}$

changes/2304.deprecation.rst

@@ -0,0 +1,6 @@
+Getting or setting the password in a 'zhmcclient.Session' object via its
+protected '_password' attribute is deprecated. Doing that will cause an
+according Python 'DeprecationWarning' to be issued. Use the new public
+'password' attribute instead. Note that there are legitimate reasons to get
+the session password in a Python program, including the zhmcclient package
+itself.

changes/2304.feature.rst

@@ -0,0 +1,6 @@
+Changed the protected '_password' attribute in the 'zhmcclient.Session' class
+to be available via a new public 'password' attribute, which is gettable and
+settable.
+Access via the protected attribute '_password' is still possible, but that
+attribute has been deprecated and getting or setting it now causes an according
+Python DeprecationWarning to be issued.

examples/async_operation_notification.py

@@ -94,9 +94,8 @@ def main():
             print("Creating a notification receiver for topic "
                   f"{job_topic_name} ...")
             try:
-                # pylint: disable=protected-access
                 receiver = zhmcclient.NotificationReceiver(
-                    job_topic_name, host, session.userid, session._password,
+                    job_topic_name, host, session.userid, session.password,
                     verify_cert=session.verify_cert)
             except zhmcclient.Error as exc:
                 print(f"Error: Cannot create notification receiver: {exc}")

examples/show_os_messages.py

@@ -84,9 +84,8 @@ def main():
 
         print(f"Creating a notification receiver for topic {msg_topic} ...")
         try:
-            # pylint: disable=protected-access
             receiver = zhmcclient.NotificationReceiver(
-                msg_topic, host, session.userid, session._password,
+                msg_topic, host, session.userid, session.password,
                 verify_cert=session.verify_cert)
         except zhmcclient.Error as exc:
             print(f"Error: Cannot create notification receiver: {exc}")

tests/unit/zhmcclient/test_session.py

@@ -21,6 +21,7 @@
 import json
 import re
 from unittest import mock
+import warnings
 import requests
 import requests_mock
 import pytest
@@ -90,8 +91,7 @@ def get_password(host, userid):
 
     assert session.host == host
     assert session.userid == userid
-    # pylint: disable=protected-access
-    assert session._password == password
+    assert session.password == password
     assert session.session_id == session_id
     assert session.get_password == get_password
     assert session.port == kwargs.get('port', DEFAULT_HMC_PORT)
@@ -130,6 +130,98 @@ def test_session_repr():
         repr_str)
 
 
+def test_password_get_no_deprecation():
+    """
+    Verify that accessing the session password via the new 'password'
+    attribute issues no deprecation warning.
+    """
+    pw1 = "mypw1"
+    session = Session("myhost", "myuser", pw1)
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", DeprecationWarning)
+
+        # The code to be tested
+        pw = session.password
+
+    # Verify that the access works
+    assert pw == pw1
+
+
+def test_password_set_no_deprecation():
+    """
+    Verify that setting the session password via the new 'password'
+    attribute issues no deprecation warning.
+    """
+    pw1 = "mypw1"
+    pw2 = "mypw2"
+    session = Session("myhost", "myuser", pw1)
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", DeprecationWarning)
+
+        # The code to be tested
+        session.password = pw2
+
+    # Verify that the setting works
+    assert session.password == pw2
+
+
+def test_password_get_deprecation():
+    """
+    Verify that accessing the session password via the deprecated '_password'
+    attribute issues a deprecation warning.
+    """
+    pw1 = "mypw1"
+    session = Session("myhost", "myuser", pw1)
+
+    with pytest.warns(DeprecationWarning) as record:
+
+        # The code to be tested
+        pw = session._password  # pylint: disable=protected-access
+
+    # Verify that the access works
+    assert pw == pw1
+
+    # Verify that one DeprecationWarning was issued
+    assert len(record) == 1
+
+    # Verify the message in the DeprecationWarning
+    msg = str(record[0].message)
+    assert re.search(r"protected '_password' attribute is deprecated", msg)
+
+    # Verify that stacklevel points at the caller
+    assert record[0].filename == __file__
+
+
+def test_password_set_deprecation():
+    """
+    Verify that setting the session password via the deprecated '_password'
+    attribute issues a deprecation warning.
+    """
+    pw1 = "mypw1"
+    pw2 = "mypw2"
+    session = Session("myhost", "myuser", pw1)
+
+    with pytest.warns(DeprecationWarning) as record:
+
+        # The code to be tested
+        session._password = pw2  # pylint: disable=protected-access
+
+    # Verify that the setting works
+    assert session.password == pw2
+
+    # Verify that one DeprecationWarning was issued
+    assert len(record) == 1
+
+    # Verify the message in the DeprecationWarning
+    msg = str(record[0].message)
+    assert re.search(r"protected '_password' attribute is deprecated", msg)
+
+    # Verify that stacklevel points at the caller
+    assert record[0].filename == __file__
+
+
 @pytest.mark.parametrize(
     "host, userid, password, use_get_password, exp_exc", [
         ('fake-host', None, None, False, ClientAuthError),
@@ -187,8 +279,7 @@ def test_session_logon(
             if get_password:
                 if password is None:
                     get_password.assert_called_with(host, userid)
-                    # pylint: disable=protected-access
-                    assert session._password == get_password.return_value
+                    assert session.password == get_password.return_value
                 else:
                     get_password.assert_not_called()
 

zhmcclient/_auto_updater.py

@@ -205,8 +205,7 @@ def open(self):
         try:
             # wait=True causes the connection to be retried for some times
             # and finally raises stomp.ConnectFailedException
-            # pylint: disable=protected-access
-            self._conn.connect(self._session.userid, self._session._password,
+            self._conn.connect(self._session.userid, self._session.password,
                                wait=True)
         except (self._stomp.exception.StompException, OSError) as exc:
             msg = f"STOMP connection failed: {exc.__class__.__name__}: {exc}"

zhmcclient/_session.py

@@ -21,6 +21,7 @@
 import time
 import re
 import logging
+import warnings
 from copy import copy
 from collections.abc import Iterable
 import requests
@@ -429,7 +430,7 @@ def __init__(self, host, userid=None, password=None, session_id=None,
             assert len(self._hosts) >= 1
         self._port = port
         self._userid = userid
-        self._password = password
+        self.__password = password
         self._verify_cert = verify_cert
         self._get_password = get_password
         self._retry_timeout_config = self.default_rt_config.override_with(
@@ -466,7 +467,7 @@ def __repr__(self):
         """
         headers = _headers_for_logging(self.headers)
         blanked_session_id = BLANKED_OUT_STRING if self._session_id else None
-        blanked_password = BLANKED_OUT_STRING if self._password else None
+        blanked_password = BLANKED_OUT_STRING if self.__password else None
         ret = (
             f"{repr_obj_id(self)} (\n"
             f"  _hosts={self._hosts!r},\n"
@@ -544,6 +545,46 @@ def userid(self):
         """
         return self._userid
 
+    @property
+    def password(self):
+        """
+        :term:`string`: HMC password that is used for this session.
+
+        If `None`, only operations that do not require authentication, can be
+        performed.
+
+        This property is gettable and settable.
+        """
+        return self.__password
+
+    @password.setter
+    def password(self, value):
+        # We do not want documentation generated for the setter, since it is
+        # described in the getter method.
+        self.__password = value
+
+    @property
+    def _password(self):
+        # For backwards compatibility, we still support access via the
+        # protected attribute '_password', but don't want to have that show up
+        # in the documentation.
+        warnings.warn(
+            "Accessing the zhmcclient.Session password via the protected "
+            "'_password' attribute is deprecated; Use the public 'password' "
+            "attribute instead", DeprecationWarning, stacklevel=2)
+        return self.__password
+
+    @_password.setter
+    def _password(self, value):
+        # For backwards compatibility, we still support modification via the
+        # protected attribute '_password', but don't want to have that show up
+        # in the documentation.
+        warnings.warn(
+            "Setting the zhmcclient.Session  password via the protected "
+            "'_password' attribute is deprecated; Use the public 'password' "
+            "attribute instead", DeprecationWarning, stacklevel=2)
+        self.__password = value
+
     @property
     def verify_cert(self):
         """
@@ -828,9 +869,9 @@ def _do_logon(self):
         if self._userid is None:
             raise ClientAuthError("Userid is not provided.")
 
-        if self._password is None:
+        if self.__password is None:
             if self._get_password:
-                self._password = \
+                self.__password = \
                     self._get_password(self._actual_host, self._userid)
             elif self._session_id:
                 raise ClientAuthError(
@@ -843,7 +884,7 @@ def _do_logon(self):
         logon_uri = '/api/sessions'
         logon_body = {
             'userid': self._userid,
-            'password': self._password
+            'password': self.__password
         }
         self._headers.pop('X-API-Session', None)  # Just in case
         self._session = self._new_session(self.retry_timeout_config)