`allura.lib.plugin`¶

Allura plugins for authentication and project registration

class allura.lib.plugin.AdminExtension¶

A base class for extending the admin areas in Allura.

After extending this, expose the app by adding an entry point in your setup.py:

[allura.admin]
myadmin = foo.bar.baz:MyCustomAdmin

Variables:: project_admin_controllers (dict) – Mapping of str (url component) to Controllers. Can be implemented as a @property function. The str url components will be mounted at /p/someproject/admin/ext/STR/ and will invoke the Controller.

update_project_sidebar_menu(sidebar_links: list['SitemapEntry']) → list['SitemapEntry']¶

Implement this function to modify the project sidebar. Check c.project if you want to limit when this displays (e.g. nbhd project, subproject, etc)

Parameters:: sidebar_links (list of allura.app.SitemapEntry) – project admin side bar links
Return type:: None

class allura.lib.plugin.AuthenticationProvider(request)¶

An interface to provide authentication services for Allura.

To use a new provider, expose an entry point in setup.py:

[allura.auth]
myprovider = foo.bar:MyAuthProvider

Then in your .ini file, set auth.method=myprovider

activate_user(user, **kw)¶: Activate user after registration

after_login(user, request)¶: This is a hook so that custom AuthenticationProviders can do things after a successful login.

by_username(username)¶

Find a user by username.

Return type:: User or None

deactivate_user(user, **kw)¶: Deactivate user (== registation not confirmed)

details_links(user)¶: Return list of pairs (url, label) with details about the user. Links will show up at admin user search page.

disable_user(user, **kw)¶: Disable user account

enable_user(user, **kw)¶: Enable user account

classmethod get(request)¶: returns the AuthenticationProvider instance for this request :rtype: AuthenticationProvider

get_last_password_updated(user)¶

Returns the date when the user updated password for a last time.

Parameters:: user – a User
Return type:: datetime

index_user(user)¶: Put here additional fields for user index in SOLR.

register_user(user_doc)¶

Register a user.

Parameters:: user_doc – a dict with ‘username’ and ‘display_name’. Optionally ‘password’ and others
Return type:: User

resend_verification_link(user, email)¶

Return type:: None

set_password(user: M.User, old_password: str | None, new_password: str, set_timestamp=True)¶

Set a user’s password.

A provider implementing this method should store the timestamp of this change when set_timestamp=True, either on user.last_password_updated or somewhere else that a custom get_last_password_updated method uses.

Also should set user.password_algorithm to the password algorithm used.

Parameters:: user – a User
Return type:: None
Raises:: HTTPUnauthorized if old_password is not valid

upload_sshkey(username, pubkey)¶

Upload an SSH Key. Providers do not necessarily need to implement this.

Return type:: None
Raises:: AssertionError with user message, upon any error

user_by_project_shortname(shortname, include_disabled=False)¶

Parameters:: str – shortname
Return type:: user: a User

user_details(user)¶

Returns detailed information about user.

Parameters:: user – a User

user_project_shortname(user)¶

Parameters:: user – a User
Return type:: str

user_project_url(user)¶

Parameters:: user – a User
Return type:: str

user_registration_date(user)¶

Returns the date in which a user registered himself/herself on the forge.

Parameters:: user – a User
Return type:: datetime

class allura.lib.plugin.ImportIdConverter¶

An interface to convert to and from import_id values for indexing, searching, or displaying.

To provide a new converter, expose an entry point in setup.py:

[allura.import_id_converter] mysource = foo.bar:SourceIdConverter

Then in your .ini file, set import_id_converter=mysource

classmethod get()¶

Return type:: ImportIdConverter

class allura.lib.plugin.LdapAuthenticationProvider(request)¶

activate_user(user, **kw)¶: Activate user after registration

by_username(username)¶

Find a user by username.

Return type:: User or None

deactivate_user(user, **kw)¶: Deactivate user (== registation not confirmed)

disable_user(user, **kw)¶: Disable user account

enable_user(user, **kw)¶: Enable user account

get_last_password_updated(user)¶

Returns the date when the user updated password for a last time.

Parameters:: user – a User
Return type:: datetime

register_user(user_doc)¶

Register a user.

Parameters:: user_doc – a dict with ‘username’ and ‘display_name’. Optionally ‘password’ and others
Return type:: User

set_password(user, old_password, new_password, set_timestamp=True)¶

Set a user’s password.

A provider implementing this method should store the timestamp of this change when set_timestamp=True, either on user.last_password_updated or somewhere else that a custom get_last_password_updated method uses.

