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

AttachmentClass

alias of DiscussionAttachment

DiscussionClass

alias of Discussion

PostClass

alias of Post

property acl

Return the Access Control List for this Application.

property activity_extras

Return a BSON-serializable dict of extra stuff to store on the activity.

property activity_name

Override this for each Artifact type.

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

default_redirect()

Redirect to url if first tool in a project. This method raises a redirect exception.

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

property 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:

  • user – allura.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

property 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

sitemap_xml()

Return a list of SitemapEntries to add to the sitemap.xml for this Application.

Default implementation returns the contents of main_menu :return:

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

property 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).

unsubscribe(user)

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

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.

property 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, mount_point=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.

class allura.app.WebhooksLookup(app)