Reformat default_settings.py for documentation using sphinx autodoc

cas_server/default_settings.py

@@ -13,84 +13,137 @@
 from django.conf import settings
 from django.contrib.staticfiles.templatetags.staticfiles import static
 
+from importlib import import_module
 
-def setting_default(name, default_value):
-    """if the config `name` is not set, set it the `default_value`"""
-    value = getattr(settings, name, default_value)
-    setattr(settings, name, value)
 
-setting_default('CAS_LOGO_URL', static("cas_server/logo.png"))
+#: URL to the logo showed in the up left corner on the default templates.
+CAS_LOGO_URL = static("cas_server/logo.png")
+#: Path to the template showed on /login then the user is not autenticated.
+CAS_LOGIN_TEMPLATE = 'cas_server/login.html'
+#: Path to the template showed on /login?service=... then the user is authenticated and has asked
+#: to be warned before being connected to a service.
+CAS_WARN_TEMPLATE = 'cas_server/warn.html'
+#: Path to the template showed on /login then to user is authenticated.
+CAS_LOGGED_TEMPLATE = 'cas_server/logged.html'
+#: Path to the template showed on /logout then to user is being disconnected.
+CAS_LOGOUT_TEMPLATE = 'cas_server/logout.html'
+#: Should we redirect users to /login after they logged out instead of displaying
+#: :obj:`CAS_LOGOUT_TEMPLATE`.
+CAS_REDIRECT_TO_LOGIN_AFTER_LOGOUT = False
 
-setting_default('CAS_LOGIN_TEMPLATE', 'cas_server/login.html')
-setting_default('CAS_WARN_TEMPLATE', 'cas_server/warn.html')
-setting_default('CAS_LOGGED_TEMPLATE', 'cas_server/logged.html')
-setting_default('CAS_LOGOUT_TEMPLATE', 'cas_server/logout.html')
-setting_default('CAS_AUTH_CLASS', 'cas_server.auth.DjangoAuthUser')
-# All CAS implementation MUST support ST and PT up to 32 chars,
-# PGT and PGTIOU up to 64 chars and it is RECOMMENDED that all
-# tickets up to 256 chars are supports so we use 64 for the default
-# len.
-setting_default('CAS_TICKET_LEN', 64)
 
-setting_default('CAS_LT_LEN', settings.CAS_TICKET_LEN)
+#: A dotted path to a class or a class implementing cas_server.auth.AuthUser.
-setting_default('CAS_ST_LEN', settings.CAS_TICKET_LEN)
+CAS_AUTH_CLASS = 'cas_server.auth.DjangoAuthUser'
-setting_default('CAS_PT_LEN', settings.CAS_TICKET_LEN)
+#: Path to certificate authorities file. Usually on linux the local CAs are in
-setting_default('CAS_PGT_LEN', settings.CAS_TICKET_LEN)
+#: /etc/ssl/certs/ca-certificates.crt. ``True`` tell requests to use its internal certificat
-setting_default('CAS_PGTIOU_LEN', settings.CAS_TICKET_LEN)
+#: authorities.
+CAS_PROXY_CA_CERTIFICATE_PATH = True
+#: Maximum number of parallel single log out requests send
+#: if more requests need to be send, there are queued
+CAS_SLO_MAX_PARALLEL_REQUESTS = 10
+#: Timeout for a single SLO request in seconds.
+CAS_SLO_TIMEOUT = 5
+#: Shared to transmit then using the view :class:`cas_server.views.Auth`
+CAS_AUTH_SHARED_SECRET = ''
 
-setting_default('CAS_TICKET_VALIDITY', 60)
-setting_default('CAS_PGT_VALIDITY', 3600)
-setting_default('CAS_TICKET_TIMEOUT', 24*3600)
-setting_default('CAS_PROXY_CA_CERTIFICATE_PATH', True)
-setting_default('CAS_REDIRECT_TO_LOGIN_AFTER_LOGOUT', False)
 
