ayx_python_sdk.providers.amp_provider package

Subpackages

Submodules

ayx_python_sdk.providers.amp_provider.amp_dcm module

AMP Provider: Proxy class for DCM API.

class ayx_python_sdk.providers.amp_provider.amp_dcm.AMPDCM[source]

Bases: DcmBase

Class that wraps DCM API work.

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()

get_connection(connection_id: str) Dict[source]

Retrieve connection information including secrets by connection ID.

Parameters:

connection_id – string with UUID of connection

get_write_lock(connection_id: str, role: str, secret_type: str, expires_in: Optional[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.

update_connection_secret(connection_id: str, lock_id: str, role: str, secret_type: str, value: str, expires_on: Optional[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.providers.amp_provider.amp_driver module

AMP Driver class definition.

class ayx_python_sdk.providers.amp_provider.amp_driver.AMPDriver(*args, **kwargs)[source]

Bases: object

The AMP Driver is a class that manages the lifecycle methods of a plugin instance.

clear_state() None[source]

Reset the AMP Driver.

connection_closed_callback(anchor_name: str, connection_name: str) None[source]

Close individual connections.

Parameters:
  • anchor_name (str) – The name of the input anchor associated with the connection to be closed.

  • connection_name (str) – The name of the input connection to be closed.

property ctrl_io: ControlIOBuffer

Get the plugin provider’s io buffer, convenience property.

property environment: AMPEnvironmentV2

Get plugin provider’s environment.

incoming_connection_complete_callback(anchor: NamedTuple) None[source]

Will call when an incoming connection is done sending RecordBatches.

Parameters:
  • anchor_name (The name of the anchor.) –

  • connection_name (The name of the connection.) –

metadata_received(anchor_name: str, connection_name: str) None[source]

Retrieve the input connection, and call plugin’s on_input_connection_initialized method.

Parameters:
  • anchor_name (str) – The name of the input anchor associated with the connection to be initialized.

  • connection_name (str) – The name of the input connection to be retrieved.

on_complete_callback() None[source]

Call plugin’s on_complete method.

property plugin: PluginV2

Get the plugin associated with this driver.

Returns:

The plugin associated with this AMP Driver instance.

Return type:

Plugin

Raises:

ValueError – If the plugin hasn’t been assigned.

record_batch_received(record_msg: pa.Table, anchor: NamedTuple) None[source]

Handle received batch and call plugin’s on_record_batch if a full record is ready.

Parameters:

record_msg (An IncomingRecords message) –

property record_io: StreamIOBuffer

Get plugin providers record buffer, convenience property.

record_packet_received(anchor_name: str, connection_name: str) None[source]

Retrieve input connection, and call plugin’s on_record_packet method.

Parameters:
  • anchor_name (str) – The name of the input anchor associated with the connection to be read from.

  • connection_name (str) – The name of the input connection to be retrieved.

run_user_init() None[source]

Allow running plugin’s init in a non-blocking executor.

ayx_python_sdk.providers.amp_provider.amp_environment module

Proxy Class for managing the SDK environment on Alteryx Multi-threaded Processing (AMP).

class ayx_python_sdk.providers.amp_provider.amp_environment.AMPEnvironment[source]

Bases: EnvironmentBase

Variables that describe the Designer environment when AMP is enabled.

property alteryx_install_dir: Path

Get the Alteryx install directory.

Returns:

The Alteryx install directory as a Path object.

Return type:

Path

property alteryx_locale: Locale

Retrieve the locale code from Alteryx Designer User Settings.

Returns:

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

Return type:

Locale

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

get_settings_conf(*args: list) dict[source]

Parse xml to retrieve settings.

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.

property proxy_configuration: dict

Get the proxy configuration settings if they exist.

Returns:

Proxy Configuration as set in Designer

Return type:

dict

property tool_id: int

Get the current tool’s workflow ID.

Returns:

Tool’s ID (specified by developer).

Return type:

int

property update_mode: UpdateMode

Get the type of update running.

Returns:

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

Return type:

UpdateMode

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

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

property workflow_dir: Path

Get the directory for the currently-running workflow.

Returns:

The workflow directory as a Path object.

Return type:

Path

ayx_python_sdk.providers.amp_provider.amp_environment_v2 module

Proxy Class for managing the SDK environment on Alteryx Multi-threaded Processing (AMP).

class ayx_python_sdk.providers.amp_provider.amp_environment_v2.AMPEnvironmentV2[source]

Bases: EnvironmentBase

Variables that describe the Designer environment when AMP is enabled.

property alteryx_install_dir: Path

Get the directory where designer is stored.

Returns:

The Alteryx install directory as a Path object.

Return type:

Path

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

Get the locale code from Alteryx user settings.

Returns:

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

Return type:

Locale

create_temp_file(extension: str = 'tmp') Path[source]

Create a temporary file managed by Designer.

Parameters:

extension – The file extension of the temp file.

Returns:

The path to where the temp file is.

Return type:

Path

property designer_version: str

Get the version of designer that is running the tool.

Returns:

A version in the format of 1.2.3.4

Return type:

str

get_log_directory() Path[source]

Return the root log directory for the current platform.

get_proxy_configuration() dict[source]
get_settings_conf(*args: list) dict[source]

Parse xml to retrieve settings.

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.

property proxy_configuration: dict

Get the proxy configuration settings if they exist.

Returns:

Proxy Configuration as set in Designer

Return type:

dict

save_engine_constants(constants: Dict[str, str]) None[source]

Save engine constants to repo.

Parameters:

constants – The dictionary of engine constants received through gRPC

save_update_mode(update_mode: int) None[source]

Save the passed in update mode.

Parameters:

update_mode – An int that corresponds to the protobuf enumeration for the update mode that designer is running in.

set_tool_config(config_xml_str: str) None[source]

Parse an xml string to dict form and set the config.

property temp_dir: str

Get the directory where designer-managed temp files are created.

Returns:

The path to the directory where temporary files are stored.

Return type:

str

tool_config: Dict = {}
property tool_id: int

Get the ID of the tool.

Returns:

Tool’s ID (specified by developer).

Return type:

int

property update_mode: UpdateMode

Get the type of tool update running.

Returns:

Enum corresponding to the type of update mode designer is running in. (Quick, Full, No Update)

Return type:

UpdateMode

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

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

property workflow_dir: Path

Get the directory where the workflow is running the tool.

Returns:

The workflow directory as a Path object.

Return type:

Path

property workflow_id: str

Get the WorkflowRunGuid for the currently-running workflow.

Returns:

The workflow id.

Return type:

str

ayx_python_sdk.providers.amp_provider.amp_input_anchor module

AMP Provider: Plugin Input Anchor class definition.

class ayx_python_sdk.providers.amp_provider.amp_input_anchor.AMPInputAnchor(name: str, allow_multiple: bool = False, optional: bool = False, connections: Optional[List[InputConnectionBase]] = None)[source]

Bases: InputAnchorBase

Manage the tool’s input anchor in AMP Provider.

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

property connections: List[InputConnectionBase]

Get the anchor connections.

Returns:

List of all the connections associated with the anchor.

Return type:

List[InputConnectionBase]

property name: str

Get the name of the input anchor.

Returns:

The name of the input anchor.

Return type:

str

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.providers.amp_provider.amp_input_connection module

AMP Provider: Plugin Input Connection class definition.

class ayx_python_sdk.providers.amp_provider.amp_input_connection.AMPInputConnection(name: str, metadata: Metadata, anchor: AMPInputAnchor)[source]

Bases: InputConnectionBase

Manage input connections in AMP Provider.

property anchor: AMPInputAnchor

Get the anchor this input connection is associated with.

Returns:

The anchor this input connection is associated with.

Return type:

InputAnchorBase

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

property name: str

Get the connection name.

Returns:

Name of the input connection.

Return type:

str

property progress: float

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

Returns:

The progress percentage of the connection.

Return type:

float

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: 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

ayx_python_sdk.providers.amp_provider.amp_io module

AMP Provider: Proxy class for SDK IO (input/output).

class ayx_python_sdk.providers.amp_provider.amp_io.AMPIO[source]

Bases: IoBase

Class that wraps all IO with Designer.

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

Create a temporary file managed by Designer.

Deprecated since version AMP: options is not used in AMP because there is no longer a differentiation between temporary persistent and temporary non-persitent files.

decrypt_password(password: str) str[source]

Deprecated since version 1.0.3: This will be removed in 2.0.0. Use functions of provider’s dcm property instead

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.

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.

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

update_progress(percent: float) None[source]

Update tool progress.

Parameters:

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

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.providers.amp_provider.amp_io_components module

AMP Provider: Proxy class for SDK IO (input/output).

class ayx_python_sdk.providers.amp_provider.amp_io_components.Anchor(name, connection)

Bases: tuple

connection

Alias for field number 1

name

Alias for field number 0

class ayx_python_sdk.providers.amp_provider.amp_io_components.ControlIOBuffer[source]

Bases: object

Component Class that wraps all Control IO for the server.

awaiting_response: Dict[str, Callable] = {}
blocking_awaiting_response: Dict[str, Any] = {}
ctrl_driver_actions = <Queue at 0x7fdeb268dd90 maxsize=0>
ctrl_in_callback = <Queue at 0x7fdeb268dc70 maxsize=0>
ctrl_out = <Queue at 0x7fdeb268d7c0 maxsize=0>
ctrl_user_callback_actions = <Queue at 0x7fdeb268ddc0 maxsize=0>
decrypt_password(encrypted_pass: str) str[source]

Decrypt the passed value and return readable.

Deprecated since version 1.0.2: Use functions of provider’s dcm property instead

async dump_queues() None[source]

Dump remaining items in all queues. NOT atomic, and destructive.

error(error_msg: str, *args: Any) None[source]
error_with_priority(priority: int, error_msg: str, *args: Any) None[source]
async flush() None[source]

Shutdown in the safest order possible.

Let workers empty the control out queue to send any remaining processing needs. Wait for any responses to be handled. Let workers empty and handle any responses from the client from ctrl_out queue flush. Let workers finish any pending actions resulting from the above.

free_write_lock(connection_id: str, role: str, secret_type: str, lock_id: str, callback_fn: Optional[Callable] = None) None[source]
get_connection(connection_id: str, callback_fn: Callable) None[source]
get_lock_and_update_secret(connection_id: str, role: str, secret_type: str, value: str, expires_on: Optional[dt.datetime], parameters: Optional[Dict[str, str]], on_complete: Optional[Callable] = None) None[source]

Set up a callback chain to request a lock, update a secret, and then free the lock.

get_write_lock(connection_id: str, role: str, secret_type: str, expires_in: Optional[dt.datetime], callback_fn: Callable) None[source]
info(info_str: str, *args: Any) None[source]
info_with_priority(priority: int, info_msg: str, *args: Any) None[source]
push_callback_action(msg: ControlIn) None[source]

Place the response message and assigned callback on the action queue.

push_ctrl_out(msg: ControlOut, callback_fn: Optional[Callable] = None) None[source]

Push ControlOut to the write queue, notifying server it has something to send.

push_driver_callback(driver_fn: Callable, *args: tuple, **kwargs: dict) Event[source]

Push a driver function and parameters. For callables that do not require a client response as an argument.

translate_msg(source_str: str, *interp_args: list) str[source]

Push the msg to the write queue, and block until response.

translate_msg_use_callback(source_str: str, interp_args: list, callback_fn: Callable) None[source]

Push the msg to the write queue, and assign a reference id for the passed callback.

DOES NOT BLOCK, and only guarantees the callback will be run before plugin shutdown.

update_connection_secret(connection_id: str, role: str, secret_type: str, value: str, expires_on: Optional[dt.datetime], parameters: Optional[Dict[str, str]], lock_id: str, callback_fn: Optional[Callable] = None) None[source]
update_progress(progress: float) None[source]

Push the msg to the write queue, and block until response.

warn(warn_msg: str, *args: Any) None[source]
warn_with_priority(priority: int, warn_msg: str, *args: Any) None[source]
class ayx_python_sdk.providers.amp_provider.amp_io_components.StreamIOBuffer[source]

Bases: object

Defines buffers for RecordTransfer transactions, and provides functions for using them.

completed_streams = <Queue at 0x7fdeb268daf0 maxsize=0>
async dump_queues() None[source]

Dump any remaining items from the queue. NOT atomic, and is destructive.

async flush() None[source]

Flush queues in the safest order we can.

Wait until all streams are received from client, ensuring we call on_record_batch for all sent. Handle any resulting writes from on_record_batch or other methods writing records.

get_stream_msgs(record: Dict) RecordTransferOut[source]

Yield n RecordOut messages with n arrow stream chunks and terminator.

Where: - n is the set chunk size in AmpStreamTransport - terminator is end_of_chunk in RecordOut.OutgoingRecords

pending_writes = <Queue at 0x7fdeb268d550 maxsize=0>
push_close_anchor_msg(name: str) None[source]

Send ControlOut with CloseOutgoingAnchor.

push_record(record: dict) None[source]

Push a arrows RecordBatch or Table to the write queue.

receive_chunk(msg: RecordTransferIn) None[source]

Receive a RecordIn message containing a chunk or full arrows data stream.

transport = <ayx_python_sdk.providers.amp_provider.data_transport.amp_transport.AmpStreamTransport object>
write_to_buffer(name: str, payload: object) None[source]

ayx_python_sdk.providers.amp_provider.amp_output_anchor module

AMP Provider: Plugin Output Anchor class definition.

class ayx_python_sdk.providers.amp_provider.amp_output_anchor.AMPOutputAnchor(name: str, allow_multiple: bool = False, optional: bool = False, num_connections: int = 0)[source]

Bases: OutputAnchorBase

Manage the tool’s output anchor in AMP Provider.

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

close() None[source]

Close the outgoing connection.

flush() None[source]

Flush the written records for this output connection.

property is_open: bool

Get the status that indicates if the anchor is open.

property metadata: Optional[Metadata]

Get the metadata for the anchor.

property name: str

Get the name of the output anchor.

Returns:

The name of the output anchor.

Return type:

str

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

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.

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

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.

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.providers.amp_provider.amp_provider module

AMP Provider: SDK Provider class definition.

class ayx_python_sdk.providers.amp_provider.amp_provider.AMPProvider[source]

Bases: ProviderBase

Class that provides resources to plugins that are run with the AMP Provider.

property dcm: AMPDCM

Get the DCM object from this provider.

Returns:

An instance of a concrete Dcm object.

Return type:

Dcm

property environment: AMPEnvironment

Get the Environment object from this provider.

Returns:

An instance of a concrete Environment object.

Return type:

EnvironmentBase

get_input_anchor(name: str) AMPInputAnchor[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

get_output_anchor(name: str) AMPOutputAnchor[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

property io: AMPIO

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

Returns:

An instance of a concrete IO object.

Return type:

IoBase

property logger: Logger

Get the Logger for the provider.

Returns:

Python logging object.

Return type:

Logger

property tool_config: Dict

Get Config XML from this provider.

ayx_python_sdk.providers.amp_provider.amp_provider_v2 module

AMP Provider: SDK Provider class definition.

class ayx_python_sdk.providers.amp_provider.amp_provider_v2.AMPProviderV2[source]

Bases: object

Class that provides resources to plugins that are run with the AMP Provider.

close_outgoing_anchor(name: str) None[source]
property dcm: ControlIOBuffer
property environment: AMPEnvironmentV2
property io: ControlIOBuffer
push_outgoing_metadata(anchor_name: str, metadata: Schema) None[source]
property record_io: StreamIOBuffer
save_tool_config(tool_config: Dict[str, Any]) None[source]

Encode the tool configuration as a Python dictionary and send it to Designer.

Parameters:

tool_config – Dictionary form of the Tool Config XML.

set_anchors(init_request: ControlIn) None[source]
property tool_config: Dict

Get the tool config from the tool’s config UI in Designer.

Returns:

The Tool Config associated with the current plugin, in the form of a Python dictionary.

Return type:

Dict[str, Any]

write_to_anchor(name: str, data: object) None[source]

ayx_python_sdk.providers.amp_provider.amp_record_packet module

AMP Provider: Record Packet class definition.

class ayx_python_sdk.providers.amp_provider.amp_record_packet.AMPRecordPacket(metadata: Metadata, df: pd.DataFrame)[source]

Bases: RecordPacket

AMP Provider: Record Packet class definition.

ayx_python_sdk.providers.amp_provider.cng_certs module

ayx_python_sdk.providers.amp_provider.grpc_util module

Utility methods and classes for use with gRPC.

class ayx_python_sdk.providers.amp_provider.grpc_util.SocketAddress(host: str, port: int)[source]

Bases: object

Class for tracking host and port information.

property address: str

Get the address string that contains both host and port.

Returns:

address – The address string in the form “host:port”

Return type:

str

classmethod from_address_str(address_str: str) SocketAddress[source]

Construct a socket address from an address string.

Parameters:

address_str (str) – A string consisting of host and port, separated by a colon, such as “localhost:8000”.

Returns:

A new instance of the SocketAddress class.

Return type:

SocketAddress

ayx_python_sdk.providers.amp_provider.grpc_util.build_sdk_engine_client(sdk_engine_address: SocketAddress) SdkToolV2Stub[source]

Build the SDK Engine Client.

Parameters:

sdk_engine_address (SocketAddress) – A socket address that corresponds to the sdk engine.

Returns:

An instance of the SDK Engine client

Return type:

client

ayx_python_sdk.providers.amp_provider.grpc_util.build_sdk_tool_server(sdk_tool_address: str)[source]

Build the SDK Tool Server.

Parameters:

sdk_tool_address (str) – A socket address that corresponds to the sdk tool.

Returns:

  • server – An instance of the SDK Tool Service gRPC server.

  • sdk_tool_address – A copy of the sdk_tool_address parameter, modified to point at server’s open port.

ayx_python_sdk.providers.amp_provider.logger_config module

Logger configuration utilities.

ayx_python_sdk.providers.amp_provider.logger_config.configure_logger() None[source]

Configure the logger for the Python SDK.

ayx_python_sdk.providers.amp_provider.logger_config.get_plugin_logger(plugin_handle: str, root_log_dir: Path) Logger[source]

Configure a file logger for a plugin.

ayx_python_sdk.providers.amp_provider.plugin_class_loader module

Plugin class loader logic.

exception ayx_python_sdk.providers.amp_provider.plugin_class_loader.PluginClassError[source]

Bases: Exception

Plugin class error.

exception ayx_python_sdk.providers.amp_provider.plugin_class_loader.PluginNotFoundError[source]

Bases: Exception

Plugin not found exception.

ayx_python_sdk.providers.amp_provider.plugin_class_loader.load_plugin_class(plugins_package: str, tool_name: str) Type[Plugin][source]

Dynamically load the plugin class.

Parameters:
  • plugins_package (str) – Path to the plugins to load from.

  • tool_name (str) – Name of the tool to load.

Returns:

plugin_class

Return type:

Type[Plugin]

Raises:

ayx_python_sdk.providers.amp_provider.sdk_tool_runner module

Runner for the SDK gRPC lifecycle.

exception ayx_python_sdk.providers.amp_provider.sdk_tool_runner.HandshakeFailedException[source]

Bases: RuntimeError

Exception for when the handshake fails.

class ayx_python_sdk.providers.amp_provider.sdk_tool_runner.SdkToolRunner(sdk_engine_address: str)[source]

Bases: object

Manage gRPC lifecycle for the SDK Plugin.

static handshake_with_sdk_engine_service() ReturnStatus[source]

Run the handshake with the SDK Engine Server.

Returns:

return_status – Whether or not the handshake is successful

Return type:

ReturnStatus

Raises:

HandshakeFailedException – If method cannot connect to the engine service

async start_service() None[source]

Start the SDK Tool Service.

async wait_for_termination() None[source]

Block and wait for the process to terminate.

ayx_python_sdk.providers.amp_provider.sdk_tool_service module

SDK Engine Service grpc class.

class ayx_python_sdk.providers.amp_provider.sdk_tool_service.SdkToolService[source]

Bases: SdkToolServicer

SDK Tool Service GRPC overrides.

ConfirmSdkToolServiceConnection(request, context) Any[source]

Missing associated documentation comment in .proto file.

InitializeSdkPlugin(request, context) Any[source]

Missing associated documentation comment in .proto file.

NotifyIncomingConnectionComplete(request, context) Any[source]

Missing associated documentation comment in .proto file.

NotifyPluginComplete(request, context) Any[source]

Missing associated documentation comment in .proto file.

PushIncomingRecordPacket(request, context) Any[source]

Missing associated documentation comment in .proto file.

ayx_python_sdk.providers.amp_provider.sdk_tool_service_v2 module

Test harness implementation of the SDK Engine service.

class ayx_python_sdk.providers.amp_provider.sdk_tool_service_v2.SdkToolServiceV2[source]

Bases: SdkToolV2Servicer

Implementation of the SDK Engine V2 service.

async Control(request_iterator, context)[source]

Handle Control messages.

Initialize plugin on initialize ControlIn, then send any ControlOut messages to the client as needed, while monitoring for client responses.

async RecordTransfer(request_iterator, context)[source]

Definition for gRPC RecordTransfer.

Consumes any data sent by the client, then send any pending RecordTransferOut messages.

cond_teardown = <asyncio.locks.Condition object at 0x7fde99ceb250 [unlocked]>
curr_driver_fn = None
driver = <ayx_python_sdk.providers.amp_provider.amp_driver.AMPDriver object>
driver_guard: Lock = <asyncio.locks.Lock object at 0x7fde99ce2d90 [unlocked]>
init_data: Future = <Future pending>
logger = <RootLogger root (WARNING)>
ready_for_records: Event = <asyncio.locks.Event object at 0x7fde99ceb2e0 [unset]>
record_batch_received: Event = <asyncio.locks.Event object at 0x7fde99ceb340 [unset]>
record_teardown = <asyncio.locks.Condition object at 0x7fde99ceb2b0 [unlocked]>

Module contents

Alteryx Python SDK: AMP Provider.

class ayx_python_sdk.providers.amp_provider.AMPDriver(*args, **kwargs)[source]

Bases: object

The AMP Driver is a class that manages the lifecycle methods of a plugin instance.

clear_state() None[source]

Reset the AMP Driver.

connection_closed_callback(anchor_name: str, connection_name: str) None[source]

Close individual connections.

Parameters:
  • anchor_name (str) – The name of the input anchor associated with the connection to be closed.

  • connection_name (str) – The name of the input connection to be closed.

property ctrl_io: ControlIOBuffer

Get the plugin provider’s io buffer, convenience property.

property environment: AMPEnvironmentV2

Get plugin provider’s environment.

incoming_connection_complete_callback(anchor: NamedTuple) None[source]

Will call when an incoming connection is done sending RecordBatches.

Parameters:
  • anchor_name (The name of the anchor.) –

  • connection_name (The name of the connection.) –

metadata_received(anchor_name: str, connection_name: str) None[source]

Retrieve the input connection, and call plugin’s on_input_connection_initialized method.

Parameters:
  • anchor_name (str) – The name of the input anchor associated with the connection to be initialized.

  • connection_name (str) – The name of the input connection to be retrieved.

on_complete_callback() None[source]

Call plugin’s on_complete method.

property plugin: PluginV2

Get the plugin associated with this driver.

Returns:

The plugin associated with this AMP Driver instance.

Return type:

Plugin

Raises:

ValueError – If the plugin hasn’t been assigned.

record_batch_received(record_msg: pa.Table, anchor: NamedTuple) None[source]

Handle received batch and call plugin’s on_record_batch if a full record is ready.

Parameters:

record_msg (An IncomingRecords message) –

property record_io: StreamIOBuffer

Get plugin providers record buffer, convenience property.

record_packet_received(anchor_name: str, connection_name: str) None[source]

Retrieve input connection, and call plugin’s on_record_packet method.

Parameters:
  • anchor_name (str) – The name of the input anchor associated with the connection to be read from.

  • connection_name (str) – The name of the input connection to be retrieved.

run_user_init() None[source]

Allow running plugin’s init in a non-blocking executor.

class ayx_python_sdk.providers.amp_provider.AMPEnvironment[source]

Bases: EnvironmentBase

Variables that describe the Designer environment when AMP is enabled.

property alteryx_install_dir: Path

Get the Alteryx install directory.

Returns:

The Alteryx install directory as a Path object.

Return type:

Path

property alteryx_locale: Locale

Retrieve the locale code from Alteryx Designer User Settings.

Returns:

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

Return type:

Locale

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

get_settings_conf(*args: list) dict[source]

Parse xml to retrieve settings.

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.

property proxy_configuration: dict

Get the proxy configuration settings if they exist.

Returns:

Proxy Configuration as set in Designer

Return type:

dict

property tool_id: int

Get the current tool’s workflow ID.

Returns:

Tool’s ID (specified by developer).

Return type:

int

property update_mode: UpdateMode

Get the type of update running.

Returns:

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

Return type:

UpdateMode

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

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

property workflow_dir: Path

Get the directory for the currently-running workflow.

Returns:

The workflow directory as a Path object.

Return type:

Path

class ayx_python_sdk.providers.amp_provider.AMPEnvironmentV2[source]

Bases: EnvironmentBase

Variables that describe the Designer environment when AMP is enabled.

property alteryx_install_dir: Path

Get the directory where designer is stored.

Returns:

The Alteryx install directory as a Path object.

Return type:

Path

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

Get the locale code from Alteryx user settings.

Returns:

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

Return type:

Locale

create_temp_file(extension: str = 'tmp') Path[source]

Create a temporary file managed by Designer.

Parameters:

extension – The file extension of the temp file.

Returns:

The path to where the temp file is.

Return type:

Path

property designer_version: str

Get the version of designer that is running the tool.

Returns:

A version in the format of 1.2.3.4

Return type:

str

get_log_directory() Path[source]

Return the root log directory for the current platform.

get_proxy_configuration() dict[source]
get_settings_conf(*args: list) dict[source]

Parse xml to retrieve settings.

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.

property proxy_configuration: dict

Get the proxy configuration settings if they exist.

Returns:

Proxy Configuration as set in Designer

Return type:

dict

raw_constants: Dict[str, str]
save_engine_constants(constants: Dict[str, str]) None[source]

Save engine constants to repo.

Parameters:

constants – The dictionary of engine constants received through gRPC

save_update_mode(update_mode: int) None[source]

Save the passed in update mode.

Parameters:

update_mode – An int that corresponds to the protobuf enumeration for the update mode that designer is running in.

set_tool_config(config_xml_str: str) None[source]

Parse an xml string to dict form and set the config.

property temp_dir: str

Get the directory where designer-managed temp files are created.

Returns:

The path to the directory where temporary files are stored.

Return type:

str

tool_config: Dict = {}
property tool_id: int

Get the ID of the tool.

Returns:

Tool’s ID (specified by developer).

Return type:

int

property update_mode: UpdateMode

Get the type of tool update running.

Returns:

Enum corresponding to the type of update mode designer is running in. (Quick, Full, No Update)

Return type:

UpdateMode

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

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

property workflow_dir: Path

Get the directory where the workflow is running the tool.

Returns:

The workflow directory as a Path object.

Return type:

Path

property workflow_id: str

Get the WorkflowRunGuid for the currently-running workflow.

Returns:

The workflow id.

Return type:

str

class ayx_python_sdk.providers.amp_provider.AMPIO[source]

Bases: IoBase

Class that wraps all IO with Designer.

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

Create a temporary file managed by Designer.

Deprecated since version AMP: options is not used in AMP because there is no longer a differentiation between temporary persistent and temporary non-persitent files.

decrypt_password(password: str) str[source]

Deprecated since version 1.0.3: This will be removed in 2.0.0. Use functions of provider’s dcm property instead

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.

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.

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

update_progress(percent: float) None[source]

Update tool progress.

Parameters:

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

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.providers.amp_provider.AMPInputAnchor(name: str, allow_multiple: bool = False, optional: bool = False, connections: Optional[List[InputConnectionBase]] = None)[source]

Bases: InputAnchorBase

Manage the tool’s input anchor in AMP Provider.

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

property connections: List[InputConnectionBase]

Get the anchor connections.

Returns:

List of all the connections associated with the anchor.

Return type:

List[InputConnectionBase]

property name: str

Get the name of the input anchor.

Returns:

The name of the input anchor.

Return type:

str

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.providers.amp_provider.AMPInputConnection(name: str, metadata: Metadata, anchor: AMPInputAnchor)[source]

Bases: InputConnectionBase

Manage input connections in AMP Provider.

property anchor: AMPInputAnchor

Get the anchor this input connection is associated with.

Returns:

The anchor this input connection is associated with.

Return type:

InputAnchorBase

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

property name: str

Get the connection name.

Returns:

Name of the input connection.

Return type:

str

property progress: float

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

Returns:

The progress percentage of the connection.

Return type:

float

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: 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.providers.amp_provider.AMPOutputAnchor(name: str, allow_multiple: bool = False, optional: bool = False, num_connections: int = 0)[source]

Bases: OutputAnchorBase

Manage the tool’s output anchor in AMP Provider.

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

close() None[source]

Close the outgoing connection.

flush() None[source]

Flush the written records for this output connection.

property is_open: bool

Get the status that indicates if the anchor is open.

property metadata: Optional[Metadata]

Get the metadata for the anchor.

property name: str

Get the name of the output anchor.

Returns:

The name of the output anchor.

Return type:

str

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

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.

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

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.

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.providers.amp_provider.AMPProvider[source]

Bases: ProviderBase

Class that provides resources to plugins that are run with the AMP Provider.

property dcm: AMPDCM

Get the DCM object from this provider.

Returns:

An instance of a concrete Dcm object.

Return type:

Dcm

property environment: AMPEnvironment

Get the Environment object from this provider.

Returns:

An instance of a concrete Environment object.

Return type:

EnvironmentBase

get_input_anchor(name: str) AMPInputAnchor[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

get_output_anchor(name: str) AMPOutputAnchor[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

property io: AMPIO

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

Returns:

An instance of a concrete IO object.

Return type:

IoBase

property logger: Logger

Get the Logger for the provider.

Returns:

Python logging object.

Return type:

Logger

property tool_config: Dict

Get Config XML from this provider.

class ayx_python_sdk.providers.amp_provider.AMPProviderV2[source]

Bases: object

Class that provides resources to plugins that are run with the AMP Provider.

close_outgoing_anchor(name: str) None[source]
property dcm: ControlIOBuffer
property environment: AMPEnvironmentV2
property io: ControlIOBuffer
push_outgoing_metadata(anchor_name: str, metadata: Schema) None[source]
property record_io: StreamIOBuffer
save_tool_config(tool_config: Dict[str, Any]) None[source]

Encode the tool configuration as a Python dictionary and send it to Designer.

Parameters:

tool_config – Dictionary form of the Tool Config XML.

set_anchors(init_request: ControlIn) None[source]
property tool_config: Dict

Get the tool config from the tool’s config UI in Designer.

Returns:

The Tool Config associated with the current plugin, in the form of a Python dictionary.

Return type:

Dict[str, Any]

write_to_anchor(name: str, data: object) None[source]
class ayx_python_sdk.providers.amp_provider.AMPRecordPacket(metadata: Metadata, df: pd.DataFrame)[source]

Bases: RecordPacket

AMP Provider: Record Packet class definition.

class ayx_python_sdk.providers.amp_provider.ControlIOBuffer[source]

Bases: object

Component Class that wraps all Control IO for the server.

awaiting_response: Dict[str, Callable] = {}
blocking_awaiting_response: Dict[str, Any] = {}
ctrl_driver_actions = <Queue at 0x7fdeb268dd90 maxsize=0>
ctrl_in_callback = <Queue at 0x7fdeb268dc70 maxsize=0>
ctrl_out = <Queue at 0x7fdeb268d7c0 maxsize=0>
ctrl_user_callback_actions = <Queue at 0x7fdeb268ddc0 maxsize=0>
decrypt_password(encrypted_pass: str) str[source]

Decrypt the passed value and return readable.

Deprecated since version 1.0.2: Use functions of provider’s dcm property instead

async dump_queues() None[source]

Dump remaining items in all queues. NOT atomic, and destructive.

error(error_msg: str, *args: Any) None[source]
error_with_priority(priority: int, error_msg: str, *args: Any) None[source]
async flush() None[source]

Shutdown in the safest order possible.

Let workers empty the control out queue to send any remaining processing needs. Wait for any responses to be handled. Let workers empty and handle any responses from the client from ctrl_out queue flush. Let workers finish any pending actions resulting from the above.

free_write_lock(connection_id: str, role: str, secret_type: str, lock_id: str, callback_fn: Optional[Callable] = None) None[source]
get_connection(connection_id: str, callback_fn: Callable) None[source]
get_lock_and_update_secret(connection_id: str, role: str, secret_type: str, value: str, expires_on: Optional[dt.datetime], parameters: Optional[Dict[str, str]], on_complete: Optional[Callable] = None) None[source]

Set up a callback chain to request a lock, update a secret, and then free the lock.

get_write_lock(connection_id: str, role: str, secret_type: str, expires_in: Optional[dt.datetime], callback_fn: Callable) None[source]
info(info_str: str, *args: Any) None[source]
info_with_priority(priority: int, info_msg: str, *args: Any) None[source]
push_callback_action(msg: ControlIn) None[source]

Place the response message and assigned callback on the action queue.

push_ctrl_out(msg: ControlOut, callback_fn: Optional[Callable] = None) None[source]

Push ControlOut to the write queue, notifying server it has something to send.

push_driver_callback(driver_fn: Callable, *args: tuple, **kwargs: dict) Event[source]

Push a driver function and parameters. For callables that do not require a client response as an argument.

translate_msg(source_str: str, *interp_args: list) str[source]

Push the msg to the write queue, and block until response.

translate_msg_use_callback(source_str: str, interp_args: list, callback_fn: Callable) None[source]

Push the msg to the write queue, and assign a reference id for the passed callback.

DOES NOT BLOCK, and only guarantees the callback will be run before plugin shutdown.

update_connection_secret(connection_id: str, role: str, secret_type: str, value: str, expires_on: Optional[dt.datetime], parameters: Optional[Dict[str, str]], lock_id: str, callback_fn: Optional[Callable] = None) None[source]
update_progress(progress: float) None[source]

Push the msg to the write queue, and block until response.

warn(warn_msg: str, *args: Any) None[source]
warn_with_priority(priority: int, warn_msg: str, *args: Any) None[source]
class ayx_python_sdk.providers.amp_provider.StreamIOBuffer[source]

Bases: object

Defines buffers for RecordTransfer transactions, and provides functions for using them.

completed_streams = <Queue at 0x7fdeb268daf0 maxsize=0>
async dump_queues() None[source]

Dump any remaining items from the queue. NOT atomic, and is destructive.

async flush() None[source]

Flush queues in the safest order we can.

Wait until all streams are received from client, ensuring we call on_record_batch for all sent. Handle any resulting writes from on_record_batch or other methods writing records.

get_stream_msgs(record: Dict) RecordTransferOut[source]

Yield n RecordOut messages with n arrow stream chunks and terminator.

Where: - n is the set chunk size in AmpStreamTransport - terminator is end_of_chunk in RecordOut.OutgoingRecords

pending_writes = <Queue at 0x7fdeb268d550 maxsize=0>
push_close_anchor_msg(name: str) None[source]

Send ControlOut with CloseOutgoingAnchor.

push_record(record: dict) None[source]

Push a arrows RecordBatch or Table to the write queue.

receive_chunk(msg: RecordTransferIn) None[source]

Receive a RecordIn message containing a chunk or full arrows data stream.

transport = <ayx_python_sdk.providers.amp_provider.data_transport.amp_transport.AmpStreamTransport object>
write_to_buffer(name: str, payload: object) None[source]