Service#

class ansys.dynamicreporting.core.Service(ansys_version: int = None, docker_image: str = 'ghcr.io/ansys-internal/nexus', data_directory: str = None, db_directory: str = None, port: int = 8000, logfile: str = None, ansys_installation: str | None = None)#

Bases: object

Provides for creating a connection to an Ansys Dynamic Reporting service.

Parameters:

ansys_versionint, optional: Three-digit format for a locally installed Ansys version. For example, 232 for Ansys 2023 R2. The default is None.
docker_imagestr, optional: Docker image to use if you do not have a local Ansys installation. The default is "ghcr.io/ansys-internal/nexus".
data_directorystr, optional: Path to the directory for storing temporary information from the Docker image. The default is creating a new directory inside the OS temporary directory. This parameter must pass a directory that exists and is empty.
db_directorystr, optional: Path to the database directory for the Ansys Dynamic Reporting service. The default is None. This parameter must pass a directory that exists and is empty.
portint, optional: Port to run the Ansys Dynamic Reporting service on. The default is 8000.
logfilestr, optional: File to write logs to. The default is None. Acceptable values are filenames or stdout for standard output.
ansys_installationstr, optional: Path to the directory where Ansys is installed locally. If Ansys is not installed locally but is to be run in a Docker image, set the value for this paraemter to "docker".

Raises:

DatabaseDirNotProvidedError: The "db_directory" argument has not been provided when using a Docker image.
CannotCreateDatabaseError: Can not create the "db_directory" when using a Docker image.
InvalidAnsysPath: The "ansys_installation" does not correspond to a valid Ansys installation. directory
AnsysVersionAbsentError: Can not find the Ansys version number from the installation directory.

Examples

Initialize the class and connect to an Ansys Dynamic Reporting service running on the localhost on port 8010 with username set to "admin" and password set to "mypsw" using a local Ansys installation:

import ansys.dynamicreporting.core as adr
installation_dir = r'C:\Program Files\ANSYS Inc\v232'
adr_service = adr.Service(ansys_installation = installation_dir)
ret = adr_service.connect(url = "http://localhost:8010", username = "admin", password = "mypsw")

Methods

`Service.connect`([url, username, password, ...])	Connect to a running service.
`Service.create_item`([obj_name, source])	Create an item that gets automatically pushed into the database.
`Service.delete`(items)	Delete objects from the database.
`Service.get_list_reports`([r_type])	Get a list of top-level reports in the database.
`Service.get_report`(report_name)	Get a `Report` item that corresponds to a report in the database with a given name.
`Service.load_templates`(json_file_path)	Load templates given a JSON-formatted file.
`Service.query`([query_type, filter, item_filter])	Query the database.
`Service.start`([username, password, ...])	Start a new service.
`Service.stop`()	Stop the service connected to the session.
`Service.visualize_report`([report_name, ...])	Render the report.

Attributes

`Service.session_guid`	GUID of the session associated with the service.
`Service.url`	URL for the service.

connect(url: str = 'http://localhost:8000', username: str = 'nexus', password: str = 'cei', session: str | None = '') → None#

Connect to a running service.

Parameters:

urlstr, optional: URL for the service. The default is http://localhost:8000.
usernamestr, optional: Username for the service. The default is "nexus".
passwordstr, optional: Password for the service. The default is "cei".
sessionstr, optional: GUID for the session to work with. The default is "", in which case a new session with its own GUID is created. All created items are then pushed on this session. Visualizations are all filtered so that only items for this session are shown.

Raises:

NotValidServer: The current Service doesn not have a valid server associated to it.

Examples

import ansys.dynamicreporting.core as adr
adr_service = adr.Service(ansys_installation = r'C:\Program Files\ANSYS Inc\v232')
ret = adr_service.connect(url="http://localhost:8010", username='admin', password = 'mypsw')

create_item(obj_name: str | None = 'default', source: str | None = 'ADR') → Item#

Create an item that gets automatically pushed into the database.

Parameters:

obj_namestr, optional: Name of the item. The default is "default".
sourcestr, optional: Name of the source to generate the item from. The default is "ADR", which is Ansys Dynamic Reporting.

Returns:

Object: Item object.

Examples

import ansys.dynamicreporting.core as adr
adr_service = adr.Service(ansys_installation = r'C:\Program Files\ANSYS Inc\v232')
ret = adr_service.connect()
my_img = adr_service.create_item()

delete(items: list) → None#

Delete objects from the database.

Parameters:

itemslist: List of objects to delete. The objects can be of one of these types: "Item", Report, "Session" or Dataset.

Note

Deleting a session or a dataset also deletes all items associated with the session or dataset. Deleting a Report also deletes all its children.

Examples

import ansys.dynamicreporting.core as adr
adr_service = adr.Service(ansys_installation=r'C:\Program Files\ANSYS Inc\v232')
adr_service.connect(url='http://localhost:8020')
all_items = adr_service.query(type='Item')
adr_service.delete(all_items)
my_report = adr_service.get_report(report_name='My Report')
adr_service.delete([my_report])

get_list_reports(r_type: str | None = 'name') → list#

Get a list of top-level reports in the database.

This method can get either a list of the names of the top-level reports or a list of Report items corresponding to these reports.

Parameters:

r_typestr, optional: Type of object to return. The default is "name", which returns a list of the names of the reports. If you set the value for this parameter to "report", this method returns a list of the Report items corresponding to these reports.

Returns:

list: List of the top-level reports in the database. The list can be of the names of these reports or the Report items corresponding to these reports.

Raises:

ConnectionToServiceError: There is no ADR service associated with the current object.

Examples

import ansys.dynamicreporting.core as adr
adr_service = adr.Service(ansys_installation=r'C:\Program Files\ANSYS Inc\v232')
adr_service.connect(url='http://localhost:8020')
top_reports = adr_service.get_list_reports()

get_report(report_name: str) → Report#

Get a Report item that corresponds to a report in the database with a given name.

Parameters:

report_namestr: Name of the report in the database. The name must be for a top-level report, not a name of a subsection within a report.

Returns:

Object: Report object. If no such object can be found, None is returned.

Raises:

ConnectionToServiceError: There is no ADR service associated with the current object.
MissingReportError: The service does not have a report with the input name.

Examples

