Myghty Documentation
Version: 1.2 Last Updated: 07/07/10 12:55:17
View: Paged  |  One Page

The Request, available in all Myghty templates as the global variable m, is the central processor of a component and all the calls it makes to other components. Following are all the useful methods and members of a request.

Note: many request methods have been converted to straight data members as of version 0.96, such as get_base_component(), get_request_args(), get_dhandler_arg(), etc. These methods are still present for existing applications but their use is deprecated. Their functionality can be located in the Request Members section.

Request Methods
abort(status_code = None)

Halts the currently executing component, and optionally sends the specified HTTP status code. Any content that is still in the output buffer is discarded. If the status code is None, the request simply ends with no further output, and the HTTP code 200:OK is returned as a normal request.

Abort can be used to send any HTTP status code desired to the client. However, to send a soft redirect via a subrequest, or a hard redirect via the "Location:" header along with 302:Moved, its easier to use m.send_redirect(), described below.

apply_escapes(text, flags)
programmatically applies escape flags to the given text, the same as they would be used inside of a substitution. text is a string to be processed, and flags is an array of single-character escape flags. The two built in flags are "u" for url escaping and "h" for HTML escaping, and user-defined flags are supported as well. See Escaping Content for more information on escape flags.
cache(component=None, cache_type=None, cache_container_class=None, **params)

Returns the cache for the current component, or if called with an optional component argument, returns the cache for the specified component. If the cache does not yet exist within the scope of the current request, it will be created using the given list of arguments, else the arguments are disregarded and the previous request-scoped cache interface is returned (note that multiple instances of a cache interface may all reference the same underlying data store, if they are of the same type). The arguments here override those set in the global configuration for the interpreter, but will usually not override the arguments specified in the %flags section of the component.

The cache type defaults to 'dbm' if a data_dir is in use, else uses 'memory'. Additional arguments can be added that are specific to MemoryContainer, DBMContainer, or other custom types of containers. See the section Data Caching.

Also called as: get_cache

cache_self(component=None, key=None, retval=None, cache_type=None, cache_container_class=None, **params)

Caches the current component (or the specified component's) output and return value. All arguments are optional. The component argument is a component argument specifying a component other than the currently executing component. The key argument is the key to store the information under, which defaults to the string "_self". The key can be modified if you want to cache the comopnent's output based on some kind of conditional information such as component arguments. The retval argument is a value object which can be used to receive the return value of the component. The rest of the parameters are the same as those for the cache/get_cache method.

The function returns True indicating that the retval has been populated and the component's output has been flushed to the output, or False indicating that the value is not yet cached (or needs refreshing) and execution should continue on into the rest of the component. See Data Caching for an example.

callers(index = None)

Returns a single component from the call stack object indicated by the given index, or if None returns the full list of components stored within the current call stack.

caller_args(index = None)

Returns a single dictionary of component arguments from the call stack object indicated by the given index, or if None returns the full list of argument dictionaries sent to each component stored within the current call stack.

call_content()

Similar to the content() method used within a component call with content, except does not push a new buffer onto the buffer stack. When combined with programmatic pushing and popping buffers onto the request via push_buffer() and pop_buffer(), it can be used for complicated content-grabbing schemes. For advanced usage.

call_next(**params)
Within a chain of inheriting pages, calls the next component in the inheritance chain, i.e. the "wrapped" component. See Inheritance for more information on the inheritance chain. Optional **params specify arguments that will override the subclass-component's default argument list on a parameter-by-parameter basis.
call_stack(index = None)

Provides access to the current call stack. The call stack is a list of StackFrame objects, which are internal representations of components calling each other. Each StackFrame object contains the fields "component", "args", "base_component", "content", "is_call_self", and "filter". The given index refers to what index within the stack to return; if it is None, the entire call stack is returned.

comp(component, **params)
calls a component, subcomponent, or method. See m.comp(component, **params).
component_exists(path)
returns True if the specified file-based component, identified by its URI, can be located. Performs the full filesystem check even if the requested component is already loaded, therefore repeated calls to this method can get expensive.
content()
returns the content of an embedded component call in the context of a component call with content. See Component Calls with Content.
create_subrequest(component, resolver_context='subrequest', **params)
Creates a subrequest, which is a child request to this one. The request can then serve a new component call, which will be serviced within the same output stream as this one. By default, the subrequest is configured in much the same way as the originating request. The **params dictionary can be used to override individual configuration parameters; any per-request parameter listed in Index of Configuration Parameters is relevant.

Users will usually prefer to use the methods make_subrequest() or subexec() since they are more compact for typical component-call scenarios. See Subrequests.

Also see Resolver Contexts for information on the resolver_context parameter.

decline()
Used by a dhandler to forego processing a directory request, and to bump the interpreter up to the enclosing directory, where it will search again for a dhandler. See dhandler.
execute()
Executes this request. Chances are you are already inside the execute call, which can only be called once on any given request object. However, if you make yourself a subrequest, then you can call execute on that object. See Subrequests.
execute_component(component, args = {}, base_component = None, content = None, store = None, is_call_self = False)
The base component-calling method, at the root of all the other component calling methods (i.e. execute(), comp(), subexec(), etc.). The richer argument set of this method is useful for calling components with an embedded content call, and also for supplying a custom output buffer to capture the component output directly. The parameters are:
  • component - the string name/URI of the component, or an actual component argument
  • args - dictionary of arguments sent to the component. this is supplied to the component via ARGS as well as via the component-scoped <%args> tag.
  • base_component - the base component for the component call. This is best left as None, where it will be determined dynamically.
  • content - reference to a function that will be attached to the m.content() method inside the component call. this is used to programmatically call a "component call with content". The function takes no arguments and is normally a "closure" within the span of the code calling the enclosing component.
  • store - reference to a buffer, such as a file, StringIO, or myghty.buffer object, where the component's output will be sent.
  • is_call_self - used internally by the m.call_self() method to mark a stack frame as the original "self caller". Just leave it as False.

Example: component call with content:

<%def testcall>
    this is testcall.  embedded content:
    [ <% m.content() %> ]
</%def>

<%python>
    def mycontent():
        m.write("this is the embedded content.")
        
    m.execute_component('testcall', args = {}, content = mycontent)
</%python>

This will produce:

this is testcall.  embedded content:
[ this is the embedded content. ]
fetch_all()
Returns a list of the full "wrapper chain" of components inheriting each other, beginning with the current inheriting component and going down to the innermost component. Each element is popped of the request's internal wrapper stack. See Inheritance for details on component inheritance.
fetch_component(path, resolver_context='component', raise_error=True)

Returns a component object corresponding to the specified component path. This path may be:

  • a URI path relative to one of the application's configured component roots, with an optional clause ":methodname" indicating a method to be called from the resulting file-based component.
  • one of the special names SELF, PARENT, REQUEST, with an optional clause ":methodname" indicating a method to be called from the resulting file-based component, or the current subcomponent's owner in the case of a subcomponent that calls SELF.
  • the name of a method component stated in the form "METHOD:modulename:classname".
When the component is located, it will be compiled and/or loaded into the current Python environment if it has not been already. In this way it is the Myghty equivalent of "import".

If the component cannot be located, it raises a myghty.exceptions.ComponentNotFound error, unless raise_error is False, in which case the method returns None.

More details on how to identify components can be found in Components.

Also see Resolver Contexts for information on the resolver_context parameter.

fetch_lead_component(path)

Fetches a component similarly to fetch_component(), but also resolves directory requests and requests for nonexistent components to dhandlers.

If the component cannot be located, or a useable dhandler cannot be located because either no dhandler was found or all valid dhandlers have already sent decline() within the span of this request, a myghty.exceptions.ComponentNotFound error is raised.

fetch_module_component(moduleorpath, classname, raise_error=True)

Fetches a module component. The value of "moduleorpath" is either a string in the form "modulename:classname", or it is a reference to a Python module containing the desired component. In the latter case, the argument "classname" must also be sent indicating the name of the desired class to load.

Using this method with a string is the same as using the fetch_component() method using the syntax "METHOD:modulename:classname".

If the module component cannot be located, a myghty.exceptions.ComponentNotFound error is raised, unless raise_error is False, in which case the method returns None.

fetch_next()
Within a chain of inheriting pages, this method returns the next component in the inheritance chain (also called the "wrapper" chain), popping it off the stack. The component can then be executed via the m.comp() or similar method. See the section Inheritance.
get_session(**params)

Creates or returns the current Myghty session object (or optionally the mod_python Session object). If the session has not been created, the given **params are used to override defaults and interpreter-wide configuration settings during initialization.

Details on the Session are described in Session.

has_content()
Inside of a subcomponent or method call, returns whether or not the component was a component call with content. See the section Component Calls with Content.
has_current_component()
Returns True if this request has a currently executing component. This becomes true once a request's execute() method has been called.
instance()
This static method returns the request corresponding to the current process and thread. You can access the current request in a globally scoped block via this method. See Global Scope.
<%python scope="global">
    req = request.instance()
</%python>
is_subrequest()
Returns True if the currently executing request is a subrequest. See the section Subrequests.
log(message)
Logs a message. The actual method of logging is specific to the underlying request implementation; for standalone and CGI it is the standard error stream, for mod_python it is a [notice] in the Apache error log.
make_subrequest(component, **params)
Creates a new subrequest with the given component object or string path component and the request arguments **params. The returned request object can then be executed via the execute() method. See Subrequests.
scomp(component, **params)
Executes a component and returns its content as a string. See m.scomp(component, **params).
send_redirect(path, hard=True)
Sends a hard or soft redirect to the specified path. A hard redirect is when the http server returns the "Location:" header and instructs the browser to go to a new URL via the 302 - MOVED_TEMPORARILY return code. A soft redirect means the new page will be executed within the same execution context as the current component. In both cases, the current component is aborted, and any buffered output is cleared. For this reason, if auto_flush is enabled (which it is not by default), you would want to call this method, particular the soft redirect, only before any content has been output, most ideally in an %init section. If auto_flush is disabled, you can call either version of this method anywhere in a component and it will work fine.
set_output_encoding(encoding, errors="strict")

Change the output_encoding, and, optionally, the encoding error handling strategy.

Generally, you will not want to change the output encdoing after you have written any output (as then your output will be in two different encodings --- probably not what you wanted unless, for example, you are generating Mime multipart output.)

See the section on Unicode Support for further details.

subexec(component, **params)
All-in-one version of make_subrequest and m.execute(). See Subrequests.
write()
Writes text to the current output buffer. If auto_flush is enabled, will flush the text to the final output stream as well.

Also called as: out
back to section top
Request Members
attributes

A dictionary where request-local information can be stored. Also can be referenced by the member notes. If the request is a subrequest, this dictionary inherits information from its parent request.

base_component
Represents the "effective" file-based component being serviced, from which methods and attributes may be accessed. When autohandlers or other inherited components are executing, this member always points to the file-based component at the bottom of the inheritance chain. This allows an inherited component to access methods or attributes that may be "dynamically overridden" further down the inheritance chain. It is equivalent to the special path SELF. When a method or def component is called via the path of another file-based component, base_component will change to reflect that file-based component for the life of the subcomponent call.
current_component
The component currently being executed. Within the body of a component, this is equivalent to self.
dhandler_path
In the case of a dhandler call, the request path adjusted to the current dhandler.

For information on dhandlers see dhandler.

encoding_errors

The current output encoding error handling strategy. This is a read-only attribute, though you may change it using the set_output_encoding method.

See the section on Unicode Support for further details.

global_args

A dictionary of custom-configured global variables to be used throughout the request. Global variables can be initialized or re-assigned here, and the new value will become available to all further component calls. Each key in this dictionary must already correspond to a value in the allow_globals configuration parameter. See Make your Own Friends for full examples.

interpreter

The Interpreter object that created this Request object.

notes
A synonym for attributes.
output_encoding

The current output encoding. This is a read-only attribute, though you may change it using the set_output_encoding method.

See the section on Unicode Support for further details.

parent_request
In a subrequest call, refers to the immediate parent request of this request, else defaults to None.
request_args

A dictionary containing the initial request arguments sent when this request was created. In an HTTP context, this usually refers to the request arguments sent by the client browser.

In the case of a subrequest (described in Subrequests), this member refers to the request arguments sent to the local subrequest. To get the original request arguments, use the root_request_args parameter.

For detailed description of component and request arguments, see Component Arguments - the <%args> tag.

request_component
Returns the top-level component corresponding to the current request.
request_path

The original path sent to this request for resolution. In the case of a subrequest, the path sent to the subrequest.

In the case of a new request that is called with a pre-existing component object, such as in a custom application interfacing to the Myghty interpreter, the request_path defaults to None, but can also be set programmatically via the request_path configuration argument.

root_request
Refers to the ultimate originating request in a string of subrequests. If this request is not a subrequest, this member references the current request.
root_request_args

Used in subrequests, returns the request arguments sent to the ultimate root request in a chain of subrequests. For a regular request with no parent, this dictionary is synonymous with request_args.

For detailed description of component and request arguments, see Component Arguments - the <%args> tag.

root_request_path

The request path for the original root request, in a chain of subrequests.

back to section top
Previous: Module Components | Next: Other Blocks