SK-2707: Improve Python SDK onboarding — docs, samples, and correctness fixes

requirements.txt

@@ -1,5 +1,5 @@
 python_dateutil >= 2.5.3
-setuptools >= 21.0.0
+setuptools >= 75.3.3
 urllib3 >= 1.25.3, < 3
 pydantic >= 2
 typing-extensions >= 4.7.1

samples/README.md

@@ -0,0 +1,65 @@
+# Skyflow Python SDK — Samples
+
+Runnable examples for the Skyflow Python SDK, grouped by area. Start with the [README](../README.md) and [API Reference](../docs/api_reference.md) for full documentation.
+
+## Prerequisites
+
+- Python 3.9 or above
+- The SDK installed: `pip install skyflow`
+- A Skyflow account, a vault, and a service account (see [Before you begin](../README.md#before-you-begin))
+- Your `vault_id`, `cluster_id`, `env`, and one credential (API key, bearer token, or service-account credentials)
+
+## Configure
+
+The samples ship with inline `<PLACEHOLDER>` strings (for example `<YOUR_VAULT_ID>`). Replace the placeholders in the sample you want to run with your own values before running it.
+
+> Never commit real credentials.
+
+## Run a sample
+
+```bash
+python samples/vault_api/insert_records.py
+```
+
+## What's here
+
+### `vault_api/`
+Core vault data operations.
+
+| Sample | Demonstrates |
+|--------|--------------|
+| `client_operations.py` | Building and managing the Skyflow client |
+| `credentials_options.py` | The different credential types |
+| `insert_records.py` | Inserting and tokenizing records (`continue_on_error`) |
+| `insert_byot.py` | Bring-your-own-token inserts |
+| `get_records.py` | Getting records by Skyflow ID |
+| `get_column_values.py` | Getting records by column name/values |
+| `update_record.py` | Updating a record |
+| `delete_records.py` | Deleting records |
+| `query_records.py` | SQL queries |
+| `detokenize_records.py` | Detokenizing tokens |
+| `tokenize_records.py` | Retrieving existing tokens |
+| `upload_file.py` | Uploading a file to a record |
+| `invoke_connection.py` | Invoking a Skyflow Connection |
+
+### `detect_api/`
+Skyflow Detect (de-identification / re-identification).
+
+| Sample | Demonstrates |
+|--------|--------------|
+| `deidentify_text.py` | De-identifying text |
+| `reidentify_text.py` | Re-identifying text |
+| `deidentify_file.py` | De-identifying a file |
+| `deidentify_file_concurrent.py` | Running a file de-identification on a background thread (thread-based concurrency, not asyncio) |
+| `get_detect_run.py` | Polling a file de-identification run by `run_id` |
+
+### `service_account/`
+Bearer-token and signed-data-token generation.
+
+| Sample | Demonstrates |
+|--------|--------------|
+| `token_generation_example.py` | Generating a bearer token |
+| `scoped_token_generation_example.py` | Tokens scoped to specific roles |
+| `token_generation_with_context_example.py` | Tokens with context (`ctx`) |
+| `signed_token_generation_example.py` | Signed data tokens |
+| `bearer_token_expiry_example.py` | Handling token expiry / regeneration |

samples/detect_api/deidentify_file_async.py → samples/detect_api/deidentify_file_concurrent.py

@@ -12,15 +12,18 @@
 from concurrent.futures import ThreadPoolExecutor
 
 """
- * Skyflow Deidentify File Example
- * 
- * This sample demonstrates how to use all available options for deidentifying files
- * using an asynchronous approach.
- * Supported file types: images (jpg, png, etc.), pdf, audio (mp3, wav), documents, 
+ * Skyflow Deidentify File Example (concurrent)
+ *
+ * This sample demonstrates how to use all available options for deidentifying files.
+ * The SDK is synchronous; this example runs the (blocking) deidentify_file call on a
+ * background thread using concurrent.futures.ThreadPoolExecutor so the main thread can
+ * continue working. This is thread-based concurrency, not asyncio — the SDK does not
+ * expose async/await coroutines.
+ * Supported file types: images (jpg, png, etc.), pdf, audio (mp3, wav), documents,
  * spreadsheets, presentations, structured text.
 """
 
-def perform_file_deidentification_async():
+def perform_file_deidentification_concurrent():
     try:
         # Step 1: Configure Credentials
         credentials = {

setup.py

@@ -18,6 +18,11 @@
     author='Skyflow',
     author_email='service-ops@skyflow.com',
     packages=find_packages(where='.', exclude=['test*']),
+    # Ship PEP 561 markers so type checkers (mypy/pyright) see the SDK's types.
+    package_data={
+        'skyflow': ['py.typed'],
+        'skyflow.generated.rest': ['py.typed'],
+    },
     url='https://github.com/skyflowapi/skyflow-python/',
     license='LICENSE',
     description='Skyflow SDK for the Python programming language',

skyflow/utils/enums/request_method.py

@@ -4,5 +4,6 @@ class RequestMethod(Enum):
     GET = "GET"
     POST = "POST"
     PUT = "PUT"
+    PATCH = "PATCH"
     DELETE = "DELETE"
     NONE = "NONE"