Onegov User API¶
Models¶
-
class
onegov.user.models.
User
(**kwargs)[source]¶ Defines a generic user.
-
type
¶ the type of the item, this can be used to create custom polymorphic subclasses of this class. See http://docs.sqlalchemy.org/en/improve_toc/ orm/extensions/declarative/inheritance.html.
-
property
es_suggestion
¶ Returns suggest-as-you-type value of the document. The field used for this property should also be indexed, or the suggestion will lead to nowhere.
If a single string is returned, the completion input equals the completion output. (My Title -> My Title)
If an array of strings is returned, all values are possible inputs and the first value is the output. (My Title/Title My -> My Title)
-
id
¶ the user id is a uuid because that’s more secure (no id guessing)
-
username
¶ the username may be any string, but will usually be an email address
-
password_hash
¶ the password is stored with the hashing algorithm defined by onegov.core
-
role
¶ the role is relevant for security in onegov.core
-
group_id
¶ the group this user belongs to
-
realname
¶ the real name of the user for display (use the
name
property to automatically get the name or the username)
-
data
¶ extra data that may be stored with this user, the format and content of this data is defined by the consumer of onegov.user by default, this data is only loaded by request, so if you need to load a lot of data columns, do something like this:
session.query(User).options(undefer("data"))
-
second_factor
¶ two-factor authentication schemes are enabled with this property if no two-factor auth is used, the value is NULL, if one is used, there should be a dictionary with the type of the two-factor authentication as well as custom values required by the two-factor implementation.
e.g.:
{ 'type': 'yubikey', 'data': 'ccccccbcgujh' }
Note that ‘data’ could also be a nested dictionary!
-
source
¶ A user can technically come from changing providers - the source refers to the last provider he used.
-
source_id
¶ A string describing the user id on the source, which is an id that is supposed never change (unlike the username, which may change).
If set, the source_id is unique per source.
-
active
¶ true if the user is active
-
signup_token
¶ the signup token used by the user
-
title
¶ Returns the realname or the username of the user, depending on what’s available first.
-
password
¶ An alias for
password_hash
.
-
is_matching_password
(password)[source]¶ Returns True if the given password (cleartext) matches the stored password hash.
-
classmethod
get_initials
(username, realname=None)[source]¶ Takes the name and returns initials which are at most two characters wide.
Examples:
admin => A nathan.drake@example.org => ND Victor Sullivan => VS Charles Montgomery Burns => CB
-
property
yubikey_serial
¶ Returns the yubikey serial of the yubikey associated with this user (if any).
-
sessions
= None¶ sessions of this user
tags of this user
-
phone_number
= None¶ the phone number of this user
-
-
class
onegov.user.models.
UserGroup
(**kwargs)[source]¶ Defines a generic user group.
-
type
¶ the type of the item, this can be used to create custom polymorphic subclasses of this class. See http://docs.sqlalchemy.org/en/improve_toc/ orm/extensions/declarative/inheritance.html.
-
id
¶ the id of the user group
-
name
¶ the name of this group
-
Collections¶
-
class
onegov.user.collections.
UserGroupCollection
(session, type='*')[source]¶ Manages a list of user groups.
Use it like this:
from onegov.user import UserGroupCollection groups = UserGroupCollection(session)
-
class
onegov.user.collections.
UserCollection
(session, **filters)[source]¶ Manages a list of users.
Use it like this:
from onegov.user import UserCollection users = UserCollection(session)
-
query
()[source]¶ Returns a query using
onegov.user.models.User
. With the current filters applied.
-
add
(username, password, role, data=None, second_factor=None, active=True, realname=None, signup_token=None, group=None)[source]¶ Add a user to the collection.
The arguments given to this function are the attributes of the
User
class with the same name.
All available tags.
-
property
usernames
¶ All available usernames.
All usernames where the user’s tags match at least one tag from the given list.
-
exists
(username)[source]¶ Returns True if the given username exists.
This function does not actually load a user, so it is the quickest way to find out if a user exists. It should be used if you don’t care about finding out anything about the user.
-
by_id
(id)[source]¶ Returns the user by the internal id.
Use this if you need to refer to a user by path. Usernames are not the correct way, since they allow for user enumeration.
-
by_username_and_password
(username, password)[source]¶ Returns the user by username and password.
Note that although the password can be empty on the user, this function will not query for empty passwords as an added security measure.
Apart from that everything is fair game though, as it is not the job of onegov.user to enforce a password policy.
-
register
(username, password, request, role='member', signup_token=None)[source]¶ Registers a new user.
The so created user needs to activated with a token before it becomes active. Use the activation_token in the data dictionary together with the
activate_with_token()
function.You probably want to use the provided
RegistrationForm
in conjunction withAuth
as it includes a lot of extras like signup links and robots protection.
-
activate_with_token
(username, token)[source]¶ Activates the user if the given token matches the verification token stored in the data dictionary.
-
by_yubikey
(token, active_only=True)[source]¶ Returns the user with the given yubikey token.
Only considers active users by default.
-
delete
(username)[source]¶ Deletes the user if it exists.
If the user does not exist, an
onegov.user.errors.UnknownUserError
is raised.
-
Commandline Interface¶
Provides commands used to manage users.
Examples:
To add a user called admin@example.org
to the towns-govikon
schema,
with the role ‘admin’:
dsn=postgres://user:password@localhost:5432/database
schema=towns-govikon
onegov-user --dsn $dsn --schema $schema add admin admin@example.org
This command will ask for a password if none was provided with --password
.
To delete a user:
dsn=postgres://user:password@localhost:5432/database
schema=towns-govikon
onegov-user --dsn $dsn --schema $schema delete admin@example.org
To check if a user exists:
dsn=postgres://user:password@localhost:5432/database
schema=towns-govikon
onegov-user --dsn $dsn --schema $schema exists admin@example.org
To change a users password:
dsn=postgres://user:password@localhost:5432/database
schema=towns-govikon
onegov-user --dsn $dsn --schema $schema change-password admin@example.org
This command will also ask for a password if none was provided with
--password
.
Forms¶
-
class
onegov.user.forms.
UserGroupForm
(*args, **kwargs)[source]¶ A generic user group form for onegov.user
-
class
onegov.user.forms.
LoginForm
(*args, **kwargs)[source]¶ A generic login form for onegov.user
-
property
login_data
¶ Returns the data required to be passed to the
onegov.user.auth.Auth
methods.
-
property
-
class
onegov.user.forms.
RegistrationForm
(*args, **kwargs)[source]¶ A generic registration form for onegov.user
-
class
onegov.user.forms.
PasswordResetForm
(*args, **kwargs)[source]¶ A generic password reset form for onegov.user.
Errors¶
-
exception
onegov.user.errors.
OnegovUserError
(message)[source]¶ Base class for all errors raised by onegov.user.
-
exception
onegov.user.errors.
InvalidActivationTokenError
(message)[source]¶ Raised when the given activation token doesn’t match.
-
exception
onegov.user.errors.
ExistingUserError
(message)[source]¶ Raised when a new user already exists.
-
exception
onegov.user.errors.
AlreadyActivatedError
(message)[source]¶ Raised when a user was already activated.