Even though it is possible to expose different parts of an application -using different URLs and paths, this usually is only +
Even though it is possible to expose different parts of an +application +using different URLs and paths, this usually +is only enough for applications which model some kind of filesystem or repository. Applications which -involve user input through forms, for example, need to be able to receive -such input by other means, and this is where request parameters come in. For + href="paths-filesystem.html">filesystem or repository. +Applications which +involve user input through forms, for example, need to be able to +receive +such input by other means, and this is where request parameters come +in. For example, when a user fills out a form in a Web browser, the following happens:
Request parameters can originate from two sources:
One useful application of parameters transferred in request bodies is the +
One useful application of parameters transferred in request bodies
+is the
sending or uploading of file contents through such parameters - this is
-described in "Request Body Parameters". Another way of uploading content in
+described in "Request Body Parameters". Another way of uploading
+content in
conjunction with the PUT request
method is mentioned below.
If the origin of the different parameters received in a request is not -particularly interesting or important, WebStack provides a convenience method +
If the origin of the different parameters received in a request is +not +particularly interesting or important, WebStack provides a convenience +method in transaction objects to get all known parameters from a request:
get_fieldsencoding parameter may be used to assist the
- process of converting parameter values to Unicode objects - see "Request Body Parameters" and "Character Encodings" for more discussion of
- this parameter.encoding parameter may be used to assist the
+process of converting parameter values to Unicode objects - see "Request Body Parameters" and "Character Encodings" for more discussion of
+this parameter.get_query_string%xx where xx
+is a two digit hexadecimal number referring to the byte value of the
+unencoded character - see "Character
+Encodings" for information on how byte values should be
+interpreted. Generally, it is not recommended to just get all parameters since there -may be some parameters from the request headers which have the same names as -some other parameters from the request body. Consequently, confusion could +
Generally, it is not recommended to just get all parameters since +there +may be some parameters from the request headers which have the same +names as +some other parameters from the request body. Consequently, confusion +could arise about the significance of various parameter values.
-When handling requests in your application, instead of treating request as
-containers of parameters and using the WebStack API methods to access those
-parameters, you can instead choose to read directly from the data sent by the
-user and interpret that data in your own way. In most situations, this is not
-really necessary - those methods will decode request parameters (for example,
-form fields) in a way which is fairly convenient - but when files are being
-sent, and when the request method is specified as
-PUT, it is necessary to obtain the input stream from the request
+
When handling requests in your application, instead of treating
+request as
+containers of parameters and using the WebStack API methods to access
+those
+parameters, you can instead choose to read directly from the data sent
+by the
+user and interpret that data in your own way. In most situations, this
+is not
+really necessary - those methods will decode request parameters (for
+example,
+form fields) in a way which is fairly convenient - but when files are
+being
+sent, and when the request method is
+specified as
+PUT, it is necessary to obtain the input stream from the
+request
and to read the file contents from that stream.
When the request does not contain standard form-encoded parameter
-information and instead contains the contents of an uploaded file, methods
-like get_fields and get_fields_from_body should be
+information and instead contains the contents of an uploaded file,
+methods
+like get_fields and get_fields_from_body
+should be
avoided and other methods in the transaction employed.
get_request_streamget_content_typeWebStack.Generic.ContentType) which describes the request
- body's contents.WebStack.Generic.ContentType)
+which describes the request body's contents.The purpose and behaviour of PUT request methods is described in the HTTP
+ href="methods.html">request methods is described in the HTTP
specification.
There are various differing approaches to the problem of +interpreting +paths to resources within Web applications, but these can mostly be +divided +into three categories:
+| Approach | +Examples | +
|---|---|
| Path as filesystem | +WebDAV interface to a repository | +
| Path as resource or service +identifier | +A Web shop with very simple paths, eg. /products,
+ /checkout, /orders |
+
| Path as opaque reference | +An e-mail reader where the messages already have strange and +unreadable message identifiers | +
The following table summarises the support for "path info" within +applications +amongst the supported server environments or frameworks within WebStack:
+| Framework | +Behaviour (Level of Support) | +
|---|---|
| BaseHTTPRequestHandler | +Same as path (correct) | +
| CGI | +Path beyond resource (correct) | +
| Java Servlet API | +Path beyond context (correct) | +
| mod_python | +Path beyond resource (correct) | +
| Twisted | +Same as path (correct) | +
| Webware | +<= 0.8.1: Not supported (needs ExtraPathInfo
+support)+> 0.8.1: Path beyond context (correct) |
+
| WSGI | +Path beyond resource (correct) | +
| Zope | +Path beyond resource (correct) | +
One thing to be aware of in the +code of an application is which part +of +a +path refers to the location of the application in a server environment +and +which refers to some resource within the application itself. Consider +this +path:
+/folder/application/resource+
Let us say that the application
+was deployed in a Zope server
+instance
+inside
+folder
+and with the name application.
+We may
+then
+say that the path to the application is this:
+
/folder/application+
Meanwhile, the path within the +application is just this: +
+/resource+
In WebStack, we refer to this latter case - the path within the +application - as the "path info".
+On transaction objects, the +following methods exist to inspect paths +to +resources within applications.
+get_path_info/ character at the very least.get_virtual_path_infoset_virtual_path_info
+method. The path should always contain a leading /
+character at the very least.Given that the path may change depending on where an +application is deployed in a server environment, it may not be very +easy to use when determining which resources are being requested or +accessed within your application. Conversely, given that the "path +info" does not mention the full path to where the resources are, +it may be difficult to use that to provide references or links to those +resources. Here is a summary of how you might use the different path +values:
+| Type of information | +Possible uses | +
|---|---|
| Path | +Building links to +resources within an application - subtract the "path info" from +the end and you should get the location of the application. | +
| Path info | +Determining which +resources are being accessed within an application. | +
| Virtual path info | +This is an +application-defined version of "path info" and is discussed below. | +
Although WebStack sets the "path info" so that applications +know which part of themselves are being accessed, you may decide +that upon +processing the request, these different parts of your application +should be +presented with different path information. For example, in a +hierarchical +structure of resources, each resource might use the first part of the +"path info" as an input to some kind of processing, but then have the +need to remove the +part they used, passing on a modified path to the other resources. For +such approaches, the "virtual path info" may be used instead, since it +permits modification within an application.
+So starting with a virtual path like this (which would be the same +as the "path info")...
+/company/department/employee+
...a resource might extract company from the start
+of the path as follows:
# Inside a respond method...+
path = trans.get_virtual_path_info() # get the virtual path
parts = path.split("/") # split the path into components - the first will be empty
Then, having processed the first non-empty part (remembering that +the first part will be an empty string)...
+if len(parts) > 1: # check to see how deep we are in the path+
process_something(parts[1]) # process the first non-empty part
...it will reconstruct the path, removing the processed part (but
+remembering to preserve a leading / character)...
trans.set_virtual_path_info("/" + "/".join(parts[2:]))
+...and hand over control to another resource which would do the same
+thing with the first of the other path components (department
+and employee), and so on.
The compelling thing about this strategy is the way that each +resource would only need to take the "virtual path info" into +consideration, and that each resource would believe that it is running +independently from any "parent" resource. Moreover, such resources +could be deployed independently and still operate in the same way +without being "hardcoded" into assuming that they always reside at a +particular level in a resource hierarchy.
+On transaction objects, the +following method exists to set virtual paths within applications.
+set_virtual_path_infoget_virtual_path_info
+method. The path should always contain a leading /
+character at the very least.Since many Web applications have complete control over how paths are -interpreted, the form of the path doesn't necessarily have to follow any -obvious structure as far as users of your application is concerned. Here's an +interpreted, the form of the path doesn't necessarily have to follow +any +obvious structure as far as users of your application is concerned. +Here's an example:
/000251923572ax-0015- -
However, many would argue that such obscure references, whilst perfectly -acceptable to machines, would make any application counter-intuitive and very -difficult to reference. Sometimes, application developers do not want people +
Many people would argue that such obscure references, whilst +perfectly +acceptable to machines, would make any application counter-intuitive +and very +difficult to reference. However, application developers sometimes +do not want people "bookmarking" resources or functions within an application, and so such concerns don't matter to them.
diff -r 7b0c3aae7b35 -r b086884cf017 docs/paths.html --- a/docs/paths.html Mon Apr 25 22:19:20 2005 +0000 +++ b/docs/paths.html Tue Apr 26 18:33:06 2005 +0000 @@ -1,176 +1,82 @@ - - +The URL at which your application shall appear is arguably the first part -of the application's user interface that any user will see. In this context, +
The URL at which your application shall appear is arguably the first +part +of the application's user interface that any user will see. Remember +that a user of your application does not have to be a real person; in +fact, a user can be any of the following things:
Some application developers have a fairly rigid view of what kind of +information a URL should contain and how it should be structured. In +this guide, we shall look at a number of different approaches.
What the URL is supposed to do is to say where (on the Internet or on an -intranet) your application resides and which resource or service is being +
What the URL is supposed to do is to say where (on the Internet or +on an +intranet) your application resides and which resource or service is +being accessed, and these look like this:
http://www.boddie.org.uk/python/WebStack.html- -
With WebStack, we also talk about a "path" as being just the part of the -URL which refers to the resource or service, ignoring the actual Internet -address, and so these look like this:
+In an application the full URL, containing the address of the +machine on which it is running, is not always interesting. In the +WebStack API (and in other Web programming frameworks), we also talk +about "paths" - a path is just the part of the +URL which refers to the resource or service, ignoring the actual +Internet +address, and so the above example would have a path which looks like +this:
/python/WebStack.html-
When writing a Web application, most of the time you just need to -concentrate on the path because the address doesn't usually tell you anything +concentrate on the path because the address doesn't usually tell you +anything you don't already know. What you need to do is to interpret the path -specified in the request in order to work out which resource or service the -request is destined for.
- +specified in the request in order to work out which resource or service +the user is trying to access.WebStack provides the following transaction methods for inspecting path +
WebStack provides the following transaction methods for inspecting +path information:
get_pathget_path_without_querySometimes, a "query string" will be provided as part of a URL; for example:
http://www.boddie.org.uk/application?param1=value1- -
The question mark character marks the beginning of the query string which -contains encoded parameter information; such information and its inspection +
The question mark character marks the beginning of the query string +which +contains encoded parameter information; such information and its +inspection is discussed in "Request Parameters and Uploads".
- -/folder/application/resource-Let us say that the application was deployed in a Zope server instance inside -
folder and with the name application. We may then
-say that the path to the application is this:
-/folder/application-Meanwhile, the path within the application is just this: -
/resource- -
On transaction objects, the following methods exist to inspect paths to -resources within applications.
-get_path_infoget_virtual_path_infoset_virtual_path_info
- method.There are various differing approaches to the problem of interpreting -paths to resources within Web applications, but these can mostly be divided -into three categories:
- -| Approach | -Examples | -
|---|---|
| Path as filesystem | -WebDAV interface to a repository | -
| Path as resource or service - identifier | -A Web shop with very simple paths, eg. /products,
- /checkout, /orders |
-
| Path as opaque reference | -An e-mail reader where the messages already have strange and - unreadable message identifiers | -
The following table summarises the support for paths within applications -amongst the supported server environments or frameworks within WebStack:
- -| Framework | -Behaviour/Level of Support | -
|---|---|
| BaseHTTPRequestHandler | -Same as path (correct) | -
| CGI | -Path beyond resource (correct) | -
| Java Servlet API | -Path beyond context (correct) | -
| mod_python | -Path beyond resource (correct) | -
| Twisted | -Same as path (correct) | -
| Webware | -<= 0.8.1: Not supported (needs ExtraPathInfo
- support)- > 0.8.1: Path beyond context (correct) |
-
| WSGI | -Path beyond resource (correct) | -
| Zope | -Path beyond resource (correct) | -