import ansys.dynamicreporting.core as adr
adr_service = adr.Service(ansys_installation=r'C:\Program Files\ANSYS Inc\v232')
adr_service.connect(url='http://localhost:8020')
my_report = adr_service.get_report(report_name = "Top Level Report')

load_templates(json_file_path: str) → None#

Load templates given a JSON-formatted file. There will be some interactive inputs if required.

Parameters:

json_file_pathstr: Path of the JSON file to be loaded.

Returns:

None.

Examples

import ansys.dynamicreporting.core as adr

adr_service = adr.Service(ansys_installation=r'C:\Program Files\ANSYS Inc\v232')
adr_service.connect(url='http://localhost:8020', username = "admin", password = "mypassword")
adr_service.load_templates(r'C:\tmp\my_json_file.json')

query(query_type: str = 'Item', filter: str | None = '', item_filter: str | None = '') → list#

Query the database.

Parameters:

query_typestr, optional: Type of objects to query. The default is "Item". Options are "Item", "Session", and "Dataset".
filterstr, optional: DEPRECATED. Use item_filter instead. Query string for filtering. The default is "". The syntax corresponds to the syntax for Ansys Dynamic Reporting. For more information, see _Query in the documentation for Ansys Dynamic Reporting.
item_filterstr, optional: Query string for filtering. The default is "". The syntax corresponds to the syntax for Ansys Dynamic Reporting. For more information, see _Query in the documentation for Ansys Dynamic Reporting.

Returns:

list: List of queried objects.

Examples

import ansys.dynamicreporting.core as adr
adr_service = adr.Service(ansys_installation = r'C:\Program Files\ANSYS Inc\v232')
ret = adr_service.connect()
imgs = adr_service.query(query_type='Item', item_filter='A|i_type|cont|image;')

property session_guid#: GUID of the session associated with the service.

start(username: str = 'nexus', password: str = 'cei', create_db: bool = False, error_if_create_db_exists: bool = False, exit_on_close: bool = False, delete_db: bool = False) → str#

Start a new service.

Parameters:

usernamestr, optional: Username for the service. The default is "nexus".
passwordstr, optional: Password for the service. The default is "cei".
create_dbbool, optional: Whether to create a new database before starting the service on top of it. The default is False. If True, this method creates a database in the directory specified by the db_directory parameter and starts the service on top of it. An error is raised if the directory specified by the db_directory parameter already exists and is not empty.
error_if_create_db_existsbool, optional: Whether to raise an error if the create_db parameter is set to True and the database already exists. The default is False, in which case the start() method uses the database found instead of creating one.
exit_on_closebool, optional: Whether to automatically shut down the service when exiting the script. The default is False, in which case the service continues to run.
delete_dbbool, optional: Whether to automatically delete the database when exiting the script. The default is False. This parameter is valid only if this parameter and the exit_on_close parameter are set to True.

Returns:

str: ID of the connected session.

Raises:

DatabaseDirNotProvidedError: There is no database directory associated with the Service.
CannotCreateDatabaseError: Error when creating the database.
AlreadyConnectedError: Object is already connected to a running ADR service.
StartingServiceError: Can not start the ADR service.
NotValidServer: Can not validate the current ADR service.

Examples

import ansys.dynamicreporting.core as adr
installation_dir = r'C:\Program Files\ANSYS Inc\v232'
adr_service = adr.Service(ansys_installation = installation_dir,
db_directory = r'D:\tmp\new_db', port = 8020)
session_guid = adr_service.start()

stop() → None#

Stop the service connected to the session.

Examples

import ansys.dynamicreporting.core as adr
installation_dir = r'C:\Program Files\ANSYS Inc\v232'
adr_service = adr.Service(ansys_installation = installation_dir, port = 8020)
session_guid = adr_service.start(username = 'admin', password = 'mypsw',
db_directory ='/tmp/dbase')
adr_service.stop()

property url#: URL for the service.

visualize_report(report_name: str | None = '', new_tab: bool | None = False, filter: str | None = '', item_filter: str | None = '') → None#

Render the report.

Parameters:

report_namestr, optional: Name of the report. the default is "", in which case all items assigned to the session are shown.
new_tabbool, optional: Whether to render the report in a new tab if the current environment is a Jupyter notebook. The default is False, in which case the report is rendered in the current location. If the environment is not a Jupyter notebook, the report is always rendered in a new tab.
filterstr, optional: DEPRECATED. Use item_filter instead. Query string for filtering. The default is "". The syntax corresponds to the syntax for Ansys Dynamic Reporting. For more information, see _Query in the documentation for Ansys Dynamic Reporting.
item_filterstr, optional: Query string for filtering. The default is "". The syntax corresponds to the syntax for Ansys Dynamic Reporting. For more information, see _Query in the documentation for Ansys Dynamic Reporting.

Returns:

Report: Rendered report.

Raises:

ConnectionToServiceError: There is no ADR service associated with the current object.
MissingReportError: The service does not have a report with the input name.

Examples

import ansys.dynamicreporting.core as adr
installation_dir = r'C:\Program Files\ANSYS Inc\v232'
adr_service = adr.Service(ansys_installation = installation_dir)
ret = adr_service.connect()
my_img = adr_service.create_item()
my_img.item_image = 'Image_to_push_on_report'
adr_service.visualize_report()