Migrating from acceldata-sdk: Overview and New Features

Info

acceldata-sdk-python is the Python SDK for automating catalog, pipeline, policy, and tagging workflows in ADOC. It replaces the legacy acceldata-sdk package and introduces updated method names along with Pydantic-based models for improved validation and developer experience.

Highlights of the New SDK

	Legacy (acceldata-sdk)	New (acceldata-sdk-python)
PyPI package	`acceldata-sdk`	`acceldata-sdk-python`
Import namespace	`acceldata_sdk`	`acceldata`
Client class	`TorchClient`	`AdocClient`
Python version	3.7+	3.10+
Data models	Hand-written classes / dataclasses	OpenAPI-generated Pydantic v2 models + typed resource wrappers
Future development	Maintenance only	All new ADOC API coverage and SDK features

Why Migrate?

1. Stay Aligned with ADOC as the Platform Evolves

Models in acceldata-sdk-python are generated from ADOC OpenAPI specifications. When ADOC adds or changes APIs, the new SDK tracks those changes quickly and with accurate types. The legacy SDK relies on hand-maintained models that lag behind server capabilities.

2. Stronger Typing and Clearer APIs

Pydantic v2 models validate request and response shapes at runtime. Resource wrappers such as PipelineResource, PipelineRunResource, AssetResource, and DatasourceResource expose a consistent to_dict() helper and group related operations on the object they represent.

3. Better Error Handling

The new SDK distinguishes:

APIError: ADOC returned a non-2xx HTTP response (with status-specific subclasses such as NotFoundError).
ApiException: A network or transport failure occurred before a response was received.
AcceldataSdkException: The SDK was used incorrectly, or a workflow-level failure occurred (for example, a policy run that finished with errors when FailOnError is configured).

This distinction makes it easier to decide whether to retry, fix credentials, or change application logic.

4. New Capabilities Are Not Available in the Legacy SDK

Examples of functionality delivered only in acceldata-sdk-python:

Pipeline management: replace_pipeline_tags, and creating a pipeline with tags.
Transient HTTP retries: RetryConfig for policy execution, profiling, and crawlers.

5. Modern Python Baseline

Requiring Python 3.10+ lets the SDK use current language features and depend on actively maintained libraries, including Pydantic v2. Plan your runtime upgrade alongside the package swap.

Support Policy

Acceldata is transitioning customers from the legacy acceldata-sdk package to acceldata-sdk-python.

Package	Status	What to Expect
acceldata-sdk-python	Active development	New ADOC features, API coverage, bug fixes, and improvements are delivered here only.
acceldata-sdk (legacy)	Maintenance mode	Security fixes and compatibility updates for up to three additional releases after the introduction of acceldata-sdk-python as the primary SDK. No new features will be added to the legacy package.

What This Means for You

Start new projects on acceldata-sdk-python.
If your existing integrations run on acceldata-sdk, plan migration within the maintenance window. After the final legacy release, the package no longer receives updates.
New ADOC capabilities, including tags, extended catalog APIs, and pipeline enhancements, are exposed only through acceldata-sdk-python. Staying on the legacy SDK limits access to platform improvements.

Migration Overview

Migration is a dependency and import swap, not a parallel install. Both packages target the same ADOC APIs but use different import paths and model types. Replace the legacy package once your code and tests are updated.

Prerequisites

Upgrade Python to 3.10 or newer.
Align SDK and ADOC versions. Install an acceldata-sdk-python release that matches your ADOC deployment version.
Update dependency files. Replace acceldata-sdk with acceldata-sdk-python in requirements.txt, pyproject.toml, or your lockfile.

Quick Reference: Common Changes

Area	Legacy	New
Install	`pip install acceldata-sdk`	`pip install acceldata-sdk-python`
Client	`from acceldata_sdk.torch_client import TorchClient`	`from acceldata.client.adoc_client import AdocClient`
Timeouts	`torch_connection_timeout_ms`, `torch_read_timeout_ms`	`connection_timeout_ms`, `read_timeout_ms`
Env vars	`TORCH_CONNECTION_TIMEOUT_MS`, `TORCH_READ_TIMEOUT_MS`	`CONNECTION_TIMEOUT_MS`, `READ_TIMEOUT_MS`
Exceptions	`TorchSdkException`	`AcceldataSdkException` (+ specific subclasses)
Pipeline create	`CreatePipeline`, `PipelineMetadata`	`CreatePipelineInputRequest`, `Meta`
Job I/O	`Node`	`JobInputOutputRef`
Policy execute	`execute_policy(..., incremental=True)`	`execute_policy(..., PolicyExecutionInput(executionType=PolicyExecutionType.INCREMENTAL))`
Policy status	`get_policy_status`	`get_policy_execution_status`

Before and After: Client Setup

Before (legacy):

from acceldata_sdk.torch_client import TorchClient client = TorchClient( url="https://<your-adoc-url>", access_key="<access-key>", secret_key="<secret-key>", torch_connection_timeout_ms=10_000, torch_read_timeout_ms=20_000, )

After (new SDK):

from acceldata.client.adoc_client import AdocClient client = AdocClient( url="https://<your-adoc-url>", access_key="<access-key>", secret_key="<secret-key>", connection_timeout_ms=10_000, read_timeout_ms=20_000, )

URL, ACCESS_KEY, and SECRET_KEY environment variables are unchanged when you configure clients from the environment.

Suggested Migration Checklist

Upgrade the runtime to Python 3.10+.
Replace the PyPI dependency and update imports (acceldata_sdk → acceldata, TorchClient → AdocClient).
Rename timeout keyword arguments and environment variables (torch_* → connection_* / read_*).
Update exception imports and handlers (TorchSdkException → AcceldataSdkException).
Refactor pipeline code to use PipelineResource / PipelineRunResource and CreatePipelineInputRequest / CreateJobInput / JobInputOutputRef.
Refactor policy execution to pass PolicyExecutionInput and use rule_type + get_policy_execution_status.
Replace Node / JobMetadata / PipelineMetadata with JobInputOutputRef / Meta.
Run integration tests against a non-production ADOC environment.
Remove acceldata-sdk from lockfiles once validation passes.

Full Migration Guide

For complete before/after mappings covering pipelines, catalog, policies, tags, removed APIs, and Airflow cross-references, see Migration Guide.

SDK Guide

For SDK installation, configuration, and usage examples, see Acceldata SDK for Python (acceldata-sdk-python).

Last updated on

Was this page helpful?