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

datacustomcode/io/reader/base.py

@@ -41,3 +41,45 @@ class BaseDataCloudReader(BaseDataAccessLayer):
         name: str,
         schema: Union[AtomicType, StructType, str, None] = None,
     ) -> PySparkDataFrame: ...
+
+    def read_dlo_deltas(self) -> PySparkDataFrame:
+        """Read the streaming change feed (deltas) for a Data Lake Object.
+
+        This is the streaming counterpart to :meth:`read_dlo`. It returns a
+        streaming DataFrame over the change feed the Data Cloud runtime
+        publishes for a streaming (``DELTA_SYNC``) transform. Concrete
+        streaming behavior is provided by the deployed Data Cloud runtime; the
+        base implementation raises :class:`NotImplementedError` so local
+        readers that do not support streaming fail clearly.
+
+        Returns:
+            A streaming PySpark DataFrame over the DLO change feed.
+
+        Raises:
+            NotImplementedError: If the active reader does not support streaming
+                deltas (e.g. the local development readers).
+        """
+        raise NotImplementedError(
+            "read_dlo_deltas is only supported when running in the Data Cloud "
+            "streaming runtime; the local reader does not support streaming "
+            "deltas."
+        )
+
+    def read_dmo_deltas(self) -> PySparkDataFrame:
+        """Read the streaming change feed (deltas) for a Data Model Object.
+
+        Streaming counterpart to :meth:`read_dmo`. See :meth:`read_dlo_deltas`
+        for behavior and the local-development caveat.
+
+        Returns:
+            A streaming PySpark DataFrame over the DMO change feed.
+
+        Raises:
+            NotImplementedError: If the active reader does not support streaming
+                deltas (e.g. the local development readers).
+        """
+        raise NotImplementedError(
+            "read_dmo_deltas is only supported when running in the Data Cloud "
+            "streaming runtime; the local reader does not support streaming "
+            "deltas."
+        )

datacustomcode/io/writer/base.py

@@ -22,6 +22,7 @@ from datacustomcode.io.base import BaseDataAccessLayer
 
 if TYPE_CHECKING:
     from pyspark.sql import DataFrame as PySparkDataFrame, SparkSession
+    from pyspark.sql.streaming import StreamingQuery
 
 
 class WriteMode(str, Enum):
@@ -57,3 +58,35 @@ class BaseDataCloudWriter(BaseDataAccessLayer):
     def write_to_dmo(
         self, name: str, dataframe: PySparkDataFrame, write_mode: WriteMode
     ) -> None: ...
+
+    def write_dlo_deltas(
+        self, name: str, dataframe: PySparkDataFrame
+    ) -> StreamingQuery:
+        """Write a streaming DataFrame of deltas to a Data Lake Object.
+
+        Streaming counterpart to :meth:`write_to_dlo`. Starts a streaming query
+        that writes each micro-batch to the target DLO via the Data Cloud
+        streaming sink and returns the resulting ``StreamingQuery`` handle. The
+        runtime owns the trigger and checkpoint location; callers pass only the
+        table name. Concrete streaming behavior is provided by the deployed
+        Data Cloud runtime; the base implementation raises
+        :class:`NotImplementedError`.
+
+        Args:
+            name: Target Data Lake Object name.
+            dataframe: Streaming PySpark DataFrame produced from a
+                ``read_dlo_deltas`` / ``read_dmo_deltas`` source.
+
+        Returns:
+            The started ``StreamingQuery``; the caller drives its lifecycle
+            (typically ``query.awaitTermination()``).
+
+        Raises:
+            NotImplementedError: If the active writer does not support streaming
+                deltas (e.g. the local development writers).
+        """
+        raise NotImplementedError(
+            "write_dlo_deltas is only supported when running in the Data Cloud "
+            "streaming runtime; the local writer does not support streaming "
+            "deltas."
+        )

datacustomcode/named_credential/__init__.py

