Module reahl.web.fw

The reahl.fw module implements the core of the Reahl web framework.

Run ‘reahl componentinfo reahl-web’ for configuration information.

Basics of defining an application

' Copyright 2018, 2022 Reahl Software Services (Pty) Ltd. All rights reserved.

@startuml
!include ../../../../base.iuml

title UserInterfaces, Widgets and Layouts


Layout " 0..1" --right-- "1" Widget
Widget --> "*" Widget: children

Widget <|.. HTML5Page  

HTML5Page -left- UrlBoundView: main_widget
UserInterface -right- "*" UrlBoundView



@enduml

ReahlWSGIApplication

class reahl.web.fw.ReahlWSGIApplication(config, start_on_first_request=False)

A web application. This class should only ever be instantiated in a WSGI script, using the from_directory method.

Changed in version 4.0: Renamed from ReahlApplication to ReahlWSGIApplication

classmethod from_directory(directory, strict_checking=True, start_on_first_request=False)

Create a ReahlWSGIApplication given the directory where its configuration is stored.

Parameters:
  • strict_checking – If False, exceptions will not be raised when dangerous defaulted config is present.

  • start_on_first_request – If True, the app is started when the first request is served.

Changed in version 5.0: Added strict_checking kwarg.

Changed in version 5.0: Added start_on_first_request.

start()

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.

stop()

Stops the ReahlWSGIApplication by “disconnecting” from the database. What “disconnecting” means may differ depending on the persistence mechanism in use.

UserInterface

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

The path where this UserInterface starts, relative to its parent UserInterface

parent_ui

The UserInterface onto which this UserInterface is grafted

slot_map

A dictionary mapping names of Slots as used in this

name

A name which is unique amongst all UserInterfaces in the application

relative_path

The path of the current Url, relative to this UserInterface

property current_view

The View which is targetted by the URL of the current :class:webob.Request.

property base_path

The path this UserInterface has in the current web application. It is appended to the URLs of all View s in this UserInterface.

assemble(**ui_arguments)

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, 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.

Parameters:
  • 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).

  • detour – If True, marks this View as the start of a detour (A series of Views which can return the user to where the detour was first entered from).

  • 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

..versionchanged:: 4.0

Removed slot_definitions keyword argument, rather use ViewFactory.set_slot().

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.

Parameters:
  • 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.

Parameters:
  • 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:

Parameters:
  • slot_map – (See define_user_interface.)

  • name – (See define_user_interface.)

define_static_directory(path)

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

Parameters:
  • 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.

Widget

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.

Parameters:
  • 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

All the Widgets that have been added as children of this Widget,

view

The current view, as passed in at construction

read_check
write_check
created_by

The factory that was used to create this Widget

layout

The Layout used for visual layout of this Widget

use_layout(layout)

Attaches the given Layout to this Widget. The Layout is also given a chance to customise the Widget.

Returns the original (modified) Widget for convenience.

Parameters:

layout – A Layout to be used in the construction of this Widget.

query_fields

Used to declare the arguments of this Widget on its class.

Override this class attribute to declare arguments this Widget, each described by a Field.

When constructed, the Widget uses the names and validation details of each Field to parse values for its arguments from the current query string. The resultant argument values are set as attributes on this Widget (with names matching the argument names).

To declare arguments on your own Widget class, assign a ExposedNames instance to query_fields and then assign a single-argument callable for each Widget argument to it. This callable will be called with the Widget instance as argument, and should return a Field describing it:

class MyWidget(Widget):
    query_fields = ExposedNames()
    query_fields.my_argument = lambda i: Field()

Changed in version 6.1: This used to be set up using a method using an exposed decorator.

get_concurrency_hash_strings()

Yields one or more strings representing the database value of this Widget.

This is used to determine whether or not the database has changed since a page was rendered, because if it did, the page is considered out of date and needs to be refreshed.

By default only Input participate in this algorithm, but you may override this method for your Widget subclass to make it participate as well - presuming it can somehow be related to a value in the database.

New in version 5.0.

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.

set_as_security_sensitive()

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.

property is_security_sensitive

Answers whether this Widget should be secured when communicating with the user browser.

add_child(child)

Adds another Widget (child) as a child Widget of this one.

Returns:

the added child for convenience.

insert_child(index, child)

Adds another Widget (child) as a child Widget of this one, at index position amongst existing children.

add_children(children)

Adds all Widgets in children children Widgets of this one.

Returns:

the list of added children for convenience.

render()

Returns an HTML representation of this Widget. (Not for general use, may be useful for testing.)

property disabled

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.

property visible

Answers whether this Widget should be rendered to the current user at all.

get_js(context=None)

Override this method if your Widget needs JavaScript to be activated on the browser side.

property user_interface

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.

Layout

class reahl.web.fw.Layout

A Layout is used to change what a Widget looks like by (e.g.) changing what css classes are used by the Widget, or by letting you add children to a Widget in customised ways.

