Welcome to RESTful Engine’s documentation!¶

Contents:

Documentation¶

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:

OutputFormat: A list of possible output formats
Status: Possible status codes returned from Report.get_status()
Hyphenation: Values indicating hyphenation settings in report
CopyMetadataOption: Values indicating whether or not to copy document metadata

Exception classes:

ReportException: Exception thrown by Report.process()

Functions:

get_version():
create_report():

How To Use This Module¶

Import the module:

import restfulengine

or:

from restfulengine import *

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 (or URI). 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 = restfulengine.create_report(
    base_uri,
    OutputFormat.pdf,
    template
)
```

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")
]

Call Report.process() with your data sources to send the request:
```
report.process(data_sources)
```
(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.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.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 or string) – A file object with a template to be processed, or a string with a URI reference to the template file. report (file) – A file object to write resulting report to

class restfulengine.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 or string) – A file object with a template to be processed, or a URI pointing to a valid file report (file) – A file object to write resulting report to

output_format = None¶

Annotation:	= Desired report output format
Type:	OutputFormat

datasets = None¶

Annotation:	= Any :py:class:`DataSet`s used by the template
Type:	DataSet[]

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.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.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.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.JsonDataSource(name='', data=None, uri=None, domain=None, username=None, password=None)¶

DataSource implementation for JSON data sources. This data source must be instantiated with either JSON data or a URI from which to retrieve JSON 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) – JSON data as a bytestring.
uri (str) – A URI from which to retrieve JSON data (such as a web URL or file location) – note, this URI must be accessible from the RESTful service which is being called.
domain (str) – A domain name to use to access JSON data source.
username (str) – User credentials to access JSON data source.
password (str) – User credentials to access JSON data source.

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.ODataDataSource(name='', uri=None, version=1, domain=None, username=None, password=None, protocol=<Protocol.identity: 'identity'>)¶

DataSource implementation for OData data sources. This data source must be instantiated with a URI pointing to the OData service.

Parameters:

name (str) – Name of this data source. This should match its name in the template.
uri (str) – A URI from which to retrieve JSON data (such as a web URL or file location) – note, this URI must be accessible from the RESTful service which is being called.
version (int) –
domain (str) – A domain name to use to access JSON data source.
username (str) – User credentials to access JSON data source.
password (str) – User credentials to access JSON data source.
protocol (Protocol) – OData authentication protocol to use. Use Protocol enum.

class Protocol¶

ODataDataSource.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.DataSet(data=None, uri=None)¶

DataSets to be used by templates; for more information, see https://wiki.windward.net/Wiki/03.AutoTag/05.AutoTag_User_Guide/02.Data_Sources/Datasets DataSets must be instantiated with either JSON data or a URI from which to retrieve JSON data. If both are specified, the data will be used.

Parameters:	data (bytes) – DataSet file (.rdlx) data as a bytestring. uri* (str) – A URI from which to retrieve DataSet file (such as a web URL or file location) – note, this URI must be accessible from the RESTful service which is being called.

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

class restfulengine.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.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.ReportException(*args)¶: Exception class for the RESTful engine Python client class

class restfulengine.OutputFormat¶

Enum of the different possible output formats

csv = 'csv'¶

docx = 'docx'¶

html = 'html'¶

pdf = 'pdf'¶

pptx = 'pptx'¶

rtf = 'rtf'¶

xlsx = 'xlsx'¶

class restfulengine.Status¶

Enum indicating status of a report

ready = 1¶

working = 2¶

error = 3¶

not_found = 4¶

class restfulengine.Hyphenation¶

Enum indicating whether to turn hyphenation on or off

on = 'on'¶

off = 'off'¶

template = 'template'¶

class restfulengine.CopyMetadataOption¶

Enum indicating whether to copy the document metadata to the report

if_no_data_source = 'nodatasource'¶

never = 'never'¶

always = 'always'¶

Welcome to RESTful Engine’s documentation!¶

Documentation¶

How To Use This Module¶

Members¶

Table Of Contents

Related Topics

This Page