User
Todo
Docstrings (module, models, utilities)
Models
- class indico.modules.users.models.users.NameFormat(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)
- f_last = 3
- f_last_upper = 7
- first_last = 0
- first_last_upper = 4
- last_f = 2
- last_f_upper = 6
- last_first = 1
- last_first_upper = 5
- class indico.modules.users.models.users.PersonMixin
Add convenience properties and methods to person classes.
Assumes the following attributes exist: * first_name * last_name * title
- property affiliation_details
- property display_full_name
Return the full name using the user’s preferred name format.
- property full_name
Return the person’s name in ‘Firstname Lastname’ notation.
- property full_name_affiliation
- get_full_name(*, show_title=False, last_name_first=True, last_name_upper=True, abbrev_first_name=True, _show_empty_names=False)
Return the person’s name in the specified notation.
- Parameters:
last_name_first – if “lastname, firstname” instead of “firstname lastname” should be used
last_name_upper – if the last name should be all-uppercase
abbrev_first_name – if the first name should be abbreviated to use only the first character
show_title – if the title of the person should be included
- property name
Return the person’s name in ‘Firstname Lastname’ notation.
- title
The title of the user
- class indico.modules.users.models.users.ProfilePictureSource(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)
- custom = 3
- gravatar = 2
- identicon = 1
- standard = 0
- class indico.modules.users.models.users.User(**kwargs)
Indico users.
A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
- accepted_terms_dt
the date the user has last accepted the terms of service and privacy policy
- address
the address of the user
- affiliation
the name of the affiliation (regardless if predefined or manually-entered)
- affiliation_id
the id of the underlying predefined affiliation
- affiliation_link
the predefined affiliation of the user
- all_emails
all emails of the user. read-only; use it only for searching by email! also, do not use it between modifying email or secondary_emails and a session expire/commit!
- api_key
the active API key of the user
- property as_principal
The serializable principal identifier of this user.
- property avatar_bg_color
- property avatar_url
- can_be_modified(user)
If this user can be modified by the given user.
- property can_get_all_multipass_groups
Check whether it is possible to get all multipass groups the user is in.
- created_dt
user account creation date
- email
the primary email address of the user
- property external_identities
The external identities of the user.
- favorite_categories
the users’s favorite categories
- favorite_events
the users’s favorite events
- favorite_users
the users’s favorite users
- first_name
the first name of the user
- force_user_locale()
Temporarily override the locale to the locale of the user.
- get_full_name(*args, **kwargs)
Return the person’s name in the specified notation.
- Parameters:
last_name_first – if “lastname, firstname” instead of “firstname lastname” should be used
last_name_upper – if the last name should be all-uppercase
abbrev_first_name – if the first name should be abbreviated to use only the first character
show_title – if the title of the person should be included
- get_identity(provider)
Return the first user identity which matches the given provider.
- Parameters:
provider – The id of the provider in question
- Returns:
The requested identity, or None if none is found
- get_merged_from_users_recursive()
Get the users merged into this users recursively.
- static get_system_user()
- property has_picture
- id
the unique id of the user
- property identifier
- identities
the identities used by this user
- in_event_settings_acls
- in_settings_acls
- is_admin
if the user is an administrator with unrestricted access to everything
- is_blocked
if the user has been blocked
- is_deleted
if the user is deleted (e.g. due to a merge)
- is_pending
if the user is pending (e.g. never logged in, only added to some list)
- is_system
if the user is the default system user
- iter_all_multipass_groups()
Iterate over all multipass groups the user is in.
- iter_identifiers(check_providers=False, providers=None)
Yields
(provider, identifier)
tuples for the user.- Parameters:
check_providers – If True, providers are searched for additional identifiers once all existing identifiers have been yielded.
providers – May be a set containing provider names to get only identifiers from the specified providers.
- property last_login_dt
The datetime when the user last logged in.
- last_name
the last/family name of the user
- property local_identities
The local identities of the user.
- property local_identity
The main (most recently used) local identity.
- locator
Define a smart locator property.
This behaves pretty much like a normal read-only property and the decorated function should return a dict containing the necessary data to build a URL for the object.
This decorator should usually be applied to a method named
locator
as this name is required for get_locator to find it automatically when just passing the object.If you need more than one locator, you can define it like this:
@locator_property def locator(self): return {...} @locator.other def locator(self): return {...}
The
other
locator can then be accessed by passingobj.locator.other
to the code expecting an object with a locator.
- log(realm, kind, module, summary, user=None, type_='simple', data=None, meta=None)
Create a new log entry for the user.
- Parameters:
realm – A value from
UserLogRealm
indicating the realm of the action.kind – A value from
LogKind
indicating the kind of the action that was performed.module – A human-friendly string describing the module related to the action.
summary – A one-line summary describing the logged action.
user – The user who performed the action.
type – The type of the log entry. This is used for custom rendering of the log message/data
data – JSON-serializable data specific to the log type.
meta – JSON-serializable data that won’t be displayed.
- Returns:
The newly created UserLogEntry
In most cases the
simple
log type is fine. For this type, any items from data will be shown in the detailed view of the log entry. You may either use a dict (which will be sorted) alphabetically or a list ofkey, value
pairs which will be displayed in the given order.
- make_email_primary(email)
Promote a secondary email address to the primary email address.
- Parameters:
email – an email address that is currently a secondary email
- merged_into_id
the id of the user this user has been merged into
- merged_into_user
the user this user has been merged into
- old_api_keys
the previous API keys of the user
- phone
the phone number of the user
- picture
the user profile picture
- picture_metadata
user profile picture metadata
- picture_source
user profile picture source
- principal_order = 0
- principal_type = 1
- query_personal_tokens(*, include_revoked=False)
Query the personal tokens of the user.
- Parameters:
include_revoked – whether to query revoked tokens as well
- reset_signing_secret()
- secondary_emails
any additional emails the user might have
- property secondary_local_identities
The local identities of the user except the main one.
- property settings
Return the user settings proxy for this user.
- signing_secret
a unique secret used to generate signed URLs
- suggested_categories
the user’s category suggestions
- property synced_fields
The fields of the user whose values are currently synced.
This set is always a subset of the synced fields define in synced fields of the idp in ‘indico.conf’.
- property synced_values
The values from the synced identity for the user.
Those values are not the actual user’s values and might differ if they are not set as synchronized.
- synchronize_data(refresh=False, silent=False)
Synchronize the fields of the user from the sync identity.
This will take only into account
synced_fields
.- Parameters:
refresh – bool – Whether to refresh the synced identity with the sync provider before instead of using the stored data. (Only if the sync provider supports refresh.)
silent – bool – Whether to just synchronize but not flash any messages
- class indico.modules.users.models.users.UserTitle(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)
- dr = 4
- mr = 1
- mrs = 3
- ms = 2
- mx = 6
- none = 0
- prof = 5
- indico.modules.users.models.users.format_display_full_name(user, obj)
- indico.modules.users.models.users.syncable_fields = {'address': l'address', 'affiliation': l'affiliation', 'email': l'primary email address', 'first_name': l'first name', 'last_name': l'family name', 'phone': l'phone number'}
Fields which can be synced as keys and a mapping to a more human readable version, used for flashing messages
- class indico.modules.users.models.affiliations.Affiliation(**kwargs)
A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
- alt_names
- city
- country_code
- classmethod get_or_create_from_data(affiliation_data)
- id
- is_deleted
- meta
Opaque external data related to this affiliation
- name
- postcode
- query: IndicoBaseQuery
A SQLAlchemy query for a model. Equivalent to
db.session.query(Model)
. Can be customized per-model by overridingquery_class
.Warning
The query interface is considered legacy in SQLAlchemy. Prefer using
session.execute(select())
instead.
- searchable_names
An indexed string containing all names for effective searching This string looks like
|||name|||altname|||altname2|||...|||
so a normal*foo*
query against it lets you do a substring search, and searching for|||foo|||
lets you do an exact match.
- street
- class indico.modules.users.models.emails.UserEmail(**kwargs)
A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
- email
the email address
- id
the unique id of the email address
- is_primary
if the email is the user’s primary email
- is_user_deleted
if the user is marked as deleted (e.g. due to a merge). DO NOT use this flag when actually deleting an email
- query: IndicoBaseQuery
A SQLAlchemy query for a model. Equivalent to
db.session.query(Model)
. Can be customized per-model by overridingquery_class
.Warning
The query interface is considered legacy in SQLAlchemy. Prefer using
session.execute(select())
instead.
- user_id
the id of the associated user
- class indico.modules.users.models.suggestions.SuggestedCategory(**kwargs)
A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
- category
- category_id
- is_ignored
- classmethod merge_users(target, source)
Merge the suggestions for two users.
- Parameters:
target – The target user of the merge.
source – The user that is being merged into target.
- query: IndicoBaseQuery
A SQLAlchemy query for a model. Equivalent to
db.session.query(Model)
. Can be customized per-model by overridingquery_class
.Warning
The query interface is considered legacy in SQLAlchemy. Prefer using
session.execute(select())
instead.
- score
- user_id
- class indico.modules.users.models.settings.UserSetting(**kwargs)
User-specific settings.
A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
- id
- module
- name
- user
- user_id
- value
- class indico.modules.users.models.settings.UserSettingsProxy(module, defaults=None, strict=True, acls=None, converters=None)
Proxy class to access user-specific settings for a certain module.
- delete(user, *names)
Delete settings.
- Parameters:
user –
{'user': user}
or{'user_id': id}
names – One or more names of settings to delete
- delete_all(user)
Delete all settings.
- Parameters:
user –
{'user': user}
or{'user_id': id}
- get(user, name, default=<object object>)
Retrieve the value of a single setting.
- Parameters:
user –
{'user': user}
or{'user_id': id}
name – Setting name
default – Default value in case the setting does not exist
- Returns:
The settings’s value or the default value
- get_all(user, no_defaults=False)
Retrieve all settings.
- Parameters:
user –
{'user': user}
or{'user_id': id}
no_defaults – Only return existing settings and ignore defaults.
- Returns:
Dict containing the settings
- property query
Return a query object filtering by the proxy’s module.
- set(user, name, value)
Set a single setting.
- Parameters:
user –
{'user': user}
or{'user_id': id}
name – Setting name
value – Setting value; must be JSON-serializable
- set_multi(user, items)
Set multiple settings at once.
- Parameters:
user –
{'user': user}
or{'user_id': id}
items – Dict containing the new settings
- indico.modules.users.models.settings.user_or_id(f)
Operations
- indico.modules.users.operations.create_user(email, data, identity=None, settings=None, other_emails=None, from_moderation=True)
Create a new user.
This may also convert a pending user to a proper user in case the email address matches such a user.
- Parameters:
email – The primary email address of the user.
data – The data used to populate the user.
identity – An Identity to associate with the user.
settings – A dict containing user settings.
other_emails – A set of email addresses that are also used to check for a pending user. They will also be added as secondary emails to the user.
from_moderation – Whether the user was created through the moderation process or manually by an admin.
- indico.modules.users.operations.delete_or_anonymize_user(user)
Delete or anonymize a user.
Deletes the user, and all their associated data. If it is not possible to delete the user, it will instead fallback to anonymizing the user.
Utilities
- indico.modules.users.util.anonymize_user(user)
Anonymize a user, removing all their personal data.
- indico.modules.users.util.build_user_search_query(criteria, exact=False, include_deleted=False, include_pending=False, include_blocked=False, favorites_first=False)
- indico.modules.users.util.get_admin_emails()
Get the email addresses of all Indico admins.
- indico.modules.users.util.get_avatar_url_from_name(first_name)
- indico.modules.users.util.get_color_for_user_id(user_id: int | str)
Calculate a unique color for a user based on their id.
- Parameters:
user_id – the user ID (int), or otherwise a string (external search results)
- indico.modules.users.util.get_gravatar_for_user(user, identicon, size=256, lastmod=None)
- indico.modules.users.util.get_linked_events(user, dt=None, limit=None, load_also=(), extra_options=())
Get the linked events and the user’s roles in them.
- Parameters:
user – A User
dt – Only include events taking place on/after that date
limit – Max number of events
- indico.modules.users.util.get_mastodon_server_name(url)
Query a Mastodon server for its name.
Get the related categories of a user for the dashboard.
- indico.modules.users.util.get_suggested_categories(user)
Get the suggested categories of a user for the dashboard.
- indico.modules.users.util.get_unlisted_events(user)
- indico.modules.users.util.get_user_by_email(email, create_pending=False)
Find a user based on his email address.
- Parameters:
email – The email address of the user.
create_pending – If True, this function searches for external users and creates a new pending User in case no existing user was found.
- Returns:
A
User
instance orNone
if not exactly one user was found.
- indico.modules.users.util.get_user_titles()
- indico.modules.users.util.log_user_update(user, changes, *, from_sync=False)
- indico.modules.users.util.merge_users(source, target, force=False)
Merge two users together, unifying all related data.
- Parameters:
source – source user (will be set as deleted)
target – target user (final)
- indico.modules.users.util.search_affiliations(q)
- indico.modules.users.util.search_users(exact=False, include_deleted=False, include_pending=False, include_blocked=False, external=False, allow_system_user=False, **criteria)
Search for users.
- Parameters:
exact – Indicates if only exact matches should be returned. This is MUCH faster than a non-exact saerch, especially when searching external users.
include_deleted – Indicates if also users marked as deleted should be returned.
include_pending – Indicates if also users who are still pending should be returned.
include_blocked – Indicates if also users marked as blocked should be returned.
external – Indicates if identity providers should be searched for matching users.
allow_system_user – Whether the system user may be returned in the search results.
criteria – A dict containing any of the following keys: name, first_name, last_name, email, affiliation, phone, address
- Returns:
A set of matching users. If external was set, it may contain both
IdentityInfo
objects for external users not yet in Indico andUser
objects for existing users.
- indico.modules.users.util.send_avatar(user)
- indico.modules.users.util.send_default_avatar(user: User | str | None)
Send a user’s default avatar as an SVG.
- Parameters:
user – A User object, string (external search results, registrations) or None (blank avatar)
- indico.modules.users.util.serialize_user(user)
Serialize user to JSON-like object.
- indico.modules.users.util.set_user_avatar(user, avatar, filename, lastmod=None)
- class indico.modules.users.ext.ExtraUserPreferences(user)
Define additional user preferences.
To use this class, subclass it and override defaults, fields and save to implement your custom logic.
- extend_defaults(defaults)
Add values to the FormDefaults.
- extend_form(form_class)
Create a subclass of the form containing the extra field.
- fields = {}
a dict containing all the fields that should be added to the user preferences
- classmethod is_active(user)
Return whether the preferences are available for the given user.
- load()
Return a dict with the current values for the user.
- process_form_data(data)
Process and save submitted data.
This modifies data so the core code doesn’t receive any extra data it doesn’t expect.
- save(data)
Save the updated settings.