Skip to main content
Windward

Running the RESTful Engine Python Client

Overview

This is a Python client for the Windward RESTful Engine.

NOTE:   Windward provides this client as a courtesy however support is limited to the Windward API only.  Windward does not provide support for the client code.

Documentation

Download the client HERE.

The Python Client for the RESTful Engine reporting service, this module defines the following classes:

  • Report: represents a report and all the options associated with it. An object of this type is also used to retrieve output documents after report is processed.
  • DataSource: represents data sources that are to be used with the template. This class in particular is meant to be an abstract base class of other DataSource classes such as AdoDataSource and XmlDataSource.
  • AdoDataSource: represents SQL-based datasources (using ADO.NET connectors).
  • XmlDataSource: represents file-based datasources, particularly, XML datasources.
  • TemplateVariable: represents variables associated with data sources in templates.
  • Version: used by get_version() to store version information.

Enumerations:

Exception classes:

Functions:

How To Use This Module

  1. Import the module:

    import restfulengine
    

    or:

    from restfulengine import *
    
  2. Create a Report either by using its constructor or calling create_report(). You must specify a service URL, an output format and a template file. If you don’t specify an output file, you are enabling asynchronous operation and later, must call Report.get_report() to retrieve the output:

    report = create_report(base_uri, OutputFormat.pdf, template)
    
  3. Set up DataSource objects and add them to a list. XmlDataSource objects or AdoDataSource objects:

    data_sources = [
        AdoDataSource(
            "MSSQL"
            "System.Data.SqlClient",
            "Data Source=mssql.windward.net;"
            "Initial Catalog=Northwind;"
            "User=demo;Password=demo")
    [
    
  4. Call Report.process() with your data sources to send the request:

    report.process(data_sources)
    
  5. (for async reports) call Report.get_status() to poll the server so you know when the report is done. Then call Report.get_report() to retrieve the output. Finally, call delete when you are done with the report to delete it from the server:

    while report.get_status() == Status.working:
        time.sleep(100)
    
    if report.get_status() == Status.ready:
        output = report.get_report()
        report.delete()
    

Members

restfulengine.report.get_version(base_uri)

Returns the Service and Engine version of the RESTful engine service running at the specified location, or None if no reasonable response was obtained.

Parameters: base_uri (str) – Location of service in URL form. Example: “http://localhost:49731/
Returns: A Version object with the service and engine versions
Return type: Version
 
restfulengine.report.create_report(base_uri, output_format, template, report=None)

Creates a Report object given a RESTful engine service URI and a template to process. If no report parameter is specified, then the report will be created asynchronously.

Parameters:
  • base_uri (str) – URI of RESTful engine service
  • output_format (OutputFormat) – Desired OutputFormat for report.
  • template (file) – A file object with a template to be processed
  • report (file) – A file object to write resulting report to
 
class restfulengine.report.Report(base_uri, output_format, template, report=None)

This class contains several methods and parameters used to create and send a request to a Windward RESTful engine service, and receive and process the response. The RESTful engine service supports asynchronous requests. This will be initiated automatically if a report output file is not specified upon instantiation of the Report object.

There are several options such as description, title, timeout, and hyphenate. When set, these options will be sent to the RESTful engine service with the template. Each of these options is stored as an instance variable. They are all initialized to None in the __init__ constructor.

After instantiation a Report object either through this constructor, or through the modules create_report() method, process() must be called in order to begin the processing. This is where you would also pass in a list of DataSource objects

For asynchronous requests, the output can be retrieved by using the get_report() method, or discarded using the delete() method. While waiting for the service to finish processing the report, the status can be queried with the get_status() method.

Parameters:
  • base_uri (str) – URI of RESTful engine service
  • output_format (OutputFormat) – Desired OutputFormat for report.
  • template (file) – A file object with a template to be processed
  • report (file) – A file object to write resulting report to
output_format = None
Annotation: = Desired report output format
Type: OutputFormat
description = None
Type: str
title = None
Type: str
subject = None
Type: str
keywords = None
Type: str
locale = None
Type: str
timeout = None
Type: int
hyphenate = None
Type: Hyphenation
track_imports = None
Type: bool
remove_unused_formats = None
Type: bool
copy_meta_data = None
Type: CopyMetadataOption
process(data_sources=None)

Puts together and sends the report request to the server. This also takes the data sources to send with the request. If an output file was specified, then this will write the results to that output file. If no output file was specified, then this requests an asynchronous report which can later be retrieved with get_report().

Parameters: data_sources (DataSource[]) – a dict of data sources for this report. The dict keys should correspond to the names of these data sources as used in the corresponding template.
get_status()

For asynchronous reports, this method queries the service for a status on this report. For possible return values, see Status

Returns: Status of this report.
Return type: Status
get_report()

For asynchronous reports, retrieves the finished report from the server.

Returns: A bytestring containing the report file
Return type: bytes
delete()

For asynchronous reports, this method sends a DELETE message to the service, which will subsequently delete this report from the server.

class restfulengine.report.DataSource(name)

A data source to pass to the engine when running the report. This class is meant to be an abstract base class, and therefore some of its interfaces are non-functional (such as the get_json() method) without a subclass implementation.

Parameters: name (str) – Name of this data source. This should match its name in the template.
name = None
Type: str
variables = None
Type: TemplateVariable[]
get_json()

Generates and returns a JSON representation of this data source. This is intended to be used when packaging up all required information for a report request by Report.process() :return: JSON dict of this data source intended for a request :rtype: dict

get_variables_json(json)

Generates and adds to existing JSON a representation of the variables of this data source. This is intended to be used by subclass’ get_json() implementations.

class restfulengine.report.AdoDataSource(name, class_name, connection_string)

DataSource implementation for data sources that support ADO (usually SQL)

Parameters:
  • name (str) – Name of this data source. This should match its name in the template.
  • class_name (str) – Class name this data source should use, e.g. “System.Data.SqlClient” for Microsoft Sql Server.
  • connection_string – Connection string. e.g. “Data Source=mssql.windward.net;Initial Catalog=Northwind; User=demo;Password=demo” would connect you to Windward’s sample database.
get_json()

Generates and returns a JSON representation of this data source. This is intended to be used when packaging up all required information for a report request by Report.process() :return: JSON dict of this data source intended for a request :rtype: dict

class restfulengine.report.XmlDataSource(name='', data=None, uri=None, schema_data=None, schema_uri=None)

DataSource implementation for XML and file-based data sources. This data source must be instantiated with either XML data or a URI from which to retrieve XML data. If both are specified, the data will be used.

Parameters:
  • name (str) – Name of this data source. This should match its name in the template.
  • data (bytes) – XML data as a bytestring.
  • uri (str) – A URI from which to retrieve XML data (such as a web URL or file location) – note, this URI must be accessible from the RESTful service which is being called.
  • schema_data (bytes) – XML data describing a schema to be used with the specified XML data.
  • schema_uri (str) – A URI for schema data. See the description for the uri parameter
get_json()

Generates and returns a JSON representation of this data source. This is intended to be used when packaging up all required information for a report request by Report.process() :return: JSON dict of this data source intended for a request :rtype: dict

class restfulengine.report.TemplateVariable(name, value)

To be added to a data source if template requires variables

Parameters:
  • name (str) – Name of variable (must match variable in template)
  • value (str) – Value to use in this variable when report is run
name = None
Type: str
value = None
Type: str
get_json()

Generates and returns a JSON representation of the variable intended for use by the subclass implementations of DataSource.get_json(). :return: a JSON representation of this variable :rtype: dict

class restfulengine.report.Version(json_resp)

Class intended for use by get_version(). It has two data members, one for the version of each the RESTful service, and the underlying Windward engine. The constructor takes the JSON response returned by a version call to the RESTful engine service, and parses it into a service version and engine version.

Parameters: json_resp (dict) – the response from an HTTP call to version
service_version = None
Type: str
engine_version = None
Type: str
exception restfulengine.report.ReportException(*args)

Exception class for the RESTful engine Python client class

class restfulengine.report.OutputFormat

Enum of the different possible output formats

class restfulengine.report.Status

Enum indicating status of a report

class restfulengine.report.Hyphenation

Enum indicating whether to turn hyphenation on or off

class restfulengine.report.CopyMetadataOption

Enum indicating whether to copy the document metadata to the report

  • Was this article helpful?