-setting_default('CAS_AUTH_SHARED_SECRET', '')
+#: Number of seconds the service tickets and proxy tickets are valid. This is the maximal time
+#: between ticket issuance by the CAS and ticket validation by an application.
+CAS_TICKET_VALIDITY = 60
+#: Number of seconds the proxy granting tickets are valid.
+CAS_PGT_VALIDITY = 3600
+#: Number of seconds a ticket is kept in the database before sending Single Log Out request and
+#: being cleared.
+CAS_TICKET_TIMEOUT = 24*3600
 
-setting_default('CAS_LOGIN_TICKET_PREFIX', 'LT')
-# Service tickets MUST begin with the characters ST so you should not change this
-# Services MUST be able to accept service tickets of up to 32 characters in length
-setting_default('CAS_SERVICE_TICKET_PREFIX', 'ST')
-# Proxy tickets SHOULD begin with the characters, PT.
-# Back-end services MUST be able to accept proxy tickets of up to 32 characters.
-setting_default('CAS_PROXY_TICKET_PREFIX', 'PT')
-# Proxy-granting tickets SHOULD begin with the characters PGT
-# Services MUST be able to handle proxy-granting tickets of up to 64
-setting_default('CAS_PROXY_GRANTING_TICKET_PREFIX', 'PGT')
-# Proxy-granting ticket IOUs SHOULD begin with the characters, PGTIOU
-# Services MUST be able to handle PGTIOUs of up to 64 characters in length.
-setting_default('CAS_PROXY_GRANTING_TICKET_IOU_PREFIX', 'PGTIOU')
 
-# Maximum number of parallel single log out requests send
+#: All CAS implementation MUST support ST and PT up to 32 chars,
-# if more requests need to be send, there are queued
+#: PGT and PGTIOU up to 64 chars and it is RECOMMENDED that all
-setting_default('CAS_SLO_MAX_PARALLEL_REQUESTS', 10)
+#: tickets up to 256 chars are supports so we use 64 for the default
-# SLO request timeout.
+#: len.
-setting_default('CAS_SLO_TIMEOUT', 5)
+CAS_TICKET_LEN = 64
 
-setting_default('CAS_SQL_HOST', 'localhost')
+#: alias of :obj:`settings.CAS_TICKET_LEN`
-setting_default('CAS_SQL_USERNAME', '')
+CAS_LT_LEN = getattr(settings, 'CAS_TICKET_LEN', CAS_TICKET_LEN)
-setting_default('CAS_SQL_PASSWORD', '')
+#: alias of :obj:`settings.CAS_TICKET_LEN`
-setting_default('CAS_SQL_DBNAME', '')
+#: Services MUST be able to accept service tickets of up to 32 characters in length.
-setting_default('CAS_SQL_DBCHARSET', 'utf8')
+CAS_ST_LEN = getattr(settings, 'CAS_TICKET_LEN', CAS_TICKET_LEN)
-setting_default('CAS_SQL_USER_QUERY', 'SELECT user AS usersame, pass AS '
+#: alias of :obj:`settings.CAS_TICKET_LEN`
-                'password, users.* FROM users WHERE user = %s')
+#: Back-end services MUST be able to accept proxy tickets of up to 32 characters.
-setting_default('CAS_SQL_PASSWORD_CHECK', 'crypt')  # crypt or plain
+CAS_PT_LEN = getattr(settings, 'CAS_TICKET_LEN', CAS_TICKET_LEN)
+#: alias of :obj:`settings.CAS_TICKET_LEN`
+#: Services MUST be able to handle proxy-granting tickets of up to 64
+CAS_PGT_LEN = getattr(settings, 'CAS_TICKET_LEN', CAS_TICKET_LEN)
+#: alias of :obj:`settings.CAS_TICKET_LEN`
+#: Services MUST be able to handle PGTIOUs of up to 64 characters in length.
+CAS_PGTIOU_LEN = getattr(settings, 'CAS_TICKET_LEN', CAS_TICKET_LEN)
 