@@ -15,6 +15,7 @@
 
 from datacustomcode.named_credential.base import NamedCredential
 from datacustomcode.named_credential.default import DefaultNamedCredential
+from datacustomcode.named_credential.errors import NamedCredentialCallError
 from datacustomcode.named_credential.spark_base import SparkNamedCredential
 from datacustomcode.named_credential.spark_default import DefaultSparkNamedCredential
 
@@ -22,5 +23,6 @@ __all__ = [
     "DefaultNamedCredential",
     "DefaultSparkNamedCredential",
     "NamedCredential",
+    "NamedCredentialCallError",
     "SparkNamedCredential",
 ]

datacustomcode/named_credential/direct/transport.py

@@ -31,11 +31,9 @@ from typing import (
 import requests
 
 from datacustomcode.named_credential.direct.auth import DynamicAuthHandler
-from datacustomcode.named_credential.direct.credentials import (
-    CredentialError,
-    CredentialStore,
-)
+from datacustomcode.named_credential.direct.credentials import CredentialStore
 from datacustomcode.named_credential.direct.url_resolver import resolve_base_url
+from datacustomcode.named_credential.errors import NamedCredentialCallError
 from datacustomcode.token_provider import (
     CredentialsTokenProvider,
     SFCLITokenProvider,
@@ -69,7 +67,7 @@ class DirectCalloutTransport:
     def callout(self, callout_request: Dict[str, Any]) -> Dict[str, Any]:
         raw_url = callout_request["path"]
         if not raw_url.startswith("callout:"):
-            raise CredentialError(
+            raise NamedCredentialCallError(
                 f"Callout URL must start with 'callout:', got '{raw_url}'."
             )
 
@@ -83,7 +81,9 @@ class DirectCalloutTransport:
         path_suffix = raw_url[sep_idx:]
 
         if callout_key == "callout:":
-            raise CredentialError(f"Named Credential name is empty in URL '{raw_url}'.")
+            raise NamedCredentialCallError(
+                f"Named Credential name is empty in URL '{raw_url}'."
+            )
 
         cred_config = self._store.get(callout_key)
         base_url = self._base_url_cache.get(callout_key)

datacustomcode/named_credential/errors.py

@@ -0,0 +1,36 @@
+# 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.
+"""Exceptions raised by Named Credential implementations."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class NamedCredentialCallError(RuntimeError):
+    """Raised when a Named Credential external callout fails."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[object] = None,
+        error_code: Optional[str] = None,
+        error_message: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.error_code = error_code
+        self.error_message = error_message

datacustomcode/run.py

@@ -43,6 +43,15 @@ 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"
@@ -132,6 +141,8 @@ 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,6 +15,7 @@
 from __future__ import annotations
 
 import ast
+import copy
 import json
 import os
 import sys
@@ -32,6 +33,8 @@ 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(),
@@ -43,6 +46,20 @@ 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": "",
 }
@@ -160,6 +177,35 @@ 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."""
 
@@ -168,6 +214,9 @@ 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:
@@ -189,14 +238,15 @@ 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 = 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]
+                name = self._resolve_name_arg(arg)
 
                 if name:
                     if method_name == "read_dlo":
@@ -207,8 +257,29 @@ 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),
@@ -217,6 +288,13 @@ 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."""
@@ -301,23 +379,51 @@ def write_requirements_file(file_path: str) -> str:
     return requirements_path
 
 
-def scan_file(file_path: str) -> DataAccessLayerCalls:
-    """Scan a single Python file for Client read/write method calls."""
+def _visit_file(file_path: str) -> ClientMethodVisitor:
+    """Parse a Python file and return the populated method visitor."""
     with open(file_path, "r") as f:
-        code = f.read()
-        tree = ast.parse(code)
-        visitor = ClientMethodVisitor()
-        visitor.visit(tree)
-        return visitor.found()
+        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
 
-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."""
+
+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.
+    """
     config: dict[str, Any]
     if type == "script":
-        config = DATA_TRANSFORM_CONFIG_TEMPLATE.copy()
+        template = (
+            STREAMING_TRANSFORM_CONFIG_TEMPLATE
+            if streaming
+            else DATA_TRANSFORM_CONFIG_TEMPLATE
+        )
+        config = copy.deepcopy(template)
     elif type == "function":
-        config = FUNCTION_CONFIG_TEMPLATE.copy()
+        config = copy.deepcopy(FUNCTION_CONFIG_TEMPLATE)
     config["entryPoint"] = os.path.basename(file_path)
     return config
 
@@ -372,22 +478,51 @@ def update_config(file_path: str) -> dict[str, Any]:
 
     if package_type == "script":
         existing_config["dataspace"] = get_dataspace(existing_config)
-        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)
+        if file_is_streaming(file_path):
+            _update_streaming_config(existing_config, file_path)
         else:
-            write["dmo"] = list(output.write_to_dmo)
-
-        existing_config["permissions"] = {"read": read, "write": write}
+            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_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},
+    }
+
+
 def get_dataspace(existing_config: dict[str, str]) -> str:
     if "dataspace" in existing_config:
         dataspace_value = existing_config["dataspace"]

