Commit 46877c64 authored by Lorenz Steinert's avatar Lorenz Steinert

updated docs

parent de86a9db
......@@ -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:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment