From 73c43fc30de06a29ae996fa00f93d7ca8748ef12 Mon Sep 17 00:00:00 2001 From: Alfredo Deza Date: Sun, 26 Jun 2011 13:02:37 -0400 Subject: [PATCH] Add documentation for RequestViewerHook --- docs/source/hooks.rst | 180 ++++++++++++++++++++++++++++++++++++++++++ pecan/hooks.py | 7 +- 2 files changed, 184 insertions(+), 3 deletions(-) diff --git a/docs/source/hooks.rst b/docs/source/hooks.rst index 4a20186..c83af18 100644 --- a/docs/source/hooks.rst +++ b/docs/source/hooks.rst @@ -84,3 +84,183 @@ the app and browse the application from our web browser:: response: 200 OK +Included Pecan Hooks +==================== +Pecan includes some hooks in its core and are very simple to start using them +away. This section will describe their different uses, how to configure them +and examples of common scenarios. + +.. _requestviewerhook: + +RequestViewerHook +================= +This hooks is very useful for debugging purposes. It has access to every +attribute the ``response`` object has plus a few others that are specific to +the framework. + +There are two main ways that this hook can provide information about a request: + +#. Terminal or logging output (via an file-like stream like `stdout`) +#. Custom header keys in the actual response. + +By default, both outputs are on if they are not configured. + +For the actual object reference, please see :ref:`pecan_hooks`. + +Automatically Enabled +--------------------- +This hook can be automatically added to the application itself if a certain key +exists in the configuration used for the app. This key is:: + + requestviewer + +It does not need to contain anything (could be an empty dictionary), and this +is enough to force Pecan to load this hook when the WSGI application is +created. + +Configuration +------------- +There are a few ways to get this hook properly configured and running. However, +it is useful to know that no actual configuration is needed to have it up and +running. + +By default it will output information about these items: + +* path : Displays the url that was used to generate this response +* status : The response from the server (e.g. '200 OK') +* method : The method for the request (e.g. 'GET', 'POST', 'PUT or 'DELETE') +* controller : The actual controller method in Pecan responsible for the response +* params : A list of tuples for the params passed in at request time +* hooks : Any hooks that are used in the app will be listed here. + +No configuration will show those values in the terminal via `stdout` and it +will also add them to the response headers (in the form of +`X-Pecan-item_name`). + +This is how the terminal output look for a `/favicon.ico` request :: + + path - /favicon.ico + status - 404 Not Found + method - GET + controller - The resource could not be found. + params - [] + hooks - ['RequestViewerHook'] + +In the above case, the file was not found, and the information was properly +gathered and returned via `stdout`. + +And this is how those same values would be seen in the response headers:: + + X-Pecan-path /favicon.ico + X-Pecan-status 404 Not Found + X-Pecan-method GET + X-Pecan-controller The resource could not be found. + X-Pecan-params [] + X-Pecan-hooks ['RequestViewerHook'] + +The hook can be configured via a dictionary (or Config object from Pecan) when +adding it to the application or via the `requestviewer` key in the actual +configuration being passed to the application. + +The configuration dictionary is flexible (none of the keys are required) and +can hold two keys: `items` and `blacklist`. + +This is how the hook would look if configured directly when using `make_app` +(shortened for brevity):: + + ... + hooks = [ + RequestViewerHook({'items':['path']}) + ] + +And the same configuration could be set in the config file like:: + + requestviewer = {'items:['path']} + +Specifying items +---------------- +Items are the actual information objects that the hook will use to return +information. Sometimes you will need a specific piece of information or +a certain bunch of them according to the development need so the defaults will +need to be changed and a list of items specified. + +.. :note: + When specifying a list of items, this list overrides completely the + defaults, so if a single item is listed, only that item will be returned by + the hook. + +Remember, the hook has access to every single attribute the request object has +and not only to the default ones that are displayed, so you can fine tune the +information displayed. + +These is a list containing all the possible attributes the hook has access to +(directly from `webob`): + +accept make_body_seekable +accept_charset make_tempfile +accept_encoding max_forwards +accept_language method +application_url params +as_string path +authorization path_info +blank path_info_peek +body path_info_pop +body_file path_qs +body_file_raw path_url +body_file_seekable postvars +cache_control pragma +call_application query_string +charset queryvars +content_length range +content_type referer +cookies referrer +copy relative_url +copy_body remote_addr +copy_get remote_user +date remove_conditional_headers +decode_param_names request_body_tempfile_limit +environ scheme +from_file script_name +from_string server_name +get_response server_port +headers str_GET +host str_POST +host_url str_cookies +http_version str_params +if_match str_postvars +if_modified_since str_queryvars +if_none_match unicode_errors +if_range upath_info +if_unmodified_since url +is_body_readable urlargs +is_body_seekable urlvars +is_xhr uscript_name + user_agent + +And these are the specific ones from Pecan and the hook: + + * controller + * hooks + * params (params is actually available from `webob` but it is parsed + by the hook for redability) + +Blacklisting +------------ +Sometimes is annoying to get information about *every* single request. For this +purpose, there is a matching list of url paths that you can pass into the hook +so that paths that do not match are returned. + +The matching is done at the start of the url path, so be careful when using +this feature. For example, if you pass a configuration like this one:: + + { 'blacklist': ['/f'] } + +It would not show *any* url that starts with `f`, effectively behaving like +a globbing regular expression (but not quite as powerful). + +For any number of blocking you may need, just add as many items as wanted:: + + { 'blacklist' : ['/favicon.ico', '/javascript', '/images'] } + +Again, the `blacklist` key can be used along with the `items` key or not (it is +not required). diff --git a/pecan/hooks.py b/pecan/hooks.py index 2918ea6..1fd3f64 100644 --- a/pecan/hooks.py +++ b/pecan/hooks.py @@ -182,10 +182,10 @@ class RequestViewerHook(PecanHook): Valid items are *any* item that the ``request`` object holds, by default it uses the following: - * url + * path + * status * method - * response - * context + * controller * params * hooks @@ -206,6 +206,7 @@ class RequestViewerHook(PecanHook): .. :note:: This key should always use a ``list`` of items to use. + For more detailed documentation about this hook, please see :ref:`requestviewerhook` ''' available = ['path', 'status', 'method', 'controller', 'params', 'hooks']