Coverage for superdjango/conf/__init__.py : 100%
Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
3Abstract
4--------
6There are a large number of settings which control SuperDjango's behavior. A means of centralizing and documenting these
7was desired.
9.. note::
10 Regarding the choice of django-appconf: Prior to SuperDjango 4, various approaches were used and all suffered from
11 one problem or another. The django-appconf app rather nicely meets the need of centralizing settings, and (as of
12 this writing) has 100% code coverage. However, should it need to be replaced, the source code is relatively
13 straight-forward, and could be adapted and modernized if need be.
15"""
16__author__ = "Shawn Davis <shawn@superdjango.com>"
17__maintainer__ = "Shawn Davis <shawn@superdjango.com>"
18__version__ = "4.1.1-d"
20# Imports
22from appconf import AppConf
23from django.conf import settings
24import os
26# Classes
29class General(AppConf):
30 """General settings used by SuperDjango.
32 To override or set the value of a general setting, add it to your ``settings.py`` file with the ``SUPERDJANGO_``
33 prefix. For example:
35 .. code-block:: python
37 SUPERDJANGO_BASE_TEMPLATE = "base_site.html"
39 """
41 AJAX_MODULE_NAME = "ajax"
42 """The name of the module (or package) that contains code for automated integration of AJAX views."""
44 API_MODULE_NAME = "api"
45 """The name of the module (or package) that contains code for automated Django REST Framework integration."""
47 BASE_TEMPLATE = "base.html"
48 """The base template to extend."""
50 DATA_PATH = None
51 """The path to data stored for the project or its apps."""
53 DATE_MASK = "%b %d, %Y"
54 """The default `strftime() <https://docs.python.org/3.7/library/datetime.html#strftime-strptime-behavior>_`
55 specification which should be used to format dates.
56 """
58 DATETIME_MASK = "%b %d, %Y %I:%M%p"
59 """The default `strftime() <https://docs.python.org/3.7/library/datetime.html#strftime-strptime-behavior>_`
60 specification which should be used to format datetime objects.
61 """
63 FORM_DEBUG = False
64 """Indicates form debugging is enabled. Note: This must be included in the context; see
65 ``superdjango.context_processors.settings_in_context``.
66 """
68 HELP_ENABLED = "superdjango.contrib.support.apps.DefaultConfig" in settings.INSTALLED_APPS
69 """Used internally in SuperDjango UI templates. Indicates whether the support application is enabled."""
71 MARKDOWN_EXTENSIONS = ["extra"]
72 """The extensions to be enabled when working with Markdown content.
74 See https://python-markdown.github.io/extensions/extra/
75 """
77 PAGINATION_LIMIT = 10
78 """The default number of records to show in a list view."""
80 REDIRECT_KEY = "next"
81 """The name of the GET key used to send a user to a URL after logging in."""
83 SCHEDULER_MODULE_NAME = "scheduler"
84 """The module name for apps wishing to contribute jobs to ``superdjango.contrib.scheduler``."""
86 SCHEDULER_PATH = os.path.join(settings.BASE_DIR, "../config", "scheduler.ini")
87 """The path to the scheduled jobs configuration."""
89 SSL_REQUIRED = not settings.DEBUG
90 """Indicates whether UI views must be served via a secure connection. By default, SSL is required except for
91 development.
92 """
94 UPPERS = [
95 "api",
96 "cname",
97 "css",
98 "hr",
99 "html",
100 "id",
101 "imap",
102 "inc",
103 "llc",
104 "pop3",
105 "purl",
106 "rss",
107 "sla",
108 "sms",
109 "smtp",
110 "ssl",
111 "tcp",
112 "tls",
113 "url",
114 "vip",
115 "xml",
116 ]
117 """The default list of strings to be converted to upper case by SuperDjango's ``title()`` shortcut."""
119 USE_CDN = not settings.DEBUG
120 """Indicates that SuperDjango's CDN should be used for static files, when available. The default is to use bundled
121 files when ``DEBUG`` is ``True`` and the preferred CDN of the resource when ``DEBUG`` is ``False.``
122 """
124 WEBMASTER_EMAIL = "webmaster@superdjango.com"
125 """The email address from which site email will be sent."""
127 WEBMASTER_NAME = "Webmaster"
128 """The name of the site's webmaster."""
130 class Meta:
131 prefix = "superdjango"
134class Internationalization(AppConf):
136 COUNTRY_CHOICES = None
137 """A choice list of ISO-3166-1 codes and country names."""
139 DEFAULT_COUNTRY_CODE = None
140 """The default country code to use for form ``CountryField``."""
142 TIMEZONE_CHOICES = None
143 """A list of choices for time zone form fields."""
145 TIMEZONE_KEY = "django_time_zone"
146 """The name of the session key used to store the user's time zone."""
148 class Meta:
149 prefix = "superdjango_i18n"
152class Support(AppConf):
153 """Configuration for ``contrib.support``."""
155 MARKDOWN_EXTENSIONS = ["extra"]
156 """A list of Markdown extensions to use when rendering support docs."""
158 PATH = os.path.join(settings.BASE_DIR, "../help")
159 """The path to support content."""
161 REQUIRES_LOGIN = True
162 """Indicates whether accessing support content requires an authenticated users."""
164 SEARCH_LOG_RESULTS = True
165 """Indicates search results should be logged. Helps improve the search catalog."""
167 SEARCH_TERMS = list()
168 """A list of terms that may be used to build the search catalog."""
170 URL = "/help/"
171 """The URL where support content may be accessed."""
173 class Meta:
174 prefix = "superdjango_support"
177class User(AppConf):
178 """User-related settings provided by SuperDjango."""
180 AUTO_CREATE_PROFILE = False
181 """Indicates that a user profile instance should be created, if possible, when one does not already exist. Consider
182 setting this to ``False`` while setting ``auto_create`` to ``True`` on your ``ProfileUpdate`` view. See profile
183 views for an example.
184 """
186 LOGIN_EXCLUDED_URLS = None
187 """Include URLs that do not (or should not) require a log in when ``LoginRequiredMiddleware`` is enabled. Django's
188 ``LOGIN_URL`` is added automatically.
189 """
191 LOGIN_REDIRECT_URL = settings.LOGIN_REDIRECT_URL
192 """The URL to which users are redirected (by default) after a successful login."""
194 LOGIN_REQUIRED = True
195 """Indicates that an authenticated user is the default for accessing views."""
197 LOGOUT_REDIRECT_URL = "/"
198 """The URL to which users are redirected after logging out."""
200 MAX_LOGIN_ATTEMPTS = None
201 """The maximum number of login attempts (int) before a user account is locked."""
203 MAX_LOGIN_MINUTES = None
204 """The number of minutes (int) between max login attempts."""
206 MAX_PASSWORD_RESET_ATTEMPTS = 3
207 """The maximum number of password reset attempts (int) before a user account is locked."""
209 MAX_PASSWORD_RESET_MINUTES = 30
210 """The number of minutes (int) between max password reset attempts."""
212 ORDER_USERS_BY = "first_name"
213 """The field name by which to order user lists."""
215 PASSWORD_RESET_LOGIN = False
216 """Indicates whether the user should be logged in after a password reset has been confirmed."""
218 PASSWORD_RESET_LOGGING_ENABLED = False
219 """Indicates logging should be enabled for password reset attempts. Requires ``PASSWORD_RESET_MODEL``."""
221 PASSWORD_RESET_MODEL = None
222 """The model used for logging password reset attempts in ``app_label.ModelName`` format."""
224 PASSWORD_RESET_USERNAME_ENABLED = False
225 """When ``True``, the reset lookup will also attempt to find a given user name if one has been given."""
227 REDIRECT_TO_CHOICES = None
228 """A list of Django choices used for the ``redirect_to`` dropdown of the ``ProfileModel``."""
230 REMEMBER_ME_ENABLED = False
231 """Indicates whether "remember me" is presented on the login form."""
233 REMEMBER_ME_SECONDS = 30 * 24 * 60 * 60
234 """The number of seconds (int) a user's session should last when the remember me option is selected. Defaults to 30
235 days.
236 """
238 SSO_SERVICE_URL = None
239 """This is the service URL sent to the provider. The provider may need to be configured to accept this URL. When
240 ``DEBUG`` is ``True``, it defaults to the development URL. Otherwise an ``ImproperlyConfigured`` is raised if this
241 value is not defined.
242 """
244 SSO_LINK_USER = False
245 """When using the ``multisso`` app, this provides the option of connecting the user account with the record of the
246 SSO provider.
247 """
249 IMPERSONATION_ENABLED_FOR_GROUPS = None
250 """Indicates user impersonation is available to users belonging to any of the group names in the list."""
252 IMPERSONATION_ENABLED_FOR_STAFF = True
253 """Indicates user impersonation is available to ``is_staff`` users."""
255 IMPERSONATION_MODEL = None
256 """The model used to log impersonation history."""
258 INVITATION_EXPIRATION = 10 * 24 * 60 * 60
259 """The number of days before a user invitation expires."""
261 INVITATION_LIMIT = None
262 """The number of invitations that a user may send."""
264 INVITATION_MODEL = None
265 """The model to use for user invitations."""
267 INVITATIONS_ENABLED = False
268 """Indicates whether users are allowed to invite other users."""
270 INVITATION_GROUPS = None
271 """A list of groups (names) into which a user will be placed upon accepting an invitation."""
273 PROFILE_MODEL = None
274 """The model used for user profile in ``app_label.ModelName`` format."""
276 REGISTRATION_AFTER_URL = None
277 """The URL to which a visitor will be directed after submitting a registration request.has been created. The default
278 is the ``RegistrationSubmitted`` view.
279 """
281 REGISTRATION_ALLOWED_DOMAINS = None
282 """A list of the email domains that are recognized (allowed) for self-registration."""
284 REGISTRATION_APPROVAL_HOURS = 48
285 """The average number of hours (int) needed to manually approve registrations when approval is required. This may be
286 displayed to users after sign-up.
287 """
289 REGISTRATION_APPROVAL_REQUIRED = False
290 """Indicates whether new registrations require admin approval."""
292 REGISTRATION_AUTO_LOGIN = True
293 """Indicates a user should be logged in upon a successful (completed) registration."""
295 REGISTRATION_BEFORE_URL = None
296 """The URL to which a visitor will be directed before a registration may be requested. For example, this could be
297 used to direct the user to a Terms and Conditions page. The page should include a link to the ``RegistrationCreate``
298 view that includes ``reg=1`` in the URL.
299 """
301 REGISTRATION_BODY = None
302 """The body of the email message sent to visitors upon new user account registration. If omitted, the standard
303 template is used.
304 """
306 REGISTRATION_CONFIRMATION_BODY = None
307 """The body of the email message sent to visitors upon new user account registration. If omitted, the standard
308 template is used.
309 """
311 REGISTRATION_CONFIRMATION_REQUIRED = True
312 """Indicates whether new user registrations require user confirmation. This invokes the Confirmation Workflow."""
314 REGISTRATION_CONFIRMATION_SUBJECT_LINE = None
315 """The subject line of the email message sent to visitors upon new user account registration. If omitted, the
316 standard template is used.
317 """
319 REGISTRATION_DECLINED_BODY = None
320 """The body of the email message sent when a registration is declined. ``REGISTRATION_APPROVAL_REQUIRED`` must
321 be ``True``. If omitted, the default template is used.
322 """
324 REGISTRATION_DECLINED_SUBJECT = None
325 """the subject line of the declined registration email. If omitted, the default template is used."""
327 REGISTRATION_DISABLED_MESSAGE =None
328 """The message to display when registration is currently disabled."""
330 REGISTRATION_DISABLED_URL = "/"
331 """The URL to which a visitor will be directed upon attempting to register an account when registration is
332 currently disabled. This defaults to the ``RegistrationDisabled`` view if enabled.
333 """
335 REGISTRATION_ENABLED = False
336 """Allows visitors to sign up for user accounts."""
338 REGISTRATION_EXPIRES_AFTER_DAYS = 7
339 """The number of days (int) a registration remains valid after it is sent."""
341 REGISTRATION_FORM = None
342 """The form to use for user registrations."""
344 REGISTRATION_GROUPS = None
345 """A list of group names to which the user should be assigned upon successful (completed) registration."""
347 REGISTRATION_MODEL = None
348 """The model (in the form of ``app_label.ModelName``) to use when registration approvals are required."""
350 REGISTRATION_OPEN_DATE = None
351 """The date upon which user registration will again be allowed."""
353 REGISTRATION_OPEN_URL = None
354 """The URL where a user may be notified (or request notification) when registration is available. This might be a
355 page or a sign-up form.
356 """
358 REGISTRATION_REDIRECT_URL = None
359 """the URL to which a new user will directed after confirming a registration. The default is the
360 ``RegistrationComplete`` view."""
362 REGISTRATION_SALT = "registration"
363 """The salt to use for creating activation keys."""
365 REGISTRATION_SUBJECT_LINE = None
366 """The subject line of the email message sent to visitors upon new user account registration. If omitted, the
367 standard template is used.
368 """
370 class Meta:
371 prefix = "superdjango_user"
374class DynamicSettingsWrapper(object):
375 """Facilitates the acquisition of settings dynamically, by wrapping ``settings.py``.
377 This class is automatically instantiated as ``SUPERDJANGO``, which makes the following example possible:
379 .. code-block:: python
381 from superdjango.conf import SUPERDJANGO
383 class Login(LoginView):
384 def get_form_class(self):
385 if SUPERDJANGO.USER_REMEMBER_ME_ENABLED:
386 return AuthenticationForm
388 return DefaultAuthenticationForm
390 Under the hood, ``SUPERDJANGO.USER_REMEMBER_ME_ENABLED`` is simply understood as
391 ``getattr(settings, "SUPERDJANGO_USER_REMEMBER_ME_ENABLED")``.
393 .. note::
394 This is either really clever or really stupid.
396 """
398 def __getattr__(self, item):
399 item = "SUPERDJANGO_%s" % item.upper()
400 return getattr(settings, item, None)
402 # noinspection PyMethodMayBeStatic
403 def get(self, name, default=None, prefix="SUPERDJANGO"):
404 """Get the named value from ``settings.py``.
406 :param name: The name of the setting.
407 :type name: str
409 :param default: The default value.
411 :param prefix: The prefix to apply to the name of the setting.
412 :type prefix: str
414 """
415 if prefix:
416 name = "%s_%s" % (prefix, name)
418 name = name.upper()
420 return getattr(settings, name, default)
422 # noinspection PyMethodMayBeStatic
423 def has(self, name, prefix="SUPERDJANGO"):
424 """Indicates whether the named value exists ``settings.py`` *and* has a value.
426 :param name: The name of the setting.
427 :type name: str
429 :param prefix: The prefix to apply to the name of the setting.
430 :type prefix: str
432 """
433 if prefix:
434 name = "%s_%s" % (prefix, name)
436 name = name.upper()
438 if hasattr(settings, name) and getattr(settings, name) is not None:
439 return True
441 return False
444SUPERDJANGO = DynamicSettingsWrapper()