Guidelines for Writing Python Scripts to be Used With WebFOCUS

The following Python script, named arithmetic_example.py contains a function named adder that adds two numbers and conforms to the requirements described in this section.

# arithmetic_example.py
 
import csv
 
 
def adder(csvin, csvout):
 
    with open(csvin,  'r', newline='') as file_in,\
         open(csvout, 'w', newline='') as file_out:
 
        fieldnames = ['addition']
 
        reader = csv.DictReader(file_in, quoting=csv.QUOTE_NONNUMERIC)
 
        writer = csv.DictWriter(file_out, quoting=csv.QUOTE_NONNUMERIC,
                                fieldnames=fieldnames)
        writer.writeheader()
 
        for row in reader:
            addition = row['a_number'] + row['another_number']
			
            writer.writerow({'addition': addition})

A Python script must conform to the following requirements in order to be compatible with WebFOCUS.

csv module requirement. The script must import the csv module because WebFOCUS sends data to the Python script using an automatically generated, temporary .csv file. The name of the file is stored in a global Python variable named csvin. The global Python variable csvout contains the name of the temporary .csv results file to be returned to WebFOCUS. WebFOCUS sets the values for csvin and csvout, and they should not be changed by the programmer. The temporary files are removed immediately and cannot be viewed by the user. The format of both files is the same. The default delimiter is a comma (,) and cannot be changed. All non-numeric fields are enclosed in double quotation marks.
The global variables csvin and csvout are defined by WebFOCUS for reading and writing .csv files.
csvin and csvout format parameter. The script must open csvin and csvout with the following format parameter:
```
newline=''
```
If newline='' is not specified, newlines embedded inside quoted fields will not be interpreted correctly, and on platforms that use \r\n line endings on write, an extra \r will be added.
reader and writer format parameter. The following format parameter should be included in the reader and writer statements, whether you are using reader and writer or DictReader and DictWriter, to enclose non-numeric values in double quotation marks and make it clear which values are numeric (they will be converted to floating point values):
```
quoting=csv.QUOTE_NONNUMERIC
```
This indicates that non-numeric (alphanumeric, text, string, and date) values are enclosed in double quotation marks and that numeric values are not. When csvin is read, all WebFOCUS numeric values will be automatically converted to Python floating-point numbers. If the WebFOCUS COMPUTE defines the returned field as integer, the decimal point and any decimal places will be truncated. In the csvin file, if a non-numeric field contains the double quotation character, it will be doubled by WebFOCUS. Python will correctly parse this because the Dialect.doublequote format parameter of the Python csv module defaults to True.
Output. The function can return multiple output fields. However, each WebFOCUS COMPUTE command can only retrieve a single output field. To retrieve multiple output fields, issue multiple COMPUTE commands. In the call to the PYTHON function, the output argument (the last argument) must match the name of a field in the OUTPUT_DATA segment of the synonym generated for the Python script.
For example, in the following Master File, the output argument is called ADDITION:
```
  SEGMENT=OUTPUT_DATA, SEGTYPE=U, PARENT=INPUT_DATA, $
    FIELDNAME=ADDITION, ALIAS=addition, USAGE=D7.1,
          ACTUAL=STRING,      MISSING=ON,      TITLE='Addition', $
```
Therefore, the last (output) argument name in the call to PYTHON must be ADDITION:
```
COMPUTE Anyname/I5 = PYTHON(synonym_name, anyarg1, anyarg2, ADDITION);
```
The output written to csvout must be a sequence, for example, a list, even for a single field.

For a list containing a single field, the correct syntax is:
```
writer.writerow([result]) 
```
The following syntax is incorrect and will return incorrect values for strings and raise an exception for numeric fields:
```
writer.writerow(result)
```
Functions. The Python script can contain one or more user-defined functions. When the metadata object (synonym) is created for the script, one of these functions must be selected as the starting point for execution of the script. The definition of the user-written function used as the starting point must contain csvin and csvout as the first positional arguments.
Note: Because the Python script will be imported, the following Python programming idiom will be ignored.
```
if __name__ == '__main__':
```
However, including it may be useful for testing outside of WebFOCUS.
Headers. Using a header record listing the field names (instead of using positional index numbers) is not required in the sample input data file when creating the synonym for the Python script or when sending data to and retrieving data from the Python script. However, using header records, and, therefore, field names, in the Python script makes it more readable. The following syntax shows a sample of how to implement headers. In the csv.DictReader statement, use of a header record is implied:
```
fieldnames = ['addition']
        reader = csv.DictReader(file_in, quoting=csv.QUOTE_NONNUMERIC)
        writer = csv.DictWriter(file_out, quoting=csv.QUOTE_NONNUMERIC,
                                fieldnames=fieldnames)
        writer.writeheader()
```
The recommendation is to use header records in the input and output .csv files. If you use sample data without a header, the field names in the generated metadata will be of the form FIELD_1 through FIELD_n.

The Adapter for Python also comes with a set or predefined statistical Python functions that you can easily invoke in WebFOCUS.

Reference: Guidelines for Writing Python Scripts to be Used With WebFOCUS