users : user management

This document describes the API of the lino.modlib.users plugin. See also User management à la Lino for getting started with user management. See Lino has its own user management if you wonder why Lino replaces Django's user management and permission system.

A tested document

This is a tested document. The following instructions are used for initialization:

>>> from lino import startup
>>> startup('lino_book.projects.min1.settings.doctests')
>>> from lino.api.doctest import *

Which means that code examples in this document use the lino_book.projects.min1 demo project.

Models

class lino.modlib.users.User

Represents a user of this site.

authenticated

This is always True. Compare with AnonymousUser.authenticated.

Fields:

username

Must be unique and cannot be empty.

initials

The nickname or initials of this user. This does not need to be unique but should provide a reasonably identifying function.

user_type

The user_type of a user is what defines her or his permissions.

Users with an empty user_type field are considered inactive and cannot log in.

See also Permissions.

partner

Pointer to the Partner instance related to this user.

Every user account can optionally point to a partner instance which holds extended contact information. One partner can have more than one user accounts.

This is a DummyField when lino_xl.lib.contacts is not installed or when User is a subclass of Partner .

person

A virtual read-only field which returns the Person MTI child of the partner (if it exists) and otherwise None.

last_login

Not used in Lino.

__str__(self)

Returns either the initials or get_full_name().

get_full_name(self)

Return the first_name plus the last_name, with a space in between. If both fields are empty, return the initials or the username.

def get_row_permission(self, ar, state, ba)

Only system managers may edit other users. See also disabled_fields().

One exception is when AnonymousUser is not readonly. This means that we want to enable online registration. In this case everybody can modify an unsaved user.

end_date
start_date

The site administrator can optionally specify a date when a user started or stopped to be active.

If start_date is given, then the user cannot sign in before that date. If end_date is given, then the user cannot sign in after that date.

These fields are used for userstats: User statistics.

class lino.modlib.users.Authority

An authority is when a user gives another user the right to "represent" them.

user

The user who gives the right of representation. author of this authority

authorized

The user who gets the right to represent the author

Tables

class lino.modlib.users.Users

Base class for all user tables.

class lino.modlib.users.AllUsers

Shows the list of all users on this site.

class lino.modlib.users.UsersOverview

A variant of Users showing only active users and only some fields. This is used on demo sites in admin_main.html to display the list of available users.

User types

class lino.modlib.users.UserTypes

The list of user types available in this application.

You can see the user types available in your application via Explorer ‣ System ‣ User Types.

Every application should define at least three named user types:

anonymous
user
admin
class lino.modlib.users.UserType

Base class for all user types.

role

The role of users having this type. This is an instance of <lino.core.roles.UserRole> or some subclass thereof.

readonly

Whether users of this type get only write-proteced access.

hidden_languages

A subset of languages which should be hidden for users of this type. Default value is hidden_languages. This is used on multilingual sites with more than 4 or 5 languages.

context(self)

Return a context manager so you can write code to be run with this as the current user type:

with UserTypes.admin.context():
    # some code

User roles and their usage

class lino.modlib.users.UserRoles

This virtual table shows a list of user roles used in this application and which user type has them.

>>> rt.show(users.UserRoles)
... 
======================== ===== ===== =====
 Name                     000   100   900
------------------------ ----- ----- -----
 cal.GuestOperator              ☑     ☑
 comments.CommentsStaff               ☑
 comments.CommentsUser          ☑     ☑
 contacts.ContactsStaff               ☑
 contacts.ContactsUser          ☑     ☑
 excerpts.ExcerptsStaff               ☑
 excerpts.ExcerptsUser          ☑     ☑
 notes.NotesStaff                     ☑
 notes.NotesUser                ☑     ☑
 office.OfficeStaff                   ☑
 office.OfficeUser              ☑     ☑
 polls.PollsAdmin                     ☑
 polls.PollsUser                ☑     ☑
======================== ===== ===== =====

Note that this table does not show UserRole subclasses which have been defined in within the user_types_module itself since these are just another hierarchy level, they are not used in any roles_required and therefore not useful for describing which permissions are given to which user type.

The current user type

This is used by lino.utils.jsgen, i.e. when generating the linoweb.js file for a given user type.

Plugin configuration

class lino.modlib.users.Plugin

See Introduction to plugins.

online_registration

Whether this site offers online registration of new users.

Roles

class lino.modlib.users.Helper

Somebody who can help others by running AssignToMe action.

class lino.modlib.users.AuthorshipTaker

Somebody who can help others by running TakeAuthorship action.

Actions

class lino.modlib.users.SendWelcomeMail

Send a welcome mail to this user.

class lino.modlib.users.ChangePassword

Change the password of this user.

current

The current password. Leave empty if the user has no password yet. And SiteAdmin users don't need to specify this at all.

new1

The new password.

new2

The new password a second time. Both passwords must match.

class lino.modlib.users.SignIn

Open a window which asks for username and password and which authenticates as this user when submitted.

class lino.modlib.users.SignOut

Sign out the current user and return to the welcome screen for anonymous visitors.

Mixins

class lino.modlib.users.Authored
manager_roles_required

The list of required roles for getting permission to edit other users' work.

By default, only SiteStaff users can edit other users' work.

An application can set manager_roles_required to some other user role class or a tuple of such classes.

Setting manager_roles_required to [] will disable this behaviour (i.e. everybody can edit the work of other users).

This is going to be passed to has_required_roles of the requesting user's profile.

Usage examples see lino_xl.lib.notes.models.Note or lino_xl.lib.cal.models.Component.

author_field_name

No longer used. The name of the field that defines the author of this object.

class lino.modlib.users.UserAuthored

Inherits from Authored.

Mixin for models that have a user field which points to the "author" of this object. The default user of new instances is automatically set to the requesting user.

user

The author of this object. A pointer to lino.modlib.users.models.User.

class lino.modlib.users.StartPlan
update_after_start

Whether to run Plan.update_plan() after starting the plan.

class lino.modlib.users.UserPlan

Mixin for anything that represents a "plan" of a given user on a given day.

What a "plan" means, depends on the inheriting child. Usage examples are an invoicing plan (lino_xl.lib.invoicing.Plan) or an accounting report ():class:lino_xl.ledger.Report).

The mixin makes sure that there is only one database instance per user. A plan is considered a low value database object to be reused frequently.

Inherits from UserAuthored.

user

The user who owns and uses this plan.

today

This date of this plan. This is automatically set to today each time the plan is called or updated.

update_plan_button
run_start_plan(self, user)

Return the database object for this plan and user. or create

update_plan(self, ar)

Implementing models should provide this method.

class lino.modlib.users.UpdatePlan

Build a new list of suggestions. This will remove all current suggestions.

doctests

Verify whether the help_text of the change_password action is set:

>>> ba = rt.models.users.Users.get_action_by_name('change_password')
>>> print(ba.action.help_text)
Change the password of this user.