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¶
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 theUserInterface.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 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 thisView
(if specified).detour – If True, marks this
View
as the start of a detour (A series ofView
s 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 parameterisedView
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 parameterisedView
that will be created when an URL is requested that matches path_regex. The arguments of the parameterisedView
are parsed from a matching URL using named groups in path_regex. These named arguments are again passed to the assemble of theView
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 parameterisedView
.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 astring.Template
, and should contain references to variables named for each argument expexted by the assemble method of the parameterisedView
.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 typeViewFactory
), upon the occurrence of anEvent
that matches event.
- define_return_transition(event, source, guard=None)¶
Creates a
Transition
that returns a user to theView
the user was on before visiting a detourView
.
- define_local_transition(event, source, guard=None)¶
Creates a
Transition
that lets the user stay on the currentView
.
- 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 thisUserInterface
.- 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 someSlots
. The ui_classUserInterface
which is effectively grafted onto the currentUserInterface
, also definedSlots
using its own names. This dictionary states how the names used in the graftedUserInterface
map to the names used by the currentUserInterface
.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 parameterisedUserInterface
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 theView
present on relative_path.- Parameters:
description – By default the
Bookmark
will use the title of the targetView
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 yourWidget
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 (aViewFactory
) matches the current View and if its guard (anAction
) 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 useUserInterface.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¶
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 byRemoteMethod.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:
mime_type – (See
MethodResult
.)encoding – (See
MethodResult
.)
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:
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
.
- 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
andReturn
.- 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 aReturn
, 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 theViewPreCondition
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 aDetour
.
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.