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¶

Get the Alteryx install directory.

Returns:: The Alteryx install directory as a Path object.
Return type:: Path

abstract property alteryx_locale¶

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¶

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¶

Get the proxy configuration settings if they exist.

Returns:: Proxy Configuration as set in Designer
Return type:: dict

abstract property tool_id¶

Get the current tool’s workflow ID.

Returns:: Tool’s ID (specified by developer).
Return type:: int

abstract property update_mode¶

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¶

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.
Returns:
Return type:: None

abstract property workflow_dir¶

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[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[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¶

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¶

Get the anchor connections.

Returns:: List of all the connections associated with the anchor.
Return type:: List[InputConnectionBase]

abstract property name¶

Get the name of the input anchor.

Returns:: The name of the input anchor.
Return type:: str

abstract property optional¶

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¶

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¶

Get the maximum number of records per packet.

Returns:: The maximum number of records in a packet.
Return type:: int, optional

abstract property 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¶

Get the connection name.

Returns:: Name of the input connection.
Return type:: str

abstract property progress¶

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¶

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[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¶

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¶: Get the status that indicates if the anchor is open.

abstract property metadata¶: Get the metadata for the anchor.

abstract property name¶

Get the name of the output anchor.

Returns:: The name of the output anchor.
Return type:: str

abstract property num_connections¶

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¶

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¶

Get the DCM object from this provider.

Returns:: An instance of a concrete Dcm object.
Return type:: Dcm

abstract property environment¶

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¶

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

Returns:: An instance of a concrete IO object.
Return type:: IoBase

abstract property logger¶

Get the Logger for the provider.

Returns:: Python logging object.
Return type:: Logger

abstract property tool_config¶: 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¶

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¶

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

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.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¶

Get the Alteryx install directory.

Returns:: The Alteryx install directory as a Path object.
Return type:: Path

abstract property alteryx_locale¶

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¶

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¶

Get the proxy configuration settings if they exist.

Returns:: Proxy Configuration as set in Designer
Return type:: dict

abstract property tool_id¶

Get the current tool’s workflow ID.

Returns:: Tool’s ID (specified by developer).
Return type:: int

abstract property update_mode¶

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¶

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.
Returns:
Return type:: None

abstract property workflow_dir¶

Get the directory for the currently-running workflow.

Returns:: The workflow directory as a Path object.
Return type:: Path

class ayx_python_sdk.core.UpdateMode[source]¶

Bases: enum.Enum

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

FULL = 'Full'¶

NO_UPDATE_MODE = ''¶

QUICK = 'Quick'¶

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.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[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¶

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¶

Get the anchor connections.

Returns:: List of all the connections associated with the anchor.
Return type:: List[InputConnectionBase]

abstract property name¶

Get the name of the input anchor.

Returns:: The name of the input anchor.
Return type:: str

abstract property optional¶

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¶

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¶

Get the maximum number of records per packet.

Returns:: The maximum number of records in a packet.
Return type:: int, optional

abstract property 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¶

Get the connection name.

Returns:: Name of the input connection.
Return type:: str

abstract property progress¶

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¶

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¶

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¶: Get the status that indicates if the anchor is open.

abstract property metadata¶: Get the metadata for the anchor.

abstract property name¶

Get the name of the output anchor.

Returns:: The name of the output anchor.
Return type:: str

abstract property num_connections¶

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¶

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.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¶

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¶

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.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¶

Get the DCM object from this provider.

Returns:: An instance of a concrete Dcm object.
Return type:: Dcm

abstract property environment¶

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¶

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

Returns:: An instance of a concrete IO object.
Return type:: IoBase

abstract property logger¶

Get the Logger for the provider.

Returns:: Python logging object.
Return type:: Logger

abstract property tool_config¶: Get Config XML from this provider.

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