Also should set user.password_algorithm to the password algorithm used.

Parameters:: user – a User
Return type:: None
Raises:: HTTPUnauthorized if old_password is not valid

upload_sshkey(username, pubkey)¶

Upload an SSH Key. Providers do not necessarily need to implement this.

Return type:: None
Raises:: AssertionError with user message, upon any error

user_by_project_shortname(shortname, **kwargs)¶

Parameters:: str – shortname
Return type:: user: a User

user_project_shortname(user)¶

Parameters:: user – a User
Return type:: str

user_registration_date(user)¶

Returns the date in which a user registered himself/herself on the forge.

Parameters:: user – a User
Return type:: datetime

class allura.lib.plugin.LdapUserPreferencesProvider¶

Store preferences in LDAP, falling back to LocalUserPreferencesProvider

get_pref(user, pref_name, multi=False)¶

Parameters:

user – a User
pref_name (str) –

Returns:

pref_value

Raises:

AttributeError if pref_name not found

set_pref(user, pref_name, pref_value)¶

Parameters:

user – a User
pref_name (str) –
pref_value –

class allura.lib.plugin.LocalAuthenticationProvider(request)¶

Stores user password hashes on the User model, in mongo.

activate_user(user, **kw)¶: Activate user after registration

by_username(username)¶

Find a user by username.

Return type:: User or None

deactivate_user(user, **kw)¶: Deactivate user (== registation not confirmed)

disable_user(user, **kw)¶: Disable user account

enable_user(user, **kw)¶: Enable user account

get_last_password_updated(user)¶

Returns the date when the user updated password for a last time.

Parameters:: user – a User
Return type:: datetime

register_user(user_doc)¶

Register a user.

Parameters:: user_doc – a dict with ‘username’ and ‘display_name’. Optionally ‘password’ and others
Return type:: User

set_password(user, old_password, new_password, set_timestamp=True)¶

Set a user’s password.

A provider implementing this method should store the timestamp of this change when set_timestamp=True, either on user.last_password_updated or somewhere else that a custom get_last_password_updated method uses.

Also should set user.password_algorithm to the password algorithm used.

Parameters:: user – a User
Return type:: None
Raises:: HTTPUnauthorized if old_password is not valid

user_by_project_shortname(shortname, include_disabled=False)¶

Parameters:: str – shortname
Return type:: user: a User

user_project_shortname(user)¶

Parameters:: user – a User
Return type:: str

user_project_url(user)¶

Parameters:: user – a User
Return type:: str

user_registration_date(user)¶

Returns the date in which a user registered himself/herself on the forge.

Parameters:: user – a User
Return type:: datetime

class allura.lib.plugin.LocalProjectRegistrationProvider¶

class allura.lib.plugin.LocalUserPreferencesProvider¶

The default UserPreferencesProvider, storing preferences on the User object in mongo.

get_pref(user, pref_name)¶

Parameters:

user – a User
pref_name (str) –

Returns:

pref_value

Raises:

AttributeError if pref_name not found

set_pref(user, pref_name, pref_value)¶

Parameters:

user – a User
pref_name (str) –
pref_value –

class allura.lib.plugin.ProjectRegistrationProvider¶

Project registration services for Allura. This is a full implementation and the default. Extend this class with your own if you need to add more functionality.

To use a new provider, expose an entry point in setup.py:

[allura.project_registration]
myprovider = foo.bar:MyAuthProvider

Then in your .ini file, set registration.method=myprovider

The provider should expose an attribute, shortname_validator which is an instance of a FormEncode validator that validates project shortnames. The to_python() method of the validator should accept a check_allowed argument to indicate whether additional checks beyond correctness of the name should be done, such as whether the name is already in use.

best_download_url(project)¶: This is the url needed to render a download button. It should be overridden for your specific envirnoment

details_links(project)¶: Return list of pairs (url, label) with details about the project. Links will show up at admin project search page

classmethod get()¶

Return type:: ProjectRegistrationProvider

index_project(project)¶: Put here additional fields given project should be indexed by SOLR.

phone_verified(user, neighborhood)¶

Check if user has completed phone verification.

Returns True if one of the following is true:

phone verification is disabled
param user:

has ‘admin’ access to :param neighborhood:
param user:

is has ‘admin’ access for some project, which belongs to :param neighborhood:
phone is already verified for a :param user:

Otherwise returns False.

project_from_url(url)¶

Returns a tuple (project, error).

Where project is the Project instane parsed from url or None if project can’t be parsed. In that case error will be a string describing the error.

rate_limit(user, neighborhood)¶: Check the various config-defined project registration rate limits, and if any are exceeded, raise ProjectRatelimitError.

register_project(neighborhood, shortname, project_name, user, user_project, private_project, apps=None, omit_event=False, **kwargs)¶: Register a new project in the neighborhood. The given user will become the project’s superuser.

registration_date(project) → datetime¶: Return the datetime the project was created.

validate_project(neighborhood, shortname, project_name, user, user_project, private_project)¶: Validate that a project can be registered, before it is

class allura.lib.plugin.ResponsiveTheme¶

class allura.lib.plugin.SiteAdminExtension¶

A base class for extending the site admin area in Allura.

After extending this, expose the extension by adding an entry point in your setup.py:

[allura.site_admin]
myext = foo.bar.baz:MySiteAdminExtension

Variables:: controllers (dict) – Mapping of str (url component) to Controllers. Can be implemented as a @property function. The str url components will be mounted at /nf/admin/STR/ and will invoke the Controller.

update_sidebar_menu(sidebar_links)¶

Change the site admin sidebar by modifying sidebar_links.

Parameters:: sidebar_links (list of allura.app.SitemapEntry) – site admin side bar links
Return type:: None

class allura.lib.plugin.ThemeProvider¶

Theme information for Allura. This is a full implementation and the default. Extend this class with your own if you need to add more functionality.

To use a new provider, expose an entry point in setup.py:

[allura.theme]
myprovider = foo.bar:MyThemeProvider

Then in your .ini file, set theme=mytheme

The variables referencing jinja template files can be changed to point at your own jinja templates. Use the standard templates as a reference, you should provide matching macros and block names.

For more information, see https://forge-allura.apache.org/p/allura/wiki/Themes%20in%20Allura/

Variables:: icons – a dictionary of sized icons for each tool

app_icon_url(app, size)¶: returns the default icon for the given app (or non-app thing like ‘subproject’). Takes an instance of class Application, or else a string. Expected to be overriden by derived Themes.

classmethod get()¶

Return type:: ThemeProvider

href(href, theme_name=None)¶: Build a full URL for a given resource path :param href: a path like css/site_style.css :param theme_name: defaults to current theme :return: a full URL

class allura.lib.plugin.UserPreferencesProvider¶

An interface for user preferences, like display_name and email_address

To use a new provider, expose an entry point in setup.py:

[allura.user_prefs]
myprefs = foo.bar:MyUserPrefProvider

Then in your .ini file, set user_prefs_storage.method=myprefs

add_multivalue_pref(user, pref_name, entry)¶

Parameters:

user – a User
pref_name (str) –
entry – can be a simple value, or a dict structure

Raises:

AttributeError if pref_name not found

additional_urls()¶

Returns a mapping of additional routes for AuthProvider.

By default, scans the provider for @expose()ed methods, which are added as pages with the same name as the method. Note that if you want the new pages to show up in the menu on the various auth pages, you will also need to add it to the list returned by AuthenticationProvider.account_navigation.

If you want to override this behavior, you can override this method and manually return a mapping of {page_name: handler, …}. Note, however, that this could break future subclasses of your providers’ ability to extend the list.

For example: {‘newroute’, newroute_handler} will add ‘newroute’ attribute to the auth controller, which will be set to newroute_handler. newroute_handler can either be an @expose()ed method, or a controller that can dispatch further sub-pages.

newroute_handler must be decorated with @expose(), but does not have to live on the provider.

classmethod get()¶

Return type:: UserPreferencesProvider

get_pref(user, pref_name)¶

Parameters:

user – a User
pref_name (str) –

Returns:

pref_value

Raises:

AttributeError if pref_name not found

remove_multivalue_pref(user, pref_name, entry)¶

Parameters:

user – a User
pref_name (str) –
entry – can be a simple value, or a dict structure

Raises:

AttributeError if pref_name not found

Raises:

ValueError if data not found

set_pref(user, pref_name, pref_value)¶

Parameters:

user – a User
pref_name (str) –
pref_value –

allura.lib.plugin.ldap_conn(who=None, cred=None)¶: Init & bind a connection with the given creds, or the admin creds if not specified.

allura.lib.plugin.ldap_conn_staysopen(who=None, cred=None)¶: You must call .unbind_s() when done with this

allura.lib.plugin.ldap_user_dn(username)¶: return a Distinguished Name for a given username

allura.lib.plugin¶

`allura.lib.plugin`¶