-setting_default('CAS_TEST_USER', 'test')
+#: Prefix of login tickets.
-setting_default('CAS_TEST_PASSWORD', 'test')
+CAS_LOGIN_TICKET_PREFIX = u'LT'
-setting_default(
+#: Prefix of service tickets. Service tickets MUST begin with the characters ST so you should not
-    'CAS_TEST_ATTRIBUTES',
+#: change this.
-    {
+CAS_SERVICE_TICKET_PREFIX = u'ST'
+#: Prefix of proxy ticket. Proxy tickets SHOULD begin with the characters, PT.
+CAS_PROXY_TICKET_PREFIX = u'PT'
+#: Prefix of proxy granting ticket. Proxy-granting tickets SHOULD begin with the characters PGT.
+CAS_PROXY_GRANTING_TICKET_PREFIX = u'PGT'
+#: Prefix of proxy granting ticket IOU. Proxy-granting ticket IOUs SHOULD begin with the characters
+#: PGTIOU.
+CAS_PROXY_GRANTING_TICKET_IOU_PREFIX = u'PGTIOU'
+
+
+#: Host for the SQL server.
+CAS_SQL_HOST = 'localhost'
+#: Username for connecting to the SQL server.
+CAS_SQL_USERNAME = ''
+#: Password for connecting to the SQL server.
+CAS_SQL_PASSWORD = ''
+#: Database name.
+CAS_SQL_DBNAME = ''
+#: Database charset.
+CAS_SQL_DBCHARSET = 'utf8'
+#: The query performed upon user authentication.
+CAS_SQL_USER_QUERY = 'SELECT user AS usersame, pass AS password, users.* FROM users WHERE user = %s'
+#: The method used to check the user password. Must be one of ``crypt``, ``ldap``,  ``hex_md5``,
+#: ``hex_sha1``, ``hex_sha224``, ``hex_sha256``, ``hex_sha384``, ``hex_sha512``, ``plain``.
+CAS_SQL_PASSWORD_CHECK = 'crypt'  # crypt or plain
+
+
+#: Username of the test user.
+CAS_TEST_USER = 'test'
+#: Password of the test user.
+CAS_TEST_PASSWORD = 'test'
+#: Attributes of the test user.
+CAS_TEST_ATTRIBUTES = {
     'nom': 'Nymous',
     'prenom': 'Ano',
     'email': 'anonymous@example.net',
     'alias': ['demo1', 'demo2']
 }
-)
 
-setting_default('CAS_ENABLE_AJAX_AUTH', False)
 
-setting_default('CAS_FEDERATE', False)
+#: A :class:`bool` for activatinc the hability to fetch tickets using javascript.
-setting_default('CAS_FEDERATE_REMEMBER_TIMEOUT', 604800)  # one week
+CAS_ENABLE_AJAX_AUTH = False
 
+
+#: A :class:`bool` for activating the federated mode
+CAS_FEDERATE = False
+#: Time after witch the cookie use for “remember my identity provider” expire (one week).
+CAS_FEDERATE_REMEMBER_TIMEOUT = 604800
+
+
+for name, default_value in globals().items():
+    # get the current setting value, falling back to default_value
+    value = getattr(settings, name, default_value)
+    # set the setting value to its value if defined, ellse to the default_value.
+    setattr(settings, name, value)
+
+
+# if the federated mode is enabled, we must use the :class`cas_server.auth.CASFederateAuth` auth
+# backend.
 if settings.CAS_FEDERATE:
     settings.CAS_AUTH_CLASS = "cas_server.auth.CASFederateAuth"
+
+
+#: SessionStore class depending of :django:setting:`SESSION_ENGINE`
+SessionStore = import_module(settings.SESSION_ENGINE).SessionStore