allura.app

class allura.app.AdminControllerMixin

Provides common functionality admin controllers need

class allura.app.Application(project, app_config_object)

The base Allura pluggable application

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

[allura]
myapp = foo.bar.baz:MyAppClass
Variables:
  • status (str) – One of ‘production’, ‘beta’, ‘alpha’, or ‘user’. By default, only ‘production’ apps are installable in projects. Default is ‘production’.
  • searchable (bool) – If True, show search box in the left menu of this Application. Default is True.
  • exportable (bool) – Default is False, Application can’t be exported to json.
  • permissions (list) – Named permissions used by instances of this Application. Default is [].
  • permissions_desc (dict) – Descriptions of the named permissions.
  • max_instances (int) – Specifies the number of tools of this type that can be added to the project. Zero indicates the system tool or one that can not be added to the project by the user. Default value is float(“inf”).
  • hidden (bool) – Default is False, Application is not hidden from the list of a project’s installed tools.
  • has_notifications (bool) – Default is True, if set to False then application will not be listed on user subscriptions table.
  • tool_description (str) – Text description of this Application.
  • relaxed_mount_points (bool) – Set to True to relax the default mount point naming restrictions for this Application. Default is False. See default mount point naming rules and relaxed mount point naming rules.
  • root (Controller) – Serves content at /<neighborhood>/<project>/<app>/. Default is None - subclasses should override.
  • api_root (Controller) – Serves API access at /rest/<neighborhood>/<project>/<app>/. Default is None - subclasses should override to expose API access to the Application.
  • admin_api_root (Controller) – Serves Admin API access at /rest/<neighborhood>/<project>/admin/<app>/. Default is None - subclasses should override to expose Admin API access to the Application.
  • admin (Controller) – Serves admin functions at /<neighborhood>/<project>/<admin>/<app>/. Default is a DefaultAdminController instance.
  • icons (dict) – Mapping of icon sizes to application-specific icon paths.
  • config_on_install (list) – ConfigOption names that should be configured by user during app installation
acl

Return the Access Control List for this Application.

admin_menu(force_options=False)

Return the admin menu for this Application.

Default implementation will return a menu with up to 4 links:

  • ‘Permissions’, if the current user has admin access to the

    project in which this Application is installed

  • ‘Options’, if this Application has custom options, or

    force_options is True

  • ‘Rename’, for editing this Application’s label

  • ‘Webhooks’, if this Application can trigger any webhooks

Subclasses should override this method to provide additional admin menu items.

Parameters:force_options – always include an ‘Options’ link in the menu, even if this Application has no custom options
Returns:a list of SitemapEntries
bulk_export(f, export_path='', with_attachments=False)

Export all artifacts in the tool into json file.

Parameters:f – File Object to write to

Set exportable to True for applications implementing this.

classmethod default_options()

Return a (name, default value) mapping of this Application’s config_options.

Return type:dict
classmethod describe_permission(permission)

Return help text describing what features permission controls.

Subclasses should define permissions_desc, a {permission: description} mapping.

Returns empty string if there is no description for permission.

doap(parent)

App’s representation for DOAP API.

Parameters:parent (xml.etree.ElementTree.Element or xml.etree.ElementTree.SubElement) – Element to contain the results
email_address

Return email address for this Application.

Email address constructed from Application’s url, and looks like this:

where 'wiki@test.p‘ comes from app url (in this case /p/test/wiki/) and ‘.in.domain.net’ comes from ‘forgemail.domain’ config entry.

Assumes self.url returns a url path without domain, starting with ‘/’

handle_artifact_message(artifact, message)

Handle message addressed to this Application.

Parameters:

Default implementation posts the message to the appropriate discussion thread for the artifact.

handle_message(topic, message)

Handle incoming email msgs addressed to this tool. Default is a no-op.

Parameters:
  • topic (str) – portion of destination email address preceeding the ‘@’
  • message (dict - result of allura.lib.mail_util.parse_message()) – parsed email message
