nominal 1.100.0__py3-none-any.whl → 1.102.0__py3-none-any.whl

nominal/core/client.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 from io import TextIOBase
 from pathlib import Path
-from typing import BinaryIO, Iterable, Mapping, Sequence
+from typing import BinaryIO, Iterable, Mapping, Sequence, overload
 
 import certifi
 import conjure_python_client
@@ -16,7 +16,6 @@ from nominal_api import (
     api,
     attachments_api,
     authentication_api,
-    event,
     ingest_api,
     scout_asset_api,
     scout_catalog,
@@ -24,7 +23,6 @@ from nominal_api import (
     scout_datasource_connection_api,
     scout_layout_api,
     scout_notebook_api,
-    scout_run_api,
     scout_template_api,
     scout_video_api,
     scout_workbookcommon_api,
@@ -34,18 +32,18 @@ from nominal_api import (
 from typing_extensions import Self, deprecated
 
 from nominal import ts
+from nominal._utils.deprecation_tools import warn_on_deprecated_argument
 from nominal.config import NominalConfig, _config
 from nominal.core._clientsbunch import ClientsBunch
 from nominal.core._constants import DEFAULT_API_BASE_URL
+from nominal.core._event_types import EventType
 from nominal.core._utils.api_tools import (
     Link,
     LinkDict,
     construct_user_agent_string,
-    create_links,
     rid_from_instance_or_string,
 )
 from nominal.core._utils.multipart import (
-    path_upload_name,
     upload_multipart_io,
 )
 from nominal.core._utils.pagination_tools import (
@@ -55,7 +53,6 @@ from nominal.core._utils.pagination_tools import (
     search_checklists_paginated,
     search_data_reviews_paginated,
     search_datasets_paginated,
-    search_events_paginated,
     search_runs_by_asset_paginated,
     search_runs_paginated,
     search_secrets_paginated,
@@ -69,7 +66,6 @@ from nominal.core._utils.query_tools import (
     create_search_checklists_query,
     create_search_containerized_extractors_query,
     create_search_datasets_query,
-    create_search_events_query,
     create_search_runs_query,
     create_search_secrets_query,
     create_search_users_query,
@@ -95,10 +91,10 @@ from nominal.core.dataset import (
     _get_datasets,
 )
 from nominal.core.datasource import DataSource
-from nominal.core.event import Event, EventType
-from nominal.core.exceptions import NominalConfigError, NominalError, NominalIngestError, NominalMethodRemovedError
+from nominal.core.event import Event, _create_event, _search_events
+from nominal.core.exceptions import NominalConfigError, NominalError, NominalMethodRemovedError
 from nominal.core.filetype import FileType, FileTypes
-from nominal.core.run import Run
+from nominal.core.run import Run, _create_run
 from nominal.core.secret import Secret
 from nominal.core.unit import Unit, _available_units
 from nominal.core.user import User
@@ -109,8 +105,6 @@ from nominal.core.workspace import Workspace
 from nominal.ts import (
     IntegralNanosecondsDuration,
     IntegralNanosecondsUTC,
-    _SecondsNanos,
-    _to_api_duration,
     _to_typed_timestamp_type,
 )
 
@@ -492,6 +486,7 @@ class NominalClient:
         )
         return list(self._iter_search_videos(query))
 
+    @overload
     def create_run(
         self,
         name: str,
@@ -503,24 +498,96 @@ class NominalClient:
         labels: Sequence[str] = (),
         links: Sequence[str | Link | LinkDict] = (),
         attachments: Iterable[Attachment] | Iterable[str] = (),
+    ) -> Run: ...
+    @overload
+    def create_run(
+        self,
+        name: str,
+        start: datetime | IntegralNanosecondsUTC,
+        end: datetime | IntegralNanosecondsUTC | None,
+        description: str | None = None,
+        *,
+        properties: Mapping[str, str] | None = None,
+        labels: Sequence[str] = (),
+        links: Sequence[str | Link | LinkDict] = (),
+        attachments: Iterable[Attachment] | Iterable[str] = (),
+        asset: Asset | str,
+    ) -> Run: ...
+    @overload
+    def create_run(
+        self,
+        name: str,
+        start: datetime | IntegralNanosecondsUTC,
+        end: datetime | IntegralNanosecondsUTC | None,
+        description: str | None = None,
+        *,
+        properties: Mapping[str, str] | None = None,
+        labels: Sequence[str] = (),
+        links: Sequence[str | Link | LinkDict] = (),
+        attachments: Iterable[Attachment] | Iterable[str] = (),
+        assets: Sequence[Asset | str],
+    ) -> Run: ...
+    @warn_on_deprecated_argument(
+        "asset", "The 'asset' parameter is deprecated and will be removed in a future release. Use 'assets' instead."
+    )
+    def create_run(
+        self,
+        name: str,
+        start: datetime | IntegralNanosecondsUTC,
+        end: datetime | IntegralNanosecondsUTC | None,
+        description: str | None = None,
+        *,
+        properties: Mapping[str, str] | None = None,
+        labels: Sequence[str] | None = None,
+        links: Sequence[str | Link | LinkDict] | None = None,
+        attachments: Iterable[Attachment] | Iterable[str] | None = None,
         asset: Asset | str | None = None,
+        assets: Sequence[Asset | str] | None = None,
     ) -> Run:
-        """Create a run."""
-        request = scout_run_api.CreateRunRequest(
-            attachments=[rid_from_instance_or_string(a) for a in attachments],
-            data_sources={},
-            description=description or "",
-            labels=list(labels),
-            links=create_links(links),
-            properties={} if properties is None else dict(properties),
-            start_time=_SecondsNanos.from_flexible(start).to_scout_run_api(),
-            title=name,
-            end_time=None if end is None else _SecondsNanos.from_flexible(end).to_scout_run_api(),
-            assets=[] if asset is None else [rid_from_instance_or_string(asset)],
-            workspace=self._clients.workspace_rid,
+        """Create a run, which is is effectively a slice of time across a collection of assets and datasources.
+
+        Args:
+            name: Name of the run to create
+            start: Starting timestamp of the run to create
+            end: Ending timestamp of the run to create, or None for an unbounded run.
+            description: Optional description of the run to create
+            properties: Optional key-value pairs to use as properties on the created run
+            labels: Optional sequence of labels for the created run
+            links: Link metadata to add to the created run
+            attachments: Attachments to associate with the created run
+            asset: Singular asset to associate with the run
+                NOTE: mutually exclusive with `assets`
+                NOTE: deprecated-- use `assets` instead.
+            assets: Sequence of assets to associate with the run
+                NOTE: mutually exclusive with `asset`
+
+        Returns:
+            Reference to the created run object
+
+        Raises:
+            ValueError: both `asset` and `assets` provided
+            ConjureHTTPError: error making request
+
+        """
+        if asset and assets:
+            raise ValueError("Only one of 'asset' and 'assets' may be provided")
+        elif asset:
+            assets = [asset]
+        elif assets is None:
+            assets = []
+
+        return _create_run(
+            self._clients,
+            name=name,
+            start=start,
+            end=end,
+            description=description,
+            properties=properties,
+            labels=labels,
+            links=links,
+            attachments=attachments,
+            asset_rids=[rid_from_instance_or_string(asset) for asset in assets],
         )
-        response = self._clients.run.create_run(self._clients.auth_header, request)
-        return Run._from_conjure(self._clients, response)
 
     def get_run(self, rid: str) -> Run:
         """Retrieve a run by its RID."""
@@ -665,7 +732,7 @@ class NominalClient:
 
         return dataset
 
-    def create_empty_video(
+    def create_video(
         self,
         name: str,
         *,
@@ -695,6 +762,8 @@ class NominalClient:
         )
         return Video._from_conjure(self._clients, response)
 
+    create_empty_video = create_video
+
     def get_video(self, rid: str) -> Video:
         """Retrieve a video by its RID."""
         response = self._clients.video.get(self._clients.auth_header, rid)
@@ -890,6 +959,10 @@ class NominalClient:
         response = self._clients.connection.get_connection(self._clients.auth_header, rid)
         return Connection._from_conjure(self._clients, response)
 
+    @deprecated(
+        "`create_video_from_mcap` is deprecated and will be removed in a future version. "
+        "Create a new video with `create_video` and then `add_mcap` to upload a file to the video."
+    )
     def create_video_from_mcap(
         self,
         path: Path | str,
@@ -910,18 +983,14 @@ class NominalClient:
         if name is None:
             name = path.name
 
-        with path.open("rb") as data_file:
-            return self.create_video_from_mcap_io(
-                data_file,
-                name=name,
-                topic=topic,
-                file_type=FileTypes.MCAP,
-                description=description,
-                labels=labels,
-                properties=properties,
-                file_name=path_upload_name(path, FileTypes.MCAP),
-            )
+        video = self.create_video(name, description=description, labels=labels, properties=properties)
+        video.add_mcap(path, topic, description)
+        return video
 
+    @deprecated(
+        "`create_video_from_mcap_io` is deprecated and will be removed in a future version. "
+        "Create a new video with `create_video` and then `add_mcap_from_io` to upload a file to the video."
+    )
     def create_video_from_mcap_io(
         self,
         mcap: BinaryIO,
@@ -940,40 +1009,9 @@ class NominalClient:
 
         If name is None, the name of the file will be used.
         """
-        if isinstance(mcap, TextIOBase):
-            raise TypeError(f"dataset {mcap} must be open in binary mode, rather than text mode")
-
-        if file_name is None:
-            file_name = name
-
-        file_type = FileType(*file_type)
-        s3_path = upload_multipart_io(
-            self._clients.auth_header, self._clients.workspace_rid, mcap, file_name, file_type, self._clients.upload
-        )
-        request = ingest_api.IngestRequest(
-            options=ingest_api.IngestOptions(
-                video=ingest_api.VideoOpts(
-                    source=ingest_api.IngestSource(s3=ingest_api.S3IngestSource(s3_path)),
-                    target=ingest_api.VideoIngestTarget(
-                        new=ingest_api.NewVideoIngestDestination(
-                            title=name,
-                            description=description,
-                            properties={} if properties is None else dict(properties),
-                            labels=list(labels),
-                            workspace=self._clients.workspace_rid,
-                            marking_rids=[],
-                        )
-                    ),
-                    timestamp_manifest=scout_video_api.VideoFileTimestampManifest(
-                        mcap=scout_video_api.McapTimestampManifest(api.McapChannelLocator(topic=topic))
-                    ),
-                )
-            )
-        )
-        response = self._clients.ingest.ingest(self._clients.auth_header, request)
-        if response.details.video is None:
-            raise NominalIngestError("error ingesting mcap video: no video created")
-        return self.get_video(response.details.video.video_rid)
+        video = self.create_video(name, description=description, labels=labels, properties=properties)
+        video.add_mcap_from_io(mcap, file_name or name, topic, description, file_type)
+        return video
 
     def create_streaming_connection(
         self,
@@ -1158,19 +1196,17 @@ class NominalClient:
         properties: Mapping[str, str] | None = None,
         labels: Iterable[str] = (),
     ) -> Event:
-        request = event.CreateEvent(
+        return _create_event(
+            clients=self._clients,
             name=name,
+            type=type,
+            start=start,
+            duration=duration,
             description=description,
-            asset_rids=[rid_from_instance_or_string(asset) for asset in assets],
-            timestamp=_SecondsNanos.from_flexible(start).to_api(),
-            duration=_to_api_duration(duration),
-            origins=[],
-            properties=dict(properties) if properties else {},
-            labels=list(labels),
-            type=type._to_api_event_type(),
+            assets=assets,
+            properties=properties,
+            labels=labels,
         )
-        response = self._clients.event.create_event(self._clients.auth_header, request)
-        return Event._from_conjure(self._clients, response)
 
     def get_event(self, rid: str) -> Event:
         events = self.get_events([rid])
@@ -1205,10 +1241,6 @@ class NominalClient:
         # TODO (drake-nominal): Expose checklist_refs to users
         return list(self._iter_search_data_reviews(assets, runs))
 
-    def _iter_search_events(self, query: event.SearchQuery) -> Iterable[Event]:
-        for e in search_events_paginated(self._clients.event, self._clients.auth_header, query):
-            yield Event._from_conjure(self._clients, e)
-
     def search_events(
         self,
         *,
@@ -1251,21 +1283,21 @@ class NominalClient:
         Returns:
             All events which match all of the provided conditions
         """
-        query = create_search_events_query(
+        return _search_events(
+            clients=self._clients,
             search_text=search_text,
             after=after,
             before=before,
-            assets=None if assets is None else [rid_from_instance_or_string(asset) for asset in assets],
+            asset_rids=[rid_from_instance_or_string(asset) for asset in assets] if assets else None,
             labels=labels,
             properties=properties,
-            created_by=rid_from_instance_or_string(created_by) if created_by else None,
-            workbook=rid_from_instance_or_string(workbook) if workbook else None,
-            data_review=rid_from_instance_or_string(data_review) if data_review else None,
-            assignee=rid_from_instance_or_string(assignee) if assignee else None,
+            created_by_rid=rid_from_instance_or_string(created_by) if created_by else None,
+            workbook_rid=rid_from_instance_or_string(workbook) if workbook else None,
+            data_review_rid=rid_from_instance_or_string(data_review) if data_review else None,
+            assignee_rid=rid_from_instance_or_string(assignee) if assignee else None,
             event_type=event_type,
             workspace_rid=self._workspace_rid_for_search(workspace or WorkspaceSearchType.ALL),
         )
-        return list(self._iter_search_events(query))
 
     def get_containerized_extractor(self, rid: str) -> ContainerizedExtractor:
         return ContainerizedExtractor._from_conjure(
@@ -1453,7 +1485,7 @@ class NominalClient:
             properties: A mapping of key-value pairs that must ALL be present on an workbook to be included.
             created_by: Searches for workbook templates with the given creator's rid
             archived: Searches for workbook templates that are archived if true
-            published: Searches f8or workbook templates that have been published if true
+            published: Searches for workbook templates that have been published if true
 
         Returns:
             All workbook templates which match all of the provided conditions

nominal/core/dataset.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import abc
 import logging
 from dataclasses import dataclass
 from datetime import timedelta
@@ -8,7 +9,7 @@ from pathlib import Path
 from types import MappingProxyType
 from typing import BinaryIO, Iterable, Mapping, Sequence, TypeAlias, overload
 
-from nominal_api import api, ingest_api, scout_catalog
+from nominal_api import api, ingest_api, scout_asset_api, scout_catalog
 from typing_extensions import Self, deprecated
 
 from nominal.core._stream.batch_processor import process_log_batch
@@ -646,6 +647,288 @@ class Dataset(DataSource, RefreshableMixin[scout_catalog.EnrichedDataset]):
         )
 
 
+def _unify_tags(datascope_tags: Mapping[str, str], provided_tags: Mapping[str, str] | None) -> Mapping[str, str]:
+    return {**datascope_tags, **(provided_tags or {})}
+
+
+class _DatasetWrapper(abc.ABC):
+    """A lightweight façade over `nominal.core.Dataset` that routes ingest calls through a *data scope*.
+
+    `_DatasetWrapper` resolves `data_scope_name` to a backing `nominal.core.Dataset` and then delegates to the
+    corresponding `Dataset` method.
+
+    How this differs from `Dataset`
+    -------------------------------
+    - All "add data" methods take an extra first argument, `data_scope_name`, which selects the target dataset.
+    - For methods that accept `tags`, this wrapper merges the scope's required tags into the provided tags.
+      User-provided tags take precedence on key collisions.
+    - Some formats cannot be safely tagged with scope tags; those wrapper methods raise `RuntimeError` when the selected
+      scope requires tags.
+
+    Subclasses must implement `_list_dataset_scopes`, which is used to resolve scopes.
+    """
+
+    # static typing for required field
+    _clients: Dataset._Clients
+
+    @abc.abstractmethod
+    def _list_dataset_scopes(self) -> Sequence[scout_asset_api.DataScope]:
+        """Return the data scopes available to this wrapper.
+
+        Subclasses provide the authoritative list of `scout_asset_api.DataScope` objects used to
+        resolve `data_scope_name` in wrapper methods.
+        """
+
+    def _get_dataset_scope(self, data_scope_name: str) -> tuple[Dataset, Mapping[str, str]]:
+        """Resolve a data scope name to its backing dataset and required series tags.
+
+        Returns:
+            A tuple of the resolved `Dataset` and the scope's required `series_tags`.
+
+        Raises:
+            ValueError: If no scope exists with the given `data_scope_name`, or if the scope is not backed by a dataset.
+        """
+        dataset_scopes = {scope.data_scope_name: scope for scope in self._list_dataset_scopes()}
+        data_scope = dataset_scopes.get(data_scope_name)
+        if data_scope is None:
+            raise ValueError(f"No such data scope found with data_scope_name {data_scope_name}")
+        elif data_scope.data_source.dataset is None:
+            raise ValueError(f"Datascope {data_scope_name} is not a dataset!")
+
+        dataset = Dataset._from_conjure(
+            self._clients,
+            _get_dataset(self._clients.auth_header, self._clients.catalog, data_scope.data_source.dataset),
+        )
+        return dataset, data_scope.series_tags
+
+    ################
+    # Add Data API #
+    ################
+
+    def add_tabular_data(
+        self,
+        data_scope_name: str,
+        path: Path | str,
+        *,
+        timestamp_column: str,
+        timestamp_type: _AnyTimestampType,
+        tag_columns: Mapping[str, str] | None = None,
+        tags: Mapping[str, str] | None = None,
+    ) -> DatasetFile:
+        """Append tabular data on-disk to the dataset selected by `data_scope_name`.
+
+        This method behaves like `nominal.core.Dataset.add_tabular_data`, except that the data scope's required
+        tags are merged into `tags` before ingest (with user-provided tags taking precedence on key collisions).
+
+        For supported file types, argument semantics, and return value details, see
+        `nominal.core.Dataset.add_tabular_data`.
+        """
+        dataset, scope_tags = self._get_dataset_scope(data_scope_name)
+        return dataset.add_tabular_data(
+            path,
+            timestamp_column=timestamp_column,
+            timestamp_type=timestamp_type,
+            tag_columns=tag_columns,
+            tags=_unify_tags(scope_tags, tags),
+        )
+
+    def add_avro_stream(
+        self,
+        data_scope_name: str,
+        path: Path | str,
+    ) -> DatasetFile:
+        """Upload an avro stream file to the dataset selected by `data_scope_name`.
+
+        This method behaves like `nominal.core.Dataset.add_avro_stream`, with one important difference:
+        avro stream ingestion does not support applying scope tags. If the selected scope requires tags, this method
+        raises `RuntimeError` rather than ingesting (potentially) untagged data. This file may still be ingested
+        directly on the dataset itself if it is known to contain the correct set of tags.
+
+        For schema requirements and return value details, see
+        `nominal.core.Dataset.add_avro_stream`.
+        """
+        dataset, scope_tags = self._get_dataset_scope(data_scope_name)
+
+        # TODO(drake): remove once avro stream supports ingest with tags
+        if scope_tags:
+            raise RuntimeError(
+                f"Cannot add avro files to datascope {data_scope_name}-- data would not get "
+                f"tagged with required tags: {scope_tags}"
+            )
+
+        return dataset.add_avro_stream(path)
+
+    def add_journal_json(
+        self,
+        data_scope_name: str,
+        path: Path | str,
+    ) -> DatasetFile:
+        """Add a journald json file to the dataset selected by `data_scope_name`.
+
+        This method behaves like `nominal.core.Dataset.add_journal_json`, with one important difference:
+        journal json ingestion does not support applying scope tags as args. If the selected scope requires tags,
+        this method raises `RuntimeError` rather than potentially ingesting untagged data. This file may still be
+        ingested directly on the dataset itself if it is known to contain the correct set of args.
+
+        For file expectations and return value details, see
+        `nominal.core.Dataset.add_journal_json`.
+        """
+        dataset, scope_tags = self._get_dataset_scope(data_scope_name)
+
+        # TODO(drake): remove once journal json supports ingest with tags
+        if scope_tags:
+            raise RuntimeError(
+                f"Cannot add journal json files to datascope {data_scope_name}-- data would not get "
+                f"tagged with required arguments: {scope_tags}"
+            )
+
+        return dataset.add_journal_json(path)
+
+    def add_mcap(
+        self,
+        data_scope_name: str,
+        path: Path | str,
+        *,
+        include_topics: Iterable[str] | None = None,
+        exclude_topics: Iterable[str] | None = None,
+    ) -> DatasetFile:
+        """Add an MCAP file to the dataset selected by `data_scope_name`.
+
+        This method behaves like `nominal.core.Dataset.add_mcap`, with one important difference:
+        MCAP ingestion does not support applying scope tags. If the selected scope requires tags, this method raises
+        `RuntimeError` rather than ingesting untagged data.
+
+        For topic-filtering semantics and return value details, see
+        `nominal.core.Dataset.add_mcap`.
+        """
+        dataset, scope_tags = self._get_dataset_scope(data_scope_name)
+
+        # TODO(drake): remove once MCAP supports ingest with tags
+        if scope_tags:
+            raise RuntimeError(
+                f"Cannot add mcap files to datascope {data_scope_name}-- data would not get "
+                f"tagged with required tags: {scope_tags}"
+            )
+
+        return dataset.add_mcap(path, include_topics=include_topics, exclude_topics=exclude_topics)
+
+    def add_ardupilot_dataflash(
+        self,
+        data_scope_name: str,
+        path: Path | str,
+        tags: Mapping[str, str] | None = None,
+    ) -> DatasetFile:
+        """Add a Dataflash file to the dataset selected by `data_scope_name`.
+
+        This method behaves like `nominal.core.Dataset.add_ardupilot_dataflash`, except that the data scope's
+        required tags are merged into `tags` before ingest (with user-provided tags taking precedence on key
+        collisions).
+
+        For file expectations and return value details, see
+        `nominal.core.Dataset.add_ardupilot_dataflash`.
+        """
+        dataset, scope_tags = self._get_dataset_scope(data_scope_name)
+        return dataset.add_ardupilot_dataflash(path, tags=_unify_tags(scope_tags, tags))
+
+    @overload
+    def add_containerized(
+        self,
+        data_scope_name: str,
+        extractor: str | ContainerizedExtractor,
+        sources: Mapping[str, Path | str],
+        *,
+        tag: str | None = None,
+        tags: Mapping[str, str] | None = None,
+    ) -> DatasetFile: ...
+    @overload
+    def add_containerized(
+        self,
+        data_scope_name: str,
+        extractor: str | ContainerizedExtractor,
+        sources: Mapping[str, Path | str],
+        *,
+        tag: str | None = None,
+        tags: Mapping[str, str] | None = None,
+        timestamp_column: str,
+        timestamp_type: _AnyTimestampType,
+    ) -> DatasetFile: ...
+    def add_containerized(
+        self,
+        data_scope_name: str,
+        extractor: str | ContainerizedExtractor,
+        sources: Mapping[str, Path | str],
+        *,
+        tag: str | None = None,
+        tags: Mapping[str, str] | None = None,
+        timestamp_column: str | None = None,
+        timestamp_type: _AnyTimestampType | None = None,
+    ) -> DatasetFile:
+        """Add data from proprietary formats using a pre-registered custom extractor.
+
+        This method behaves like `nominal.core.Dataset.add_containerized`, except that the data scope's required
+        tags are merged into `tags` before ingest (with user-provided tags taking precedence on key collisions).
+
+        This wrapper also enforces that `timestamp_column` and `timestamp_type` are provided together (or omitted
+        together) before delegating.
+
+        For extractor inputs, tagging semantics, timestamp metadata behavior, and return value details, see
+        `nominal.core.Dataset.add_containerized`.
+        """
+        dataset, scope_tags = self._get_dataset_scope(data_scope_name)
+        if timestamp_column is None and timestamp_type is None:
+            return dataset.add_containerized(
+                extractor,
+                sources,
+                tag=tag,
+                tags=_unify_tags(scope_tags, tags),
+            )
+        elif timestamp_column is not None and timestamp_type is not None:
+            return dataset.add_containerized(
+                extractor,
+                sources,
+                tag=tag,
+                tags=_unify_tags(scope_tags, tags),
+                timestamp_column=timestamp_column,
+                timestamp_type=timestamp_type,
+            )
+        else:
+            raise ValueError(
+                "Only one of `timestamp_column` and `timestamp_type` were provided to `add_containerized`, "
+                "either both must or neither must be provided."
+            )
+
+    def add_from_io(
+        self,
+        data_scope_name: str,
+        data_stream: BinaryIO,
+        file_type: tuple[str, str] | FileType,
+        *,
+        timestamp_column: str,
+        timestamp_type: _AnyTimestampType,
+        file_name: str | None = None,
+        tag_columns: Mapping[str, str] | None = None,
+        tags: Mapping[str, str] | None = None,
+    ) -> DatasetFile:
+        """Append to the dataset selected by `data_scope_name` from a file-like object.
+
+        This method behaves like `nominal.core.Dataset.add_from_io`, except that the data scope's required tags
+        are merged into `tags` before ingest (with user-provided tags taking precedence on key collisions).
+
+        For stream requirements, supported file types, argument semantics, and return value details, see
+        `nominal.core.Dataset.add_from_io`.
+        """
+        dataset, scope_tags = self._get_dataset_scope(data_scope_name)
+        return dataset.add_from_io(
+            data_stream,
+            timestamp_column=timestamp_column,
+            timestamp_type=timestamp_type,
+            file_type=file_type,
+            file_name=file_name,
+            tag_columns=tag_columns,
+            tags=_unify_tags(scope_tags, tags),
+        )
+
+
 @deprecated(
     "poll_until_ingestion_completed() is deprecated and will be removed in a future release. "
     "Instead, call poll_until_ingestion_completed() on individual DatasetFiles."