sift-stack-py 0.3.2__py3-none-any.whl

sift_py/ingestion/config/yaml/error.py

@@ -0,0 +1,44 @@
+from typing import Any, List, Optional
+
+from typing_extensions import Self
+
+_PREFIX = "  "
+_YAML_SEP = "---"
+_LIST_ITEM_PREFIX = "- "
+
+
+class YamlConfigError(Exception):
+    """
+    When the YAML config has missing or invalid properties.
+    """
+
+    message: str
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+    @classmethod
+    def _invalid_property(
+        cls,
+        actual_value: Any,
+        key_name: str,
+        expected_type: str,
+        ancestors: Optional[List[str]] = None,
+    ) -> Self:
+        header = f"Expected '{key_name.lstrip(_LIST_ITEM_PREFIX)}' to be <{expected_type}> but it is <{type(actual_value).__name__}>\n{_YAML_SEP}\n"
+
+        if ancestors is None or len(ancestors) == 0:
+            return cls(f"{header}{key_name}: <{expected_type}>")
+
+        key_value_path = ""
+
+        current_indentation_level = 0
+
+        for ancestor in ancestors:
+            key_value_path += f"{_PREFIX * current_indentation_level}{ancestor}:\n"
+            current_indentation_level += 1
+
+        key_value_path += f"{_PREFIX * current_indentation_level}{key_name}: <{expected_type}>"
+        output = f"{header}{key_value_path}"
+
+        return cls(output)

sift_py/ingestion/config/yaml/load.py

@@ -0,0 +1,126 @@
+from pathlib import Path
+from typing import Any, Dict, List, cast
+
+import yaml
+
+import sift_py.yaml.rule as rule_yaml
+from sift_py.ingestion.config.yaml.error import YamlConfigError
+from sift_py.ingestion.config.yaml.spec import (
+    FlowYamlSpec,
+    TelemetryConfigYamlSpec,
+)
+from sift_py.yaml.channel import ChannelConfigYamlSpec, _validate_channel, _validate_channel_anchor
+from sift_py.yaml.rule import RuleYamlSpec
+from sift_py.yaml.utils import _type_fqn
+
+load_named_expression_modules = rule_yaml.load_named_expression_modules
+
+
+def read_and_validate(path: Path) -> TelemetryConfigYamlSpec:
+    """
+    Reads in the telemetry config YAML file found at `path` and validates it. Any errors that may occur at the parsing
+    step will return an error whose source is the `yaml` package. Any errors that may occur during the
+    validation step will return a `sift_py.ingestion.config.yaml.error.YamlConfigError`.
+    """
+    raw_config = _read_yaml(path)
+    return _validate_yaml(raw_config)
+
+
+def _validate_yaml(raw_config: Dict[Any, Any]) -> TelemetryConfigYamlSpec:
+    asset_name = raw_config.get("asset_name")
+
+    if not isinstance(asset_name, str):
+        raise YamlConfigError._invalid_property(asset_name, "asset_name", "str")
+
+    ingestion_client_key = raw_config.get("ingestion_client_key")
+
+    if not isinstance(ingestion_client_key, str):
+        raise YamlConfigError._invalid_property(ingestion_client_key, "ingestion_client_key", "str")
+
+    organization_id = raw_config.get("organization_id")
+
+    if organization_id is not None and not isinstance(organization_id, str):
+        raise YamlConfigError._invalid_property(ingestion_client_key, "organization_id", "str")
+
+    channels = raw_config.get("channels")
+
+    if channels is not None:
+        if not isinstance(channels, dict):
+            raise YamlConfigError._invalid_property(
+                channels,
+                "channels",
+                f"Dict[str, {ChannelConfigYamlSpec}]",
+                None,
+            )
+
+        for anchor, channel_config in cast(Dict[Any, Any], channels).items():
+            _validate_channel_anchor(anchor)
+            _validate_channel(channel_config)
+
+    rules = raw_config.get("rules")
+
+    if rules is not None:
+        if not isinstance(rules, list):
+            raise YamlConfigError._invalid_property(
+                rules,
+                "rules",
+                f"List[{_type_fqn(RuleYamlSpec)}]",
+                None,
+            )
+
+        for rule in cast(List[Any], rules):
+            rule_yaml._validate_rule(rule)
+
+    flows = raw_config.get("flows")
+
+    if flows is not None:
+        if not isinstance(flows, list):
+            raise YamlConfigError._invalid_property(
+                flows,
+                "flows",
+                f"List[{_type_fqn(FlowYamlSpec)}]",
+                None,
+            )
+
+        for flow in cast(List[Any], flows):
+            _validate_flow(flow)
+
+    return cast(TelemetryConfigYamlSpec, raw_config)
+
+
+def _read_yaml(path: Path) -> Dict[Any, Any]:
+    with open(path, "r") as f:
+        return cast(Dict[Any, Any], yaml.safe_load(f.read()))
+
+
+def _validate_flow(val: Any):
+    flow = cast(Dict[Any, Any], val)
+
+    name = flow.get("name")
+
+    if not isinstance(name, str):
+        raise YamlConfigError._invalid_property(
+            name,
+            "- name",
+            "str",
+            ["flows"],
+        )
+
+    channels = flow.get("channels")
+
+    if channels is not None:
+        if not isinstance(channels, list):
+            raise YamlConfigError._invalid_property(
+                channels,
+                "channels",
+                f"List<{ChannelConfigYamlSpec}>",
+                ["flows"],
+            )
+
+        for channel in cast(List[Any], channels):
+            try:
+                _validate_channel(channel)
+            except YamlConfigError as err:
+                raise YamlConfigError(
+                    f"Flow '{name}' contains an invalid channel reference:\n{err}"
+                )

