lino.core.site¶

Defines the Site class. See Introducing the Site class and Introduction to plugins and The languages of a Lino site.

Module Attributes

LanguageInfo(django_code, name, index, suffix)

noindex:

Functions

`class2str`(cl)
`classdir`(cl)
`gettext_noop`(s)
`html2text`(html, **kwargs)
`to_locale`(language)	Simplified copy of django.utils.translation.to_locale, but we need it while the settings module is being loaded, i.e. we cannot yet import django.utils.translation.

Classes

`LanguageInfo`(django_code, name, index, suffix)	noindex:
`NOT_PROVIDED`()
`Site`([settings_globals, local_apps])	The base class for a Lino application.
`TestSite`(args, *kwargs)	Used to simplify doctest strings because it inserts default values for the two first arguments that are mandatory but not used in our examples.

class lino.core.site.LanguageInfo(django_code, name, index, suffix)¶

Bases: tuple

Noindex:

django_code¶: Alias for field number 0

index¶: Alias for field number 2

name¶: Alias for field number 1

suffix¶: Alias for field number 3

lino.core.site.to_locale(language)¶: Simplified copy of django.utils.translation.to_locale, but we need it while the settings module is being loaded, i.e. we cannot yet import django.utils.translation. Also we don't need the to_lower argument.

class lino.core.site.Site(settings_globals=None, local_apps=[], **kwargs)¶

Bases: object

The base class for a Lino application. This class is designed to be overridden by both application developers and local site administrators. Your SITE setting is expected to contain an instance of a subclass of this.

plugins¶

An AttrDict with one entry for each installed plugin, mapping the app_label of every plugin to the corresponding lino.core.plugin.Plugin instance.

This attribute is automatically filled by Lino and available as dd.plugins already before Django starts to import models.py modules.

modules¶: Old name for models. Deprecated.

models¶

An AttrDict which maps every installed app_label to the corresponding models.py module object.

This is also available as the shortcut rt.models.

See Introduction to plugins

beid_protocol¶: Until 20180926 this was a string like e.g. 'beid' in order to use a custom protocol for reading eid cards. Now it is deprecated. Use lino_xl.lib.beid.Plugin.urlhandler_prefix instead.

upload_to_tpl = 'uploads/%Y/%m'¶: The value to use as upload_to for the Upload.file field.

auto_fit_column_widths = True¶: The default value for the auto_fit_column_widths of tables in this application.

site_locale = None¶

The locale to use for certain localized things on this site.

Used by format_currency().

This should be a string of type '<language>_<country>.<encoding>', and it must have been generated previously. For example:

sudo locale-gen de_BE.utf8

kernel = None¶: This attribute is available only after startup(). See lino.core.kernel.

readonly = False¶: Setting this to True turns this site in a readonly site. This means that DATABASES must point to the DATABASES of some other (non-readonly) site, and that initdb will do nothing.

hoster_status_url = 'http://bugs.saffre-rumma.net/'¶: This is mentioned in 500.html.

description = None¶

A multi-line plain text description of up to 250 characters.

Common practice is to fill this from your SETUP_INFO.

It is listed on https://www.lino-framework.org/apps.html

device_type = 'desktop'¶

The default device type used on this server. Should be one of 'desktop', 'tablet' or 'mobile'.

This is used by DeviceTypeMiddleware.

obj2text_template = '*{0}*'¶

The format template to use when rendering a ForeignKey as plain text.

Note: reSTructuredText uses italic and bold. Changing this can cause lots of trivial failures in test suites. It is also used by lino.modlib.notify when generating the mail body.

postgres_migratable_plugin_prefixes = []¶: List of prefixes used in initdb and pm prep command for plugins other then the plugins whose name startswith lino. For example: for plugins in welfare app, put 'welfare' in the list, so it the commands will prepare the postgres database properly.

make_missing_dirs = True¶: Set this to False if you don't want Lino to automatically create missing directories when needed. If this is False, Lino will raise an exception in these cases, asking you to create it yourself.

site_dir = None¶: The directory where Lino stores local files. See Lino and local files.

project_dir = None¶: The Django project directory for this site. See Lino and local files.

media_root = None¶: The root directory at which to build the Javascript and json cache files. See Lino and local files.

project_name = None¶

A nickname for this project.

This is used only when LINO_CACHE_ROOT is set, and only to set the site_dir. In that case all Lino projects in a given repository must have a unique project name.

