updated docs

bin/module/esme.py

@@ -23,7 +23,9 @@ except ImportError:
 
 
 class Error(Flag):
-    """Error constants for the FsrLdap class"""
+    """
+    Error constants for the FsrLdap class
+    """
     UNSEC_SEARCH = auto()
     NO_FILE = auto()
     LDAP_FAIL = auto()
@@ -33,14 +35,18 @@ class Error(Flag):
 
 
 def current_user():
-    """get the current user"""
+    """
+    get the uid of the current user
+    """
     if pwd:
         return pwd.getpwuid(os.geteuid()).pw_name
     return getpass.getuser()
 
 
 def resort_fsr(fsr, num_cols=5):
-    """resort list for pascal style sorting"""
+    """
+    resort list of names by pascal style
+    """
     fsr += [""] * (num_cols - len(fsr) % num_cols)
     depth = len(fsr) // num_cols
 
@@ -53,7 +59,9 @@ def resort_fsr(fsr, num_cols=5):
 
 
 class FsrLdap:
-    """Class die die protokoll .tex datei erstellt"""
+    """
+    Class providing LDAP integration
+    """
 
     def __init__(self, server, base, share_dir, config, debug=False,
                  timeout=1, testing=None):
@@ -77,7 +85,11 @@ class FsrLdap:
         self.config = config
 
     def _get_protokollant_ldap(self):
-        """search the LDAP for the current user"""
+        """
+        get the name of the current user by searching the LDAP-Server
+        if the search is unsuccessful return Error.UNSEC_SEARCH
+        if the search fails because of a LDAPException return Error.LDAP_FAIL
+        """
         logging.info("Fetching Protokollant from LDAP ...")
         try:
             fil = "(uid="+current_user()+")"
@@ -88,15 +100,20 @@ class FsrLdap:
             return Error.UNSEC_SEARCH
         except ldap.core.exceptions.LDAPException as error_message:
             if self.debug:
-                logging.warning("Couldn't Connect to ldap. \
-                                Using fallback default. %s" % error_message)
+                logging.warning("Couldn't connect to the LDAP-Server. \
+                                Using fall-back default. %s" % error_message)
             else:
-                logging.warning("Couldn't Connect to ldap. Using fallback default.")  # noqa: E501
+                logging.warning("Couldn't Connect to the LDAP-Server. Using fall-back default.")  # noqa: E501
             return Error.LDAP_FAIL
 
     @staticmethod
     def _get_fallback_protokollant(config=None):
-        """get protokollant from user input or config"""
+        """
+        get the name of the Protokollant from user input or config
+        The values are used in this order:
+        - the Protokollant provided by the user
+        - config['PROTOKOLL']['Protokollant']
+        """
         protokollant = ''
         if config:
             protokollant = config['PROTOKOLL']['Protokollant']
@@ -106,13 +123,20 @@ class FsrLdap:
         return protokollant
 
     def get_protokollant(self, config=None):
-        """get protokollant"""
+        """
+        get the Name of the Protokollant
+        The Name sources are used in this order:
+        - LDAP-Server
+        - user input
+        - config
+
+        if non is found return an empty string
+        """
         if not config:
             config = self.config
 
         protokollant = self._get_protokollant_ldap()
         if isinstance(protokollant, tuple):
-            pass
             protokollant = protokollant[0]
         elif isinstance(protokollant, Flag):
             if protokollant in Error.UNSEC_SEARCH | Error.LDAP_FAIL:
@@ -122,7 +146,12 @@ class FsrLdap:
         return protokollant
 
     def _get_fsr_ldap(self):
-        """get fsr from LDAP"""
+        """
+        get the list of the names of the FSR by searching the LDAP-Server
+
+        if the search is unsuccessful return Error.UNSEC_SEARCH
+        if the search fails because of a LDAPException return Error.LDAP_FAIL
+        """
         logging.info("Fetching FSR from LDAP ...")
         try:
             fil = '(cn=intern)'
@@ -141,15 +170,19 @@ class FsrLdap:
             return Error.UNSEC_SEARCH
         except ldap.core.exceptions.LDAPException as error_message:
             if self.debug:
-                logging.warning("Couldn't Connect to ldap. \
-                                Using fallback File. %s" % error_message)
+                logging.warning("Couldn't Connect to the LDAP-Server. \
+                                Using the fall-back file. %s" % error_message)
             else:
-                logging.warning("Couldn't Connect to ldap. Using fallback File.")  # noqa: E501
+                logging.warning("Couldn't Connect to the LDAP-Server. Using fall-back file.")  # noqa: E501
             return (Error.LDAP_FAIL, error_message)
 
     @staticmethod
     def _get_fallback_fsr(share_dir):
-        """get fsr form fallback file"""
+        """
+        get the list of the names of the FSR from the fall back file
+
+        if the file is not found return Error.NO_FILE
+        """
         if os.path.isfile(os.path.join(share_dir, 'fsr')):
             with codecs.open(os.path.join(share_dir, 'fsr'),
                              'r', 'utf-8') as fobj:
@@ -162,7 +195,15 @@ class FsrLdap:
         return Error.NO_FILE
 
     def get_fsr(self, share_dir=None, gen_fallback=None):
-        """get fsr"""
+        """
+        get a sorted list of the names of the FSR
+        The name sources are used in this order:
+        - LDAP-Server
+        - user input
+        - fall-back file
+
+        if non is found return an empty list
+        """
         if not share_dir:
             share_dir = self.share_dir
 
@@ -179,8 +220,14 @@ class FsrLdap:
         return resort_fsr(fsr, num_cols=self.config['PROTOKOLL'].getint('NUM_COLS'))  # noqa: E501
 
     def _get_fsr_extern_ldap(self):
-        """get the EFSR from LDAP"""
-        logging.info("Fetching EFSR from LDAP ...")
+        """
+        get the list of the names of the eFSR
+        by searching the LDAP-Server
+
+        if the search is unsuccessful return Error.UNSEC_SEARCH
+        if the search fails because of a LDAPException return Error.LDAP_FAIL
+        """
+        logging.info("Fetching eFSR from LDAP ...")
         try:
             fil = '(cn=extern)'
             fsr_extern = []
@@ -201,12 +248,15 @@ class FsrLdap:
                 logging.warning("Couldn't Connect to ldap. \
                                 Using fallback File. %s" % error_message)
             else:
-                logging.warning("Couldn't Connect to ldap. Using fallback File.")  # noqa: E501
+                logging.warning("Couldn't connect to the LDAP-Server. Using fall-back file.")  # noqa: E501
             return (Error.LDAP_FAIL, error_message)
 
     @staticmethod
     def _get_fallback_fsr_extern(share_dir):
-        """get fsr_extern from fallback file"""
+        """
+        get the list of the names of the extern FSR from the fall back file
+        if the file is not found return Error.NO_FILE
+        """
         if os.path.isfile(os.path.join(share_dir, 'fsr_extern')):
             with codecs.open(os.path.join(share_dir, 'fsr_extern'),
                              'r', 'utf-8') as fobj:
@@ -219,7 +269,14 @@ class FsrLdap:
         return Error.NO_FILE
 
     def get_fsr_extern(self, share_dir=None, gen_fallback=None):
-        """get fsr extern"""
+        """
+        get a sorted list of the names of the eFSR
+        The name sources are used in this order:
+        - LDAP-Server
+        - fall-back file
+
+        if non is found return an empty list
+        """
         if not share_dir:
             share_dir = self.share_dir
 
@@ -238,7 +295,12 @@ class FsrLdap:
 
 
 def get_sprecher(config=None):
-    """get sprecher from user input or config"""
+    """
+    get Sprecher from user input or config
+    The values are used in this order:
+    - the Sprecher provided by the user
+    - config['PROTOKOLL']['Sprecher']
+    """
     sprecher = ''
     if config:
         sprecher = config['PROTOKOLL']['Sprecher']
@@ -249,7 +311,13 @@ def get_sprecher(config=None):
 
 
 def get_date(test=False):
-    """get current date then ask user"""
+    """
+    get current date then ask user
+    The dates are used in this order:
+    - if test is true use the 01.01.2000
+    - the date provided by the user
+    - the current system time
+    """
     if test:
         date = ('01.01.2000', '2000', '01', '01')
     else:
@@ -276,7 +344,9 @@ def get_date(test=False):
 
 
 def get_editor(editor):
-    """get the editor to use from user input"""
+    """
+    get the editor to use from user input
+    """
     etmp = input("Editor ["+editor+"]: ")
     if etmp != "":
         return etmp
@@ -284,7 +354,18 @@ def get_editor(editor):
 
 
 def get_config(rundir, config_path=None, default=False):
