Python Resources
Python resources are the heart of the functionality of the WebDev module. These resources are completely dynamic, and can handle all parts of the HTTP protocol, formulating any type of response.
Each time an incoming HTTP request arrives at a URL where a Python resource is mounted, the corresponding Python script will be run. Each Python resource can have a script for each HTTP method. In practice, most Python resources will probably only implement one or two of these, usually doGet or doPost at a minimum. The available methods are as follows:
- doGet
- doPost
- doPut
- doDelete
- doHead
- doOptions
- doTrace
- doPatch
Return Value
Return values for each do* functions can generate a response, which should always be a dictionary. In the dictionary, the keys in the table below are recognized. The keys are listed here in the order they are evaluated. For example, if you have both file and bytes, only file will take effect. The exception is the contentType key, which may be included with any of the other keys to override the default content type.
| HTTP Response | Description |
|---|
html | HTML source as a string. The value should be a string, which should be the source of an HTML document. Content type is assumed to be text/html.
|
json | The value is assumed to either be a string (which should be valid json) or to be a Python object, which will then be encoded into a json string. Content type will be application/json. |
file | The value should be a string, which should be the path to a file on the server's filesystem. If no contentType is specified, then the system will attempt to probe the content type from the operating system using java.nio.Files.probeContentType. If the file key is present, but the value points to a file that doesn't exist, an HTTP 404 will be returned. |
bytes | The value should be a byte array. The default content type is application/octet-stream, but you probably want to specify your own. |
response | If none of the other keys are present, the system will look for the key response which will be stringified and then returned with the content type text/plain. |
contentType | The mime type of the response. Needed only if ambiguous. |
If your implementation of the do* function returns a dictionary with none of the above keys, an HTTP 500 error will be returned. However, if you return None, no HTTP 500 error will be returned. In this case, it is assumed that you used the request['servletResponse'] parameter to directly formulate your HTTP response.
This feature was changed in Ignition version 8.1.8:
As of 8.1.8, the default encoding for html, json, and response types was changed to UTF-8. Formerly they used ISO-8859-1.Parameters
Each do* method receives the same two parameters (also called arguments): 'request' and 'session'.
Request Parameter
The request parameter is a dictionary with information about the incoming web request.
| Key | Type | Description |
|---|
context | object | A reference to the Gateway's context object. This provides direct access to the Ignition GatewayContext. More information about this object may be found in the Ignition SDK Programmer's Guide and associated JavaDocs. |
data | plain text or raw byte array | The data on the request. If the content type is application/json, it will be a Python structure (list or dictionary). If not, it will either be plain text or a raw byte array. If the incoming request body was not text, it will be available as a byte array. |
postData | string | This parameter is only present for the doPost method, and its value is different based upon the value of the incoming HTTP request's Content-Type header. If the content type is 'application/json', then the request['postData'] will be a Python dictionary structure which is the result of parsing the JSON document that was posted. If the content type starts with 'text/', then the value of request['postData'] will be the text which was posted, as a string. |
headers | dictionary | A dictionary of header : value pairs. If multiple values were returned for the same header, values will be in a tuple. The HTTP request headers will be in a dictionary under request['headers']. For example, you could read the User-Agent string with request['headers']['User-Agent']. |
params | dictionary | This will be contained in a dictionary accessible via request['params'].
Any URL parameters such as the following:
/system/webdev/project/foo?param1=value¶m2=other_value
For the given example, request['params'] = {'param1':'value', 'param2':'other_value'}. |
remainingPath | string | request['remainingPath'] will be "/bar". Remaining path will be "None" if nothing is found after the resource name. This provides the remaining text after a file resource. If you have a resource called 'foo', and a request is made to:
/system/webdev/project/foo/bar
|
remoteAddr | string | Returns the IP address of the client. Gives the remote IP address of the entity that made the web request.
Note: This is from the perspective of the web server, and so may not be what you expect due to the effects of things like NAT-ing routers.
|
remoteHost | string | Returns the fully qualified name of the client. Gives the remote host of the entity that made the web request.
Note: This is from the perspective of the web server, and so may not be what you expect due to the effects of things like NAT-ing routers.
|
scheme | string | The scheme is available via request['scheme']. The value will be 'http' or 'https'. |
servletRequest | object | The underlying Java HttpServletRequest object. This parameter and the following servletResponse parameter give you direct access to the underlying Java servlet request and response objects. This provides direct access to the Ignition GatewayContext. More information about this object may be found in the Ignition SDK developer guide and associated JavaDocs. |
servletResponse | object | The underlying Java HttpServletResponse object. |
Session Parameter
The session parameter is a Python dictionary which may be used to hold information which persists across multiple different calls to your Web Dev Python Resource, or across multiple Python Resources. Session management is handled automatically, and this dictionary is created for each new client session. (The client must have cookies enabled for sessions to work). You may place any key-value pairs in the session dictionary you'd like, just make sure that the values are things that can be serialized. All normal Python types (scalar, dictionary, lists, and tuples) are serializable.
If authentication is required, will have a 'user' attribute containing information about the authenticated user, and a 'retryAttempts' attribute with the number of attempts made.