customise_widget()

Override this method in subclasses to allow your Layout to change its Widget upon construction. There is no need to call super(), as the superclass implementation does nothing.

WidgetFactory

class reahl.web.fw.WidgetFactory(widget_class, *widget_args, **widget_kwargs)

An object used by the framework to create a Widget, once needed.

Parameters:
  • 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.

use_layout(layout)

If called on the factory, .use_layout will be called in the Widget created, passing along the given layout.

Parameters:

layout – A layout to be used with the newly created Widget

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.

Bookmark

class reahl.web.fw.Bookmark(base_path, relative_path, description, query_arguments=None, ajax=False, detour=False, exact=True, locale=None, 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:

Parameters:
  • 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).

  • locale – Force the Bookmark to be for a page in the given locale, instead of using the current locale (default).

  • 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.

Changed in version 3.2: Added the locale kwarg.

classmethod for_widget(description, query_arguments=None, **bookmark_kwargs)

Creates a “page-internal” Bookmark for a Widget with the arguments as specified.

Parameters:
  • 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.

with_description(description)

Returns a new Bookmark, like this one, except that it has description for its description.

property is_page_internal

Answers whether this Bookmark is for a Widget on the current page only.

on_view(view)

For page-internal Bookmarks, answers a new Bookmark which is to the current Bookmark, but on the given View.

New in version 3.2.

EventHandler

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.

Transition

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.

View

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.

ViewFactory

class reahl.web.fw.ViewFactory(regex_path, title, slot_definitions=None, 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.

get_relative_path(**arguments)

Returns a string containing the path this View would have relative to its UserInterface, given the arguments passed.

Parameters:

url_arguments – Values for the arguments of the parameterised View to which the relative_path should lead. (Just omit these if the target View is not parameterised.)

add_precondition(precondition)

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.

set_page(page_factory)

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, locale=None, **url_arguments)

Returns a Bookmark to the View this Factory represents.

Parameters:
  • 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)

  • locale – (See Bookmark.)

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

UrlBoundView

class reahl.web.fw.UrlBoundView(user_interface, relative_path, title, slot_definitions=None, 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. These subclasses should not implement their own __init__ methods, rather use .assemble() for customisation.

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

The title of this View

read_check

The UrlBoundView will only be allowed to be viewed if this no-arg callable returns True.

write_check

The UrlBoundView will only be allowed to receive user input if this no-arg callable returns True.

assemble()

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.

set_page(page_factory)

Supplies a Factory for the page to be used when displaying this View.

add_precondition(precondition)

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, locale=None)

Returns a Bookmark for this UrlBoundView.

keyword description:

A textual description to be used by links representing this View to a user.

keyword query_arguments:

A dictionary mapping names to values to be used for query string arguments.

keyword ajax:

(not for general use)

keyword locale:

(See Bookmark.)

Changed in version 3.2: Added locale kwarg.

ParameterisedPath

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.

Parameters:
  • 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.

RegexPath

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.

Parameters:
  • 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.

SubResources

' Copyright 2017, 2018, 2022 Reahl Software Services (Pty) Ltd. All rights reserved.

@startuml
!include ../../../../../base.iuml

title Invoking server-side methods from a browser

SubResource -up-|> Resource
RemoteMethod -up-|> SubResource
CheckedRemoteMethod -up-|> RemoteMethod
EventChannel -up-|> RemoteMethod

RemoteMethod -right- MethodResult
JsonResult -up-|> MethodResult
WidgetResult -up-|> MethodResult
RedirectAfterPost -up-|> MethodResult
noRedirectAfterPost -up-|> MethodResult

@enduml

SubResource