sift_py/ingestion/config/yaml/spec.py

@@ -0,0 +1,58 @@
+"""
+Formal specification of the types that `sift_py` expects when loading a telemetry config from a YAML file.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from typing_extensions import NotRequired, TypedDict
+
+import sift_py.yaml.channel as channel_yaml
+import sift_py.yaml.rule as rule_yaml
+
+RuleYamlSpec = rule_yaml.RuleYamlSpec
+NamedExpressionYamlSpec = rule_yaml.NamedExpressionYamlSpec
+ChannelConfigYamlSpec = channel_yaml.ChannelConfigYamlSpec
+ChannelEnumTypeYamlSpec = channel_yaml.ChannelEnumTypeYamlSpec
+ChannelBitFieldElementYamlSpec = channel_yaml.ChannelBitFieldElementYamlSpec
+
+
+class TelemetryConfigYamlSpec(TypedDict):
+    """
+    Formal spec that defines what the telemetry config should look like in YAML.
+
+    `asset_name`: The name of the asset to telemeter.
+    `ingestion_client_key`: User-defined string-key that uniquely identifies this telemetry config.
+    `organization_id`: Optional ID of user's organization. Required if user belongs to multiple orgs.
+    `channels`: Sensors that send the data.
+    `rules`: Rules that, when evaluated to a true, will perform some sort of acction.
+    `flows`: A list of named groups of channels that send data together.
+    """
+
+    asset_name: str
+    ingestion_client_key: str
+    organization_id: NotRequired[str]
+    channels: Dict[str, ChannelConfigYamlSpec]
+    rules: NotRequired[List[RuleYamlSpec]]
+    flows: NotRequired[List[FlowYamlSpec]]
+
+
+class FlowYamlSpec(TypedDict):
+    """
+    Formal spec that defines what a flow should look like in YAML.
+    """
+
+    name: str
+    channels: List[ChannelConfigYamlSpec]
+
+
+class YamlConfigError(Exception):
+    """
+    When the YAML config has missing or invalid properties.
+    """
+
+    message: str
+
+    def __init__(self, message: str):
+        super().__init__(message)

sift_py/ingestion/config/yaml/test_load.py

@@ -0,0 +1,25 @@
+import pytest
+
+from sift_py.ingestion.config.yaml import load
+from sift_py.ingestion.config.yaml.error import YamlConfigError
+
+
+def test__validate_flow():
+    load._validate_flow(
+        {
+            "name": "reading",
+            "channels": [
+                {"name": "voltage", "data_type": "double"},
+            ],
+        }
+    )
+
+    with pytest.raises(YamlConfigError):
+        load._validate_flow(
+            {
+                "name": "reading",
+                "channels": [
+                    {"name": "voltage", "data_type": "dubble"},
+                ],
+            }
+        )

sift_py/ingestion/flow.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Dict, List, Type, TypedDict
+
+from sift.ingest.v1.ingest_pb2 import IngestWithConfigDataChannelValue
+from sift.ingestion_configs.v1.ingestion_configs_pb2 import (
+    ChannelConfig as ChannelConfigPb,
+)
+from sift.ingestion_configs.v1.ingestion_configs_pb2 import (
+    FlowConfig as FlowConfigPb,
+)
+from typing_extensions import Self
+
+from sift_py._internal.convert.protobuf import AsProtobuf
+from sift_py.ingestion.channel import ChannelConfig, ChannelValue, channel_fqn
+
+
+class FlowConfig(AsProtobuf):
+    """
+    Describes a flow which is a set of channels whose values are often ingested together, allowing
+    users to send multiple data points for multiple channels in a single request.
+
+    `channel_by_fqn`:
+        A mapping of a channel's fully-qualified name to the index of the `sift_py.ingestion.channel.ChannelConfig`
+        as it appears in the `channels` attribute.
+    """
+
+    name: str
+    channels: List[ChannelConfig]
+    channel_by_fqn: Dict[str, int]
+
+    def __init__(self, name: str, channels: List[ChannelConfig]):
+        self.name = name
+        self.channels = channels
+        self.channel_by_fqn = {channel_fqn(c): i for i, c in enumerate(channels)}
+
+    def as_pb(self, klass: Type[FlowConfigPb]) -> FlowConfigPb:
+        return klass(
+            name=self.name,
+            channels=[conf.as_pb(ChannelConfigPb) for conf in self.channels],
+        )
+
+    @classmethod
+    def from_pb(cls, message: FlowConfigPb) -> Self:
+        return cls(
+            name=message.name,
+            channels=[ChannelConfig.from_pb(c) for c in message.channels],
+        )
+
+
+class Flow(TypedDict):
+    """
+    Represents a single flow that will be sent to Sift. Because this class uses `sift_py.ingestion.channel.ChannelValue`
+    which is a fully qualified channel value, a specific ordering of items in `channel_values` is not required. If a
+    particular flow has 5 channels, it is okay to send only data for 3 channels using this class.
+    """
+
+    flow_name: str
+    timestamp: datetime
+    channel_values: List[ChannelValue]
+
+
+class FlowOrderedChannelValues(TypedDict):
+    """
+    Represents a single flow that will be sent to Sift. Unlike `sift_py.ingestion.flow.Flow`, this class requires
+    that the ordering of channel values in `channel_values` match what the flow associated with `flow_name` expects.
+    If a channel doesn't have particular data to send for a particular time, `sift_py.ingestion.channel.empty_value` should be used
+    """
+
+    flow_name: str
+    timestamp: datetime
+    channel_values: List[IngestWithConfigDataChannelValue]

sift_py/ingestion/manager.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Callable, Dict, Iterator, Optional, TypedDict
+
+from typing_extensions import Self, TypeAlias
+
+from sift_py.grpc.transport import SiftChannel
+from sift_py.ingestion.config.telemetry import TelemetryConfig
+from sift_py.ingestion.service import IngestionService
+
+IngestionServiceBuilder: TypeAlias = Callable[[SiftChannel], IngestionService]
+
+
+class IngestionServicesManager:
+    """
+    Allows for the initialization of multiple instances of `sift_py.ingestion.service.IngestionService` from
+    either telemetry configs or builders under a single wrapper class that assists in managing data-ingestion
+    for multiple telemetry configs.
+
+    The initializer of this class can be used directly, but prefer to use either `from_builders` or `from_telemetry_configs`.
+    Prefer to use `from_builders` if you have custom options that you want to provide to `sift_py.ingestion.service.IngestionService.__init__`.
+
+    Example usage:
+
+    ```python
+    manager = IngestionServicesManager.from_telementry_configs(grpc_channel, {
+        "config_a": config_a,
+        "config_b": config_b,
+    })
+
+    with manager.ingestion_service("config_a") as config_a:
+        config_a.try_ingest_flow(...)
+
+    with manager.ingestion_service("config_b") as config_b:
+        config_b.try_ingest_flow(...)
+    ```
+    """
+
+    _transport_channel: SiftChannel
+    _ingestion_services: Dict[str, IngestionService]
+
+    def __init__(
+        self, transport_channel: SiftChannel, ingestion_services: Dict[str, IngestionService]
+    ):
+        self._transport_channel = transport_channel
+        self._ingestion_services = ingestion_services
+
+    @classmethod
+    def from_builders(
+        cls, channel: SiftChannel, builders: Dict[str, IngestionServiceBuilder]
+    ) -> Self:
+        return cls(
+            transport_channel=channel,
+            ingestion_services={key: builder(channel) for key, builder in builders.items()},
+        )
+
+    @classmethod
+    def from_telemetry_configs(
+        cls, channel: SiftChannel, telemetry_configs: Dict[str, TelemetryConfig]
+    ) -> Self:
+        return cls(
+            transport_channel=channel,
+            ingestion_services={
+                key: IngestionService(channel, config) for key, config in telemetry_configs.items()
+            },
+        )
+
+    def get_ingestion_service_by_identifier(self, identifier: str) -> Optional[IngestionService]:
+        return self._ingestion_services.get(identifier)
+
+    def __getitem__(self, identifier: str) -> Optional[IngestionService]:
+        return self.get_ingestion_service_by_identifier(identifier)
+
+    @contextmanager
+    def ingestion_service(self, identifier: str) -> Iterator[IngestionService]:
+        ingestion_service = self[identifier]
+
+        if ingestion_service is None:
+            raise IngestionServiceManagerError(
+                f"An ingestion service is not configured for the identifier '{identifier}'."
+            )
+
+        yield ingestion_service
+
+
+class IngestionServiceManagerError(Exception):
+    def __init__(self, msg: str):
+        return super().__init__(msg)
+
+
+class TelemetryConfigByIdentifierMap(TypedDict):
+    identifier: str
+    telemetry_config: TelemetryConfig
+
+
+class IngestionConfigServiceBuilderIdentifierMap(TypedDict):
+    identifier: str
+    builder: IngestionServiceBuilder

sift_py/ingestion/rule/__init__.py

@@ -0,0 +1,4 @@
+"""
+This module is deprecated and exists only to re-export members
+of `sift_py.rule`. Prefer to use that module.
+"""

sift_py/ingestion/rule/config.py

@@ -0,0 +1,11 @@
+import sift_py.rule.config as rule_config
+
+RuleConfig = rule_config.RuleConfig
+RuleAction = rule_config.RuleAction
+RuleActionCreateDataReviewAnnotation = rule_config.RuleActionCreateDataReviewAnnotation
+RuleActionCreatePhaseAnnotation = rule_config.RuleActionCreatePhaseAnnotation
+RuleActionAnnotationKind = rule_config.RuleActionAnnotationKind
+RuleActionKind = rule_config.RuleActionKind
+RuleActionKindStrRep = rule_config.RuleActionKindStrRep
+ExpressionChannelReference = rule_config.ExpressionChannelReference
+ExpressionChannelReferenceChannelConfig = rule_config.ExpressionChannelReferenceChannelConfig

sift_py/ingestion/service.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from sift.ingest.v1.ingest_pb2 import (
+    IngestWithConfigDataChannelValue,
+    IngestWithConfigDataStreamRequest,
+)
+from sift.ingestion_configs.v1.ingestion_configs_pb2 import IngestionConfig
+
+from sift_py.grpc.transport import SiftChannel
+from sift_py.ingestion._internal.ingest import _IngestionServiceImpl
+from sift_py.ingestion.buffer import BufferedIngestionService, OnErrorCallback
+from sift_py.ingestion.channel import ChannelValue
+from sift_py.ingestion.config.telemetry import TelemetryConfig
+from sift_py.ingestion.flow import Flow, FlowConfig, FlowOrderedChannelValues
+
+
+class IngestionService(_IngestionServiceImpl):
+    """
+    A fully configured service that, when instantiated, is ready to start ingesting data.
+
+    - `transport_channel`: A gRPC transport channel. Prefer to use `SiftChannel`.
+    - `ingestion_config`: The underlying strongly-typed ingestion config. Users of this service don't need to be concerned with this.
+    - `asset_name`: The name of the asset to telemeter.
+    - `flow_configs_by_name`: A mapping of flow config name to the actual flow config.
+    - `run_id`: The ID of the optional run to associated ingested data with.
+    - `organization_id`: ID of the organization of the user.
+    - `overwrite_rules`:
+        If there are rules in Sift that aren't found in the local telemetry config, then initializing
+        an `IngestionService` will raise an exception advising the user to update their telemetry config
+        with the missing rule before proceeding. Setting this field to `True` replace all rules currently
+        in Sift with the rules in the telemetry config.
+    - `end_stream_on_error`:
+        By default any errors that may occur during ingestion API-side are produced asynchronously and ingestion
+        won't be interrupted. The errors produced are surfaced on the user errors page. Setting this field to `True`
+        will ensure that any errors that occur during ingestion is returned immediately, terminating the stream. This
+        is useful for debugging purposes.
+    """
+
+    transport_channel: SiftChannel
+    ingestion_config: IngestionConfig
+    asset_name: str
+    flow_configs_by_name: Dict[str, FlowConfig]
+    run_id: Optional[str]
+    organization_id: Optional[str]
+    end_stream_on_error: bool
+
+    def __init__(
+        self,
+        channel: SiftChannel,
+        config: TelemetryConfig,
+        run_id: Optional[str] = None,
+        overwrite_rules: bool = False,
+        end_stream_on_error: bool = False,
+    ):
+        super().__init__(channel, config, run_id, overwrite_rules, end_stream_on_error)
+
+    def ingest(self, *requests: IngestWithConfigDataStreamRequest):
+        """
+        This method performs the actual data ingestion given a list of data ingestion requests.
+        """
+        super().ingest(*requests)
+
+    def attach_run(
+        self,
+        channel: SiftChannel,
+        run_name: str,
+        description: Optional[str] = None,
+        organization_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ):
+        """
+        Retrieve an existing run or create one to use during this period of ingestion.
+        """
+        super().attach_run(channel, run_name, description, organization_id, tags)
+
+    def detach_run(self):
+        """
+        Detach run from this period of ingestion. Subsequent data ingested won't be associated with
+        the run being detached.
+        """
+        super().detach_run()
+
+    def try_create_ingestion_request(
+        self,
+        flow_name: str,
+        timestamp: datetime,
+        channel_values: List[ChannelValue],
+    ) -> IngestWithConfigDataStreamRequest:
+        """
+        Creates an `IngestWithConfigDataStreamRequest`, i.e. a flow, given a `flow_name` and a
+        list of `ChannelValue` objects. Channels that appear in the flow config but not in the
+        `channel_values` will be assigned an empty value.
+
+        This function will perform validation checks to ensure that the values provided in the dictionary; this
+        includes:
+          - Making sure the flow exists
+          - Making sure that the there are no unexpected channels provided for the given flow
+          - Making sure the channel value is the expected type
+          - Making sure that the timestamp is in UTC
+          - Making sure channels that belong to a component have the 'component' field for the channel value
+
+        If any of the above validations fail then a `IngestionValidationError` will be raised.
+
+        If for performance reasons you'd prefer to skip the validation checks, or perhaps you did the
+        validations on your own, prefer to use `create_ingestion_request`. Any errors that occur during
+        ingestion will be handled by the Sift API.
+        """
+        return super().try_create_ingestion_request(flow_name, timestamp, channel_values)
+
+    def create_ingestion_request(
+        self,
+        flow_name: str,
+        timestamp: datetime,
+        channel_values: List[IngestWithConfigDataChannelValue],
+    ) -> IngestWithConfigDataStreamRequest:
+        """
+        Unlike `try_create_ingestion_request`, this skips argument validations. Useful for when user has already done their own
+        argument validation or if they require low-latency execution time client-side.
+
+        If there are errors that occur during ingestion and the `end_stream_on_error` attribute is set to `False`,
+        the data ingestion stream will skip over them and errors instead will be produced asynchronously and become
+        available in the UI application in the errors page. If `end_stream_on_error` is set to `True`, then the
+        data ingestion stream will be terminated if an error is encountered during ingestion.
+
+        These are some things to look out for when using this method instead of `try_create_ingestion_request`:
+        - Values in `channel_values` must appear in the same order its corresponding channel appears in the flow config
+          associated with the `flow_name`.
+        - The length of `channel_values` is expected to match the length of the channel configs list of the flow config
+          associated with `flow_name`. `sift_py.ingestion.channel.empty_value()` may be used if you require empty values.
+        - The `timestamp` must be in UTC.
+        """
+        return super().create_ingestion_request(flow_name, timestamp, channel_values)
+
+    def ingest_flows(self, *flows: FlowOrderedChannelValues):
+        """
+        Combines the requests creation step and ingestion into a single call.
+        See `create_ingestion_request` for information about how client-side validations are handled.
+        """
+        return super().ingest_flows(*flows)
+
+    def try_ingest_flows(self, *flows: Flow):
+        """
+        Combines the requests creation step and ingestion into a single call.
+        See `try_create_ingestion_request` for information about how client-side validations are handled.
+        """
+        return super().try_ingest_flows(*flows)
+
+    def buffered_ingestion(
+        self,
+        buffer_size: Optional[int] = None,
+        flush_interval_sec: Optional[float] = None,
+        on_error: Optional[OnErrorCallback] = None,
+    ) -> BufferedIngestionService:
+        """
+        This method automates buffering requests and streams them in batches. It is recommended to be used
+        in a with-block. Failure to put this in a with-block may result in some data not being ingested unless
+        the caller explicitly calls `sift_py.ingestion.buffer.BufferedIngestionService.flush` before the returned
+        instance of `sift_py.ingestion.buffer.BufferedIngestionService` goes out of scope. Once the with-block
+        is exited then a final call to the aforementioned `flush` method  will be made to ingest the remaining data.
+
+        Buffered ingestion works by automatically flushing and ingesting data into Sift whenever the buffer is filled.
+        The size of the buffer is configured via the `buffer_size` argument and defaults to `sift_py.ingestion.buffer.DEFAULT_BUFFER_SIZE`.
+
+        It is also possible to configure buffered ingestion to periodically flush the buffer regardless of whether or not the buffer
+        is filled. The interval between flushes is set via the `flush_interval_sec` argument which is the number of seconds between each flush.
+        If a flush were to occur due to the buffer being filled, then the timer will restart. If `flush_interval_sec` is `None`, then flushes will only
+        occur once the buffer is filled and at the end of the scope of the with-block.
+
+        If an error were to occur that would cause the context manager to call `__exit__`, one last attempt to flush the buffer will be made
+        before the error is re-raised for the caller to handle. If the caller would instead like to customize `__exit__` behavior in the case
+        of an error, they can make use of the `on_error` argument whose type signature is a function where the first argument is the error,
+        the second is the buffer containing the uningested request, and the third argument being a function where, when called, will attempt
+        to flush the buffer.
+
+        Example usage:
+
+        ```python
+        # With client-side validations
+        with ingestion_service.buffered_ingestion() as buffered_ingestion:
+            for _ in range(10_000):
+                buffered_ingestion.try_ingest_flows({
+                    "flow_name": "readings",
+                    "timestamp": datetime.now(timezone.utc),
+                    "channel_values": [
+                        {
+                            "channel_name": "my-channel",
+                    ],
+                })
+
+        # Without client-side validations and a custom buffer size
+        with ingestion_service.buffered_ingestion(2_000) as buffered_ingestion:
+            for _ in range(6_000):
+                buffered_ingestion.ingest_flows({
+                    "flow_name": "readings",
+                    "timestamp": datetime.now(timezone.utc),
+                    "channel_values": [double_value(3)]
+                })
+
+        # With default buffer size and periodic flushes of 3.2 seconds
+        with ingestion_service.buffered_ingestion(flush_interval_sec=3.2) as buffered_ingestion:
+            for _ in range(6_000):
+                buffered_ingestion.ingest_flows({
+                    "flow_name": "readings",
+                    "timestamp": datetime.now(timezone.utc),
+                    "channel_values": [double_value(3)]
+                })
+
+        # Custom code to run when error
+        def on_error_calback(err, buffer, flush):
+            # Save contents of buffer to disk
+            ...
+            # Try once more to flush the buffer
+            flush()
+
+        with ingestion_service.buffered_ingestion(on_error=on_error_calback) as buffered_ingestion:
+            ...
+        ```
+        """
+        return BufferedIngestionService(self, buffer_size, flush_interval_sec, on_error)
+
+    def create_flow(self, flow_config: FlowConfig):
+        """
+        Like `try_create_new_flow` but will automatically overwrite any existing flow config with `flow_config` if they
+        share the same name. If you'd an exception to be raise in the case of a name collision then see `try_create_new_flow`.
+        """
+        super().create_flow(flow_config)
+
+    def try_create_flow(self, flow_config: FlowConfig):
+        """
+        Tries to create a new flow at runtime. Will raise an `IngestionValidationError` if there already exists
+        a flow with the name of the `flow_config` argument. If you'd like to overwrite any flow configs with that
+        have the same name as the provided `flow_config`, then see `create_new_flow`.
+        """
+        super().try_create_flow(flow_config)