From bc999e2a35281be9883617de7e3b51428b423f64 Mon Sep 17 00:00:00 2001 From: Dave Chen Date: Mon, 10 Aug 2015 15:53:34 +0800 Subject: [PATCH] Improve a few random docstrings - For triple-quoted strings, always use double quote characters to be consistent with the docstring convention in PEP 257. - Multi line docstrings should start with a one line summary followed by an empty line Change-Id: I591cd69f0ec9e7caabf559de09df422911dab91b Partial-Bug: 1482773 --- keystone/common/ldap/core.py | 31 ++++++++++++++++++------------- keystone/common/utils.py | 20 ++++++++++++-------- keystone/tests/unit/fakeldap.py | 7 ++++--- 3 files changed, 34 insertions(+), 24 deletions(-) diff --git a/keystone/common/ldap/core.py b/keystone/common/ldap/core.py index e18936aaac..fdd3633aa2 100644 --- a/keystone/common/ldap/core.py +++ b/keystone/common/ldap/core.py @@ -329,7 +329,7 @@ def dn_startswith(descendant_dn, dn): @six.add_metaclass(abc.ABCMeta) class LDAPHandler(object): - '''Abstract class which defines methods for a LDAP API provider. + """Abstract class which defines methods for a LDAP API provider. Native Keystone values cannot be passed directly into and from the python-ldap API. Type conversion must occur at the LDAP API @@ -417,7 +417,8 @@ class LDAPHandler(object): method to any derivations of the abstract class the code will fail to load and run making it impossible to forget updating all the derived classes. - ''' + + """ @abc.abstractmethod def __init__(self, conn=None): self.conn = conn @@ -623,15 +624,16 @@ def _common_ldap_initialization(url, use_tls=False, tls_cacertfile=None, class MsgId(list): - '''Wrapper class to hold connection and msgid.''' + """Wrapper class to hold connection and msgid.""" pass def use_conn_pool(func): - '''Use this only for connection pool specific ldap API. + """Use this only for connection pool specific ldap API. This adds connection object to decorated API as next argument after self. - ''' + + """ def wrapper(self, *args, **kwargs): # assert isinstance(self, PooledLDAPHandler) with self._get_pool_connection() as conn: @@ -798,11 +800,12 @@ class PooledLDAPHandler(LDAPHandler): def result3(self, msgid, all=1, timeout=None, resp_ctrl_classes=None): - '''This method is used to wait for and return the result of an - operation previously initiated by one of the LDAP asynchronous - operation routines (eg search_ext()) It returned an invocation - identifier (a message id) upon successful initiation of their - operation. + """This method is used to wait for and return result. + + This method returns the result of an operation previously initiated by + one of the LDAP asynchronous operation routines (eg search_ext()). It + returned an invocation identifier (a message id) upon successful + initiation of their operation. Input msgid is expected to be instance of class MsgId which has LDAP session/connection used to execute search_ext and message idenfier. @@ -810,7 +813,8 @@ class PooledLDAPHandler(LDAPHandler): The connection associated with search_ext is released once last hard reference to MsgId object is freed. This will happen when function which requested msgId and used it in result3 exits. - ''' + + """ conn, msg_id = msgid return conn.result3(msg_id, all, timeout) @@ -829,7 +833,7 @@ class PooledLDAPHandler(LDAPHandler): class KeystoneLDAPHandler(LDAPHandler): - '''Convert data types and perform logging. + """Convert data types and perform logging. This LDAP inteface wraps the python-ldap based interfaces. The python-ldap interfaces require string values encoded in UTF-8. The @@ -852,7 +856,8 @@ class KeystoneLDAPHandler(LDAPHandler): Data returned from the LDAP call is converted back from UTF-8 encoded strings into the Python data type used internally in OpenStack. - ''' + + """ def __init__(self, conn=None): super(KeystoneLDAPHandler, self).__init__(conn=conn) diff --git a/keystone/common/utils.py b/keystone/common/utils.py index 837279b912..8e05f3f830 100644 --- a/keystone/common/utils.py +++ b/keystone/common/utils.py @@ -246,7 +246,7 @@ def setup_remote_pydev_debug(): def get_unix_user(user=None): - '''Get the uid and user name. + """Get the uid and user name. This is a convenience utility which accepts a variety of input which might represent a unix user. If successful it returns the uid @@ -272,7 +272,8 @@ def get_unix_user(user=None): lookup. :return: tuple of (uid, name) - ''' + + """ if isinstance(user, six.string_types): try: @@ -301,7 +302,7 @@ def get_unix_user(user=None): def get_unix_group(group=None): - '''Get the gid and group name. + """Get the gid and group name. This is a convenience utility which accepts a variety of input which might represent a unix group. If successful it returns the gid @@ -328,7 +329,8 @@ def get_unix_group(group=None): lookup. :return: tuple of (gid, name) - ''' + + """ if isinstance(group, six.string_types): try: @@ -359,7 +361,7 @@ def get_unix_group(group=None): def set_permissions(path, mode=None, user=None, group=None, log=None): - '''Set the ownership and permissions on the pathname. + """Set the ownership and permissions on the pathname. Each of the mode, user and group are optional, if None then that aspect is not modified. @@ -376,7 +378,8 @@ def set_permissions(path, mode=None, user=None, group=None, log=None): if None do not set. :param logger log: logging.logger object, used to emit log messages, if None no logging is performed. - ''' + + """ if user is None: user_uid, user_name = None, None @@ -422,7 +425,7 @@ def set_permissions(path, mode=None, user=None, group=None, log=None): def make_dirs(path, mode=None, user=None, group=None, log=None): - '''Assure directory exists, set ownership and permissions. + """Assure directory exists, set ownership and permissions. Assure the directory exists and optionally set its ownership and permissions. @@ -442,7 +445,8 @@ def make_dirs(path, mode=None, user=None, group=None, log=None): if None do not set. :param logger log: logging.logger object, used to emit log messages, if None no logging is performed. - ''' + + """ if log: if mode is None: diff --git a/keystone/tests/unit/fakeldap.py b/keystone/tests/unit/fakeldap.py index 02b79be386..2f1ebe57b2 100644 --- a/keystone/tests/unit/fakeldap.py +++ b/keystone/tests/unit/fakeldap.py @@ -212,7 +212,7 @@ FakeShelves = {} class FakeLdap(core.LDAPHandler): - '''Emulate the python-ldap API. + """Emulate the python-ldap API. The python-ldap API requires all strings to be UTF-8 encoded. This is assured by the caller of this interface @@ -225,7 +225,8 @@ class FakeLdap(core.LDAPHandler): strings, decodes them to unicode for operations internal to this emulation, and encodes them back to UTF-8 when returning values from the emulation. - ''' + + """ __prefix = 'ldap:' @@ -583,7 +584,7 @@ class FakeLdapPool(FakeLdap): clientctrls=clientctrls) def unbind_ext_s(self): - '''Added to extend FakeLdap as connector class.''' + """Added to extend FakeLdap as connector class.""" pass