class reahl.web.fw.SubResource(view, 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(view, unique_name, path_argument_fields, *args, **kwargs)

Returns a Factory which the framework will use, once needed, in order to create this SubResource.

Parameters:
  • 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.

get_url()

Returns the Url that resolves to this SubResource.

RemoteMethod

class reahl.web.fw.RemoteMethod(view, name, callable_object, default_result, idempotent=False, immutable=False, method=None, disable_csrf_check=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.

Parameters:
  • 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.

  • default_result – The MethodResult returned by RemoteMethod.make_result().

  • idempotent – Whether this method will yield the same side-effects and results when called more than once, or not. Idempotent methods are accessible via GET method. Methods that are not idempotent are accessible by POST http method.

  • immutable – Pass True to guarantee that this method will not make changes in the database (the database is rolled back to ensure this). Immutable methods are idempotent.

  • method – The http method supported by this RemoteMethod is derived from whether it is idempotent or not. By default a RemoteMethod is accessible via http ‘get’ if it is idempotent, else by ‘post’. This behaviour can be overridden by specifying an http method explicitly using the method keyword argument.

  • disable_csrf_check

    Pass True to prevent this RemoteMethod from doing the usual CSRF check.

    Changed in version 5.0: idempotent and immutable kwargs split up into two and better defined.

    Changed in version 5.0: method keyword argument added to explicitly state http method.

    Changed in version 5.2: disable_csrf_check keyword argument added.

cleanup_after_exception(input_values, ex)

Override this method in a subclass to trigger custom behaviour after the method triggered a DomainException.

cleanup_after_success()

Override this method in a subclass to trigger custom behaviour after the method completed successfully.

make_result(input_values)

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.

Parameters:

input_values – The current request.GET or request.POST depending on the request.method.

CheckedRemoteMethod

class reahl.web.fw.CheckedRemoteMethod(view, name, callable_object, result, idempotent=False, immutable=False, disable_csrf_check=False, **parameters)

A RemoteMethod whose input is governed by instances of Field like input usually is.

Parameters:
  • name – (See RemoteMethod.)

  • callable_object – (See RemoteMethod.) Should expect a keyword argument for each key in parameters.

  • result – (See RemoteMethod.)

  • idempotent – (See RemoteMethod.)

  • immutable – (See RemoteMethod.)

  • parameters – A dictionary containing a Field for each argument name expected.

Changed in version 5.0: Split immutable into immutable and idempotent kwargs.

EventChannel

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.

make_result(input_values)

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.

Parameters:

input_values – The current request.GET or request.POST depending on the request.method.

cleanup_after_exception(input_values, ex)

Override this method in a subclass to trigger custom behaviour after the method triggered a DomainException.

cleanup_after_success()

Override this method in a subclass to trigger custom behaviour after the method completed successfully.

MethodResult

class reahl.web.fw.MethodResult(catch_exception=<class 'reahl.component.exceptions.DomainException'>, mime_type='text/html', encoding='utf-8', replay_request=False)

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.

Parameters:
  • catch_exception – The class of Exeption for which this MethodResult will generate an exceptional Response if thrown while the RemoteMethod executes (default: DomainException).

  • mime_type – The mime type to use as html content type when sending this MethodResult back to a browser.

  • encoding – The encoding to use when sending this MethodResult back to a browser.

  • replay_request – If True, first recreate everything (including this MethodResult) before generating the final response in order to take possible changes made by the execution of the RemoteMethod into account.

Changed in version 3.2: Added the replay_request functionality.

Changed in version 3.2: Set the default for catch_exception to DomainException

create_response(return_value)

Override this in your subclass to create a webob.Response for the given return_value which was returned when calling the RemoteMethod.

create_exception_response(exception)

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.

render(return_value)

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.

render_exception(exception)

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.

RedirectAfterPost

class reahl.web.fw.RedirectAfterPost(mime_type='text/html', encoding='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.

Parameters:

Changed in version 4.0: Renamed content_type to mime_type and charset to encoding in line with MethodResult args.

create_response(return_value)

Override this in your subclass to create a webob.Response for the given return_value which was returned when calling the RemoteMethod.

create_exception_response(exception)

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.

JsonResult

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.

Parameters:
render(return_value)

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.

render_exception(exception)

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.

WidgetResult

class reahl.web.fw.WidgetResult(result_widgets, as_json_and_result=None)

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.

A JavaScript <script> tag is rendered also, containing the JavaScript activating code for the new contents of this refreshed Widget.

Changed in version 6.1: result_widget parameter changed to be a list, renamed to result_widgets. Deprecated kwarg as_json_and_result

render(return_value)

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.

render_exception(exception)

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.

Controlling flow via Detours and Redirects

ViewPreCondition

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.

Parameters:
  • 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.

Redirect

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

Detour

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 Return, 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.

Return

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.

Utility

Url

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.

set_scheme(scheme)

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.

set_query_from(value_dict, doseq=False)

Sets the query string of this Url from a dictionary.

property netloc

Returns the authority part of the URl as per RFC3968, also sometimes referred to as the netloc part in Python docs.

property is_network_absolute

Answers whether this URL is absolute according to RFC3986 (ie, whether the Url includes a scheme, hostname and port).

make_network_absolute()

Ensures that this URL has a scheme, hostname and port matching that of the current Request URL.

make_network_relative()

Removes the scheme, hostname and port from this URL.

as_network_absolute()

Returns a new Url equal to this one, except that it does not contain a scheme, hostname or port.

make_locale_absolute(locale=None)

Ensures that this URL starts with a string indicating the current locale (if not using the default locale).

make_locale_relative()

Ensures that this URL does not include a starting path indicating locale.

as_locale_relative()

Returns a new Url equal to this one, except that it does not include the starting path indicating locale.

with_new_locale(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.

is_currently_active(exact_path=False)

Answers whether this Url is currently active (see is_active_on).

query_is_subset(other_url)

Answers whether name=value pairs present in this Url’s query string is a subset of those present in other_url.

Exceptions

CannotCreate

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.

ValidationException

exception reahl.web.fw.ValidationException(commit=False, message=None, detail_messages=[], handled_inline=True, json_string=None)

Indicates that one or more Fields received invalid data.