-    """get the location of the config file and load configparser"""
+    """
+    get the location of the config file and load configparser
+    The files are used in this order:
+    - `config_path`
+    - if default is specified:
+      - `rundir/../etc/proto.ini.default`
+    - `rundir/../etc/proto.ini`
+    - `rundir/../etc/proto.ini.default`
+
+    if the file given by config_path is not found return Error.NO_FILE
+    if the default file is not found return Error.NO_DEFAULT_FILE
+    """
     if config_path:
         if os.path.isfile(config_path):
             config = configparser.ConfigParser()
@@ -299,7 +380,7 @@ def get_config(rundir, config_path=None, default=False):
             return config
         logging.warning('No default File found at '
                         + os.path.abspath(os.path.join(rundir,
-                            '../etc/proto.ini.default')))  # noqa: E501
+                                                       '../etc/proto.ini.default')))  # noqa: E501
         return Error.NO_DEFAULT_FILE
     elif os.path.isfile(os.path.join(rundir,
                                      '../etc/proto.ini')) and not default:
@@ -311,12 +392,23 @@ def get_config(rundir, config_path=None, default=False):
         config = configparser.ConfigParser()
         config.read(os.path.join(rundir, '../etc/proto.ini.default'))
         return config
-    logging.warning('No ini file found. Using hardcoded defaults.')
+    logging.warning('No ini file found. Using hard codded defaults.')
     return Error.NO_DEFAULT_FILE
 
 
 def get_share(rundir, config=None, sharedir=None):
-    """get the location of the share directory"""
+    """
+    get the location of the share directory
+    The directories are used in this order:
+    - `sharedir`
+    - the one provided in config['PROTOKOLL']['share']
+        - if the path is a relative one it is relative
+          to the script directory
+    - `rundir/../share`
+
+    if a provided directory is not found return Error.NO_FILE
+    if the default directory is not found return Error.NO_DEFAULT_FILE
+    """
     if sharedir:
         if os.path.isdir(sharedir):
             return sharedir
@@ -338,7 +430,18 @@ def get_share(rundir, config=None, sharedir=None):
 
 
 def get_path(rundir, config=None, path=None):
-    """get the location of the protokoll directory"""
+    """
+    get the location of the Protokoll directory
+    The directories are used in this order:
+    - `path`
+    - the one provided in config['PROTOKOLL']['path']
+        - if the path is a relative one it is relative
+          to the script directory
+    - `rundir/../..`
+
+    if a provided directory is not found return Error.NO_FILE
+    if the default directory is not found return Error.NO_DEFAULT_FILE
+    """
     if path:
         if os.path.isdir(path):
             return path
@@ -360,28 +463,47 @@ def get_path(rundir, config=None, path=None):
 
 
 def get_ldap_server(config=None, server=None):
-    """get the ldap server for the fsr lookup"""
+    """
+    get the LDAP-Server for the FSR lookup
+    The servers are used in this order:
+    - the server provided by server
+    - the server provided by config['SERVER']['NAME']
+    - `rincewind.fs.physik.uni-kl.de`
+    """
     if server:
         return server
     if config:
         return config['SERVER']['NAME']
-    logging.warning('No LDAP Server supplied. Triing to use "rincwind.fs.physik.uni-kl.de".')  # noqa: E501
+    logging.warning('No LDAP Server supplied. Tiring to use "rincewind.fs.physik.uni-kl.de".')  # noqa: E501
     return "rincewind.fs.physik.uni-kl.de"
 
 
 def get_ldap_base(config=None, base=None):
-    """get the search base for the ldap server"""
+    """
+    get the search base for the LDAP-Server
+    The bases are used in this order:
+    - the base provided by base
+    - the base provided by config['SERVER']['BASE']
+    - `dc=fs,dc=physik,dc=uni-kl,dc=de`
+    """
     if base:
         return base
     if config:
         return config['SERVER']['BASE']
     logging.warning('No LDAP search base supplied. '
-                    'Triing to use "dc=fs,dc=physik,dc=uni-kl,dc=de".')
+                    'Tiring to use "dc=fs,dc=physik,dc=uni-kl,dc=de".')
     return "dc=fs,dc=physik,dc=uni-kl,dc=de"
 
 
 def get_server_timeout(config=None, test=None):
-    """get the timeout for the connection to the ldap server"""
+    """
+    get the timeout for the connection to the LDAP-Server
+    The timeouts are used in this order:
+    - if test is true:
+      - `1`
+    - config['SERVER']['connect_timeout']
+    - `10`
+    """
     if test:
         return 1
     if config: