From 382edf272163710c93170092322f016b1b95a070 Mon Sep 17 00:00:00 2001 From: saileshwar-skyflow Date: Fri, 22 May 2026 12:49:30 +0530 Subject: [PATCH 1/6] SK-2838: add deprecation banner for v1 readme --- README.md | 4 + docs/migrate_to_v2.md | 244 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 248 insertions(+) create mode 100644 docs/migrate_to_v2.md diff --git a/README.md b/README.md index b64a0bc7..883a9eb2 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # Skyflow-python +> **Python V2.1.0 IS NOW AVAILABLE:** A new, improved version of the Skyflow SDK is ready with flexible authentication, multi-vault support, builder patterns, and richer error diagnostics. V1 is in maintenance mode (security patches only) and will reach End of Life on October 31, 2026. We recommend upgrading to v2.1.0 — see the **[Migration Guide](docs/migrate_to_v2.md)** for step-by-step instructions. + + + --- ## Description This Python SDK is designed to help developers easily implement Skyflow into their python backend. diff --git a/docs/migrate_to_v2.md b/docs/migrate_to_v2.md new file mode 100644 index 00000000..4c94eb04 --- /dev/null +++ b/docs/migrate_to_v2.md @@ -0,0 +1,244 @@ +# Migrate from v1 to v2 + +This guide outlines the steps required to migrate the Skyflow Python SDK from version 1 (v1) to version 2 (v2). + +## Authentication + +In v2, multiple authentication options have been introduced. You can now provide credentials in the following ways: + +- **Passing credentials in ENV** (`SKYFLOW_CREDENTIALS`) (**Recommended**) +- **API Key** +- **Path to your credentials JSON file** +- **Stringified JSON of your credentials** +- **Bearer token** + +These options allow you to choose the authentication method that best suits your use case. + +### v1 (Old): Passing the token provider function below as a parameter to the Configuration. + +```python +# User defined function to provide access token to the vault apis +def token_provider(): + global bearer_token + if not is_expired(bearer_token): + return bearer_token + bearer_token, _ = generate_bearer_token('') + return bearer_token +``` + +#### v2 (New): Passing one of the following: + +```python +# Option 1: API Key (Recommended) +credentials = { + 'api_key': '', # API key +} + +# Option 2: Environment Variables (Recommended) +# Set SKYFLOW_CREDENTIALS in your environment + +# Option 3: Credentials File +credentials = { + 'path': '', # Path to credentials file +} + +# Option 4: Stringified JSON +credentials = { + 'credentials_string': '', # Credentials as string +} + +# Option 5: Bearer Token +credentials = { + 'token': '', # Bearer token +} +``` + +**Notes:** +- Use only ONE authentication method. +- API Key or Environment Variables are recommended for production use. +- Secure storage of credentials is essential. + +### Initializing the client + +In v2, we have introduced a Builder design pattern for client initialization and added support for multi-vault. This allows you to configure multiple vaults during client initialization. + +During client initialization, you can pass the following parameters: + +- **`vault_id`** and **`cluster_id`**: These values are derived from the vault ID & vault URL. +- **`env`**: Specify the environment (e.g., SANDBOX or PROD). +- **`credentials`**: The necessary authentication credentials. + +#### v1 (Old): + +```python +# Initializing a Skyflow Client instance with a SkyflowConfiguration object +config = Configuration('', '', token_provider) +client = Client(config) +``` + +#### v2 (New): + +```python +# Initializing a Skyflow Client instance +client = ( + Skyflow.builder() + .add_vault_config({ + 'vault_id': '', # Primary vault + 'cluster_id': '', # ID from your vault URL e.g., https://{clusterId}.vault.skyflowapis.com + 'env': Env.PROD, # Env by default it is set to PROD + 'credentials': credentials # Individual credentials + }) + .add_skyflow_credentials(credentials) # Skyflow credentials will be used if no individual credentials are passed + .set_log_level(LogLevel.INFO) # set log level by default it is set to ERROR + .build() +) +``` + +**Key Changes:** +- `vault_url` replaced with `cluster_id`. +- Added environment specification (`env`). +- Instance-specific log levels. + +### Request & Response Structure + +In v2, with the introduction of constructor parameters, you can now pass parameters to `InsertRequest`. This request needs +- **`table_name`**: The name of the table. +- **`values`**: An array of objects containing the data to be inserted. +The response will be of type `InsertResponse` class, which contains `inserted_fields` and errors. + +**Note:** Similar patterns apply to other operations like Get, Update, Delete. See the [README](../README.md) for complete examples. + +#### v1 (Old): Request Building + +```python +client.insert( + { + "records": [ + { + "table": "cards", + "fields": { + "cardNumber": "41111111111", + "cvv": "123", + }, + } + ] + }, + InsertOptions(True), +) +``` + +#### v2 (New): Request Building + +```python +from skyflow.vault.data import InsertRequest + +# Prepare Insertion Data +insert_data = [ + { + 'card_number': '', + 'cvv': '', + }, +] + +table_name = '' # Replace with your actual table name + +# Create Insert Request +insert_request = InsertRequest( + table=table_name, + values=insert_data, + return_tokens=True, # Optional: Get tokens for inserted data + continue_on_error=True # Optional: Continue on partial errors +) + +# Perform Secure Insertion +response = skyflow_client.vault('').insert(insert_request) +``` + +#### v1 (Old): Response Structure + +```json +{ + "records": [ + { + "table": "cards", + "fields": { + "cardNumber": "f3907186-e7e2-466f-91e5-48e12c2bcbc1", + "cvv": "1989cb56-63da-4482-a2df-1f74cd0dd1a5", + "skyflow_id": "d863633c-8c75-44fc-b2ed-2b58162d1117" + }, + "request_index": 0 + } + ] +} +``` + +#### v2 (New): Response Structure + +```python +InsertResponse( + inserted_fields=[ + { + 'skyflow_id': 'a8f3ed5d-55eb-4f32-bf7e-2dbf4b9d9097', + 'card_number': '5479-4229-4622-1393' + } + ], + errors=[] +) +``` + +### Request Options + +In v2, we have introduced constructor parameters, allowing you to set options as key-value pairs as parameters in request. + +#### v1 (Old): + +```python +options = InsertOptions( + tokens = True +) +``` + +#### v2 (New): + +```python +insert_request = InsertRequest( + table=table_name, # Replace with the table name + values=insert_data, + return_tokens=False, # Do not return tokens + continue_on_error=False, # Stop inserting if any record fails + upsert='', # Replace with the column name used for upsert logic, if any + token_mode=TokenMode.DISABLE, # Disable BYOT + tokens='' # Set with tokens when TokenMode is ENABLE +) +``` + +### Error Structure + +In v2, we have enriched the error details to provide better debugging capabilities. +The error response now includes: +- **http_status**: The HTTP status code. +- **grpc_code**: The gRPC code associated with the error. +- **details** & **message**: A detailed description of the error. +- **request_id**: A unique request identifier for easier debugging. + +#### v1 (Old) Error Structure: + +```json +{ + "code": "", + "message": "" +} +``` + +#### v2 (New) Error Structure: + +```python +{ + "http_status": "", + "grpc_code": , + "http_code": , + "message": "", + "request_id": "", + "details": [ "
" ] +} +``` \ No newline at end of file From ae260a00eeb57b0ecc83dc22e871fcee8132d7bc Mon Sep 17 00:00:00 2001 From: Devesh-Skyflow Date: Tue, 26 May 2026 18:49:21 +0530 Subject: [PATCH 2/6] feat(SK-2838): add v1.x deprecation warning on client initialization Co-Authored-By: Claude Sonnet 4.6 --- skyflow/vault/_client.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/skyflow/vault/_client.py b/skyflow/vault/_client.py index 96d86232..3f017047 100644 --- a/skyflow/vault/_client.py +++ b/skyflow/vault/_client.py @@ -3,6 +3,7 @@ ''' import json import types +import warnings import requests import asyncio from requests.adapters import HTTPAdapter @@ -21,6 +22,12 @@ class Client: def __init__(self, config: Configuration): + warnings.warn( + "skyflow-python v1.x is deprecated and will reach End of Life on October 31, 2026. " + "Please migrate to v2: https://github.com/skyflowapi/skyflow-python/blob/main/docs/migrate_to_v2.md", + UserWarning, + stacklevel=2 + ) interface = InterfaceName.CLIENT.value From ba29e811e63f40d537fd195454a70bec2ac1f2d0 Mon Sep 17 00:00:00 2001 From: Devesh-Skyflow Date: Tue, 26 May 2026 18:52:31 +0530 Subject: [PATCH 3/6] chore(SK-2838): update setup.py description with EOL notice Co-Authored-By: Claude Sonnet 4.6 --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 6c48fc93..5a00ff5c 100644 --- a/setup.py +++ b/setup.py @@ -16,7 +16,7 @@ packages=find_packages(where='.', exclude=['test*']), url='https://github.com/skyflowapi/skyflow-python/', license='LICENSE', - description='Skyflow SDK for the Python programming language', + description='[DEPRECATED - EOL 2026-10-31] Skyflow Python SDK v1.x. Migrate to v2: https://github.com/skyflowapi/skyflow-python/blob/main/docs/migrate_to_v2.md', long_description=open('README.rst').read(), install_requires=[ 'PyJWT', From a3b7334dc7f7891a02def5c56b5f1b24fbb2889a Mon Sep 17 00:00:00 2001 From: Devesh-Skyflow Date: Tue, 26 May 2026 20:00:56 +0530 Subject: [PATCH 4/6] chore(SK-2838): add workflow_dispatch, update release/v1/* trigger, upgrade action versions Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/internal-release.yml | 3 ++- .github/workflows/shared-build-and-deploy.yml | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/internal-release.yml b/.github/workflows/internal-release.yml index cafdb9c9..c0942e27 100644 --- a/.github/workflows/internal-release.yml +++ b/.github/workflows/internal-release.yml @@ -1,6 +1,7 @@ name: Internal Release on: + workflow_dispatch: push: tags-ignore: - '*.*' @@ -11,7 +12,7 @@ on: - "skyflow/version.py" - "samples/**" branches: - - release/* + - release/v1/* jobs: build-and-deploy: diff --git a/.github/workflows/shared-build-and-deploy.yml b/.github/workflows/shared-build-and-deploy.yml index 738ae2d9..0bd1cc9a 100644 --- a/.github/workflows/shared-build-and-deploy.yml +++ b/.github/workflows/shared-build-and-deploy.yml @@ -17,11 +17,11 @@ jobs: build-and-deploy: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 with: fetch-depth: 0 - - uses: actions/setup-python@v2 + - uses: actions/setup-python@v5 - name: Install dependencies run: | python -m pip install --upgrade pip From 4e784feb5de5f28d06aa087ad2e25158bb7124fd Mon Sep 17 00:00:00 2001 From: Devesh-Skyflow Date: Wed, 27 May 2026 16:15:09 +0530 Subject: [PATCH 5/6] chore: revert workflow changes and add breaking changes summary to migration guide Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/internal-release.yml | 3 +-- .github/workflows/shared-build-and-deploy.yml | 4 ++-- docs/migrate_to_v2.md | 15 +++++++++++++++ 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/.github/workflows/internal-release.yml b/.github/workflows/internal-release.yml index c0942e27..cafdb9c9 100644 --- a/.github/workflows/internal-release.yml +++ b/.github/workflows/internal-release.yml @@ -1,7 +1,6 @@ name: Internal Release on: - workflow_dispatch: push: tags-ignore: - '*.*' @@ -12,7 +11,7 @@ on: - "skyflow/version.py" - "samples/**" branches: - - release/v1/* + - release/* jobs: build-and-deploy: diff --git a/.github/workflows/shared-build-and-deploy.yml b/.github/workflows/shared-build-and-deploy.yml index 0bd1cc9a..738ae2d9 100644 --- a/.github/workflows/shared-build-and-deploy.yml +++ b/.github/workflows/shared-build-and-deploy.yml @@ -17,11 +17,11 @@ jobs: build-and-deploy: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v2 with: fetch-depth: 0 - - uses: actions/setup-python@v5 + - uses: actions/setup-python@v2 - name: Install dependencies run: | python -m pip install --upgrade pip diff --git a/docs/migrate_to_v2.md b/docs/migrate_to_v2.md index 4c94eb04..7bfa6bb0 100644 --- a/docs/migrate_to_v2.md +++ b/docs/migrate_to_v2.md @@ -2,6 +2,21 @@ This guide outlines the steps required to migrate the Skyflow Python SDK from version 1 (v1) to version 2 (v2). +--- + +## Breaking Changes from V1 to V2 + +| Area | V1 | V2 | +|------|----|----| +| **Client initialization** | `Configuration(vaultID, vaultURL, tokenProvider)` passed to `Client()` | `Credentials` + `VaultConfig` passed to `Skyflow()` | +| **Vault URL** | Single `vaultURL` string | Split into `vaultId` + `clusterId` | +| **Request/response types** | Raw `dict` | Typed request/response objects (e.g. `InsertRequest` / `InsertResponse`) | +| **Error handling** | `SkyflowError` with basic message | Restructured with `httpStatus`, `details`, and `requestId` | +| **Logging** | Global `set_log_level(LogLevel.X)` | Per-instance `logLevel` set on the `Skyflow` client | +| **Import paths** | `from skyflow.vault import Client` | New module structure across all packages | + +--- + ## Authentication In v2, multiple authentication options have been introduced. You can now provide credentials in the following ways: From 36051d90fd24123b8c5edecb8abdd8f061dc2672 Mon Sep 17 00:00:00 2001 From: Devesh-Skyflow Date: Wed, 27 May 2026 16:17:29 +0530 Subject: [PATCH 6/6] docs: use bullet points for breaking changes summary Co-Authored-By: Claude Sonnet 4.6 --- docs/migrate_to_v2.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/migrate_to_v2.md b/docs/migrate_to_v2.md index 7bfa6bb0..0bc5e5b8 100644 --- a/docs/migrate_to_v2.md +++ b/docs/migrate_to_v2.md @@ -6,14 +6,12 @@ This guide outlines the steps required to migrate the Skyflow Python SDK from ve ## Breaking Changes from V1 to V2 -| Area | V1 | V2 | -|------|----|----| -| **Client initialization** | `Configuration(vaultID, vaultURL, tokenProvider)` passed to `Client()` | `Credentials` + `VaultConfig` passed to `Skyflow()` | -| **Vault URL** | Single `vaultURL` string | Split into `vaultId` + `clusterId` | -| **Request/response types** | Raw `dict` | Typed request/response objects (e.g. `InsertRequest` / `InsertResponse`) | -| **Error handling** | `SkyflowError` with basic message | Restructured with `httpStatus`, `details`, and `requestId` | -| **Logging** | Global `set_log_level(LogLevel.X)` | Per-instance `logLevel` set on the `Skyflow` client | -| **Import paths** | `from skyflow.vault import Client` | New module structure across all packages | +- **Client initialization**: `Configuration(vaultID, vaultURL, tokenProvider)` passed to `Client()` is replaced by `Credentials` + `VaultConfig` passed to `Skyflow()`. +- **Vault URL**: `vaultURL` is now split into `vaultId` + `clusterId`. +- **Request/response types**: Operations like insert, get, detokenize now use typed request/response objects (e.g. `InsertRequest` / `InsertResponse`) instead of raw `dict`. +- **Error handling**: `SkyflowError` restructured to include `httpStatus`, `details`, and `requestId`. +- **Logging**: Global `set_log_level(LogLevel.X)` replaced by per-instance `logLevel` set on the `Skyflow` client. +- **Import paths**: New module structure across all packages. ---