salesforce-data-customcode 6.1.0.dev1__py3-none-any.whl → 6.1.0.dev2__py3-none-any.whl

datacustomcode/named_credential/types/http_response_builder.py

@@ -0,0 +1,24 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any, Dict
+
+from datacustomcode.named_credential.types.http_response import HTTPResponse
+
+
+class HTTPResponseBuilder:
+    @staticmethod
+    def build(response_dict: Dict[str, Any]) -> HTTPResponse:
+        return HTTPResponse.model_validate(response_dict)

datacustomcode/named_credential_config.py

@@ -0,0 +1,105 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import (
+    ClassVar,
+    Generic,
+    Type,
+    TypeVar,
+    Union,
+)
+
+from datacustomcode.common_config import (
+    BaseConfig,
+    BaseObjectConfig,
+    default_config_file,
+)
+from datacustomcode.named_credential.base import NamedCredential
+from datacustomcode.named_credential.spark_base import SparkNamedCredential
+
+_N = TypeVar("_N", bound=NamedCredential)
+_S = TypeVar("_S", bound=SparkNamedCredential)
+
+
+class NamedCredentialObjectConfig(BaseObjectConfig, Generic[_N]):
+    type_to_create: ClassVar[Type[NamedCredential]] = NamedCredential  # type: ignore[type-abstract]
+
+    def to_object(self) -> NamedCredential:
+        type_ = self.type_to_create.subclass_from_config_name(self.type_config_name)
+        return type_(**self.options)
+
+
+class NamedCredentialConfig(BaseConfig):
+    named_credential_config: Union[
+        NamedCredentialObjectConfig[NamedCredential], None
+    ] = None
+
+    def update(self, other: "NamedCredentialConfig") -> "NamedCredentialConfig":
+        def merge(
+            config_a: Union[NamedCredentialObjectConfig, None],
+            config_b: Union[NamedCredentialObjectConfig, None],
+        ) -> Union[NamedCredentialObjectConfig, None]:
+            if config_a is not None and config_a.force:
+                return config_a
+            if config_b:
+                return config_b
+            return config_a
+
+        self.named_credential_config = merge(
+            self.named_credential_config, other.named_credential_config
+        )
+        return self
+
+
+class SparkNamedCredentialObjectConfig(BaseObjectConfig, Generic[_S]):
+    type_to_create: ClassVar[Type[SparkNamedCredential]] = SparkNamedCredential  # type: ignore[type-abstract]
+
+    def to_object(self) -> SparkNamedCredential:
+        type_ = self.type_to_create.subclass_from_config_name(self.type_config_name)
+        return type_(**self.options)
+
+
+class SparkNamedCredentialConfig(BaseConfig):
+    spark_named_credential_config: Union[
+        SparkNamedCredentialObjectConfig[SparkNamedCredential], None
+    ] = None
+
+    def update(
+        self, other: "SparkNamedCredentialConfig"
+    ) -> "SparkNamedCredentialConfig":
+        def merge(
+            config_a: Union[SparkNamedCredentialObjectConfig, None],
+            config_b: Union[SparkNamedCredentialObjectConfig, None],
+        ) -> Union[SparkNamedCredentialObjectConfig, None]:
+            if config_a is not None and config_a.force:
+                return config_a
+            if config_b:
+                return config_b
+            return config_a
+
+        self.spark_named_credential_config = merge(
+            self.spark_named_credential_config, other.spark_named_credential_config
+        )
+        return self
+
+
+# Global Named Credential config instance
+named_credential_config = NamedCredentialConfig()
+named_credential_config.load(default_config_file())
+
+
+# Global Spark Named Credential config instance
+spark_named_credential_config = SparkNamedCredentialConfig()
+spark_named_credential_config.load(default_config_file())

datacustomcode/run.py

@@ -27,6 +27,7 @@ from typing import (
 from datacustomcode.config import config
 from datacustomcode.einstein_predictions_config import einstein_predictions_config
 from datacustomcode.llm_gateway_config import llm_gateway_config
+from datacustomcode.named_credential_config import named_credential_config
 from datacustomcode.scan import find_base_directory, get_package_type
 
 
@@ -42,15 +43,6 @@ def _set_config_option(config_obj, key: str, value: Optional[str]) -> None:
         config_obj.options[key] = value
 
 
-def _read_streaming_source(config_json: dict) -> Optional[str]:
-    """Return the streaming source name from config.json's ``streamingSource``."""
-    source = config_json.get("streamingSource")
-    if not isinstance(source, dict):
-        return None
-    name = source.get("name")
-    return str(name) if name else None
-
-
 def _update_config_options(profile: Optional[str], sf_cli_org: Optional[str]):
     if sf_cli_org:
         config_key = "sf_cli_org"
@@ -64,6 +56,9 @@ def _update_config_options(profile: Optional[str], sf_cli_org: Optional[str]):
         _set_config_option(
             llm_gateway_config.llm_gateway_config, config_key, sf_cli_org
         )
+        _set_config_option(
+            named_credential_config.named_credential_config, config_key, sf_cli_org
+        )
     elif profile != "default":
         config_key = "credentials_profile"
         _set_config_option(config.reader_config, config_key, profile)
@@ -72,6 +67,9 @@ def _update_config_options(profile: Optional[str], sf_cli_org: Optional[str]):
             einstein_predictions_config.einstein_predictions_config, config_key, profile
         )
         _set_config_option(llm_gateway_config.llm_gateway_config, config_key, profile)
