SK-2813: Python SDK v2 — code quality, security hardening, and message fixes

README.md

@@ -703,18 +703,65 @@ options = {
 
 Embed context values into a bearer token during generation so you can reference those values in your policies. This enables more flexible access controls, such as tracking end-user identity when making API calls using service accounts, and facilitates using signed data tokens during detokenization.
 
-Generate bearer tokens containing context information using a service account with the context_id identifier. Context information is represented as a JWT claim in a Skyflow-generated bearer token. Tokens generated from such service accounts include a context_identifier claim, are valid for 60 minutes, and can be used to make API calls to the Data and Management APIs, depending on the service account's permissions.
+Generate bearer tokens containing context information using a service account with the `context_id` identifier. Context information is represented as a JWT claim in a Skyflow-generated bearer token. Tokens generated from such service accounts include a `context_identifier` claim, are valid for 60 minutes, and can be used to make API calls to the Data and Management APIs, depending on the service account's permissions.
+
+The `ctx` parameter accepts either a **string** or a **dict**:
+
+**String context** — use when your policy references a single context value:
+
+```python
+options = {'ctx': 'user_12345'}
+token, _ = generate_bearer_token(filepath, options)
+```
+
+**Dict context** — use when your policy needs multiple context values for conditional data access. Each key in the dict maps to a Skyflow CEL policy variable under `request.context.*`:
+
+```python
+options = {
+    'ctx': {
+        'role': 'admin',
+        'department': 'finance',
+        'user_id': 'user_12345',
+    }
+}
+token, _ = generate_bearer_token(filepath, options)
+```
+
+With the dict above, your Skyflow policies can reference `request.context.role`, `request.context.department`, and `request.context.user_id` to make conditional access decisions.
+
+Dict keys must contain only alphanumeric characters and underscores (`[a-zA-Z0-9_]`). Invalid keys will raise a `SkyflowError`.
 
 > [!TIP]
-> See the full example in the samples directory: [token_generation_with_context_example.py](samples/service_account/token_generation_with_context_example.py)  
-> See [docs.skyflow.com](https://docs.skyflow.com) for more details on authentication, access control, and governance for Skyflow.
+> See the full example in the samples directory: [token_generation_with_context_example.py](samples/service_account/token_generation_with_context_example.py)
+> See Skyflow's [context-aware authorization](https://docs.skyflow.com) and [conditional data access](https://docs.skyflow.com) docs for policy variable syntax like `request.context.*`.
 
 #### Generate signed data tokens: `generate_signed_data_tokens(filepath, options)`
 
 Digitally sign data tokens with a service account's private key to add an extra layer of protection. Skyflow generates data tokens when sensitive data is inserted into the vault. Detokenize signed tokens only by providing the signed data token along with a bearer token generated from the service account's credentials. The service account must have the necessary permissions and context to successfully detokenize the signed data tokens.
 
+The `ctx` parameter on signed data tokens also accepts either a **string** or a **dict**, using the same format as bearer tokens:
+
+```python
+# String context
+options = {
+    'ctx': 'user_12345',
+    'data_tokens': ['dataToken1', 'dataToken2'],
+    'time_to_live': 90,
+}
+
+# Dict context
+options = {
+    'ctx': {
+        'role': 'analyst',
+        'department': 'research',
+    },
+    'data_tokens': ['dataToken1', 'dataToken2'],
+    'time_to_live': 90,
+}
+```
+
 > [!TIP]
-> See the full example in the samples directory: [signed_token_generation_example.py](samples/service_account/signed_token_generation_example.py)  
+> See the full example in the samples directory: [signed_token_generation_example.py](samples/service_account/signed_token_generation_example.py)
 > See [docs.skyflow.com](https://docs.skyflow.com) for more details on authentication, access control, and governance for Skyflow.
 
 ## Logging

samples/detect_api/deidentify_file_async.py

@@ -0,0 +1,124 @@
+from skyflow.error import SkyflowError
+from skyflow import Env, Skyflow, LogLevel
+from skyflow.utils.enums import DetectEntities, MaskingMethod, DetectOutputTranscriptions
+from skyflow.vault.detect import DeidentifyFileRequest, TokenFormat, Transformations, DateTransformation, Bleep, FileInput
+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, 
+ * spreadsheets, presentations, structured text.
+"""
+
+def perform_file_deidentification_async():
+    try:
+        # Step 1: Configure Credentials
+        credentials = {
+            'path': '/path/to/credentials.json'  # Path to credentials file
+        }
+
+        # Step 2: Configure Vault
+        vault_config = {
+            'vault_id': '<YOUR_VAULT_ID>',  # Replace with your vault ID
+            'cluster_id': '<YOUR_CLUSTER_ID>',  # Replace with your cluster ID
+            'env': Env.PROD,  # Deployment environment
+            'credentials': credentials
+        }
+
+        # Step 3: Configure & Initialize Skyflow Client
+        skyflow_client = (
+            Skyflow.builder()
+            .add_vault_config(vault_config)
+            .set_log_level(LogLevel.INFO)  # Use LogLevel.ERROR in production
+            .build()
+        )
+
+        # Step 4: Create File Object
+        file_path = '<FILE_PATH>'  # Replace with your file path
+
+        deidentify_request = DeidentifyFileRequest(
+            file=FileInput(file_path=file_path),  # File to de-identify
+            # entities=[DetectEntities.SSN, DetectEntities.CREDIT_CARD],  # Entities to detect
+            allow_regex_list=['<YOUR_REGEX_PATTERN>'],  # Optional: Patterns to allow
+            restrict_regex_list=['<YOUR_REGEX_PATTERN>'],  # Optional: Patterns to restrict
+
+            # Token format configuration
+            token_format=TokenFormat(
+                vault_token=[DetectEntities.SSN],  # Use vault tokens for these entities
+            ),
+
+            # Optional: Custom transformations
+            # transformations=Transformations(
+            #     shift_dates=DateTransformation(
+            #         max_days=30,
+            #         min_days=10,
+            #         entities=[DetectEntities.DOB]
+            #     )
+            # ),
+
+                # Output configuration
+                output_directory='<OUTPUT_DIRECTORY_PATH>',  # Where to save processed file
+                wait_time=15,  # Max wait time in seconds (max 64)
+
+            # Image-specific options
+            output_processed_image=True,  # Include processed image in output
+            output_ocr_text=True,  # Include OCR text in response
+            masking_method=MaskingMethod.BLACKBOX,  # Masking method for images
+
+            # PDF-specific options
+            pixel_density=15,  # Pixel density for PDF processing
+            max_resolution=2000,  # Max resolution for PDF
+
+            # Audio-specific options
+            output_processed_audio=True,  # Include processed audio
+            output_transcription=DetectOutputTranscriptions.PLAINTEXT_TRANSCRIPTION,  # Transcription type
+
+            # Audio bleep configuration
+
+            # bleep=Bleep(
+            #     gain=5,  # Loudness in dB
+            #     frequency=1000,  # Pitch in Hz
+            #     start_padding=0.1,  # Padding at start (seconds)
+            #     stop_padding=0.2  # Padding at end (seconds)
+            # )
+        )
+
+        # Create a thread pool executor
+        executor = ThreadPoolExecutor(max_workers=1)
+
+        future = executor.submit(
+            lambda: skyflow_client.detect().deidentify_file(deidentify_request)
+        )
+
+        def handle_response(future):
+            exception = future.exception()
+            if exception is not None:
+                if isinstance(exception, SkyflowError):
+                    # Handle Skyflow-specific errors
+                    print('\nSkyflow Error:', {
+                        'http_code': exception.http_code,
+                        'grpc_code': exception.grpc_code,
+                        'http_status': exception.http_status,
+                        'message': exception.message,
+                        'details': exception.details
+                    })
+                else:
+                    # Handle unexpected errors
+                    print('Unexpected Error:', exception)
+                return
+
+            # Handle Successful Response
+            result = future.result()
+            print("\nDeidentify File Response:", result)
+
+        future.add_done_callback(handle_response)
+
+        executor.shutdown(wait=True)
+
+    except Exception as error:
+        # Handle unexpected errors
+        print('Unexpected Error:', error)
+

samples/service_account/signed_token_generation_example.py

@@ -18,42 +18,54 @@
 credentials_string = json.dumps(skyflow_credentials)
 
 
-options = {
-    'ctx': 'CONTEXT_ID',
-    'data_tokens': ['DATA_TOKEN1', 'DATA_TOKEN2'],
-    'time_to_live': 90,  # in seconds
-}
+# Approach 1: Signed data tokens with string context
+def get_signed_tokens_with_string_context():
+    options = {
+        'ctx': 'user_12345',
+        'data_tokens': ['DATA_TOKEN1', 'DATA_TOKEN2'],
+        'time_to_live': 90,  # in seconds
+    }
+    try:
+        data_token, signed_data_token = generate_signed_data_tokens(file_path, options)
+        return data_token, signed_data_token
+    except Exception as e:
+        print(f'Error: {str(e)}')
 
-def get_signed_bearer_token_from_file_path():
-    # Generate signed bearer token from credentials file path.
-    global bearer_token
 
+# Approach 2: Signed data tokens with JSON object context (dict)
+# Each key maps to a Skyflow CEL policy variable under request.context.*
+# For example: request.context.role == "analyst" and request.context.department == "research"
+def get_signed_tokens_with_object_context():
+    options = {
+        'ctx': {
+            'role': 'analyst',
+            'department': 'research',
+            'user_id': 'user_67890',
+        },
+        'data_tokens': ['DATA_TOKEN1', 'DATA_TOKEN2'],
+        'time_to_live': 90,
+    }
     try:
-        if not is_expired(bearer_token):
-            return bearer_token
-        else:
-            data_token, signed_data_token = generate_signed_data_tokens(file_path, options)
-            return data_token, signed_data_token
-
+        data_token, signed_data_token = generate_signed_data_tokens(file_path, options)
+        return data_token, signed_data_token
     except Exception as e:
-        print(f'Error generating token from file path: {str(e)}')
+        print(f'Error: {str(e)}')
 
 
-def get_signed_bearer_token_from_credentials_string():
-    # Generate signed bearer token from credentials string.
-    global bearer_token
-
+# Approach 3: Signed data tokens from credentials string
+def get_signed_tokens_from_credentials_string():
+    options = {
+        'ctx': 'user_12345',
+        'data_tokens': ['DATA_TOKEN1', 'DATA_TOKEN2'],
+        'time_to_live': 90,
+    }
     try:
-        if not is_expired(bearer_token):
-            return bearer_token
-        else:
-            data_token, signed_data_token = generate_signed_data_tokens_from_creds(credentials_string, options)
-            return data_token, signed_data_token
-
+        data_token, signed_data_token = generate_signed_data_tokens_from_creds(credentials_string, options)
+        return data_token, signed_data_token
     except Exception as e:
-        print(f'Error generating token from credentials string: {str(e)}')
-
+        print(f'Error: {str(e)}')
 
-print(get_signed_bearer_token_from_file_path())
 
-print(get_signed_bearer_token_from_credentials_string())
+print("String context:", get_signed_tokens_with_string_context())
+print("Object context:", get_signed_tokens_with_object_context())
+print("Creds string:", get_signed_tokens_from_credentials_string())

samples/service_account/token_generation_with_context_example.py

@@ -18,11 +18,13 @@
 }
 credentials_string = json.dumps(skyflow_credentials)
 
-options = {'ctx': '<CONTEXT_ID>'}
 
-def get_bearer_token_with_context_from_file_path():
-    # Generate bearer token with context from credentials file path.
+# Approach 1: Bearer token with string context
+# Use a simple string identifier when your policy references a single context value.
+# In your Skyflow policy, reference this as: request.context
+def get_bearer_token_with_string_context():
     global bearer_token
+    options = {'ctx': 'user_12345'}
 
     try:
         if not is_expired(bearer_token):
@@ -31,14 +33,40 @@ def get_bearer_token_with_context_from_file_path():
             token, _ = generate_bearer_token(file_path, options)
             bearer_token = token
             return bearer_token
+    except Exception as e:
+        print(f'Error generating token: {str(e)}')
+
+
+# Approach 2: Bearer token with JSON object context (dict)
+# Use a dict when your policy needs multiple context values for conditional data access.
+# Each key maps to a Skyflow CEL policy variable under request.context.*
+# For example: request.context.role == "admin" and request.context.department == "finance"
+def get_bearer_token_with_object_context():
+    global bearer_token
+    options = {
+        'ctx': {
+            'role': 'admin',
+            'department': 'finance',
+            'user_id': 'user_12345',
+        }
+    }
 
+    try:
+        if not is_expired(bearer_token):
+            return bearer_token
+        else:
+            token, _ = generate_bearer_token(file_path, options)
+            bearer_token = token
+            return bearer_token
     except Exception as e:
-        print(f'Error generating token from file path: {str(e)}')
+        print(f'Error generating token: {str(e)}')
 
 
+# Approach 3: Bearer token with string context from credentials string
 def get_bearer_token_with_context_from_credentials_string():
-    # Generate bearer token with context from credentials string.
     global bearer_token
+    options = {'ctx': 'user_12345'}
+
     try:
         if not is_expired(bearer_token):
             return bearer_token
@@ -47,9 +75,9 @@ def get_bearer_token_with_context_from_credentials_string():
             bearer_token = token
             return bearer_token
     except Exception as e:
-        print(f"Error generating token from credentials string: {str(e)}")
-
+        print(f"Error generating token: {str(e)}")
 
-print(get_bearer_token_with_context_from_file_path())
 
-print(get_bearer_token_with_context_from_credentials_string())
+print("String context:", get_bearer_token_with_string_context())
+print("Object context:", get_bearer_token_with_object_context())
+print("Creds string:", get_bearer_token_with_context_from_credentials_string())

setup.py

@@ -7,7 +7,7 @@
 
 if sys.version_info < (3, 8):
     raise RuntimeError("skyflow requires Python 3.8+")
-current_version = '2.0.0.dev0+f7d26df'
+current_version = '2.0.2'
 
 setup(
     name='skyflow',

skyflow/client/skyflow.py

@@ -62,9 +62,6 @@ def set_log_level(self, log_level):
     def get_log_level(self):
         return self.__builder._Builder__log_level
 
-    def update_log_level(self, log_level):
-        self.__builder._Builder__set_log_level(log_level)
-
     def vault(self, vault_id = None) -> Vault:
         vault_config = self.__builder.get_vault_config(vault_id)
         return vault_config.get(OptionField.VAULT_CONTROLLER)

skyflow/error/_skyflow_error.py

@@ -1,5 +1,4 @@
 from skyflow.utils import SkyflowMessages
-from skyflow.utils.logger import log_error
 
 class SkyflowError(Exception):
     def __init__(self,
@@ -15,4 +14,4 @@ def __init__(self,
         self.http_status = http_status if http_status else SkyflowMessages.HttpStatus.BAD_REQUEST.value
         self.details = details
         self.request_id = request_id
-        super().__init__()
+        super().__init__(message)