API Reference

This page contains specific information on the polyanalyst6api package classes and methods.

class polyanalyst6api.api.API(url=None, username=None, password=None, ldap_server=None, *, token=None, **kwargs)

PolyAnalyst API

Parameters:

• url (Optional[str]) – The scheme, host and port(if exists) of a PolyAnalyst server (e.g. https://localhost:5043/, http://example.polyanalyst.com)

• username (Optional[str]) – (optional) The username to log in with

• password (Optional[str]) – (optional) The password for specified username

• ldap_server (Optional[str]) – (optional) LDAP Server address

• token (Optional[str]) – (optional) API Token

If ldap_server is provided, then login will be performed via LDAP Server.

Usage:

>>> with API(POLYANALYST_URL, USERNAME, PASSWORD) as api:
...     print(api.get_server_info())

get(endpoint, **kwargs)

Shortcut for GET requests via request

Parameters:

• endpoint (str) – PolyAnalyst API endpoint

• kwargs – requests.request() keyword arguments

Return type:

Any

get_parameters()

Returns list of nodes with parameters supported by Parameters node. :rtype: List[Dict[str, Union[str, List]]]

Deprecated since version 0.18.0: Use Parameters.get() instead.

get_project_import_status(import_id)

Get the status of project import. The status contains UUIDs of projects after import is completed.

Parameters:

import_id (str) – the import identifier

Return type:

Dict

New in version 0.24.0.

get_projects_list()

Get a list of projects.

Raises:

APIException if version of PolyAnalyst older than 2815

Return type:

List[Optional[Dict[str, Union[str, int, bool]]]]

New in version 0.31.0.

get_server_info()

Returns general server information including build number, version and commit hashes.

Return type:

Optional[Dict[str, Union[int, str, Dict[str, str]]]]

get_versions()

Returns api versions supported by PolyAnalyst server.

Return type:

List[str]

import_project(file_path, project_location='', project_space=None, on_conflict='Cancel', wait=False)

Import project from file on server file system.

Parameters:

• file_path (Union[str, PathLike]) – absolute path to the file on server file system

• project_location (str) – the name of the folder in the project manager where you want to import the project. The default folder is Root.

• project_space (Optional[str]) – the name of the physical location in the project manager where you want to import the project. The default space is Projects & reports.

• on_conflict (str) – the strategy to resolve import conflict. Allowed options are: Cancel, Overwrite, ChangeExistingId, ChangeImportingId. By default, the import will be cancelled if the project already exist.

• wait (bool) – wait for project import to finish. False by default.

Return type:

Union[str, Dict]

Returns:

import identifier if wait is False and import status otherwise

New in version 0.24.0.

Changed in version 0.33.0: Added parameter project_space to select project physical location

login()

Logs in to PolyAnalyst with user credentials. :rtype: None

Changed in version 0.32.1: Use self.ldap_server = ‘’ to auto select LDAP server

logout()

Logs out current user from PolyAnalyst

Return type:

None

post(endpoint, **kwargs)

Shortcut for POST requests via request

Parameters:

• endpoint (str) – PolyAnalyst API endpoint

• kwargs – requests.request() keyword arguments

Return type:

Any

project(uuid)

Returns Project instance with given uuid.

Parameters:

uuid (str) – The project uuid

Return type:

Project

report(uuid)

Returns Report instance with given report uuid.

Parameters:

uuid (str) – The report uuid

Return type:

Report

New in version 0.30.0.

request(url, method, **kwargs)

Sends method request to endpoint and returns tuple of requests.Response and json-encoded content of a response.

Parameters:

• url (str) – url or PolyAnalyst API endpoint

• method (str) – request method (e.g. GET, POST)

• kwargs – requests.request() keyword arguments

Return type:

Tuple[Response, Any]

run_task(id)

Starts scheduler task execution.

Parameters:

id (int) – the task ID

Return type:

None

class polyanalyst6api.drive.Drive(api)

create_folder(name, path='')

Create a new folder inside the PolyAnalyst’s user directory.

Parameters:

• name (str) – the folder name

• path (Union[str, PathLike]) – a relative path of the folder’s parent directory

Return type:

None

delete_file(name, path='')

Delete the file in the PolyAnalyst’s user directory.

Parameters:

• name (str) – the filename

• path (Union[str, PathLike]) – a relative path of the file’s parent directory

Return type:

None

delete_folder(name, path='')

Delete the folder in the PolyAnalyst’s user directory.

Parameters:

• name (str) – the folder name

• path (Union[str, PathLike]) – a relative path of the folder’s parent directory

Return type:

None

download_file(name, path='', dest=None)

Download the binary content of the file to memory or stream to local file.

Parameters:

• name (str) – the filename

• path (Union[str, PathLike]) – a relative path of the file’s parent directory

• dest (Optional[IO]) – the file or file-like object to write drive’s file content

Return type:

bytes

Usage::

>>> file_content = api.drive.download_file(name='cars.csv', path='/data')
# The method call above downloads the whole file body into memory. If you're
# planning on downloading big file (more than 100 megabyte sized file),
# consider using the streaming download shown below.
>>> with open('local_file_that_doesnt_exist_yet.csv', 'wb+') as file:
...     api.drive.download_file(name='cars.csv', path='/data', dest=file)

list(path='/', mask='|*.*')

Get a list of files and subdirectories in the PolyAnalyst’s user directory.

Parameters:

• path (str) – a relative path from user’s home folder

• mask (str) – a file name and mask divided by |. For example, |*.* - get all(by default), or |.ps6|README.txt

Return type:

List

Returns:

a list of dictionaries with ‘name’, ‘lastModified’ and ‘size’(only for files) values

New in version 0.36.0.

upload(source, dest='', recursive=True)

Upload file or folder to PolyAnalyst server.

Pass recursive as False to just create folder on the server without uploading inner files and folders.

Parameters:

• source (Union[str, PathLike]) – path to the local file or folder

• dest (str) – (optional) path to the folder in the PolyAnalyst’s user directory

• recursive (bool) – (optional) upload subdirectories recursively

Raises:

TypeError if source is not string or path-like object. ValueError if source does not exist

Return type:

None

upload_file(file, name=None, path='')

Upload the file to the PolyAnalyst’s user directory.

Warning

Make sure to create a new file or file-like object for every Drive.upload_file() call!

Note

Always prefer Drive.upload() over this method.

Parameters:

• file (IO) – the file or file-like object to upload

• name (Optional[str]) – the filename other than file’s name

• path (Union[str, PathLike]) – (optional) a relative path of the file’s parent directory

Return type:

None

Usage::

>>> drive = Drive(...)
>>> with open('CarData.csv', mode='rb') as file:
...     drive.upload_file(file, name='cars.csv', path='/data')

class polyanalyst6api.project.Project(api, uuid)

This class maintains all operations with the PolyAnalyst’s project and nodes.

Parameters:

• api – An instance of API class

• uuid (str) – The uuid of the project you want to interact with

Changed in version 0.31.0: Added nodes list updating while initializing the class

abort()

Aborts the execution of all nodes in the project.

Return type:

None

dataset(node)

Get dataset wrapper object.

Parameters:

node (Union[str, Dict[str, str]]) – node name or dict with name and type of the node

New in version 0.16.0.

delete(force_unload=False)

Delete the project from server.

Parameters:

force_unload (bool) – Delete project regardless other users

Return type:

None

By default, the project will be deleted only if it’s not loaded to memory. To delete the project that loaded to memory (there are users working on this project right now) set force_unload to True. This operation available only for project owner and administrators, and cannot be undone.

execute(*args, wait=False, ignore_first_n_pabusy=0)

Initiates execution of nodes and returns execution wave identifier.

Parameters:

• args (Union[str, Dict[str, str]]) – node names and/or dicts with name and type of nodes

• wait (bool) – wait for nodes execution to complete

• ignore_first_n_pabusy (int) – (deprecated) when waiting for execution to complete skip the first specified numbers of PABusy

Return type:

Optional[int]

Changed in version 0.34.0: Added ignore_first_n_pabusy parameter

Usage:

>>> wave_id = prj.execute('Internet Source', 'Python')

use wait=True to wait for the passed nodes execution to complete.

>>> prj.execute('Export to MS Word', wait=True)

or, if there are several nodes in the project with the same name, pass them as dicts with name and type keys (and because of this, you can also pass items of Project.get_node_list())

>>> prj.execute(
...     {'name': 'Example node', 'type': 'DataSource'},
...     {'name': 'Example node', 'type': 'Dataset'},
...     'Federated Search',
...     prj.get_node_list()[1],
... )

or, if you want to execute all nodes, call this method with no args:

>>> prj.execute()

execute_to(node, wait=False)

Execute a sequence of nodes to the given node.

Similar to Project.execute(), except for two differences:

• accepts only one node

• execution of a sequence of nodes stops at the given node and does not continue further

Parameters:

• node (Union[str, Dict[str, str]]) – node name or a dict with node name and type

• wait (bool) – wait until node is executed

Return type:

Optional[int]

Returns:

execution task identifier if wait is False else None

New in version 0.30.0.

export(file_path, options=None, wait=False)

Export project to a server file system.

Parameters:

• file_path (Union[str, PathLike]) – The path to which you want to export a project. Can be absolute path or contain PolyAnalyst alias, i.e. Open access folder or User home folder. The file extension defines project format: ps6, pa6, psar6, paar6 or pagridar6.

• options (Optional[Dict]) –

  Dict of export parameters: *

  ids: List of project IDs to export into one file: psar6, paar6 or pagridar6. Defaults to current project.

  compressionLevel: Compression level: store, fastest, fast, normal, maximum or ultra. Defaults to normal.

  keepBackups: Keep backup versions. Defaults to True.

  keepMacrosAndVars: Keep user and server macros and variables. Defaults to True.

  keepSliceStatistics: Keep slice usage statistics. Defaults to False.

  overwriteExisting: Replace existing file. Defaults to False.

  dicts: Dict of project dictionaries. Defaults to {}.

  usedDicts: Dict of server-side non-embedded dictionaries. Defaults to {}.

  usedParsers: List of used parsers to include. Defaults to [].

• wait (bool) – Wait until the project export is completed. Defaults to False.

Raises:

ClientException – if compressionLevel is not one of the defined

Return type:

Union[str, Dict[str, Any]]

Returns:

export identifier if wait is False and export status otherwise

Usage:

>>> prj.export('@administrator@/example.pa6')
>>> # or
>>> status = prj.export(
>>>     'C:/Users/Public/Documents/test.paar6',
>>>     {
>>>         'overwriteExisting': True,
>>>         'compressionLevel': 'maximum',
>>>     },
>>>     wait=True
>>> )

New in version 0.28.0.

get_execution_statistics()

Returns the execution statistics for nodes in the project.

Similar to Project.get_nodes() but nodes contains extra information and the project statistics. :rtype: Tuple[Dict[str, Dict[str, Union[str, int]]], Dict[str, int]]

Deprecated since version 0.15.0: Use Project.get_execution_stats() instead.

get_execution_stats(skip_hidden=None)

Returns nodes execution statistics.

Parameters:

skip_hidden (Optional[bool]) – Return statistics only of nodes in the project (i.e. exclude publication and compound nodes).

Return type:

List[Dict[str, Union[str, int]]]

New in version 0.15.0.

Changed in version 0.25.0: Added skip_hidden optional parameter.

get_export_status(export_id)

Get the status of project export

Parameters:

export_id (str) – the export identifier

Return type:

Dict[str, Any]

New in version 0.28.0.

get_node_list()

Returns a list of project nodes. :rtype: List[Dict[str, Union[str, int]]]

New in version 0.15.0.

get_nodes()

Returns a dictionary of project’s nodes information. :rtype: Dict[str, Dict[str, Union[str, int]]]

Deprecated since version 0.15.0: Use Project.get_node_list() instead.

get_report_list()

Returns a list of project reports. :rtype: List[Dict[str, str]]

New in version 0.30.0.

get_tasks()

Returns task list info.

Return type:

List[Dict[str, Any]]

is_running(wave_id)

Checks that execution wave is still running in the project.

If wave_id is -1 then the project is checked against any active execution, saving, publishing operations.

Parameters:

wave_id (int) – Execution wave identifier

Return type:

bool

load(wait=False)

Load project to the memory.

Parameters:

wait (bool) – wait until the project loading is completed. Defaults to False.

Raises:

APIException if version of PolyAnalyst older than 2815

Return type:

Union[str, Dict[str, Any]]

Returns:

load identifier if wait is False and load status otherwise

New in version 0.31.

parameters(name)

Get parameters wrapper object.

Parameters:

name (str) – Parameters node name

New in version 0.18.0.

preview(node)

Returns first 1000 rows of data from node, texts and strings are cutoff after 250 symbols.

Parameters:

node (Union[str, Dict[str, str]]) – node name or dict with name and type of node

Return type:

List[Dict[str, Any]]

Deprecated since version 0.16.0: Use Dataset.preview() instead.

repair()

Initiate the project repairing operation.

Return type:

None

save()

Initiates saving of all changes that have been made in the project.

Return type:

None

set_parameters(node, node_type, parameters, declare_unsync=True, hard_update=True)

Set parameters of the selected Parameters node in the project.

Parameters:

• node (str) – name of Parameters node

• node_type (str) – node type, which parameters need to be set.

• parameters (Dict[str, Any]) – default parameters of the node to be set.

• declare_unsync (bool) – reset the status of the Parameters node.

• hard_update (bool) – update every child node with new parameters if True, otherwise reset their statuses. Works only if declare_unsync is True.

Return type:

None

Deprecated since version 0.18.0: Use Parameters.set() instead.

status()

Get project status.

Raises:

APIException if version of PolyAnalyst older than 2815

Returns:

project status

New in version 0.31.

unload(force_unload=False)

Unload the project from the memory.

From version 0.26.2 this function ensures that the project is unloaded despite PABusy error by repeating requests (maximum 10) until PA either returns an ok response or returns an error ‘the project has not been opened’, which means project is also unloaded.

Raises:

PABusy if PABusy returned for all 10 request attempts

Raises:

APIException if the project has been unloaded before this function was called

Return type:

None

Changed in version 0.30.0: Added force_unload parameter, which when used allows server to unload a project even with running nodes

wait_for_completion(node, wave_id=None)

Waits for the node in a sequence of nodes to complete. Returns True if node have completed successfully and False otherwise.

Unlike execute(…, wait=True), which returns only after an entire node sequence has completed, this method returns immediately after the specified node has completed.

Parameters:

• node (Union[str, Dict[str, str]]) – Node name or dict with name and type of node that runs within execution wave

• wave_id (Optional[int]) – Execution wave identifier

Return type:

bool

Deprecated since version 0.17.0: Use Project.is_running() instead.

Changed in version 0.23.0: Introduced this deprecated method back. Added wave_id argument.

class polyanalyst6api.project.DataSet(prj, node)

get_info()

Get information about dataset.

Return type:

Dict[str, Any]

get_progress()

Get dataset progress.

Return type:

Dict[str, Union[str, int]]

iter_rows(start=0, stop=None)

Iterate over rows in dataset.

Parameters:

• start (int) –

• stop (Optional[int]) –

Raises:

ValueError if start or stop is out of datasets’ row range

Return type:

Iterator[Dict[str, Union[bool, str, int, float, None]]]

Usage:

# download first 10 rows
>>> head = []
>>> for row in ds.iter_rows(0, 10):
...     head.append(row)
# download full dataset and convert it to pandas.DataFrame
>>> table = list(ds.iter_rows())
>>> df = pandas.DataFrame(table)

preview(precision=6, include_blank_cells=False)

Get dataset preview.

Contains the first 1000 rows, string/text are cut off after 250 symbols. By default, numbers are rounded to 6 significant digits and blank cells are omitted.

Parameters:

• precision (int) – (optional) number of significant digits. 6 by default.

• include_blank_cells (bool) – (optional) include blank cells in dataset. False by default.

Raises:

APIException if non-default parameters are used with the old version of server, which doesn’t support them. In this case retry the method with default parameters.

Return type:

List[Dict[str, Any]]

New in version 0.24.0: The precision and include_blank_cells parameters.

class polyanalyst6api.project.Parameters(prj, _id)

clear(*node_types, declare_unsync=True)

Clears parameters and strategies of node_types for the Parameters node. If node_types is empty it clears parameters and strategies of all nodes.

Parameters:

• node_types (List[str]) – node types which parameters needs to be cleared

• declare_unsync (bool) – reset status of the Parameters node

Return type:

Optional[List[str]]

get()

Returns list of nodes with parameters and strategies supported by Parameters node.

set(node_type, parameters, strategies=None, declare_unsync=True, hard_update=True, wait=True)

Sets node_type parameters and strategies for the Parameters node.

If parameters is the list of dictionaries with parameters then /configure-array endpoint is used otherwise /configure.

Parameters:

• node_type (str) – node type which parameters needs to be set

• parameters (Union[Dict[str, str], List[Dict[str, str]]]) – node type parameters

• strategies (Optional[List[int]]) – node type strategies

• declare_unsync (bool) – reset status of the Parameters node. True by default.

• hard_update (bool) – update every child node with new parameters if True, otherwise reset their statuses. Works only if declare_unsync is True. True by default.

• wait (bool) – wait for this node to set parameters for each child node. True by default.

Return type:

Optional[List[str]]

class polyanalyst6api.report.Report(api, uuid)

This class maintains all operations with the PolyAnalyst’s report.

Parameters:

• api – An instance of API class

• uuid (str) – The uuid of the report you want to interact with

New in version 0.30.0.

components()

Return components list info.

Return type:

List[Dict[str, Union[str, int, List[int]]]]

get_slice_statistics()

Get slice statistics.

Return type:

Dict[str, Dict[str, Union[str, Any]]]

Returns:

Slice statistics

import_slice_statistics(slice_stats)

Import slice statistics.

Parameters:

slice_stats (Dict[str, Dict[str, Union[str, Any]]]) – Slice statistics

Return type:

None

publications()

Return publications list info.

Return type:

List[Dict[str, Union[str, int]]]

Exceptions

exception polyanalyst6api.PAException

Generic error class, catch-all for most polyanalyst6api issues.

exception polyanalyst6api.APIException(msg, endpoint=None, status_code=None)

Indicate errors that involve responses from PolyAnalyst’s API.

Parameters:

• msg (str) – The exception message

• endpoint (str) – The resource endpoint

• status_code (int) – The http status code

exception polyanalyst6api.PABusy

exception polyanalyst6api.ClientException

Indicate errors that don’t involve interaction with PolyAnalyst’s API.