Skip to main content

Python SDK V1 to V2 Migration Guide

PluginV2 is the current plugin interface of the Python SDK. It runs on the AMP engine through AMPProviderV2. Plugin, informally called V1, targets the original Engine through ProviderBase. Both interfaces are part of ayx_python_sdk. This guide covers a migration between two back-end interfaces in the same SDK, not a move to a different product.

Write new plugins against PluginV2. Existing Plugin-based tools keep running unless you choose to port them.

Class and Import Changes

V1 (Plugin)

V2 (PluginV2)

from ayx_python_sdk.core import Plugin, ProviderBase, InputConnectionBase, register_plugin

from ayx_python_sdk.core import PluginV2, Anchor

class MyTool(Plugin):

class MyTool(PluginV2):

def __init__(self, provider: ProviderBase):

def __init__(self, provider: AMPProviderV2): Import AMPProviderV2 from ayx_python_sdk.providers.amp_provider.amp_provider_v2.

AyxPlugin = register_plugin(MyTool) at module scope.

Removed. The AMP provider finds the PluginV2 subclass directly, so there is no registration call.

The tool configuration XML file (<ToolFolder>Config.xml) doesn’t change in this migration. Both engines load the same <AlteryxJavaScriptPlugin> root, the same EngineDllEntryPoint, and the same SDKVersion. You choose the version with the Python class, not with the configuration schema.

Lifecycle Method Changes

V2 has no equivalent of the V1 on_input_connection_opened method. The SDK now opens anchors and propagates metadata for you, so your code doesn’t make those calls. V2 adds on_incoming_connection_complete, which isn’t a renamed V1 method.

V1

V2

Notes

on_input_connection_opened(self, input_connection: InputConnectionBase)

No direct equivalent.

V1 used this method to open output anchors with cloned metadata (self.output_anchor.open(input_connection.metadata.clone())). V2 propagates metadata automatically, so there is nothing to open.

on_record_packet(self, input_connection: InputConnectionBase)

on_record_batch(self, batch: "pyarrow.Table", anchor: Anchor)

In V1, you call input_connection.read() to get a RecordPacketBase from the connection. In V2, the SDK passes the data to you as a pyarrow.Table. The Anchor named tuple (anchor.name and anchor.connection) identifies the source anchor and connection. It replaces the InputConnectionBase object.

No equivalent. V1 had a connection-open method only, not a completion method.

on_incoming_connection_complete(self, anchor: Anchor)

This method isn’t a renamed on_input_connection_opened. It runs when a connection finishes sending data, including when an optional anchor receives nothing. It doesn’t run when a connection opens. If your V1 code used on_input_connection_opened to set up state for each connection, move that setup into __init__ or into the first on_record_batch call for that anchor.

on_complete(self)

on_complete(self)

The purpose is the same: final cleanup, and the place where an input-type plugin with no incoming connections writes its output.

Writing to an Output Anchor

V1 requires you to open the anchor with metadata before any write. You then write RecordPacketBase instances to it.

 # V1
self.output_anchor = self.provider.get_output_anchor("Output")
self.output_anchor.open(input_connection.metadata.clone())
...
self.output_anchor.write(packet)

V2 reduces this to one call. You write a pyarrow.Table directly, and there is no anchor object to get or open.

 # V2
self.provider.write_to_anchor("Output", table)

If you build the table from a pandas.DataFrame, convert it with pyarrow.Table.from_pandas(df) before you write it. This is a common pattern for plugins that assemble results in memory instead of streaming them.

In V2, setting output metadata is optional. If you set it, do it in __init__, not when the SDK passes you an anchor.

Provider Surface Changes

Most of provider.io and provider.environment carry over unchanged. These behave the same way in both versions: io.info, io.warn, io.translate_msg, io.decrypt_password, update_progress, environment.update_only, environment.designer_version, environment.tool_id, and so on. A few details differ:

  • Plugin configuration: provider.tool_config works in both versions. In V2, it returns the same data as provider.environment.tool_config, so you can keep the V1 call as it is.

  • Temporary files: V1 uses provider.io.create_temp_file(...). V2 uses provider.environment.create_temp_file(...).

  • Anchor lookup: V1 uses provider.get_input_anchor(name) and provider.get_output_anchor(name). V2 uses provider.incoming_anchors[name] and provider.outgoing_anchors[name].

Worked Example: A Passthrough Plugin

A passthrough plugin reads a batch from its input anchor and writes it back out unchanged. This example isolates the anchor and lifecycle changes from any other plugin-specific logic. The V1-to-V2 rewrite touches every point in this guide.

 # V1
from ayx_python_sdk.core import (
    InputConnectionBase,
    Plugin,
    ProviderBase,
    register_plugin,
)


class ConversionPassthrough(Plugin):
    def __init__(self, provider: ProviderBase):
        self.name = "Pass through"
        self.provider = provider
        self.output_anchor = self.provider.get_output_anchor("Output")
        self.provider.io.info(f"{self.name} tool started")

    def on_input_connection_opened(self, input_connection: InputConnectionBase) -> None:
        self.output_anchor.open(input_connection.metadata.clone())

    def on_record_packet(self, input_connection: InputConnectionBase) -> None:
        packet = input_connection.read()
        self.output_anchor.write(packet)

    def on_complete(self) -> None:
        self.provider.io.info(f"{self.name} tool done")


AyxPlugin = register_plugin(ConversionPassthrough)
 # V2
from ayx_python_sdk.core import Anchor, PluginV2
from ayx_python_sdk.providers.amp_provider.amp_provider_v2 import AMPProviderV2

import pyarrow as pa


class ConversionPassthrough(PluginV2):
    def __init__(self, provider: AMPProviderV2):
        self.name = "Pass through"
        self.provider = provider
        self.provider.io.info(f"{self.name} tool started")

    def on_record_batch(self, batch: "pa.Table", anchor: Anchor) -> None:
        df = batch.to_pandas()
        batch_to_send = pa.Table.from_pandas(df=df)
        self.provider.write_to_anchor("Output", batch_to_send)

    def on_incoming_connection_complete(self, anchor: Anchor) -> None:
        self.provider.io.info(f"Connection {anchor.connection} on Anchor {anchor.name}")

    def on_complete(self) -> None:
        self.provider.io.info(f"{self.name} tool done")

Nothing in this example is specific to one plugin. The constructor no longer gets an output anchor. The on_record_batch method receives a pyarrow.Table directly, and the module no longer ends with a register_plugin(...) call.

The round trip through batch.to_pandas() and pa.Table.from_pandas(...) isn’t required for a pure passthrough. The call self.provider.write_to_anchor("Output", batch) does the same thing. The round trip shows the shape that you use when the plugin inspects or transforms the data with pandas before it writes the data back out.

Testing

Both versions test the same way in principle. You construct the plugin against a mock provider, run its lifecycle methods, and check what it wrote and logged. The harness classes differ, and PluginV2 uses SdkToolTestService. For the current harness, go to the Python Test Harness Guide.

Don’t port V1 test fixtures by hand. The way that the tests mock input and output anchors changed along with the anchor API.

Migration Checklist

  1. Swap the base class and the imports (Plugin and ProviderBase to PluginV2 and AMPProviderV2), and delete the register_plugin(...) and AyxPlugin line.

  2. Replace on_input_connection_opened with setup in __init__ or with per-batch setup in on_record_batch. Don’t assume that it maps to on_incoming_connection_complete.

  3. Replace on_record_packet and input_connection.read() with on_record_batch(batch, anchor), and work on batch (a pyarrow.Table) directly.

  4. Replace self.output_anchor.open(...) and self.output_anchor.write(...) with one self.provider.write_to_anchor(name, table) call. Delete the anchor-open step.

  5. Keep provider.tool_config, which still works in V2. Move provider.io.create_temp_file to provider.environment.create_temp_file.

  6. Regenerate your tests against SdkToolTestService instead of porting V1 test fixtures.

  7. Run the plugin again through the test harness, and test it in Designer before you remove the V1 code.