datacustomcode/template.py

@@ -23,8 +23,12 @@ 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) -> None:
+
+def copy_script_template(target_dir: str, streaming: bool = False) -> None:
     """Copy the template to the target directory."""
     os.makedirs(target_dir, exist_ok=True)
 
@@ -39,6 +43,14 @@ def copy_script_template(target_dir: str) -> 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/script/examples/streaming_deltas/entrypoint.py

@@ -0,0 +1,49 @@
+"""Streaming BYOC transform: read a DLO change feed and write the deltas back.
+
+This example is the streaming counterpart to a normal batch entrypoint. Instead
+of a batch ``Client`` with ``read_dlo`` / ``write_to_dlo`` (which read and write
+a bounded snapshot), it uses a :class:`StreamingClient` and its streaming delta
+methods:
+
+* ``client.read_dlo_deltas()`` returns a *streaming* DataFrame over the
+  Change Data Feed of the source DLO. Each row carries the source columns plus
+  change-feed metadata columns (``_record_type``, ``_commit_*``).
+* ``client.write_dlo_deltas(name, df)`` starts a streaming query that writes
+  each micro-batch to the target DLO and returns the ``StreamingQuery`` handle.
+  The runtime owns the trigger, and checkpoint location — the caller only
+  chooses the table.
+
+The transform in between is ordinary PySpark. Because the source is a change
+feed, keep the metadata columns on the DataFrame you hand to
+``write_dlo_deltas`` — the sink relies on them to merge changes correctly.
+
+This entrypoint only runs inside the Data Cloud streaming (``DELTA_SYNC``)
+runtime; the local ``datacustomcode run`` readers/writers raise
+``NotImplementedError`` for the delta methods.
+"""
+
+from pyspark.sql.functions import col, upper
+
+from datacustomcode.client import StreamingClient
+
+
+def main():
+    client = StreamingClient()
+
+    # Streaming DataFrame over the source DLO's change feed.
+    deltas = client.read_dlo_deltas()
+
+    # Ordinary PySpark transform.
+    transformed = deltas.withColumn("description__c", upper(col("description__c")))
+
+    # Start the streaming write. write_dlo_deltas returns the StreamingQuery;
+    # the trigger and checkpoint location are provided by the runtime.
+    query = client.write_dlo_deltas("Account_std_copy__dll", transformed)
+
+    # Drive the query's lifecycle. In the streaming runtime this blocks until
+    # the job is stopped by the platform.
+    query.awaitTermination()
+
+
+if __name__ == "__main__":
+    main()