Return type:

None

has_access(user, topic)

Return True if user can send email to topic. Default is False.

Parameters:
  • userallura.model.User instance
  • topic – str
Return type:

bool

classmethod has_resource(resource_path)

Determine whether this Application has the resource pointed to by resource_path.

If the resource is not found for the immediate class, its parents will be searched. The return value is the class that “owns” the resource, or None if the resource is not found.

classmethod icon_url(size)

Return URL for icon of the given size.

Subclasses can define their own icons by overriding icons.

install(project)

Whatever logic is required to initially set up a tool

installable

Checks whether to add a tool to the project.

Return True if app can be installed.

Return type:bool
is_visible_to(user)

Return True if user can view this app.

Return type:bool
main_menu()

Return a list of SitemapEntries to display in the main project nav for this Application.

Default implementation returns sitemap without any children.

classmethod options_on_install()

Return a list of config_options which should be configured by user during app installation.

Return type:list
parent_security_context()

Return the parent of this object.

Used for calculating permissions based on trees of ACLs.

sidebar_menu()

Return a list of SitemapEntries to render in the left sidebar for this Application.

sidebar_menu_js()

Return Javascript needed by the sidebar menu of this Application.

Returns:a string of Javascript code
classmethod status_int()

Return the status of this Application as an int.

Used for sorting available Apps by status in the Admin interface.

subscribe(user)

Subscribe user to the allura.model.notification.Mailbox for this Application.

subscribe_admins()

Subscribe all project Admins (for this Application’s project) to the allura.model.notification.Mailbox for this Application.

uninstall(project=None, project_id=None)

Whatever logic is required to tear down a tool

uninstallable

Return True if this app can be uninstalled. Controls whether the ‘Delete’ option appears on the admin menu for this app.

By default, an app can be uninstalled iff it can be installed, although some apps may want/need to override this (e.g. an app which can not be installed directly by a user, but may be uninstalled).

classmethod validate_mount_point(mount_point)

Check if mount_point is valid for this Application.

In general, subclasses should not override this, but rather toggle the strictness of allowed mount point names by toggling Application.relaxed_mount_points.

Parameters:mount_point (str) – the mount point to validate
Return type:A regex Match object if the mount point is valid, else None
class allura.app.ConfigOption(name, ming_type, default, label=None, help_text=None, validator=None, extra_attrs=None)

Definition of a configuration option for an Application.

default

Return the default value for this ConfigOption.

render_attrs()

Return extra_attrs formatted in a way that allows inserting into html tag

class allura.app.DefaultAdminController(app)

Provides basic admin functionality for an Application.

To add more admin functionality for your Application, extend this class and then assign an instance of it to the admin attr of your Application:

class MyApp(Application):
    def __init__(self, *args):
        super(MyApp, self).__init__(*args)
        self.admin = MyAdminController(self)
configure(**kw)

Handle POST to delete the Application or update its config.options.

edit_label()

Renders form to update the Application’s mount_label.

index(**kw)

Home page for this controller.

Redirects to the ‘permissions’ page by default.

options()

Renders form to update the Application’s config.options.

permissions()

Render the permissions management web page.

update(card=None, **kw)

Handle POST to update permissions for the Application.

update_label(mount_label)

Handles POST to update the Application’s mount_label.

class allura.app.SitemapEntry(label, url=None, children=None, className=None, ui_icon=None, small=None, tool_name=None, matching_urls=None, extra_html_attrs=None)

A labeled URL, which may optionally have children.

Used for generating trees of links.

bind_app(app)

Recreate this SitemapEntry in the context of app.

Returns:SitemapEntry
extend(sitemap_entries)

Extend our children with sitemap_entries.

Parameters:sitemap_entries – list of SitemapEntry

For each entry, if it doesn’t already exist in our children, add it. If it does already exist in our children, recursively extend the children or our copy with the children of the new copy.

matches_url(request)

Return True if this SitemapEntry ‘matches’ the url of request.