Paths To and Within Applications

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/operation

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/operation

In WebStack, we refer to this latter case - the path within the application - as the "path info".

WebStack API - Paths To Resources Within Applications

On transaction objects, the following methods exist to inspect paths to resources within applications.

get_path_info
This gets the path of a resource within an application. The path should always contain a leading / character at the very least.
An optional encoding parameter may be used to assist the process of converting the path to a Unicode object - see "Character Encodings" for more information.
get_virtual_path_info
This gets the path of a resource within a part of an application - the application itself decides the scope of the path and can set the "virtual path info" using the set_virtual_path_info method. The path should either contain a leading / character optionally followed by other characters, or an empty string.
An optional encoding parameter may be used to assist the process of converting the path to a Unicode object - see "Character Encodings" for more information.
get_processed_virtual_path_info
This gets the virtual path information which is considered to have been processed or traversed, and consists of the part of the path info which does not appear in the virtual path info. In other words, when components at the start of the virtual path info are removed, such components will appear at the end of the processed virtual path info.
An optional encoding parameter may be used to assist the process of converting the path to a Unicode object - see "Character Encodings" for more information.

Choosing the Right Path Value

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.
Path without path infoFinding the location of the application in a server environment. (This is the path with the "path info" subtracted from the end.)
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.

Using the Virtual Path

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.

WebStack API - Paths To Resources Within Applications

On transaction objects, the following method exists to set virtual paths within applications.

set_virtual_path_info
This sets the virtual path, affecting subsequent calls to the get_virtual_path_info method. The path should either contain a leading / character optionally followed by other characters, or an empty string.

Summary

The following illustration hopefully provides a more memorable way of representing the structure of paths:

URL
Protocol, host, port Path
Path without query Query
Path without path info Path info
Processed virtual path info Virtual path info
http://www.python.org /folder/application /resource /operation ? a=1&b=2