{salesforce_data_customcode-6.1.0.dev2.dist-info → salesforce_data_customcode-6.1.0.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: salesforce-data-customcode
-Version: 6.1.0.dev2
+Version: 6.1.0.dev4
 Summary: Data Cloud Custom Code SDK
 License-Expression: Apache-2.0
 License-File: LICENSE.txt
@@ -170,15 +170,22 @@ Your Python dependencies can be packaged as .py files, .zip archives (containing
 
 ## API
 
-Your entry point script will define logic using the `Client` object which wraps data access layers.
+Your entry point script will define logic using the `Client` object (for batch transforms) or the `StreamingClient` object (for streaming delta transforms), which wrap the data access layers. Both are singletons; a single transform should use one or the other, not both.
 
-You should only need the following methods:
+For a batch transform, use `Client`. You should only need the following methods:
 * `find_file_path(file_name)` – Resolve a bundled file (placed under `payload/files/`) to a `pathlib.Path` that exists. Works the same locally and inside Data Cloud — see [Bundled file resolution](#bundled-file-resolution) below for the full lookup order. Raises `FileNotFoundError` if the file isn't found.
 * `read_dlo(name)` – Read from a Data Lake Object by name
 * `read_dmo(name)` – Read from a Data Model Object by name
 * `write_to_dlo(name, spark_dataframe, write_mode)` – Write to a Data Model Object by name with a Spark dataframe
 * `write_to_dmo(name, spark_dataframe, write_mode)` – Write to a Data Lake Object by name with a Spark dataframe
 
+For a streaming (delta) transform, use `StreamingClient`, which exposes the streaming counterparts:
+* `read_dlo_deltas()` – Read the streaming change feed (deltas) of a Data Lake Object as a streaming DataFrame.
+* `read_dmo_deltas()` – Read the streaming change feed (deltas) of a Data Model Object as a streaming DataFrame.
+* `write_dlo_deltas(name, spark_dataframe)` – Write a streaming DataFrame of deltas to a Data Lake Object; returns the started `StreamingQuery`
+
+`find_file_path`, `llm_gateway_generate_text`, and `einstein_predict` are available on both clients.
+
 For example:
 ```python
 from datacustomcode import Client
@@ -194,6 +201,36 @@ client.write_to_dlo('output_DLO')
 > [!WARNING]
 > Currently we only support reading from DMOs and writing to DMOs or reading from DLOs and writing to DLOs, but they cannot mix.
 
+### Streaming (delta) transforms
+
+Streaming BYOC transforms process a Data Lake Object's Change Data Feed continuously instead of reading a bounded snapshot. Use a `StreamingClient` and its `*_deltas` methods in place of the batch `Client` read/write methods:
+
+```python
+from pyspark.sql.functions import col, upper
+
+from datacustomcode import StreamingClient
+
+client = StreamingClient()
+
+# read_dlo_deltas returns a *streaming* DataFrame over the change feed.
+# The runtime resolves the single streaming source, so no name is passed.
+deltas = client.read_dlo_deltas()
+
+# Ordinary PySpark transform.
+transformed = deltas.withColumn("description__c", upper(col("description__c")))
+
+# write_dlo_deltas starts a streaming query and returns the StreamingQuery.
+# The runtime owns the trigger and checkpoint location; you
+# choose only the target table.
+query = client.write_dlo_deltas("Output__dll", transformed)
+query.awaitTermination()
+```
+
+Notes:
+
+- These methods only run inside the Data Cloud streaming (`DELTA_SYNC`) runtime. Locally (`datacustomcode run`) they raise `NotImplementedError`, since there is no change feed to stream.
+- A complete runnable entry point is provided in [`examples/streaming_deltas/entrypoint.py`](src/datacustomcode/templates/script/examples/streaming_deltas/entrypoint.py).
+
 ### Bundled file resolution
 
 Place bundled files (CSVs, prompt files, etc.) under `payload/files/`. The same `client.find_file_path("data.csv")` call resolves consistently across all three runtimes: