The reahl.fw module implements the core of the Reahl web framework.
Basics of defining an application¶
- class reahl.web.fw.ReahlWSGIApplication(config)¶
A web application. This class should only ever be instantiated in a WSGI script, using the from_directory method.
- classmethod from_directory(directory)¶
Create a ReahlWSGIApplication given the directory where its configuration is stored.
Starts the ReahlWSGIApplication by “connecting” to the database. What “connecting” means may differ depending on the persistence mechanism in use. It could include enhancing classes for persistence, etc.
Stops the ReahlWSGIApplication by “disconnecting” from the database. What “disconnecting” means may differ depending on the persistence mechanism in use.
- class reahl.web.fw.UserInterface(parent_ui, relative_base_path, slot_map, for_bookmark, name, **ui_arguments)¶
A UserInterface holds a collection of View instances, each View with its own URL relative to the UserInterface itself. UserInterfaces can also contain other UserInterfaces.
Programmers create their own UserInterface class by inheriting from UserInterface, and overriding UserInterface.assemble() to define the contents of the UserInterface.
UserInterfaces are not instantiated by programmers, a UserInterface is defined as a sub-user_interface of a given parent UserInterface by calling the UserInterface.define_user_interface() from inside the UserInterface.assemble() method of its parent UserInterface.
The class of UserInterface to be used as root for the entire web application is configured via the web.site_root config setting.
- relative_base_path = None¶
The path where this UserInterface starts, relative to its parent UserInterface
- parent_ui = None¶
The UserInterface onto which this UserInterface is grafted
- slot_map = None¶
A dictionary mapping names of Slots as used in this
- name = None¶
A name which is unique amongst all UserInterfaces in the application
- relative_path = None¶
The path of the current Url, relative to this UserInterface
The path this UserInterface has in the current web application. It is appended to the URLs of all View s in this UserInterface.
Programmers override this method in order to define the contents of their UserInterface. This mainly means defining Views or other UserInterfaces inside the UserInterface being assembled. The default implementation of assemble is empty, so there’s no need to call the super implementation from an overriding implementation.
- define_page(widget_class, *args, **kwargs)¶
Called from assemble to create the WidgetFactory to use when the framework needs to create a Widget for use as the page for this UserInterface. Pass the class of Widget that will be constructed in widget_class. Next, pass all the arguments that should be passed to widget_class upon construction, except the first one (its view).
- define_view(relative_path, title=None, page=None, slot_definitions=None, detour=False, view_class=None, read_check=None, write_check=None, cacheable=False, **assemble_args)¶
Called from assemble to specify how a View will be created when the given URL (relative_path) is requested from this UserInterface.
- title – The title to be used for the View.
- page – A WidgetFactory that will be used as the page to be rendered for this View (if specified).
- slot_definitions – A dictionary stating which WidgetFactory to use for plugging in which Slot.
- detour – Specifies whether this View is a Detour or not.
- view_class – The class of View to be constructed (in the case of parameterised View s).
- read_check – A no-arg function returning a boolean value. It will be called to determine whether the current user is allowed to see this View or not.
- write_check – A no-arg function returning a boolean value. It will be called to determine whether the current
- cacheable – Whether this View can be cached. user is allowed to perform any actions linked to this View or not.
- assemble_args – keyword arguments that will be passed to the assemble of this View upon creation
- define_regex_view(path_regex, path_template, view_class=None, factory_method=None, read_check=None, write_check=None, **assemble_args)¶
Called from assemble to create a ViewFactory for a parameterised View that will be created when an URL is requested that matches path_regex. The arguments of the parameterised View are parsed from a matching URL using named groups in path_regex. These named arguments are again passed to the assemble of the View upon construction.
- path_regex – The regex referring to the View. It should contain a named group for each argument expected by the assemble method of the parameterised View.
- path_template – A string containing a template which can be used to construct an actual URL, given the arguments of this parameterised View. This string will be used to construct a string.Template, and should contain references to variables named for each argument expexted by the assemble method of the parameterised View.
- view_class – The class of View which is to be constructed.
- factory_method – Pass a method that will be called to create a View instead of passing view_class if you’d like.
- read_check – Same as with define_view.
- write_check – Same as with define_view.
- assemble_args – Same as with define_view.
- define_transition(event, source, target, guard=None)¶
Creates a Transition that will allow a user to be transitioned from source to target (both of type ViewFactory), upon the occurrence of an Event that matches event.
- define_return_transition(event, source, guard=None)¶
Creates a Transition that returns a user to the View the user was on before visiting a detour View.
- define_local_transition(event, source, guard=None)¶
Creates a Transition that lets the user stay on the current View.
- define_redirect(relative_path, bookmark)¶
Defines an URL that will cause the user to be redirected to the given Bookmark whenever visited.
- define_user_interface(path, ui_class, slot_map, name=None, **assemble_args)¶
Called from assemble to specify how a UserInterface will be created when the given path is visited in this UserInterface.
- path – The path for which the UserInterface will be constructed.
- ui_class – The class of UserInterface which will be constructed.
- slot_map – The current UserInterface defines contents for some Slots. The ui_class UserInterface which is effectively grafted onto the current UserInterface, also defined Slots using its own names. This dictionary states how the names used in the grafted UserInterface map to the names used by the current UserInterface.
- name – A name for the UserInterface that is grafted on. The name should be unique in an application.
- assemble_args – Keyword arguments that will be passed to the assemble method of the grafted UserInterface after construction.
- define_regex_user_interface(path_regex, path_template, ui_class, slot_map, name=None, **assemble_args)¶
Called from assemble to create a UserInterfaceFactory for a parameterised UserInterface that will be created when an URL is requested that matches path_regex. See also define_regex_view.
Arguments are similar to that of define_regex_view, except for:
- slot_map – (See define_user_interface.)
- name – (See define_user_interface.)
Defines an URL which is mapped to a directory from which files will be served directly. The URL is mapped to a similarly named subdirectory of the static root of the web application, as configured, as configured by the setting web.static_root.
- define_static_files(path, files)¶
Defines an URL which is mapped to serve the list of static files given.
- get_bookmark(description=None, relative_path=None, query_arguments=None, ajax=False)¶
Returns a Bookmark for the View present on relative_path.
- description – By default the Bookmark will use the title of the target View as its description, unless overridden by passing description.
- query_arguments – A dictionary containing arguments that should be put onto the query string of the Url of the Bookmark.
- ajax – Links to Bookmarks for which ajax=True are changed browser-side to enable ajax-related functionality. This is used by the framework and is not meant to be set by a programmer.
- class reahl.web.fw.Widget(view, read_check=None, write_check=None)¶
Any user interface element in Reahl is a Widget. A direct instance of this class will not display anything when rendered. A User interface is composed of Widgets by adding other Widgets to a Widget such as this one, forming a whole tree of Widgets.
- view – The current View.
- read_check – A no-arg callable. If it returns True, the Widget will be rendered for the current user, else not.
- write_check – A no-arg callable. If it returns True, the current user is allowed to write to this Widget. The act of writing to a Widget is defined differently for subclasses of Widget. On this high level, the Widget will also merely be displayed to the user if the user can write to the Widget.
- classmethod factory(*widget_args, **widget_kwargs)¶
Obtains a Factory for this Widget. A Factory for this Widget is merely an object that will be used by the framework to instantiate the Widget only once needed. Pass the exact arguments and keyword arguments that you would have passed to the Widget’s constructor, except the very first argument of Widgets: the view.
- children = None¶
All the Widgets that have been added as children of this Widget,
- view = None¶
The current view, as passed in at construction
- read_check = None¶
- write_check = None¶
- created_by = None¶
The factory that was used to create this Widget
- add_default_slot(slot_name, widget_factory)¶
If this Widget contains a Slot named slot_name, and no contents are available to be plugged into this Slot, the given widget_factory will be used to populate the Slot by default.
Call this method to explicitly mark this Widget as being security sensitive. It may be necessary to call this method when the automatic mechanisms for determining the security sensitivity of a Widget do not suffice.
Answers whether this Widget should be secured when communicating with the user browser.
Adds another Widget (child) as a child Widget of this one.
- insert_child(index, child)¶
Adds another Widget (child) as a child Widget of this one, at index position amongst existing children.
Adds all Widgets in children children Widgets of this one.
Returns an HTML representation of this Widget. (Not for general use, may be useful for testing.)
Answers whether this Widget should be rendered to the current user in such a way that the user will see the Widget, but not be able to interact with it.
Answers whether this Widget should be rendered to the current user at all.
The current UserInterface.
- define_event_handler(event, target=None)¶
Defines (and returns) an EventHandler that will allow an Event matching event from any View on which this Widget is placed. If given, the user will be transitioned to a View matching target (a ViewFactory) in response to the Event.
- class reahl.web.fw.WidgetFactory(widget_class, *widget_args, **widget_kwargs)¶
An object used by the framework to create a Widget, once needed.
- widget_class – The kind of Widget to be constructed.
- widget_args – All the arguments needed by widget_class except the first argument of Widgets: view
- widget_kwargs – All the keyword arguments of widget_class.
- add_default_slot(name, widget_factory)¶
Specify a widget_factory to be used to create the contents of the reahl.web.ui.Slot named name if no contents are supplied by other means for the Slot.
- class reahl.web.fw.Bookmark(base_path, relative_path, description, query_arguments=None, ajax=False, detour=False, exact=True, read_check=None, write_check=None)¶
Like a bookmark in a browser, an instance of this class is a way to refer to a View in a WebApplication that takes into account where the View is relative to the root of the URL hierarchy of the application.
Bookmark should not generally be constructed directly by a programmer, use one of the following to obtain a Bookmark:
- base_path – The entire path of the UserInterface to which the target View belongs.
- relative_path – The path of the target View, relative to its UserInterface.
- description – The textual description to be used by links to the target View.
- query_arguments – A dictionary containing name, value mappings to be put onto the query string of the href of this Bookmark.
- ajax – (not for general use).
- detour – Set this to True, to indicate that the target View is marked as being a detour (See UrlBoundView).
- exact – (not for general use).
- read_check – A no-args callable, usually the read_check of the target View. If it returns True, the current user will be allowed to see (but not click) links representing this Bookmark.
- write_check – A no-args callable, usually the write_check of the target View. If it returns True, the current user will be allowed to click links representing this Bookmark.
- classmethod for_widget(description, query_arguments=None, **bookmark_kwargs)¶
Creates a “page-internal” Bookmark for a Widget with the arguments as specified.
- description – The textual description that will be used in links created for this Bookmark.
- query_arguments – A dictionary containing the arguments the target Widget should have when a user follows a link.
- bookmark_kwargs – Keyword arguments sent as-is to the constructor of Bookmark.
Returns a new Bookmark, like this one, except that it has description for its description.
Answers whether this Bookmark is for a Widget on the current page only.
- class reahl.web.fw.EventHandler(user_interface, event, target)¶
An EventHandler is used to transition the user to the View that matches target (a ViewFactory), but only if the occurring Event matches event.
- class reahl.web.fw.Transition(controller, event, source, target, guard=None)¶
A Transition is a special kind of EventHandler. Transitions are used to define how a user is transitioned amongst many Views in response to different Events that may occur. A Transition will only be used if its source (a ViewFactory) matches the current View and if its guard (an Action) returns True. If not specified, a guard is used which always the Transition to be used.
- class reahl.web.fw.View(user_interface)¶
A View is how Reahl denotes the target of any URL. Although there are many types of View (to deal with static files, for example), the most used View is an UrlBoundView.
- class reahl.web.fw.ViewFactory(regex_path, title, slot_definitions, page_factory=None, detour=False, view_class=None, factory_method=None, read_check=None, write_check=None, cacheable=False, view_kwargs=None)¶
Used to specify to the framework how it should create a View, once needed. This class should not be instantiated directly. Programmers should use UserInterface.define_view and related methods to specify what Views a UserInterface should have. These methods return the ViewFactory so created.
In the .assemble() of a UserInterface, ViewFactories are passed around to denote Views as the targets of Events or the source and target of Transitions.
Adds the given precondition to the View that will be created by this ViewFactory. (See ViewPreCondition.)
- set_slot(name, contents)¶
Supplies a Factory (contents) for how the contents of the Slot named name should be created.
Supplies a Factory for the page to be used when displaying the View created by this ViewFactory.
- as_bookmark(user_interface, description=None, query_arguments=None, ajax=False, **url_arguments)¶
Returns a Bookmark to the View this Factory represents.
- user_interface – The user_interface where this ViewFactory is defined.
- description – A textual description which will be used on links that represent the Bookmark on the user interface.
- query_arguments – A dictionary with (name, value) pairs to put on the query string of the Bookmark.
- ajax – (not for general use)
- url_arguments – Values for the arguments of the parameterised View to which the Bookmark should lead. (Just omit these if the target View is not parameterised.)
- class reahl.web.fw.UrlBoundView(user_interface, relative_path, title, slot_definitions, page_factory=None, detour=False, read_check=None, write_check=None, cacheable=False, **view_arguments)¶
A View that is rendered to the browser when a user visits a particular URL on the site. An UrlBoundView defines how the named Slots of a page Widget should be populated for a particular URL.
A programmer should create subclasses of UrlBoundView when creating parameterised Views.
A programmer should not construct instances of this class (or its subclasses). Rather use UserInterface.define_view and related methods to define ViewFactories which the framework will use at the correct time to instantiate an UrlBoundView.
The .view of any Widget is an instance of UrlBoundView.
- title = None¶
The title of this View
This method is called (on the UrlBoundView) each time after an UrlBoundView was created for use during a single request cycle. Its main purpose is to deliver the values of the arguments of a parameterised UrlBoundView. To have a parameterised View, you have to subclass UrlBoundView and override .assemble, giving it a signature with keyword arguments that match the arguments specified when defining the View.
Inside .assemble you can change the title of the View, the contents of the Slots that will be populated by the View, or even the security check functions of the View – differently, depending on the actual argument values received by this method. You may also want to first do a database lookup, for example, based on the argument values before finalising these details of the View.
If argument values are received here that are invalid (such as the primary key of a database row which turns out not to exist), raise a CannotCreate exception to indicate that. Doing that will result in the browser receiving an HTTP 404 error.
- set_slot(name, contents)¶
Supplies a Factory (contents) for the framework to use to create the contents of the Slot named name.
Supplies a Factory for the page to be used when displaying this View.
Adds a ViewPreCondition to this UrlBoundView. The View will only be accessible if the ViewPreCondition is satisfied.
- as_bookmark(description=None, query_arguments=None, ajax=False)¶
Returns a Bookmark for this UrlBoundView.
- description – A textual description to be used by links representing this View to a user.
- query_arguments – A dictionary mapping names to values to be used for query string arguments.
- ajax – (not for general use)
- class reahl.web.fw.ParameterisedPath(discriminator, argument_fields)¶
Represents a relative path of the URL of a View which is parameterised. The first element of such a path (its discriminator) is a chosen URL. Subsequent path elements of the path are the values for the arguments of the parameterised View, embedded in the path.
- discriminator – The first element of a ParameterisedPath, used to match it against an URL in a string.
- argument_fields – A dictionary which maps argument names of the View to instances of reahl.component.modelinterface.Field that can be used to input (from an URL) or output (to an URL) the arguments of the View.
- class reahl.web.fw.RegexPath(regex, template, argument_fields)¶
Represents a relative path of the URL of a parameterised View. The path is a combination of path elements and values for arguments to the View that are embedded in the path.
- regex – If a given path string has to be matched against this RegexPath, the string regex is used as a regular expression to check for a match, and also to identify the input for the argument values embedded in the URL path. As such, the regular expression in regex should contain a group named for each parameter of the View (as named in argument_fields.
- template – A string containing a PEP-292 template which is used to form an URL, given values for all the arguments of the View. The template should contain a variable expansion for each parameter of the View (as named in argument_fields).
- argument_fields – A dictionary which maps argument names of the View to instances of reahl.component.modelinterface.Field that can be used to input (and parse) or output the argument values of the View.
- class reahl.web.fw.SubResource(unique_name)¶
A Resource that a Widget can register underneath the URL of the View the Widget is present on. This can be used to create URLs for whatever purpose the Widget may need server-side URLs for.
Parameters: unique_name – A name for this subresource which will be unique in the UserInterface where it is used.
- classmethod factory(unique_name, path_argument_fields, *args, **kwargs)¶
Returns a Factory which the framework will use, once needed, in order to create this SubResource.
- unique_name – The unique name used to construct the URL for this SubResource.
- path_argument_fields – A dictionary mapping the names of arguments to the SubResource to Fields that can be used to input or output values for these arguments.
- args – Extra arguments to be passed directly to the __init__ of the SubResource when created.
- kwargs – Extra keyword arguments to be passed directly to the __init__ of the SubResource when created.
Returns the Url that resolves to this SubResource.
- class reahl.web.fw.RemoteMethod(name, callable_object, default_result, immutable=False)¶
A server-side method that can be invoked from a browser via an URL. The method will return its result back to the browser in different ways, depending on which type of default_result it is constructed with.
- name – A unique name from which the URL of this RemoteMethod will be constructed.
- callable_object – A callable object which will receive either the raw query arguments (if immutable), or the raw POST data (if not immutable) as keyword arguments.
- immutable – Whether this method will yield the same side-effects and results when called more than once, or not. Immutable methods are accessible via GET method, non-immutable methods via POST.
- cleanup_after_exception(input_values, ex)¶
Override this method in a subclass to trigger custom behaviour after the method triggered a DomainException.
Override this method in a subclass to trigger custom behaviour after the method completed successfully.
Override this method to be able to determine (at run time) what MethodResult to use for this method. The default implementation merely uses the default_result given during construction of the RemoteMethod.
- class reahl.web.fw.CheckedRemoteMethod(name, callable_object, result, immutable=False, **parameters)¶
A RemoteMethod whose input is governed by instances of Field like input usually is.
- name – (See RemoteMethod.)
- callable_object – (See RemoteMethod.) Should expect a keyword argument for each key in parameters.
- result – (See RemoteMethod.)
- immutable – (See RemoteMethod.)
- parameters – A dictionary containing a Field for each argument name expected.
- class reahl.web.fw.EventChannel(form, controller, name)¶
A RemoteMethod used to receive Events originating from Buttons on Forms.
Programmers should not need to work with an EventChannel directly.
- class reahl.web.fw.MethodResult(catch_exception=None, content_type=u'text/html', charset=u'utf-8')¶
A RemoteMethod can be constructed to yield its results back to a browser in different ways. MethodResult is the superclass of all such different kinds of results.
- catch_exception – The class of Exeption to catch if thrown while the RemoteMethod executes.
- content_type – The content type to use when sending this MethodResult back to a browser.
- charset – The charset to use when sending this MethodResult back to a browser.
Override this in your subclass to create a webob.Response for the given return_value which was returned when calling the RemoteMethod.
Override this in your subclass to create a webob.Response for the given exception instance which happened during execution of the RemoteMethod. This method will only be called when the exception is raised, and only if you specified for it to be caught using catch_exception when this MethodResult was created.
Instead of overriding .create_response to customise how return_value will be reported, this method can be overridden instead, supplying only the body of a normal 200 Response.
Instead of overriding .create_exception_response to customise how exception will be reported, this method can be overridden instead, supplying only the body of a normal 200 Response.
- class reahl.web.fw.RedirectAfterPost(content_type=u'text/html', charset=u'utf-8')¶
A MethodResult which will cause the browser to be redirected to the Url returned by the called RemoteMethod instead of actually returning the result for display. A RedirectAfterPost is meant to be used by the EventChannel only.
- content_type –
- charset –
- class reahl.web.fw.JsonResult(result_field, **kwargs)¶
A MethodResult that can be used to let a RemoteMethod return its result to the browser in JSon format.
- result_field – A reahl.component.modelinterface.Field instance to be used for outputting the return value of the RemoteMethod as a string.
- kwargs – Other keyword arguments are sent to MethodResult, see MethodResult.
- class reahl.web.fw.WidgetResult(result_widget)¶
A MethodResult used to render a given Widget (result_widget) back to the browser in response to a RemoteMethod being invoked. The HTML rendered is only the contents of the result_widget, not its containing HTML element. WidgetResult is one way in which to re-render a server-side Widget via Ajax inside a browser without refreshing an entire page in the process.
Controlling flow via Detours and Redirects¶
- class reahl.web.fw.ViewPreCondition(condition_callable, exception=Exception())¶
A ViewPreCondition can be used to control whether a user can visit a particular View or not. If the condition_callable returns False, exception will be raised. Useful exceptions exist, like Detour and Return.
- condition_callable – A no-arg callable indicating whether this condition is satisfied (returns True) or not (returns False).
- exception – An exception to be raised if this condition is not satisfied.
- class reahl.web.fw.Redirect(target)¶
An exception that can be raised by a ViewPreCondition to send the user to a different View (matching target, a ViewFactory).
- class reahl.web.fw.Detour(target, return_to=None)¶
An exception that can be raised by a ViewPreCondition to send the user temporarily to a different View (matching target, a ViewFactory). If return_to (also a ViewFactory) is specified, and a user triggers a ReturnTransition, the user will be returned to a View matching return_to. If return_to is not specified, the user will be returned to the View for which the ViewPreCondition failed initially.
- class reahl.web.fw.Return(default)¶
An exception that can be raised by a ViewPreCondition to send the user back to a View which originally failed a PreCondition that sent the user elsewhere via a Detour.
- class reahl.web.fw.Url(url_string)¶
An Url represents an URL, and is used to modify URLs, or manipulate them in other ways. Construct it with an URL in a string.
- classmethod get_current_url(request=None)¶
Returns the Url requested by the current Request.
- scheme = None¶
- username = None¶
- password = None¶
- hostname = None¶
- port = None¶
- path = None¶
- query = None¶
- fragment = None¶
Sets the scheme part of the Url (the http or https before the :), ensuring that the port is also correct accorging to the new scheme. Ports numbers are set from web.default_http_port and web.encrypted_http_port configuration settings.
Sets the query string of this Url from a dictionary.
Returns the authority part of the URl as per RFC3968, also sometimes referred to as the netloc part in Python docs.
Answers whether this URL is absolute according to RFC3986 (ie, whether the Url includes a scheme, hostname and port).
Ensures that this URL has a scheme, hostname and port matching that of the current Request URL.
Removes the scheme, hostname and port from this URL.
Returns a new Url equal to this one, except that it does not contain a scheme, hostname or port.
Ensures that this URL starts with a string indicating the current locale (if not using the default locale).
Ensures that this URL does not include a starting path indicating locale.
Returns a new Url equal to this one, except that it does not include the starting path indicating locale.
Returns a new Url equal to this one, but with a starting path for the locale given.
- is_active_on(current_url, exact_path=False)¶
Answers whether this Url matches the current_url. If exact_path=False this Url also matches current_url if this Url is ‘underneath’ current_url in the Url hierarchy.
Answers whether this Url is currently active (see is_active_on).
Answers whether name=value pairs present in this Url’s query string is a subset of those present in other_url.
- exception reahl.web.fw.CannotCreate¶
Programmers raise this to indicate that the arguments given via URL to a View or UserInterface that is parameterised were invalid.