External Python API#
The external Python API is provided by the Python interpreter included in the CEI/Ansys distributions. The Ansys Dynamic Reporting and EnSight installations include the cpython or cpython.bat commands that access this interpreter. This API does not require EnSight to access ADR Nexus servers. It can be used to add data items to an ADR Nexus server, read items from a server for export, generate derivative items to be pushed back into the database or other custom operations.
It should be noted that while this API is independent of EnSight and can be used in an instance of cpython, it can also be used from within the EnSight embedded Python interpreter as a lower-level alternative to the EnSight Python Ansys Dynamic Reporting API.
Startup#
The external Python API is a little different from the EnSight internal Ansys Dynamic Reporting API. The major changes being that the caller must be more aware of the session and dataset items and that some of the other automated mechanisms provided by EnSight are not available.
The following code snippet illustrates how to import the necessary API modules (technically, import requests is not necessary, but some of the API calls are simpler with that module available):
from ansys.dynamicreporting.core.utils import report_remote_server, report_objects
import requests
Simple Example#
This snippet creates a new database, starts an ADR Nexus server, verifies the server and shuts it down. It uses the port=None option to allow the system to find and use a non-conflicting port to run the server on. If needed, the port is returned as part of the URL returned by: serverobj.get_URL().
db_dir = "D:/data/example_database"
report_remote_server.create_new_local_database(None,
directory=db_dir)
serverobj = report_remote_server.Server()
report_remote_server.launch_local_database_server(None,
port=None,
directory=db_dir,
connect=serverobj)
version_number = serverobj.validate()
serverobj.stop_local_server()
Using the External Python API with another CPython installation#
If running from the Python interpreter contained in the Ansys Dynamic Reporting installation, run:
from ansys.dynamicreporting.core.utils import report_remote_server, report_objects
import requests
If running from any other Python interpreter, the import cei should be replaced with code that adds the appropriate paths to the sys.path module. The modules are located in the nexus{XXX}/template_editor directory. For example an Ansys installation might use C:\Program Files\Ansys Inc\v252\CEI\nexus252\template_editor. In this case, the startup sequence needed to use the API from another Python interpreter would be:
import sys
sys.path.append(r'C:\\Program Files\\Ansys Inc\\v252\\CEI\\nexus252')
from template_editor import report_objects
from tempalte_editor import report_remote_server
core.report_remote_server module#
This module includes the interfaces needed to manage ADR Nexus servers.
Module functions#
Many of these functions support Qt integration. The parent option specifies the Qt widget that should be the parent if they are to display any GUI elements. If parent is specified as None, no GUI elements will be presented to the user and the operation will just return an error status.
report_remote_server.launch_local_database_server#
bError = launch_local_database_server(parent,
directory="",
no_directory_prompt=False,
port=8000,
connect=None,
terminate_on_python_exit=False,
delete_db_on_python_exit=False,
username="nexus",
password="cei,
verbose=True,
return_info=None,
raise_exception=False,
use_system_tray=None,
server_timeout=180.0, **kwargs)
This function will try to launch a local ADR Nexus server using the database found in the specified directory on the specified port. If parent is not set None, the function will interact with the user via Qt modal dialogs (parent will be the parent of the dialogs) to select database directory, ports, username and password. One can bypass the prompt to select the server directory using the no_directory_prompt keyword argument.
By default, a launched server will continue to run after the current Python session stops. There is a server method stop_local_server() that can be used to stop the launched server. Otherwise, the terminate_on_python_exit keyword can be set to True to cause the server to be automatically shut down if the current Python interpreter instance exits cleanly.
If the delete_db_on_python_exit argument is also set to True, then once the server is automatically shut down the database directory it was connected to will be deleted.
If the Qt parent is not set to None and the server has not been set to terminate on exit, then the use_system_tray option can be used to cause the server to place a menu in the system tray. This menu will allow for the server to be stopped, the logs to be reviewed and other options.
When launching a server, this function will try to connect to the launched server for some time before assuming the launch has failed. The length of this timeout is specified by the server_timeout keyword.
By default, the function will return True on success or False on failure. If raise_exception is True, the function will raise an exception instead of returning False.
The username and password for the database should be specified using those keywords.
If the connect keyword is specified, it should be an instance of the report_remote_server.Server class. This object will be populated with the launched server details when the function returns. It is a handy way to capture a dynamically selected port.
The port keyword can be set to the specific port number the ADR Nexus server should use. The port keyword may also be set to None, in which case the system will search for an open port on which to start the ADR Nexus server, starting at 8000. If this option is selected, it is critical that the 'connect' keyword be set, otherwise there will be no mechanism for one to know the actual port that was used.
The verbose keyword controls the level of log output generated by the ADR Nexus server and determines if the user is allowed to modify any dynamically selected port number.
In addition to the above mentioned arguments, this method supports all
of the options available to the Ansys Dynamic Reporting Launcher CLI (through **kwargs).
report_remote_server.create_new_local_database#
bError = create_new_local_database(parent,
directory="",
return_info={},
raise_exception=False)
This function will create a new, empty database with the default username and password in the directory specified by the directory keyword. If parent is None, this function will try to create the database and return True on success without presenting any GUI elements. It is very important to set the directory keyword if passing None as the parent. Otherwise, parent should be a Qt widget object that will serve as the parent of modal dialog used to select the directory to contain the new database. The target directory should be empty as this method will insert a media directory, a db.sqlite3 file and a manage.py file. The return_info argument is optional. If a dictionary is passed, information about the created database will be stored in it.
If raise_exception is True, method will throw an error instead of returning the error flag.
report_remote_server.connect_to_server_dialog#
bError = connect_to_server_dialog(parent, server, title=None)
This method presents a dialog to the user with a window title specified by the title keyword that allows the user to enter all of the information needed to connect to an ADR Nexus server. It then attempts to connect to the server and returns True if the connection succeeded. The server argument should be an instance of the report_remote_server.Server class which will be initialized with the entered values. This method can only be called from a PyQt application. You can specify None for the parent, but it will have the same effect as displaying a modal dialog with no parent specified. Do not use this method if your application should not display any GUI.
report_remote_server.Server#
This class provides an interface to the ADR Nexus server. Most of the core API can be accessed via an instance of this class. The Server object has methods for creating instances of data item and template objects.
core.report_objects module#
This module provides the core data items that can be pushed into an Ansys Dynamic Reporting database. This includes the session, dataset and item objects. Generally, these classes should be created using the Server object methods create_item, create_layout, default_dataset and default_session or via one of the Server query methods.
Class hierarchy#
BaseRESTObject - Abstract Ansys Dynamic Reporting REST object interface base class
DatasetREST - Dataset information
SessionREST - Session information
ItemREST - Core data items
TemplateREST - Abstract base class for all template (layout and generator) classes
LayoutREST - Abstract base class for all layout classes
basicREST - Basic column layout class
panelREST - Column layout class with support for pullouts and headers
boxREST - Explicit child layout class
tabsREST - Layout that organizes layout children into tabs
carouselREST - Layout that organizes children into a 'carousel' presentation
sliderREST - Specialized image layout for interactive image review/comparison
footerREST - Page footer layout
headerREST - Page header layout
iteratorREST - Tag-based layout replicator
tagpropsREST - Map item/layout tags into properties
tocREST - Table of contents/figure list layout
reportlinkREST - Cross layout linking
GeneratorREST - Abstract base class for all generator classes
tablemergeREST - Table merge generator for merging multiple tables into a single table
tablereduceREST - Table reduction generator that may collapse rows/columns into aggregated values
tablerowcolumnfilterREST - Table row/column filter generator for removing/organizing table rows and columns
tablevaluefilterREST - Table value filter generator for processing table values
tablesortfilterREST - Table sort/filter generator for re-organizing tables
sqlqueriesREST - SQL query generator for pulling data into the report from external SQL databases
treemergeREST - tree merge generator for merging multiple trees into a single tree
Examples#
A simple example of how this API might be used:
from ansys.dynamicreporting.core.utils import report_remote_server, report_objects
serverobj = report_remote_server.Server(url="http://localhost:8000",
username="nexus", password="cei")
session = serverobj.get_default_session()
session.application = "My Application"
session.version = "10.2"
item = serverobj.create_item(name="Simple header", source="My Python script")
item.set_payload_html("<h1>An Example Header</h1>")
error = serverobj.put_objects([item])
This would start a new session that connects to an ADR Nexus server already running on port 8000 of the local system. The server has a default dataset and a default session object. We change the name and version of the session application before creating a new data item. The data item is populated with some HTML source and then pushed to the server. The put_objects() call will push the item, the session and the dataset objects all to the ADR Nexus server.
A more complex example that generates an ASCII table of three columns representing a username, a version number and a date (as a floating point value):
# core Python modules
from dateutil import parser
import datetime
import random
import requests
import numpy
# Ansys Dynamic Reporting modules
from ansys.dynamicreporting.core.utils import report_remote_server, report_objects
# time values can be represented as double precision counts of seconds from a standard time_base
time_base = datetime.datetime(1970, 1, 1)
def make_time(s):
dt = parser.parse(s)
return (dt - time_base).total_seconds()
# generate a row of random values
def row_gen(start, end):
users = ['bob', 'fred', 'mary', 'jill']
versions = ['1.1', '2.0', '1.3', '1.0']
t0 = make_time(start)
t1 = make_time(end)
return [users[random.randint(0,3)], versions[random.randint(0,3)], t0 + (t1 - t0)*random.random()]
# connect to the default ADR Nexus server (this assumes the server had been started previously
s = report_remote_server.Server("http://localhost:8000", "nexus", "cei")
nrows = 40
ncols = 3
item = s.create_item(name="Text List Example", source="externalAPI", sequence=0)
array = numpy.zeros((nrows, ncols), dtype="\|S20")
for i in range(nrows):
array[i] = row_gen("1/1/2017", "2/1/2017")
item.set_payload_table_values(array,
rowlbls=None,
collbls=["User", "Version", "Date"],
title="January")
item.add_tag('month', 'Jan')
item.add_tag('user_version_example')
if s.put_objects(item) == requests.codes.ok:
print("Success")