+        _set_config_option(
+            named_credential_config.named_credential_config, config_key, profile
+        )
 
 
 def run_entrypoint(
@@ -134,8 +132,6 @@ def run_entrypoint(
         _set_config_option(config.reader_config, "dataspace", dataspace)
         _set_config_option(config.writer_config, "dataspace", dataspace)
 
-        config.streaming_source = _read_streaming_source(config_json)
-
     _update_config_options(profile, sf_cli_org)
 
     for dependency in dependencies:

datacustomcode/scan.py

@@ -15,7 +15,6 @@
 from __future__ import annotations
 
 import ast
-import copy
 import json
 import os
 import sys
@@ -33,8 +32,6 @@ import pydantic
 from datacustomcode.version import get_version
 
 DATA_ACCESS_METHODS = ["read_dlo", "read_dmo", "write_to_dlo", "write_to_dmo"]
-STREAMING_READ_METHODS = ["read_dlo_deltas", "read_dmo_deltas"]
-STREAMING_WRITE_METHODS = ["write_dlo_deltas"]
 
 DATA_TRANSFORM_CONFIG_TEMPLATE = {
     "sdkVersion": get_version(),
@@ -46,20 +43,6 @@ DATA_TRANSFORM_CONFIG_TEMPLATE = {
     },
 }
 
-STREAMING_TRANSFORM_CONFIG_TEMPLATE = {
-    "sdkVersion": get_version(),
-    "entryPoint": "",
-    "dataspace": "default",
-    "streamingSource": {
-        "type": "dlo",
-        "name": "",
-    },
-    "permissions": {
-        "read": {},
-        "write": {},
-    },
-}
-
 FUNCTION_CONFIG_TEMPLATE = {
     "entryPoint": "",
 }
@@ -177,35 +160,6 @@ class DataAccessLayerCalls(pydantic.BaseModel):
         return next(iter(self.write_to_dmo))
 
 
-class StreamingDataAccessLayerCalls(pydantic.BaseModel):
-    read_dlo_deltas: bool
-    read_dmo_deltas: bool
-    write_dlo_deltas: frozenset[str]
-
-    @pydantic.model_validator(mode="after")
-    def validate_access_layer(self) -> StreamingDataAccessLayerCalls:
-        if self.read_dlo_deltas and self.read_dmo_deltas:
-            raise ValueError(
-                "Cannot read DLO and DMO deltas in the same streaming transform."
-            )
-        if not self.read_dlo_deltas and not self.read_dmo_deltas:
-            raise ValueError(
-                "A streaming transform must read from at least one DLO or DMO "
-                "delta stream (read_dlo_deltas / read_dmo_deltas)."
-            )
-        if not self.write_dlo_deltas:
-            raise ValueError(
-                "A streaming transform must write to at least one DLO via "
-                "write_dlo_deltas."
-            )
-        return self
-
-    @property
-    def read_layer(self) -> str:
-        """Return the read source layer, ``"dlo"`` or ``"dmo"``."""
-        return "dlo" if self.read_dlo_deltas else "dmo"
-
-
 class ClientMethodVisitor(ast.NodeVisitor):
     """AST Visitor that finds all instances of Client read/write method calls."""
 
@@ -214,9 +168,6 @@ class ClientMethodVisitor(ast.NodeVisitor):
         self._read_dmo_instances: set[str] = set()
         self._write_to_dlo_instances: set[str] = set()
         self._write_to_dmo_instances: set[str] = set()
-        self._read_dlo_deltas: bool = False
-        self._read_dmo_deltas: bool = False
-        self._write_dlo_deltas_instances: set[str] = set()
         self.variable_values: Dict[str, Union[str, None]] = {}
 
     def visit_Assign(self, node: ast.Assign) -> None:
@@ -238,15 +189,14 @@ class ClientMethodVisitor(ast.NodeVisitor):
             node.func.value, ast.Name
         ):
             method_name = node.func.attr
-
-            if method_name == "read_dlo_deltas":
-                self._read_dlo_deltas = True
-            elif method_name == "read_dmo_deltas":
-                self._read_dmo_deltas = True
-
             if method_name in DATA_ACCESS_METHODS and node.args:
                 arg = node.args[0]
-                name = self._resolve_name_arg(arg)
+                name = None
+
+                if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
+                    name = arg.value
+                elif isinstance(arg, ast.Name) and arg.id in self.variable_values:
+                    name = self.variable_values[arg.id]
 
                 if name:
                     if method_name == "read_dlo":
@@ -257,29 +207,8 @@ class ClientMethodVisitor(ast.NodeVisitor):
                         self._write_to_dlo_instances.add(name)
                     elif method_name == "write_to_dmo":
                         self._write_to_dmo_instances.add(name)
-            elif method_name in STREAMING_WRITE_METHODS and node.args:
-                name = self._resolve_name_arg(node.args[0])
-                if name and method_name == "write_dlo_deltas":
-                    self._write_dlo_deltas_instances.add(name)
         self.generic_visit(node)
 
-    def _resolve_name_arg(self, arg: ast.expr) -> Union[str, None]:
-        """Resolve a string-literal or tracked-variable first argument."""
-        if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
-            return arg.value
-        if isinstance(arg, ast.Name) and arg.id in self.variable_values:
-            return self.variable_values[arg.id]
-        return None
-
-    @property
-    def is_streaming(self) -> bool:
-        """Whether any streaming (delta) access method was found."""
-        return (
-            self._read_dlo_deltas
-            or self._read_dmo_deltas
-            or bool(self._write_dlo_deltas_instances)
-        )
-
     def found(self) -> DataAccessLayerCalls:
         return DataAccessLayerCalls(
             read_dlo=frozenset(self._read_dlo_instances),
@@ -288,13 +217,6 @@ class ClientMethodVisitor(ast.NodeVisitor):
             write_to_dmo=frozenset(self._write_to_dmo_instances),
         )
 
-    def found_streaming(self) -> StreamingDataAccessLayerCalls:
-        return StreamingDataAccessLayerCalls(
-            read_dlo_deltas=self._read_dlo_deltas,
-            read_dmo_deltas=self._read_dmo_deltas,
-            write_dlo_deltas=frozenset(self._write_dlo_deltas_instances),
-        )
-
 
 class ImportVisitor(ast.NodeVisitor):
     """AST Visitor that extracts external package imports from Python code."""
@@ -379,51 +301,23 @@ def write_requirements_file(file_path: str) -> str:
     return requirements_path
 
 
-def _visit_file(file_path: str) -> ClientMethodVisitor:
-    """Parse a Python file and return the populated method visitor."""
-    with open(file_path, "r") as f:
-        tree = ast.parse(f.read())
-    visitor = ClientMethodVisitor()
-    visitor.visit(tree)
-    return visitor
-
-
 def scan_file(file_path: str) -> DataAccessLayerCalls:
-    """Scan a single Python file for batch Client read/write method calls."""
-    return _visit_file(file_path).found()
-
-
-def scan_file_streaming(file_path: str) -> StreamingDataAccessLayerCalls:
-    """Scan a single Python file for StreamingClient delta method calls."""
-    return _visit_file(file_path).found_streaming()
-
-
-def file_is_streaming(file_path: str) -> bool:
-    """Return whether the entrypoint uses streaming (delta) access methods."""
-    return _visit_file(file_path).is_streaming
-
+    """Scan a single Python file for Client read/write method calls."""
+    with open(file_path, "r") as f:
+        code = f.read()
+        tree = ast.parse(code)
+        visitor = ClientMethodVisitor()
+        visitor.visit(tree)
+        return visitor.found()
 
-def dc_config_json_from_file(
-    file_path: str, type: str, streaming: bool = False
-) -> dict[str, Any]:
-    """Create a Data Cloud Custom Code config JSON from a script.
 
-    Args:
-        file_path: Path to the entrypoint.
-        type: Package type, ``"script"`` or ``"function"``.
-        streaming: For scripts, a streaming
-            (``streamingSource``) config instead of a batch one.
-    """
+def dc_config_json_from_file(file_path: str, type: str) -> dict[str, Any]:
+    """Create a Data Cloud Custom Code config JSON from a script."""
     config: dict[str, Any]
     if type == "script":
-        template = (
-            STREAMING_TRANSFORM_CONFIG_TEMPLATE
-            if streaming
-            else DATA_TRANSFORM_CONFIG_TEMPLATE
-        )
-        config = copy.deepcopy(template)
+        config = DATA_TRANSFORM_CONFIG_TEMPLATE.copy()
     elif type == "function":
-        config = copy.deepcopy(FUNCTION_CONFIG_TEMPLATE)
+        config = FUNCTION_CONFIG_TEMPLATE.copy()
     config["entryPoint"] = os.path.basename(file_path)
     return config
 
@@ -478,49 +372,20 @@ def update_config(file_path: str) -> dict[str, Any]:
 
     if package_type == "script":
         existing_config["dataspace"] = get_dataspace(existing_config)
-        if file_is_streaming(file_path):
-            _update_streaming_config(existing_config, file_path)
+        output = scan_file(file_path)
+        read: dict[str, list[str]] = {}
+        if output.read_dlo:
+            read["dlo"] = list(output.read_dlo)
         else:
-            existing_config.pop("streamingSource", None)
-            output = scan_file(file_path)
-            read: dict[str, list[str]] = {}
-            if output.read_dlo:
-                read["dlo"] = list(output.read_dlo)
-            else:
-                read["dmo"] = list(output.read_dmo)
-            write: dict[str, list[str]] = {}
-            if output.write_to_dlo:
-                write["dlo"] = list(output.write_to_dlo)
-            else:
-                write["dmo"] = list(output.write_to_dmo)
-
-            existing_config["permissions"] = {"read": read, "write": write}
-    return existing_config
-
-
-def _update_streaming_config(existing_config: dict[str, Any], file_path: str) -> None:
-    output = scan_file_streaming(file_path)
-    read_layer = output.read_layer
-
-    source = existing_config.get("streamingSource")
-    if not isinstance(source, dict):
-        source = {}
-    source_name = source.get("name", "")
-    existing_config["streamingSource"] = {"type": read_layer, "name": source_name}
-
-    if not source_name:
-        logger.warning(
-            "streamingSource.name is empty in config.json. A streaming "
-            "transform must declare its read source; set streamingSource.name "
-            "to the DLO/DMO the transform reads from."
-        )
+            read["dmo"] = list(output.read_dmo)
+        write: dict[str, list[str]] = {}
+        if output.write_to_dlo:
+            write["dlo"] = list(output.write_to_dlo)
+        else:
+            write["dmo"] = list(output.write_to_dmo)
 
-    read_names = [source_name] if source_name else []
-    write_names = list(output.write_dlo_deltas)
-    existing_config["permissions"] = {
-        "read": {read_layer: read_names},
-        "write": {"dlo": write_names},
-    }
+        existing_config["permissions"] = {"read": read, "write": write}
+    return existing_config
 
 
 def get_dataspace(existing_config: dict[str, str]) -> str:

datacustomcode/template.py

@@ -23,12 +23,8 @@ from datacustomcode.constants import FEATURE_TEMPLATE_MAPPING
 script_template_dir = os.path.join(os.path.dirname(__file__), "templates", "script")
 function_template_dir = os.path.join(os.path.dirname(__file__), "templates", "function")
 
-STREAMING_EXAMPLE_ENTRYPOINT = os.path.join(
-    script_template_dir, "examples", "streaming_deltas", "entrypoint.py"
-)
 
-
-def copy_script_template(target_dir: str, streaming: bool = False) -> None:
+def copy_script_template(target_dir: str) -> None:
     """Copy the template to the target directory."""
     os.makedirs(target_dir, exist_ok=True)
 
@@ -43,14 +39,6 @@ def copy_script_template(target_dir: str, streaming: bool = False) -> None:
             logger.debug(f"Copying file {source} to {destination}...")
             shutil.copy2(source, destination)
 
-    if streaming:
-        destination = os.path.join(target_dir, "payload", "entrypoint.py")
-        logger.debug(
-            f"Copying streaming example {STREAMING_EXAMPLE_ENTRYPOINT} to "
-            f"{destination}..."
-        )
-        shutil.copy2(STREAMING_EXAMPLE_ENTRYPOINT, destination)
-
 
 def copy_function_template(target_dir: str, use_in_feature: Optional[str]) -> None:
     os.makedirs(target_dir, exist_ok=True)

datacustomcode/templates/function/example/chunking_with_external_callout/README.md

@@ -0,0 +1,119 @@
+# Chunking with a Gemini Named Credential Callout
+
+Splits each input document into paragraph-sized chunks and calls Google's
+**Gemini** `generateContent` API for every chunk. The model returns a summary,
+category, sentiment, and topics, which are attached to the chunk as citations so
+the search index can filter and rank on them. Gemini is reached through a
+**Named Credential**, so this code never handles the endpoint URL or the API key.
+
+## How the callout works
+
+```python
+CALLOUT_URL = "callout:gemini"  # callout:<NC name>[/<path>]
+
+request = (
+    HTTPRequestBuilder()
+    .set_url(CALLOUT_URL)
+    .set_method(HTTPMethod.POST)
+    .set_headers({"Content-Type": "application/json"})
+    .build()
+)
+# Body is sent verbatim (serialize it yourself); the response body is a raw string.
+response = runtime.named_credential.request(request, json.dumps(payload))
+if response.is_success:
+    envelope = json.loads(response.body)
+    text = envelope["candidates"][0]["content"]["parts"][0]["text"]
+```
+
+The request asks for `responseMimeType: application/json` with a `responseSchema`,
+so Gemini returns the classification as a JSON string in
+`candidates[0].content.parts[0].text` — decode it, then decode that text again.
+
+The `gemini` Named Credential's URL already includes the full
+`/v1beta/models/<model>:generateContent` path, so the callout is just
+`callout:gemini` with **no path suffix** (anything after the name is appended to
+the credential's URL).
+
+## Configure the Named Credential
+
+1. Create an **External Credential** (e.g. `google_api_key`) that injects your
+   Gemini API key as the `X-goog-api-key` header.
+2. Create a **Named Credential** named `gemini`:
+   - **URL**: `https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent`
+   - **Enabled for Callouts** + **Generate Authorization Header**: on
+   - **External Credential**: `google_api_key`
+
+## Test locally
+
+```bash
+DATACUSTOMCODE_EXTERNAL_CALLOUT_CONFIG=/abs/path/to/external_callout_config.json \
+  sf data-code-extension function run \
+    --entrypoint payload/entrypoint.py \
+    --test-with payload/tests/test.json \
+    --target-org <your-org-alias>
+```
+
+With `--target-org` the SDK fetches only the **URL** from the org's Named
+Credential; **auth is always taken from `external_callout_config.json`** locally
+(the org's External Credential is used only in the Data Cloud runtime). So the
+`X-goog-api-key` must be in the local config for a local test. Omit
+`--target-org` to run fully offline using `target_url`.
+
+```json
+{
+    "credentials": {
+        "callout:gemini": {
+            "auth_type": "Custom",
+            "custom_headers": { "X-goog-api-key": "YOUR_GEMINI_API_KEY" },
+            "target_url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent"
+        }
+    }
+}
+```
+
+Place `external_callout_config.json` in the **parent of your payload folder** (or
+point `DATACUSTOMCODE_EXTERNAL_CALLOUT_CONFIG` at it). It is never packaged into
+the deployment zip. Get a key from [Google AI Studio](https://aistudio.google.com/apikey);
+**do not commit it.**
+
+## Auth types
+
+`auth_type` selects how auth is injected for local testing. It should mirror the
+External Credential your Named Credential uses in the org, so local and deployed
+runs behave the same. This example uses `Custom` (Gemini's `X-goog-api-key`);
+all four supported types:
+
+```json
+{
+    "credentials": {
+        "callout:my_custom_api": {
+            "auth_type": "Custom",
+            "custom_headers": { "X-goog-api-key": "YOUR_API_KEY" }
+        },
+        "callout:my_basic_api": {
+            "auth_type": "Basic",
+            "username": "svc_user",
+            "password": "YOUR_PASSWORD"
+        },
+        "callout:my_oauth_api": {
+            "auth_type": "OAuth",
+            "access_token": "YOUR_ACCESS_TOKEN"
+        },
+        "callout:my_jwt_api": {
+            "auth_type": "Jwt",
+            "token": "YOUR_JWT"
+        }
+    }
+}
+```
+
+| `auth_type` | Fields read | Header sent |
+| ----------- | ------------------------------- | --------------------------------------- |
+| `Basic`     | `username`, `password`          | `Authorization: Basic <base64 user:pw>` |
+| `Custom`    | `custom_headers` (sent verbatim)| the headers you list                    |
+| `OAuth`     | `access_token` or `token`       | `Authorization: Bearer <token>`         |
+| `Jwt`       | `access_token` or `token`       | `Authorization: Bearer <token>`         |
+
+`OAuth`/`Jwt` take a token you supply for the local run — the SDK does not fetch
+or refresh it. In the Data Cloud runtime the Named Credential handles token
+acquisition; this local config only stands in for that during testing.

datacustomcode/templates/function/example/chunking_with_external_callout/config.json

@@ -0,0 +1,3 @@
+{
+    "entryPoint": "entrypoint.py"
+}