ayx_python_sdk.core package

Submodules

ayx_python_sdk.core.constants module

Constant definitions.

class ayx_python_sdk.core.constants.Anchor(name, connection)

Bases: tuple

connection

Alias for field number 1

name

Alias for field number 0

ayx_python_sdk.core.dcm_base module

DCM API base class definition.

class ayx_python_sdk.core.dcm_base.DcmBase[source]

Bases: abc.ABC

Dcm base class.

This base class provides API to work with engine’s DCM objects .

abstract free_write_lock(connection_id: str, role: str, secret_type: str, lock_id: str) None[source]

Free a lock obtained from a previous call to get_write_lock().

Parameters
  • connection_id – string with UUID of connection

  • role – A role such as ?oauth?

  • secret_type – A secret type such as ?oauth_token?

  • lock_id – A lock_id acquired from a previous call to get_write_lock()

abstract get_connection(connection_id: str) Dict[source]

Retrieve connection information including secrets by connection ID.

Parameters

connection_id – string with UUID of connection

abstract get_write_lock(connection_id: str, role: str, secret_type: str, expires_in: Optional[datetime.datetime]) Dict[source]

Attempt to acquire an exclusive write lock.

Parameters
  • connection_id – string with UUID of connection

  • role – A role such as ?oauth?

  • secret_type – A secret type such as ?oauth_token?

  • expires_in – (Optional) A DateTime value in which to ask for the lock to be held for in milliseconds. Defaults to 0.

abstract update_connection_secret(connection_id: str, lock_id: str, role: str, secret_type: str, value: str, expires_on: Optional[datetime.datetime], parameters: Optional[Dict[str, str]]) Dict[source]

Update a single secret for role and secret_type to value as well as the optional expires_on and parameters.

Parameters
  • connection_id – A connection ID

  • lock_id – A lock ID acquired from get_write_lock()

  • role – A role such as ?oauth?

  • secret_type – A secret type such as ?oauth_token?

  • value – The new value to store for the secret

  • expires_on – (Optional) DateTime of expiration of this secret

  • parameters – Dict of parameter values for this secret (this is arbitrary user data stored as JSON)

ayx_python_sdk.core.doc_utilities module

Utility functions for documentation.

ayx_python_sdk.core.doc_utilities.inherit_docs(cls: Type) Type[source]

Inherit the documentation from parent classes if it doesn’t exist on methods.

Parameters

cls – The child class that inherits its parent’s documentation.

Returns

Child class with documentation.

Return type

Type

ayx_python_sdk.core.environment_base module

Runtime Environment information.

class ayx_python_sdk.core.environment_base.EnvironmentBase[source]

Bases: abc.ABC

Environment Information class definition.

This class provides information about the runtime environment of the tool that is running. For example, if it is running as update only, the version of the system running, etc.

abstract property alteryx_install_dir: pathlib.Path

Get the Alteryx install directory.

Returns

The Alteryx install directory as a Path object.

Return type

Path

abstract property alteryx_locale: Literal['en', 'it', 'fr', 'de', 'ja', 'es', 'pt', 'zh']

Retrieve the locale code from Alteryx Designer User Settings.

Returns

The language/region that Alteryx is using to display messages.

Return type

Locale

abstract property designer_version: str

Return the version of Designer that is being used.

Returns

A version in the format of 1.2.3.4

Return type

str

abstract get_settings_conf(keys: list, version_override: str = '') dict[source]

Parse xml to retrieve settings.

abstract parse_settings_key_value(settings_str: str, line_delimiter: str = '\n', key_delimiter: str = '=') dict[source]

Extract a key value pair from an xml text entry set by Designer.

abstract property proxy_configuration: dict

Get the proxy configuration settings if they exist.

Returns

Proxy Configuration as set in Designer

Return type

dict

abstract property tool_id: int

Get the current tool’s workflow ID.

Returns

Tool’s ID (specified by developer).

Return type

int

abstract property update_mode: ayx_python_sdk.core.environment_base.UpdateMode

Get the type of update running.

Returns

Enumeration corresponding to the update mode that the workflow is running in.

Return type

UpdateMode

abstract property update_only: bool

Check if the engine is running in update-only mode.

Returns

Boolean value that indicates if the engine is running in update only.

Return type

bool

abstract update_tool_config(new_config: dict) None[source]

Update the tool’s configuration.

Parameters

new_config – The new configuration to set for the tool.

Return type

None

abstract property workflow_dir: pathlib.Path

Get the directory for the currently-running workflow.

Returns

The workflow directory as a Path object.

Return type

Path

class ayx_python_sdk.core.environment_base.UpdateMode(value)[source]

Bases: enum.Enum

The types of update modes that can run in Alteryx Designer.

FULL = 'Full'
NO_UPDATE_MODE = ''
QUICK = 'Quick'

ayx_python_sdk.core.exceptions module

Exception class definition.

exception ayx_python_sdk.core.exceptions.AnchorNotFoundException[source]

Bases: Exception

Exception for when a requested anchor can’t be found for the tool.

class ayx_python_sdk.core.exceptions.DcmEError(message: str, error_code: int, detail: str = '')[source]

Bases: object

Class for storage of DcmE error information.

exception ayx_python_sdk.core.exceptions.DcmEException(msg: str, error: ayx_python_sdk.core.exceptions.DcmEError)[source]

Bases: Exception

Class for exception happened during DcmE transactions.

exception ayx_python_sdk.core.exceptions.WorkflowRuntimeError(msg: str)[source]

Bases: Exception

Exception for a workflow runtime error.

ayx_python_sdk.core.field module

Record Field class definition.

class ayx_python_sdk.core.field.Field(name: str, field_type: ayx_python_sdk.core.field.FieldType, size: int = 0, scale: int = 0, source: Optional[str] = None, description: Optional[str] = None)[source]

Bases: object

A record field that contains metadata like field name.

as_arrow_metadata() dict[source]

Return dict representation of the field using ayx keys.

class ayx_python_sdk.core.field.FieldType(value)[source]

Bases: enum.Enum

Field types.

See AyxData/include/AyxData/dc/common/FieldType.h C++ enumeration.

blob = 16
bool = 1
byte = 2
date = 13
datetime = 15
double = 8
fixeddecimal = 6
float = 7
int16 = 3
int32 = 4
int64 = 5
spatialobj = 17
string = 9
time = 14
v_string = 11
v_wstring = 12
wstring = 10

ayx_python_sdk.core.input_anchor_base module

Input Anchor Interface class definition.

class ayx_python_sdk.core.input_anchor_base.InputAnchorBase[source]

Bases: abc.ABC

Input Anchor Interface class definition.

abstract property allow_multiple: bool

Get the status that indicates if multiple connections are allowed.

Returns

Boolean value that indicates if multiple connections are allowed.

Return type

bool

abstract property connections: List[ayx_python_sdk.core.input_connection_base.InputConnectionBase]

Get the anchor connections.

Returns

List of all the connections associated with the anchor.

Return type

List[InputConnectionBase]

abstract property name: str

Get the name of the input anchor.

Returns

The name of the input anchor.

Return type

str

abstract property optional: bool

Get the status that indicates if the input anchor is optional.

Returns

Boolean value that indicates if input anchor is optional.

Return type

bool

ayx_python_sdk.core.input_connection_base module

Input Connection Base class definition.

class ayx_python_sdk.core.input_connection_base.InputConnectionBase[source]

Bases: abc.ABC

Input connection that receives data from upstream tools.

abstract property anchor: InputAnchorBase

Get the anchor this input connection is associated with.

Returns

The anchor this input connection is associated with.

Return type

InputAnchorBase

property max_packet_size: Optional[int]

Get the maximum number of records per packet.

Returns

The maximum number of records in a packet.

Return type

int, optional

abstract property metadata: Optional[Metadata]

Get the connection metadata.

Returns

The metadata associated with this input connection.

This returns None when accessed before the input connection has been opened, since the metadata isn’t known until that point.

Return type

Metadata, optional

abstract property name: str

Get the connection name.

Returns

Name of the input connection.

Return type

str

abstract property progress: float

Get the progress percentage of records received on this input connection.

Returns

The progress percentage of the connection.

Return type

float

abstract read() RecordPacketBase[source]

Read a record packet from the incoming connection.

Returns

A record packet that contains the data received by this connection.

Return type

RecordPacketBase

property status: ayx_python_sdk.core.input_connection_base.InputConnectionStatus

Get the current state of the input connection.

Returns

Enum value corresponding to the state of the input connection

CREATED = 1 INITIALIZED = 2 RECEIVING_RECORDS = 3 CLOSED = 4

Return type

InputConnectionStatus

class ayx_python_sdk.core.input_connection_base.InputConnectionStatus(value)[source]

Bases: enum.IntEnum

Enumeration for connection state.

CLOSED = 4
CREATED = 1
INITIALIZED = 2
RECEIVING_RECORDS = 3

ayx_python_sdk.core.io_base module

IO (input/output) utility functions for reading from and writing to Alteryx Designer.

class ayx_python_sdk.core.io_base.IoBase[source]

Bases: abc.ABC

IO Base class definition.

abstract create_temp_file(extension: str = 'tmp', options: int = 0) Path[source]

Create a temporary file managed by Alteryx Designer.

Parameters
  • extension – The extension of the new file.

  • options

    Lifecycle management options for the temp file.

    0: A normal temp file. It is cleaned up by Designer when a Run completes.

    1: A temp file for a GUI element, like a browse, that the GUI is responsible for cleaning up.

    2: A temp file for a GUI element, like a browse, that the GUI is responsible for cleaning up. Additionally, the file name is not made to be unique. Use when the extension argument already contains a unique ID.

Returns

Path to the new temp file.

Return type

Path

abstract decrypt_password(password: str) str[source]

Decrypt password.

Parameters

password – Password to decrypt.

Returns

Decrypted password.

Return type

str

abstract error(error_msg: str) None[source]

Display an error message in the Alteryx Designer Results window.

Parameters

error_msg – A string to show as an error in the Designer Results window.

abstract info(info_msg: str) None[source]

Display an info message in the Alteryx Designer Results window.

Parameters

info_msg – A string to show as an info message in the Designer Results window.

abstract translate_msg(msg: str, *args: Any) str[source]

Translate a message to the current locale.

Deprecated since version 0.1.0a: translate_msg is not the recommended translation mechanism. Refer to the documentation on localization.

Parameters
  • msg – A string to translate.

  • args – Arguments for string interpolation.

Returns

The translated string.

Return type

str

abstract update_progress(percent: float) None[source]

Update tool progress.

Parameters

percent – A number between 0 and 100 to indicate the progress percentage.

abstract warn(warn_msg: str) None[source]

Display a warning message in the Alteryx Designer Results window.

Parameters

warn_msg – A string to show as a warning in the Designer Results window.

ayx_python_sdk.core.metadata module

Defines a class for record metadata.

class ayx_python_sdk.core.metadata.Metadata(fields: Optional[List[ayx_python_sdk.core.field.Field]] = None)[source]

Bases: object

Record Metadata class.

This metadata is received by input connections, and written to output anchors. A metadata object is a composition of ordered Field objects.

add_field(name: str, field_type: ayx_python_sdk.core.field.FieldType, size: int = 0, scale: int = 0, source: str = '', description: str = '') ayx_python_sdk.core.field.Field[source]

Add a field to the record metadata.

Parameters
  • name – The name of the field.

  • field_type – The type of data that the field represents.

  • size

    The size of the data.

    For strings, this is the maximum number of characters. For blobs, this is the maximum number of bytes.

  • scale – The scale of the data. This only applies to fixeddecimal type.

  • source – The source of the data.

  • description – A description about the data that lives in this field.

Returns

The field that was added to the metadata.

Return type

Field

clone() ayx_python_sdk.core.metadata.Metadata[source]

Make a deep copy of the record info.

Returns

A copy of this metadata object.

Return type

Metadata

ayx_python_sdk.core.observable_mixin module

Observable Mixin class definition.

class ayx_python_sdk.core.observable_mixin.ObservableMixin[source]

Bases: object

Mixin to make an object observable.

An observable object has 3 new methods available on it: subscribe, subscribe_all, and notify_topic.

notify_topic(topic: Any, **payload: Any) None[source]

Notify a topic of an event.

This calls any callbacks that have been registered to listen for notifications to this topic. The payload can be any assortment of key-value pairs.

Parameters
  • topic – The topic to notify.

  • **payload – Any assortment of key-value pairs to give to the callback functions.

subscribe(topic: Any, callback: Callable) None[source]

Subscribe to a topic.

The callback for this subscription is called any time the topic is published to. The arguments passed to the callable depend on the payload given by notifier.

Parameters
  • topic – The topic to subscribe to. Any time this class notifies this topic, the callback function is called.

  • callback – The callback function to call when the given topic is notified of an event.

subscribe_all(callback: Callable) None[source]

Subscribe to all topics.

The callback for this subscription is called any time any topic is published to. The arguments passed to the callable depend on the payload given by notifier.

Parameters

callback – The callback function to call when any topic is notified of an event.

ayx_python_sdk.core.output_anchor_base module

Output Anchor Description implementation.

class ayx_python_sdk.core.output_anchor_base.OutputAnchorBase[source]

Bases: abc.ABC

Output Anchor Base class definition.

abstract property allow_multiple: bool

Get the status that indicates if multiple connections are allowed.

Returns

Boolean value that indicates if multiple connections are allowed.

Return type

bool

abstract close() None[source]

Close the outgoing connection.

abstract flush() None[source]

Flush the written records for this output connection.

abstract property is_open: bool

Get the status that indicates if the anchor is open.

abstract property metadata: Optional[Metadata]

Get the metadata for the anchor.

abstract property name: str

Get the name of the output anchor.

Returns

The name of the output anchor.

Return type

str

abstract property num_connections: int

Get the number of connections attached to the anchor.

Returns

The number of downstream connections on this anchor.

Return type

int

abstract open(metadata: Metadata) None[source]

Open the output anchor.

Write the outgoing record metadata and open this connection for outgoing packets.

Parameters

metadata – The metadata to set for this anchor.

abstract property optional: bool

Get the status that indicates if the output anchor is optional.

Returns

Boolean value that indicates if output anchor is optional.

Return type

bool

abstract update_progress(percentage: float) None[source]

Update the progress on downstream connections.

Parameters

percentage – The percentage to write to Designer, that indicates the progress of output on this anchor.

abstract write(record_packet: RecordPacketBase) None[source]

Write a RecordPacket to the outgoing connection.

Parameters

record_packet – The record packet to write to the output anchor.

ayx_python_sdk.core.plugin module

The Abstract Base class definition for plugins.

For a custom plugin, a user will inherit from Plugin and implement all of the abstract methods.

class ayx_python_sdk.core.plugin.Plugin(provider: ProviderBase)[source]

Bases: abc.ABC

The Abstract Base class for Plugin.

abstract on_complete() None[source]

Clean up any plugin resources, or push records for an input tool.

This method gets called when all other plugin processing is complete.

This method IS NOT called during update-only mode.

In this method, a Plugin designer should perform any cleanup for their plugin. However, if the plugin is an input-type tool (it has no incoming connections), processing (record generation) should occur here.

Note: A tool with an optional input anchor and no incoming connections should also write any records to output anchors here.

abstract on_input_connection_opened(input_connection: InputConnectionBase) None[source]

Process an opened input connection.

The method that gets called whenever an input connection is opened.

When an input connection is opened, it receives metadata. Prior to being opened, its metadata is None.

This method IS called during update-only mode.

In this method, a Plugin designer should make sure to open any output anchors during update-only mode in order to ensure that metadata is properly propagated in Designer.

Parameters

input_connection – The input connection that was opened.

abstract on_record_packet(input_connection: InputConnectionBase) None[source]

Process any incoming records.

The method that gets called whenever an input connection receives records.

This method IS NOT called during update-only mode.

In this method, a Plugin designer should read from the input connection and process the record packet that it produces.

Parameters

input_connection – The input connection that received a record.

ayx_python_sdk.core.plugin_v2 module

The Abstract Base class definition for plugins.

For a custom plugin, a user will inherit from Plugin and implement all of the abstract methods.

class ayx_python_sdk.core.plugin_v2.PluginV2(provider: AMPProviderV2)[source]

Bases: abc.ABC

The Abstract Base class for Plugin.

abstract on_complete() None[source]

Clean up any plugin resources, or push records for an input tool.

This method gets called when all other plugin processing is complete.

In this method, a Plugin designer should perform any cleanup for their plugin. However, if the plugin is an input-type tool (it has no incoming connections), processing (record generation) should occur here.

Note: A tool with an optional input anchor and no incoming connections should also write any records to output anchors here.

abstract on_incoming_connection_complete(anchor: ayx_python_sdk.core.constants.Anchor) None[source]

Call when an incoming connection is done sending data including when no data is sent on an optional input anchor.

This method IS NOT called during update-only mode.

Parameters

anchor – NamedTuple containing anchor.name and anchor.connection_name.

abstract on_record_batch(batch: Table, anchor: ayx_python_sdk.core.constants.Anchor) None[source]

Process the passed record batch.

The method that gets called whenever the plugin receives a record batch on an input.

This method IS NOT called during update-only mode.

Parameters
  • batches – A pyarrow Table containing the received batch.

  • anchor – A namedtuple(‘Anchor’, [‘name’, ‘connection_name’]) containing input connection identifiers.

ayx_python_sdk.core.provider_base module

Record Provider implementation.

Record providers instantiate input and output connections for the tool and pass information along to the record processor.

class ayx_python_sdk.core.provider_base.ProviderBase[source]

Bases: abc.ABC

Record Provider for the tool.

abstract property dcm: Dcm

Get the DCM object from this provider.

Returns

An instance of a concrete Dcm object.

Return type

Dcm

abstract property environment: EnvironmentBase

Get the Environment object from this provider.

Returns

An instance of a concrete Environment object.

Return type

EnvironmentBase

abstract get_input_anchor(name: str) InputAnchorBase[source]

Get an input anchor by name.

Parameters

name – The name of the anchor to get.

Returns

An instance of a concrete InputAnchorBase object with the name requested.

Return type

InputAnchorBase

abstract get_output_anchor(name: str) OutputAnchorBase[source]

Get an output anchor by name.

Parameters

name – The name of the anchor to get.

Returns

An instance of a concrete OutputAnchorBase object with the name requested.

Return type

OutputAnchorBase

abstract property io: IoBase

Get the IO (input/output) object from this provider.

Returns

An instance of a concrete IO object.

Return type

IoBase

abstract property logger: Logger

Get the Logger for the provider.

Returns

Python logging object.

Return type

Logger

abstract property tool_config: Dict

Get Config XML from this provider.

ayx_python_sdk.core.proxy_requests module

Utility module for proxy authentication and configuration.

ayx_python_sdk.core.proxy_requests.create_proxied_session(tool_provider: ProviderBase, use_engine_credentials: bool = True) pypac.api.PACSession[source]

Create and return a requests session for an environment using a proxy.

PACSession will apply any settings found for PAC on the system. If use_engine_credentials is False you must apply your own credentials to the returned session.

ayx_python_sdk.core.record_packet module

Simple Record Packet class definition.

class ayx_python_sdk.core.record_packet.RecordPacket(metadata: ayx_python_sdk.core.metadata.Metadata, df: pd.DataFrame)[source]

Bases: ayx_python_sdk.core.record_packet_base.RecordPacketBase

Simple record packet based on pandas.

This record packet is a generic format based on the pandas dataframe and the Record class.

classmethod from_dataframe(metadata: ayx_python_sdk.core.metadata.Metadata, df: pd.DataFrame) RecordPacket[source]

Build a packet from a dataframe.

Parameters
  • metadata – The metadata for the record packet.

  • df – The dataframe to generate records from.

property metadata: ayx_python_sdk.core.metadata.Metadata

Get the packet metadata.

Returns

The metadata for records contained in the packet.

Return type

Metadata

to_dataframe() pd.DataFrame[source]

Get the packet data as a dataframe.

Returns

The dataframe that contains all records in the packet.

Return type

pd.DataFrame

ayx_python_sdk.core.record_packet_base module

Record Packet Base class definition.

class ayx_python_sdk.core.record_packet_base.RecordPacketBase[source]

Bases: abc.ABC

Abstract class that describes a record packet.

abstract classmethod from_dataframe(metadata: Metadata, df: pd.DataFrame) RecordPacketBase[source]

Set the packet data from a dataframe.

Parameters
  • metadata – The metadata for the records.

  • df – The dataframe to generate records from.

abstract property metadata: Metadata

Get the packet metadata.

Returns

The metadata for records contained in the packet.

Return type

Metadata

to_anonymized_string() str[source]

Return the string representation of a record packet, anonymizing the data within before conversion.

Returns

Unique identifier generated from the data within a record packet.

Return type

str

abstract to_dataframe() pd.DataFrame[source]

Get the packet data as a dataframe.

Returns

The dataframe that contains all records in the packet.

Return type

pd.DataFrame

to_readable_string() str[source]

Return the string representation of a record packet, with a human-readable pandas dataframe.

Returns

Human-readable form of the record packet.

Return type

str

ayx_python_sdk.core.register_plugin module

Function definition for registering a plugin with the SDK.

ayx_python_sdk.core.register_plugin.register_e1_plugin(user_plugin_class: Type[Plugin], version: Optional[str] = None) Type[E1PluginProxy][source]

Register a plugin with the E1 SDK Provider.

Parameters
  • user_plugin_class – Python Plugin to register.

  • version – Version of the tool being used.

Returns

Copy of the passed-in Plugin, subclassed for the E1 Provider.

Return type

E1PluginProxy

ayx_python_sdk.core.register_plugin.register_file_provider_plugin(user_plugin_class: Type[Plugin], version: Optional[str] = None) None[source]

Register a plugin with the File Provider.

Parameters

user_plugin_class – Python Plugin to register.

ayx_python_sdk.core.register_plugin.register_plugin(plugin_class: Type[Plugin], version: Optional[str] = None) Optional[Type[E1PluginProxy]][source]

Register a plugin with the SDK.

The return value of this function should be assigned to a variable called AyxPlugin in the entrypoint to the tool in order for the E1 Python SDK to properly recognize it.

Parameters

plugin_class – Python Plugin to register. This plugin is written using the Python SDK.

Returns

The Plugin, subclassed for the provider that it was registered with.

Return type

E1PluginProxy, optional

ayx_python_sdk.core.testing module

Convenience functions, classes, and fixtures for user-generated unit testing.

ayx_python_sdk.core.testing.BatchTuple

alias of ayx_python_sdk.core.testing.Batchtuple

class ayx_python_sdk.core.testing.SdkToolTestService(plugin_class: Type[ayx_python_sdk.core.plugin_v2.PluginV2], input_anchor_config: Dict[str, Optional[pyarrow.lib.schema]], output_anchor_config: Dict[str, Optional[pyarrow.lib.schema]], config_mock: str)[source]

Bases: object

A minimal in-process client for testing user plugins.

MAPPING = ['NONE', 'INFO', 'WARN', 'ERROR', 'FILEINPUT', 'FILEOUTPUT']
property data_streams: Dict[str, List[pyarrow.lib.RecordBatch]]

Capture any data written via provider.io.write_to_anchor().

The completed stream is represented by a dictionary, typed like so: {

“<Output Anchor name>”: [pa.RecordBatch]

} If provider.io.write_to_anchor is never called, the data_streams attribute should be an empty dictionary.

Returns

A mapping between output anchor names and the corresponding list of RecordBatches written to that output anchor.

Return type

Dict[str, List[pa.RecordBatch]

property io_stream: List[str]

Store any strings sent over through provider.io.

This is roughly the format the resulting strings follow:

“(INFO|WARN|ERROR):(.*)”

For example, this provider.io call in the plugin code:

self.provider.io.info(“Test Code”)

would show up as “INFO:Test Code” in self.io_stream.

Returns

All strings generated by provider.io calls within the plugin code.

Return type

List[str]

run_on_complete() None[source]

Prepare and run the plugin’s on_complete method, and capture the I/O and data streams.

run_on_incoming_connection_complete(anchor: ayx_python_sdk.core.constants.Anchor) None[source]

Prepare and run the plugin’s on_incoming_connection_complete method, and capture the I/O and data streams.

run_on_record_batch(batch: pyarrow.lib.RecordBatch, anchor: ayx_python_sdk.core.constants.Anchor) None[source]

Prepare and run the plugin’s on_record_batch method, and capture the I/O and data streams.

ayx_python_sdk.core.utils module

Utility functions definitions for plugin SDK.

ayx_python_sdk.core.utils.is_spatial(metadata: pa.Metadata) bool[source]

Return true if the given arrow type is a spatial object (string + ‘ayx’ meta info).

Module contents

Alteryx Python SDK: Core classes and interfaces.

class ayx_python_sdk.core.Anchor(name, connection)

Bases: tuple

connection

Alias for field number 1

name

Alias for field number 0

class ayx_python_sdk.core.DcmBase[source]

Bases: abc.ABC

Dcm base class.

This base class provides API to work with engine’s DCM objects .

abstract free_write_lock(connection_id: str, role: str, secret_type: str, lock_id: str) None[source]

Free a lock obtained from a previous call to get_write_lock().

Parameters
  • connection_id – string with UUID of connection

  • role – A role such as ?oauth?

  • secret_type – A secret type such as ?oauth_token?

  • lock_id – A lock_id acquired from a previous call to get_write_lock()

abstract get_connection(connection_id: str) Dict[source]

Retrieve connection information including secrets by connection ID.

Parameters

connection_id – string with UUID of connection

abstract get_write_lock(connection_id: str, role: str, secret_type: str, expires_in: Optional[datetime.datetime]) Dict[source]

Attempt to acquire an exclusive write lock.

Parameters
  • connection_id – string with UUID of connection

  • role – A role such as ?oauth?

  • secret_type – A secret type such as ?oauth_token?

  • expires_in – (Optional) A DateTime value in which to ask for the lock to be held for in milliseconds. Defaults to 0.

abstract update_connection_secret(connection_id: str, lock_id: str, role: str, secret_type: str, value: str, expires_on: Optional[datetime.datetime], parameters: Optional[Dict[str, str]]) Dict[source]

Update a single secret for role and secret_type to value as well as the optional expires_on and parameters.

Parameters
  • connection_id – A connection ID

  • lock_id – A lock ID acquired from get_write_lock()

  • role – A role such as ?oauth?

  • secret_type – A secret type such as ?oauth_token?

  • value – The new value to store for the secret

  • expires_on – (Optional) DateTime of expiration of this secret

  • parameters – Dict of parameter values for this secret (this is arbitrary user data stored as JSON)

class ayx_python_sdk.core.EnvironmentBase[source]

Bases: abc.ABC

Environment Information class definition.

This class provides information about the runtime environment of the tool that is running. For example, if it is running as update only, the version of the system running, etc.

abstract property alteryx_install_dir: pathlib.Path

Get the Alteryx install directory.

Returns

The Alteryx install directory as a Path object.

Return type

Path

abstract property alteryx_locale: Literal['en', 'it', 'fr', 'de', 'ja', 'es', 'pt', 'zh']

Retrieve the locale code from Alteryx Designer User Settings.

Returns

The language/region that Alteryx is using to display messages.

Return type

Locale

abstract property designer_version: str

Return the version of Designer that is being used.

Returns

A version in the format of 1.2.3.4

Return type

str

abstract get_settings_conf(keys: list, version_override: str = '') dict[source]

Parse xml to retrieve settings.

abstract parse_settings_key_value(settings_str: str, line_delimiter: str = '\n', key_delimiter: str = '=') dict[source]

Extract a key value pair from an xml text entry set by Designer.

abstract property proxy_configuration: dict

Get the proxy configuration settings if they exist.

Returns

Proxy Configuration as set in Designer

Return type

dict

abstract property tool_id: int

Get the current tool’s workflow ID.

Returns

Tool’s ID (specified by developer).

Return type

int

abstract property update_mode: ayx_python_sdk.core.environment_base.UpdateMode

Get the type of update running.

Returns

Enumeration corresponding to the update mode that the workflow is running in.

Return type

UpdateMode

abstract property update_only: bool

Check if the engine is running in update-only mode.

Returns

Boolean value that indicates if the engine is running in update only.

Return type

bool

abstract update_tool_config(new_config: dict) None[source]

Update the tool’s configuration.

Parameters

new_config – The new configuration to set for the tool.

Return type

None

abstract property workflow_dir: pathlib.Path

Get the directory for the currently-running workflow.

Returns

The workflow directory as a Path object.

Return type

Path

class ayx_python_sdk.core.Field(name: str, field_type: ayx_python_sdk.core.field.FieldType, size: int = 0, scale: int = 0, source: Optional[str] = None, description: Optional[str] = None)[source]

Bases: object

A record field that contains metadata like field name.

as_arrow_metadata() dict[source]

Return dict representation of the field using ayx keys.

class ayx_python_sdk.core.FieldType(value)[source]

Bases: enum.Enum

Field types.

See AyxData/include/AyxData/dc/common/FieldType.h C++ enumeration.

blob = 16
bool = 1
byte = 2
date = 13
datetime = 15
double = 8
fixeddecimal = 6
float = 7
int16 = 3
int32 = 4
int64 = 5
spatialobj = 17
string = 9
time = 14
v_string = 11
v_wstring = 12
wstring = 10
class ayx_python_sdk.core.InputAnchorBase[source]

Bases: abc.ABC

Input Anchor Interface class definition.

abstract property allow_multiple: bool

Get the status that indicates if multiple connections are allowed.

Returns

Boolean value that indicates if multiple connections are allowed.

Return type

bool

abstract property connections: List[ayx_python_sdk.core.input_connection_base.InputConnectionBase]

Get the anchor connections.

Returns

List of all the connections associated with the anchor.

Return type

List[InputConnectionBase]

abstract property name: str

Get the name of the input anchor.

Returns

The name of the input anchor.

Return type

str

abstract property optional: bool

Get the status that indicates if the input anchor is optional.

Returns

Boolean value that indicates if input anchor is optional.

Return type

bool

class ayx_python_sdk.core.InputConnectionBase[source]

Bases: abc.ABC

Input connection that receives data from upstream tools.

abstract property anchor: InputAnchorBase

Get the anchor this input connection is associated with.

Returns

The anchor this input connection is associated with.

Return type

InputAnchorBase

property max_packet_size: Optional[int]

Get the maximum number of records per packet.

Returns

The maximum number of records in a packet.

Return type

int, optional

abstract property metadata: Optional[Metadata]

Get the connection metadata.

Returns

The metadata associated with this input connection.

This returns None when accessed before the input connection has been opened, since the metadata isn’t known until that point.

Return type

Metadata, optional

abstract property name: str

Get the connection name.

Returns

Name of the input connection.

Return type

str

abstract property progress: float

Get the progress percentage of records received on this input connection.

Returns

The progress percentage of the connection.

Return type

float

abstract read() RecordPacketBase[source]

Read a record packet from the incoming connection.

Returns

A record packet that contains the data received by this connection.

Return type

RecordPacketBase

property status: ayx_python_sdk.core.input_connection_base.InputConnectionStatus

Get the current state of the input connection.

Returns

Enum value corresponding to the state of the input connection

CREATED = 1 INITIALIZED = 2 RECEIVING_RECORDS = 3 CLOSED = 4

Return type

InputConnectionStatus

class ayx_python_sdk.core.IoBase[source]

Bases: abc.ABC

IO Base class definition.

abstract create_temp_file(extension: str = 'tmp', options: int = 0) Path[source]

Create a temporary file managed by Alteryx Designer.

Parameters
  • extension – The extension of the new file.

  • options

    Lifecycle management options for the temp file.

    0: A normal temp file. It is cleaned up by Designer when a Run completes.

    1: A temp file for a GUI element, like a browse, that the GUI is responsible for cleaning up.

    2: A temp file for a GUI element, like a browse, that the GUI is responsible for cleaning up. Additionally, the file name is not made to be unique. Use when the extension argument already contains a unique ID.

Returns

Path to the new temp file.

Return type

Path

abstract decrypt_password(password: str) str[source]

Decrypt password.

Parameters

password – Password to decrypt.

Returns

Decrypted password.

Return type

str

abstract error(error_msg: str) None[source]

Display an error message in the Alteryx Designer Results window.

Parameters

error_msg – A string to show as an error in the Designer Results window.

abstract info(info_msg: str) None[source]

Display an info message in the Alteryx Designer Results window.

Parameters

info_msg – A string to show as an info message in the Designer Results window.

abstract translate_msg(msg: str, *args: Any) str[source]

Translate a message to the current locale.

Deprecated since version 0.1.0a: translate_msg is not the recommended translation mechanism. Refer to the documentation on localization.

Parameters
  • msg – A string to translate.

  • args – Arguments for string interpolation.

Returns

The translated string.

Return type

str

abstract update_progress(percent: float) None[source]

Update tool progress.

Parameters

percent – A number between 0 and 100 to indicate the progress percentage.

abstract warn(warn_msg: str) None[source]

Display a warning message in the Alteryx Designer Results window.

Parameters

warn_msg – A string to show as a warning in the Designer Results window.

class ayx_python_sdk.core.Metadata(fields: Optional[List[ayx_python_sdk.core.field.Field]] = None)[source]

Bases: object

Record Metadata class.

This metadata is received by input connections, and written to output anchors. A metadata object is a composition of ordered Field objects.

add_field(name: str, field_type: ayx_python_sdk.core.field.FieldType, size: int = 0, scale: int = 0, source: str = '', description: str = '') ayx_python_sdk.core.field.Field[source]

Add a field to the record metadata.

Parameters
  • name – The name of the field.

  • field_type – The type of data that the field represents.

  • size

    The size of the data.

    For strings, this is the maximum number of characters. For blobs, this is the maximum number of bytes.

  • scale – The scale of the data. This only applies to fixeddecimal type.

  • source – The source of the data.

  • description – A description about the data that lives in this field.

Returns

The field that was added to the metadata.

Return type

Field

clone() ayx_python_sdk.core.metadata.Metadata[source]

Make a deep copy of the record info.

Returns

A copy of this metadata object.

Return type

Metadata

class ayx_python_sdk.core.OutputAnchorBase[source]

Bases: abc.ABC

Output Anchor Base class definition.

abstract property allow_multiple: bool

Get the status that indicates if multiple connections are allowed.

Returns

Boolean value that indicates if multiple connections are allowed.

Return type

bool

abstract close() None[source]

Close the outgoing connection.

abstract flush() None[source]

Flush the written records for this output connection.

abstract property is_open: bool

Get the status that indicates if the anchor is open.

abstract property metadata: Optional[Metadata]

Get the metadata for the anchor.

abstract property name: str

Get the name of the output anchor.

Returns

The name of the output anchor.

Return type

str

abstract property num_connections: int

Get the number of connections attached to the anchor.

Returns

The number of downstream connections on this anchor.

Return type

int

abstract open(metadata: Metadata) None[source]

Open the output anchor.

Write the outgoing record metadata and open this connection for outgoing packets.

Parameters

metadata – The metadata to set for this anchor.

abstract property optional: bool

Get the status that indicates if the output anchor is optional.

Returns

Boolean value that indicates if output anchor is optional.

Return type

bool

abstract update_progress(percentage: float) None[source]

Update the progress on downstream connections.

Parameters

percentage – The percentage to write to Designer, that indicates the progress of output on this anchor.

abstract write(record_packet: RecordPacketBase) None[source]

Write a RecordPacket to the outgoing connection.

Parameters

record_packet – The record packet to write to the output anchor.

class ayx_python_sdk.core.Plugin(provider: ProviderBase)[source]

Bases: abc.ABC

The Abstract Base class for Plugin.

abstract on_complete() None[source]

Clean up any plugin resources, or push records for an input tool.

This method gets called when all other plugin processing is complete.

This method IS NOT called during update-only mode.

In this method, a Plugin designer should perform any cleanup for their plugin. However, if the plugin is an input-type tool (it has no incoming connections), processing (record generation) should occur here.

Note: A tool with an optional input anchor and no incoming connections should also write any records to output anchors here.

abstract on_input_connection_opened(input_connection: InputConnectionBase) None[source]

Process an opened input connection.

The method that gets called whenever an input connection is opened.

When an input connection is opened, it receives metadata. Prior to being opened, its metadata is None.

This method IS called during update-only mode.

In this method, a Plugin designer should make sure to open any output anchors during update-only mode in order to ensure that metadata is properly propagated in Designer.

Parameters

input_connection – The input connection that was opened.

abstract on_record_packet(input_connection: InputConnectionBase) None[source]

Process any incoming records.

The method that gets called whenever an input connection receives records.

This method IS NOT called during update-only mode.

In this method, a Plugin designer should read from the input connection and process the record packet that it produces.

Parameters

input_connection – The input connection that received a record.

class ayx_python_sdk.core.PluginV2(provider: AMPProviderV2)[source]

Bases: abc.ABC

The Abstract Base class for Plugin.

abstract on_complete() None[source]

Clean up any plugin resources, or push records for an input tool.

This method gets called when all other plugin processing is complete.

In this method, a Plugin designer should perform any cleanup for their plugin. However, if the plugin is an input-type tool (it has no incoming connections), processing (record generation) should occur here.

Note: A tool with an optional input anchor and no incoming connections should also write any records to output anchors here.

abstract on_incoming_connection_complete(anchor: ayx_python_sdk.core.constants.Anchor) None[source]

Call when an incoming connection is done sending data including when no data is sent on an optional input anchor.

This method IS NOT called during update-only mode.

Parameters

anchor – NamedTuple containing anchor.name and anchor.connection_name.

abstract on_record_batch(batch: Table, anchor: ayx_python_sdk.core.constants.Anchor) None[source]

Process the passed record batch.

The method that gets called whenever the plugin receives a record batch on an input.

This method IS NOT called during update-only mode.

Parameters
  • batches – A pyarrow Table containing the received batch.

  • anchor – A namedtuple(‘Anchor’, [‘name’, ‘connection_name’]) containing input connection identifiers.

class ayx_python_sdk.core.ProviderBase[source]

Bases: abc.ABC

Record Provider for the tool.

abstract property dcm: Dcm

Get the DCM object from this provider.

Returns

An instance of a concrete Dcm object.

Return type

Dcm

abstract property environment: EnvironmentBase

Get the Environment object from this provider.

Returns

An instance of a concrete Environment object.

Return type

EnvironmentBase

abstract get_input_anchor(name: str) InputAnchorBase[source]

Get an input anchor by name.

Parameters

name – The name of the anchor to get.

Returns

An instance of a concrete InputAnchorBase object with the name requested.

Return type

InputAnchorBase

abstract get_output_anchor(name: str) OutputAnchorBase[source]

Get an output anchor by name.

Parameters

name – The name of the anchor to get.

Returns

An instance of a concrete OutputAnchorBase object with the name requested.

Return type

OutputAnchorBase

abstract property io: IoBase

Get the IO (input/output) object from this provider.

Returns

An instance of a concrete IO object.

Return type

IoBase

abstract property logger: Logger

Get the Logger for the provider.

Returns

Python logging object.

Return type

Logger

abstract property tool_config: Dict

Get Config XML from this provider.

class ayx_python_sdk.core.RecordPacket(metadata: ayx_python_sdk.core.metadata.Metadata, df: pd.DataFrame)[source]

Bases: ayx_python_sdk.core.record_packet_base.RecordPacketBase

Simple record packet based on pandas.

This record packet is a generic format based on the pandas dataframe and the Record class.

classmethod from_dataframe(metadata: ayx_python_sdk.core.metadata.Metadata, df: pd.DataFrame) RecordPacket[source]

Build a packet from a dataframe.

Parameters
  • metadata – The metadata for the record packet.

  • df – The dataframe to generate records from.

property metadata: ayx_python_sdk.core.metadata.Metadata

Get the packet metadata.

Returns

The metadata for records contained in the packet.

Return type

Metadata

to_dataframe() pd.DataFrame[source]

Get the packet data as a dataframe.

Returns

The dataframe that contains all records in the packet.

Return type

pd.DataFrame

class ayx_python_sdk.core.RecordPacketBase[source]

Bases: abc.ABC

Abstract class that describes a record packet.

abstract classmethod from_dataframe(metadata: Metadata, df: pd.DataFrame) RecordPacketBase[source]

Set the packet data from a dataframe.

Parameters
  • metadata – The metadata for the records.

  • df – The dataframe to generate records from.

abstract property metadata: Metadata

Get the packet metadata.

Returns

The metadata for records contained in the packet.

Return type

Metadata

to_anonymized_string() str[source]

Return the string representation of a record packet, anonymizing the data within before conversion.

Returns

Unique identifier generated from the data within a record packet.

Return type

str

abstract to_dataframe() pd.DataFrame[source]

Get the packet data as a dataframe.

Returns

The dataframe that contains all records in the packet.

Return type

pd.DataFrame

to_readable_string() str[source]

Return the string representation of a record packet, with a human-readable pandas dataframe.

Returns

Human-readable form of the record packet.

Return type

str

class ayx_python_sdk.core.UpdateMode(value)[source]

Bases: enum.Enum

The types of update modes that can run in Alteryx Designer.

FULL = 'Full'
NO_UPDATE_MODE = ''
QUICK = 'Quick'
ayx_python_sdk.core.register_plugin(plugin_class: Type[Plugin], version: Optional[str] = None) Optional[Type[E1PluginProxy]][source]

Register a plugin with the SDK.

The return value of this function should be assigned to a variable called AyxPlugin in the entrypoint to the tool in order for the E1 Python SDK to properly recognize it.

Parameters

plugin_class – Python Plugin to register. This plugin is written using the Python SDK.

Returns

The Plugin, subclassed for the provider that it was registered with.

Return type

E1PluginProxy, optional