If this is None, Lino will find a default value by splitting project_dir and taking the last part (or the second-last if the last part is 'settings'.

django_settings = None¶: This is a reference to the globals() dictionary of your settings.py file (the one you provided when instantiating the Site object).

startup_time = None¶: The time when this Site has been instantiated, in other words the startup time of this Django process. Don't modify this.

top_level_menus = [('master', 'Master'), ('main', None), ('reports', 'Reports'), ('config', 'Configure'), ('explorer', 'Explorer'), ('site', 'Site')]¶: The list of top-level menu items. See The application menu and The XL and application menus.

ignore_model_errors = False¶: Not yet sure whether this is needed. Maybe when generating documentation.

loading_from_dump = False¶

Whether the process is currently loading data from a Python dump.

When loading from a python dump, application code should not generate certain automatic data because that data is also part of the dump.

This is normally False, but a Python dump created with pm dump2py explicitly calls install_migrations(), which sets this to True.

Application code should not change this setting except for certain special test cases.

migration_class = None¶

If you maintain a data migrator module for your application, specify its name here.

See Database Migration and/or lino.utils.dpy.install_migrations().

TODO: rename this to migrator_class

partners_app_label = 'contacts'¶: Temporary setting, see Polymorphism.

trusted_templates = False¶: Set this to True if you are sure that the users of your site won't try to misuse Jinja's capabilities.

uid = 'myuid'¶

A universal identifier for this Site. This is needed when synchronizing with CalDAV server. Locally created calendar components in remote calendars will get a UID based on this parameter, using "%s@%s" % (self.pk, settings.SITE.kernel).

The default value is 'myuid', and you should certainly override this on a production server that uses remote calendars.

project_model = None¶

Specifies the application's project model.

A project in this context means what the users consider "the central most important thing that is used to classify most other things". For example in Lino Avanti the "project" is a Client while in Lino Tera it is a therapy.

This can be either None (the default value) or the full name of the model used as "central project model" in this application.

If this is not None, all models that inherit from ProjectRelated will have an additional ForeignKey to this model.

TODO: convert this into a plugin setting of the office plugin?

user_model = None¶

The database model used for users. This is automatically set to 'users.User' when lino.modlib.users is installed.

Default value is None, meaning that this application has no user management. See also set_user_model()

See also About logging.

get_database_settings()¶

Return a dict to be set as the DATABASE setting.

The default behaviour uses SQLite (1) on a file named default.db in the site_dir if that attribute is specified, and (2) in :memory: when site_dir is None.

And alternative might be for example:

def get_database_settings(self):
    return {
        'default': {
            'ENGINE': 'django.db.backends.mysql',
            'NAME': 'test_' + self.project_name,
            'USER': 'django',
            'PASSWORD': os.environ['MYSQL_PASSWORD'],
            'HOST': 'localhost',
            'PORT': 3306,
            'OPTIONS': {
               "init_command": "SET storage_engine=MyISAM",
            }
        }
    }

run_lino_site_module()¶: See The LINO_SITE_MODULE.

load_plugins()¶

Load all plugins and build the INSTALLED_APPS setting for Django.

This includes a call to get_apps_modifiers() and get_installed_apps().

get_requirements()¶: Collect requirements from plugins. Add some more requirements which depend on options in the local settings.py file.

unused_load_actors()¶

Collect desktop.py modules.

Deprecated. We plan to remove the design_name attribute.

Note the situation when a desktop.py module exists but causes itself an ImportError because it contains a programming mistake. In that case we want the traceback to occur, not to silently do as if no desktop.py module existed.

setup_plugins()¶

Deprecated. Use get_plugin_configs() instead.

This method is called exactly once during site startup, after load_plugins() but before populating the models registry.

See Introduction to plugins.

setup_cache_directory()¶

When LINO_CACHE_ROOT is set, Lino adds a stamp file called lino_cache.txt to every project's cache directory in order to avoid duplicate use of same cache directory.

lino_cache.txt¶: A small text file with one line of text which contains the path of the project which uses this cache directory.

set_user_model(spec)¶: This can be called during the on_init of plugins which provide user management (the only plugin which does this is currently lino.modlib.users).

get_auth_method()¶

Returns the authentication method used on this site. This is one of None, 'remote' or 'session'.

It depends on the values in user_model, default_user and remote_user_header.

It influences the results of get_middleware_classes() and get_installed_apps(), and the content of AUTHENTICATION_BACKENDS.

is_hidden_app(app_label)¶: Return True if the app is known, but has been disabled using get_apps_modifiers().

update_settings(**kw)¶: This may be called from within a lino_local.py.

define_settings(**kwargs)¶

Same as update_settings(), but raises an exception if a setting already exists.

TODO: Currently this exception is deactivated. Because it doesn't work as expected. For some reason (maybe because settings is being imported twice on a devserver) it raises a false exception when override_defaults() tries to use it on MIDDLEWARE_CLASSES...

startup()¶

Start up this Site.

You probably don't want to override this method as it might be called several times. e.g. under mod_wsgi: another thread has started and not yet finished startup().

If you want to run custom code on site startup, override do_site_startup().

do_site_startup()¶

This method is called exactly once during site startup, just between the pre_startup and the post_startup signals. A hook for subclasses.

TODO: rename this to on_startup?

property logger¶: This must not be used before Django has done its logging config. For example don't use it in a settings.py module.

get_settings_subdirs(subdir_name)¶: Yield all (existing) directories named subdir_name of this Site's project directory and its inherited project directories.

makedirs_if_missing(dirname)¶: Make missing directories if they don't exist and if make_missing_dirs is True.

is_abstract_model(module_name, model_name)¶

Return True if the named model is declared as being extended by lino.core.plugin.Plugin.extends_models.

Typical usage:

class MyModel(dd.Model):
     class Meta:
         abstract = dd.is_abstract_model(__name__, 'MyModel')

See Plugin inheritance.

is_installed_model_spec(model_spec)¶: Deprecated. This feature was a bit too automagic and caused bugs to pass silently. See e.g. 2013-10-25.

is_installed(app_label)¶: Return True if INSTALLED_APPS contains an item which ends with the specified app_label.

setup_model_spec(obj, name)¶

If the value of the named attribute of obj is a string, replace it by the model specified by that string.

Example usage:

# library code:
class ThingBase(object):
    the_model = None

    def __init__(self):
        settings.SITE.setup_model_spec(self, 'the_model')

# user code:
class MyThing(ThingBase):
    the_model = "contacts.Partner"

on_each_app(methname, *args)¶

Call the named method on the models.py module of each installed app.

Note that this mechanism is deprecated. It is still used (on names like setup_workflows and setup_site) for historical reasons but will disappear one day.

for_each_app(func, *args, **kw)¶

Call the given function on each installed plugin. Successor of on_each_app().

This also loops over plugins that don't have a models module and the base plugins of plugins which extend some plugin.

demo_date(*args, **kwargs)¶

Deprecated. Should be replaced by today(). Compute a date using lino.utils.date_offset() based on the process startup time (or the_demo_date if this is set).

Used in Python fixtures and unit tests.

today(*args, **kwargs)¶

Almost the same as datetime.date.today().

One difference is that the system's today is replaced by the_demo_date if that attribute is set.

Another difference is that arguments can be passed to add some offset. See atelier.utils.date_offset().

This feature is being used in many test cases where e.g. the age of people would otherwise change.

welcome_text()¶: Return the text to display in a console window when this application starts.

using_text()¶: Return the text to display in a console window when Lino starts.

site_version()¶

Return the name of the application running on this site, including the version (if a version is specified).

Used in footnote or header of certain printed documents.

install_migrations(*args)¶: See lino.utils.dpy.install_migrations().

parse_date(s)¶: Convert a string formatted using date_format_strftime or date_format_extjs into a (y,m,d) tuple (not a datetime.date instance). See /blog/2010/1130.

parse_time(s)¶: Convert a string into a datetime.time instance using regex. only supports hours and min, not seconds.

parse_datetime(s)¶: Convert a string formatted using datetime_format_strftime or datetime_format_extjs into a datetime.datetime instance.

register_virtual_field(vf)¶: Call lino_resolve_type after startup.

setup_actions()¶: Hook for subclasses to add or modify actions.

get_used_libs(html=None)¶

Yield a list of (name, version, url) tuples describing the third-party software used on this site.

This function is used by using_text() and welcome_html().

apply_languages()¶: This function is called when a Site object gets instantiated, i.e. while Django is still loading the settings. It analyzes the languages attribute and converts it to a tuple of LanguageInfo objects.

setup_languages()¶: Reduce Django's LANGUAGES to my languages. Note that lng.name are not yet translated, we take these from django.conf.global_settings.

diagnostic_report_rst(*args)¶: Returns a string with a diagnostic report about this site. diag is a command-line shortcut to this.

is_imported_partner(obj)¶: Return whether the specified Partner instance obj is to be considered as imported from some legacy database.

site_header()¶

Used in footnote or header of certain printed documents.

The convention is to call it as follows from an appy.pod template (use the html function, not xhtml)

do text
from html(settings.SITE.site_header())

Note that this is expected to return a unicode string possibly containing valid HTML (not XHTML) tags for formatting.

get_dashboard_items(user)¶

Expected to yield a sequence of items to be rendered on the dashboard (admin_main.html).

The default implementation calls get_dashboard_items on every installed plugin and yields all items.

The items will be rendered in that order, except if lino.modlib.dashboard is installed to enable per-user customized dashboard.

property site_config¶

This property holds a cached version of the one and only SiteConfig row that holds site-wide database-stored and web-editable Site configuration parameters.

If no instance exists (which happens in a virgin database), we create it using default values from site_config_defaults.

This is always None when lino.modlib.system is not installed.

clear_site_config()¶

Clear the cached SiteConfig instance.

This is needed e.g. when the test runner has created a new test database.

property quicklinks¶

The list of quick links.

This is lazily created when first accessed.

get_quicklink_items(user_type)¶: Yield the quick links that are visible for the given user type.

get_quicklinks()¶

Return or yield a sequence of quick link descriptors to be added to the list of quick links.

Override this to define application-specific quick links.

setup_quicklinks(unused, tb)¶

Customize the list of quick links. Override this to define application-specific quick links.

Default implementation calls get_quicklinks and setup_quicklinks for each installed plugin.

The quicklinks yielded by get_quicklinks will be added before calling setup_quicklinks.

get_site_menu(user_type)¶: Return this site's main menu for the given UserType. Must be a lino.core.menus.Toolbar instance. Applications usually should not need to override this.

setup_menu(user_type, main)¶

Set up the application's menu structure.

See The application menu and The XL and application menus.

get_middleware_classes()¶

Yields the strings to be stored in the MIDDLEWARE_CLASSES setting.

In case you don't want to use this method for defining MIDDLEWARE_CLASSES, you can simply set MIDDLEWARE_CLASSES in your settings.py after the Site has been instantiated.

Django and standard HTTP authentication

get_main_html(ar, **context)¶: Return a chunk of html to be displayed in the main area of the admin index. This is being called only if get_main_action() returns None. The default implementation renders the admin_main.html template.

build_site_cache(force=False, later=False)¶

Populate the site cache, especially the lino*.js files, one per user user type and language.

force: rebuild the files even if they are up to date
later: don't rebuild now, just touch the settings.py so that they get rebuild next time.

get_welcome_messages(ar)¶: Yields a list of "welcome messages" (see lino.core.actors.Actor.get_welcome_messages()) of all actors. This is being called from admin_main.html.

add_welcome_handler(func, actor=None, msg=None)¶: Add the given callable as a "welcome handler". Lino will call every welcome handler for every incoming request, passing them a BaseRequest instance representing this request as positional argument. The callable is expected to yield a series of messages (usually either 0 or 1). Each message must be either a string or a E.span element.

copyright_name = None¶: Name of copyright holder of the site's content.

server_url = 'http://127.0.0.1:8000/'¶

The "official" URL used by "normal" users when accessing this Lino site.

This is used by templates such as summary.eml (used by lino.modlib.notify to send notification emails)

Django has a HttpRequest.build_absolute_uri() method, but e.g. notification emails are sent via linod where no HttpRequest exists. That's why we need to manually set server_url.

site_prefix = '/'¶

The string to prefix to every URL of the Lino web interface.

This must start and end with a *slash. Default value is '/'.

This must be set if your project is not being served at the "root" URL of your server.

If this is different from the default value, Lino also sets SESSION_COOKIE_PATH.

When this Site is running under something else than a development server, this setting must correspond to your web server's configuration. For example if you have:

WSGIScriptAlias /foo /home/luc/mypy/lino_sites/foo/wsgi.py

Then your settings.py should specify:

site_prefix = '/foo/'

send_email(subject, sender, body, recipients)¶: Send an email message with the specified arguments (the same signature as django.core.mail.EmailMessage.

recipients is an iterator over a list of strings with email addresses. Any address containing '@example.com' will be removed. Does nothing if the resulting list of recipients is empty.

If body starts with "<", then it is considered to be HTML.

welcome_html(ui=None)¶: Return a HTML version of the "This is APPLICATION version VERSION using ..." text. to be displayed in the About dialog, in the plain html footer, and maybe at other places.

login(username=None, **kw)¶

Open a session as the user with the given username.

For usage from a shell or a tested document. Does not require any password because when somebody has command-line access we trust that she has already authenticated.

It returns a BaseRequest object.

get_letter_date_text(today=None)¶: Returns a string like "Eupen, den 26. August 2013".

decfmt(v, places=2, **kw)¶: Format a Decimal value using lino.utils.moneyfmt(), but applying the site settings lino.Lino.decimal_group_separator and lino.Lino.decimal_separator.

format_currency(*args, **kwargs)¶

Return the given number as a string formatted according to the site_locale setting on this site.

All arguments are forwarded to locale.locale().

lookup_filter(fieldname, value, **kw)¶: Return a models.Q to be used if you want to search for a given string in any of the languages for the given babel field.

get_plugin_setting(plugin_name, option_name, *default)¶: Return the given plugin setting if the plugin is installed, otherwise the provided default value.

class lino.core.site.TestSite(*args, **kwargs)¶

Bases: Site

Used to simplify doctest strings because it inserts default values for the two first arguments that are mandatory but not used in our examples.

Example:

>> from lino.core.site import Site
>> Site(globals(), ...)

>> from lino.core.site import TestSite as Site >> Site(...)