Lino and your Django settings¶
This section explains some basic things about your Django settings and Lino. See also Modifying your local settings.py.
Django settings module¶
The Django settings module is the most important thing in Django. Almost everything you do with Django requires the settings module to be loaded. Django does that automagically as soon as you import some module which needs the settings. And when that moment arrives, Django needs to know the name of your settings module.
You can specify this either using the
environment variable or the --settings command-line option of
certain admin commands.
To illustrate this, let's open a Python session in an environment with
Django installed but without any
environment variable defined, and then type:
>>> from django.conf import settings
This will pass. But as soon as you want to actually access some attribute of
settings, you will get an ImproperlyConfigured exception:
>>> print(settings.DEBUG) Traceback (most recent call last): ... django.core.exceptions.ImproperlyConfigured: Requested setting DEBUG, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
The Django settings module must be importable. That is, if
DJANGO_SETTINGS_MODULE contains e.g.
Django will do the equivalent of
When we speak about "the
settings.py file", then we actually
mean the Django settings module. That's because the filename of a
Django settings module is often in a file named
But in reality it can be some arbitrary filename. For example the
lino_book.projects.min1.settings.demo. This layout is called a
settings package, it is useful when you want to have different
variants of settings modules.
How Lino integrates into Django settings¶
Here is a typical
settings.py file of a Lino project:
from foo.bar.settings import * SITE = Site(globals()) # ... your local settings here
That is, you import the content of some existing Lino project into
your local settings module and then define a
settings.py file always contains the following line:
SITE = Site(globals())
SITE setting is what turns your Django project into a
More about this in Introducing the Site class.
You might surprise to see the following contruct:
from foo.bar.settings import * class Site(Site): title = "My title" SITE = Site(globals())
We are just using a feature of the Python language which allows us to define a new class based on an existing class and having the same name as its parent.
settings.py files are small¶
Lino helps you to keep
settings.py files small because it delegates the
responsibility of maintaining default values for Django settings to the
settings.py file for a Lino site consists of a few lines
(plus, on a production site, the lines for defining your
setting). Compare this to a
settings.py file generated by Django's
startproject command which contains 120 lines of text (Django version
>>> from atelier.sheller import Sheller >>> shell = Sheller() # will run in a temporary directory >>> shell("django-admin startproject foo") >>> shell("wc -l foo/foo/settings.py") 120 foo/foo/settings.py >>> shell("django-admin --version") 2.2.7 3.0rc1
In some projects we use a whole package of settings:
settings/__init.py: the base for all modules of this package.
settings/demo.py: instantiates a
SITEvariable and thus is designed to be used directly as a
Site-wide default settings¶
Lino applications (unlike Django projects) have a hook for specifying site-wide default values for their Django settings. This concept is mostly useful on servers where many Lino sites are running (as described in Configuring site-wide default settings). Actually they are not system-wide but environment-wide.
Each time a Lino process starts (when a
gets instantiated), it checks whether an environment variable
LINO_SITE_MODULE is exists. And if it does, Lino expects it
to be the name of a Python module, will import that module and, if it
contains a function named
setup_site, will call that function,
passing it the Site instance as one and only positional parameter.
For example you can do:
$ export LINO_SITE_MODULE=my_site_options
And then create a file named
my_site_options.py somewhere on
PYTHONPATH with the following content:
def setup_site(self): self.update_settings(ADMINS=[("John", "email@example.com")]) self.update_settings(EMAIL_HOST="mail.provider.com") self.update_settings(DEBUG=True) self.update_settings(ALLOWED_HOSTS=['127.0.0.1']) self.use_java = False
Keep in mind
lino_local.py is a file containing site-wide local settings,
i.e. local settings to be applied to all projects.
The file just defines default values, individual projects can still decide to override them.
This file is usually in a directory
Lino will use these settings only if that directory is in
PYTHON_PATH and if the project defines an environment
LINO_SITE_MODULE containing the string
On servers where this was used, when upgrading to a Lino version after
20160109, you should set
LINO_SITE_MODULE to the string
djangosite_local in order to maintain the old behaviour: