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 ( | V2 ( |
|---|---|
| |
| |
| |
| Removed. The AMP provider finds the |
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 |
|---|---|---|
| No direct equivalent. | V1 used this method to open output anchors with cloned metadata ( |
| | In V1, you call |
No equivalent. V1 had a connection-open method only, not a completion method. | | This method isn’t a renamed |
| | 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_configworks in both versions. In V2, it returns the same data asprovider.environment.tool_config, so you can keep the V1 call as it is.Temporary files: V1 uses
provider.io.create_temp_file(...). V2 usesprovider.environment.create_temp_file(...).Anchor lookup: V1 uses
provider.get_input_anchor(name)andprovider.get_output_anchor(name). V2 usesprovider.incoming_anchors[name]andprovider.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
Swap the base class and the imports (
PluginandProviderBasetoPluginV2andAMPProviderV2), and delete theregister_plugin(...)andAyxPluginline.Replace
on_input_connection_openedwith setup in__init__or with per-batch setup inon_record_batch. Don’t assume that it maps toon_incoming_connection_complete.Replace
on_record_packetandinput_connection.read()withon_record_batch(batch, anchor), and work onbatch(apyarrow.Table) directly.Replace
self.output_anchor.open(...)andself.output_anchor.write(...)with oneself.provider.write_to_anchor(name, table)call. Delete the anchor-open step.Keep
provider.tool_config, which still works in V2. Moveprovider.io.create_temp_filetoprovider.environment.create_temp_file.Regenerate your tests against
SdkToolTestServiceinstead of porting V1 test fixtures.Run the plugin again through the test harness, and test it in Designer before you remove the V1 code.