lsst-daf-butler 29.2025.4700__tar.gz → 29.2025.4900__tar.gz

{lsst_daf_butler-29.2025.4700/python/lsst_daf_butler.egg-info → lsst_daf_butler-29.2025.4900}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lsst-daf-butler
-Version: 29.2025.4700
+Version: 29.2025.4900
 Summary: An abstraction layer for reading and writing astronomical data to datastores.
 Author-email: Rubin Observatory Data Management <dm-admin@lists.lsst.org>
 License-Expression: BSD-3-Clause OR GPL-3.0-or-later

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/_butler.py

@@ -506,9 +506,10 @@ class Butler(LimitedButler):  # numpydoc ignore=PR02
         # Create Registry and populate tables
         registryConfig = RegistryConfig(config.get("registry"))
         dimensionConfig = DimensionConfig(dimensionConfig)
-        _RegistryFactory(registryConfig).create_from_config(
+        registry = _RegistryFactory(registryConfig).create_from_config(
             dimensionConfig=dimensionConfig, butlerRoot=root_uri
         )
+        registry.close()
 
         _LOG.verbose("Wrote new Butler configuration file to %s", configURI)
 
@@ -2222,3 +2223,7 @@ class Butler(LimitedButler):  # numpydoc ignore=PR02
             Metrics object to record butler statistics.
         """
         raise NotImplementedError()
+
+    @abstractmethod
+    def close(self) -> None:
+        raise NotImplementedError()

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/_labeled_butler_factory.py

@@ -25,9 +25,11 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+from __future__ import annotations
+
 __all__ = ("LabeledButlerFactory", "LabeledButlerFactoryProtocol")
 
-from collections.abc import Callable, Mapping
+from collections.abc import Mapping
 from typing import Protocol
 
 from lsst.resources import ResourcePathExpression
@@ -38,10 +40,6 @@ from ._butler_repo_index import ButlerRepoIndex
 from ._utilities.named_locks import NamedLocks
 from ._utilities.thread_safe_cache import ThreadSafeCache
 
-_FactoryFunction = Callable[[str | None], Butler]
-"""Function that takes an access token string or `None`, and returns a Butler
-instance."""
-
 
 class LabeledButlerFactoryProtocol(Protocol):
     """Callable to retrieve a butler from a label."""
@@ -84,7 +82,7 @@ class LabeledButlerFactory:
         else:
             self._repositories = dict(repositories)
 
-        self._factories = ThreadSafeCache[str, _FactoryFunction]()
+        self._factories = ThreadSafeCache[str, _ButlerFactory]()
         self._initialization_locks = NamedLocks()
 
         # This may be overridden by unit tests.
@@ -138,10 +136,18 @@ class LabeledButlerFactory:
         based on the end user instead of the service. See
         https://gafaelfawr.lsst.io/user-guide/gafaelfawringress.html#requesting-delegated-tokens
         """
-        factory = self._get_or_create_butler_factory_function(label)
-        return factory(access_token)
+        factory = self._get_or_create_butler_factory(label)
+        return factory.create_butler(access_token)
+
+    def close(self) -> None:
+        """Reset the factory cache, and release any resources associated with
+        the cached instances.
+        """
+        factories = self._factories.clear()
+        for factory in factories.values():
+            factory.close()
 
-    def _get_or_create_butler_factory_function(self, label: str) -> _FactoryFunction:
+    def _get_or_create_butler_factory(self, label: str) -> _ButlerFactory:
         # We maintain a separate lock per label.  We only want to instantiate
         # one factory function per label, because creating the factory sets up
         # shared state that should only exist once per repository.  However, we
@@ -154,16 +160,16 @@ class LabeledButlerFactory:
             factory = self._create_butler_factory_function(label)
             return self._factories.set_or_get(label, factory)
 
-    def _create_butler_factory_function(self, label: str) -> _FactoryFunction:
+    def _create_butler_factory_function(self, label: str) -> _ButlerFactory:
         config_uri = self._get_config_uri(label)
         config = ButlerConfig(config_uri)
         butler_type = config.get_butler_type()
 
         match butler_type:
             case ButlerType.DIRECT:
-                return _create_direct_butler_factory(config, self._preload_unsafe_direct_butler_caches)
+                return _DirectButlerFactory(config, self._preload_unsafe_direct_butler_caches)
             case ButlerType.REMOTE:
-                return _create_remote_butler_factory(config)
+                return _RemoteButlerFactory(config)
             case _:
                 raise TypeError(f"Unknown butler type '{butler_type}' for label '{label}'")
 
@@ -177,34 +183,45 @@ class LabeledButlerFactory:
             return config_uri
 
 
-def _create_direct_butler_factory(config: ButlerConfig, preload_unsafe_caches: bool) -> _FactoryFunction:
-    import lsst.daf.butler.direct_butler
+class _ButlerFactory(Protocol):
+    def create_butler(self, access_token: str | None) -> Butler: ...
+    def close(self) -> None: ...
+
+
+class _DirectButlerFactory(_ButlerFactory):
+    def __init__(self, config: ButlerConfig, preload_unsafe_caches: bool) -> None:
+        import lsst.daf.butler.direct_butler
 
-    # Create a 'template' Butler that will be cloned when callers request an
-    # instance.
-    butler = Butler.from_config(config)
-    assert isinstance(butler, lsst.daf.butler.direct_butler.DirectButler)
+        # Create a 'template' Butler that will be cloned when callers request
+        # an instance.
+        self._butler = Butler.from_config(config)
+        assert isinstance(self._butler, lsst.daf.butler.direct_butler.DirectButler)
 
-    # Load caches so that data is available in cloned instances without
-    # needing to refetch it from the database for every instance.
-    butler._preload_cache(load_dimension_record_cache=preload_unsafe_caches)
+        # Load caches so that data is available in cloned instances without
+        # needing to refetch it from the database for every instance.
+        self._butler._preload_cache(load_dimension_record_cache=preload_unsafe_caches)
 
-    def create_butler(access_token: str | None) -> Butler:
+    def create_butler(self, access_token: str | None) -> Butler:
         # Access token is ignored because DirectButler does not use Gafaelfawr
         # authentication.
-        return butler.clone()
+        return self._butler.clone()
 
-    return create_butler
+    def close(self) -> None:
+        self._butler.close()
 
 
-def _create_remote_butler_factory(config: ButlerConfig) -> _FactoryFunction:
-    import lsst.daf.butler.remote_butler._factory
+class _RemoteButlerFactory(_ButlerFactory):
+    def __init__(self, config: ButlerConfig) -> None:
+        import lsst.daf.butler.remote_butler._factory
 
-    factory = lsst.daf.butler.remote_butler._factory.RemoteButlerFactory.create_factory_from_config(config)
+        self._factory = lsst.daf.butler.remote_butler._factory.RemoteButlerFactory.create_factory_from_config(
+            config
+        )
 
-    def create_butler(access_token: str | None) -> Butler:
+    def create_butler(self, access_token: str | None) -> Butler:
         if access_token is None:
             raise ValueError("Access token is required to connect to a Butler server")
-        return factory.create_butler_for_access_token(access_token)
+        return self._factory.create_butler_for_access_token(access_token)
 
-    return create_butler
+    def close(self) -> None:
+        pass

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/_limited_butler.py

@@ -30,10 +30,10 @@ from __future__ import annotations
 __all__ = ("LimitedButler",)
 
 import logging
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from collections.abc import Iterable, Iterator
-from contextlib import contextmanager
-from typing import Any, ClassVar
+from contextlib import AbstractContextManager, contextmanager
+from typing import Any, ClassVar, Literal, Self
 
 from lsst.resources import ResourcePath
 
@@ -48,7 +48,7 @@ from .dimensions import DimensionUniverse
 log = logging.getLogger(__name__)
 
 
-class LimitedButler(ABC):
+class LimitedButler(AbstractContextManager):
     """A minimal butler interface that is sufficient to back
     `~lsst.pipe.base.PipelineTask` execution.
     """
@@ -100,6 +100,31 @@ class LimitedButler(ABC):
         """
         raise NotImplementedError()
 
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Literal[False]:
+        try:
+            self.close()
+        except Exception:
+            log.exception("An exception occurred during Butler.close()")
+        return False
+
+    def close(self) -> None:
+        """Release all resources associated with this Butler instance.  The
+        instance may no longer be used after this is called.
+
+        Notes
+        -----
+        Instead of calling ``close()`` directly, you can use the Butler object
+        as a context manager.  For example::
+
+          with Butler(...) as butler:
+              butler.get(...)
+          # butler is closed after exiting the block.
+        """
+        pass
+
     def get(
         self,
         ref: DatasetRef,

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/_quantum_backed.py

@@ -55,7 +55,7 @@ from .datastore import Datastore
 from .datastore.record_data import DatastoreRecordData, SerializedDatastoreRecordData
 from .datastores.file_datastore.retrieve_artifacts import retrieve_and_zip
 from .dimensions import DimensionUniverse
-from .registry.interfaces import DatastoreRegistryBridgeManager, OpaqueTableStorageManager
+from .registry.interfaces import Database, DatastoreRegistryBridgeManager, OpaqueTableStorageManager
 
 if TYPE_CHECKING:
     from ._butler import Butler
@@ -83,6 +83,9 @@ class QuantumBackedButler(LimitedButler):
         The registry dataset type definitions, indexed by name.
     metrics : `lsst.daf.butler.ButlerMetrics` or `None`, optional
         Metrics object for tracking butler statistics.
+    database : `Database`, optional
+        Database instance used by datastore.  Not required -- only provided
+        to allow database connections to be closed during cleanup.
 
     Notes
     -----
@@ -130,6 +133,7 @@ class QuantumBackedButler(LimitedButler):
         storageClasses: StorageClassFactory,
         dataset_types: Mapping[str, DatasetType] | None = None,
         metrics: ButlerMetrics | None = None,
+        database: Database | None = None,
     ):
         self._dimensions = dimensions
         self._predicted_inputs = set(predicted_inputs)
@@ -142,6 +146,7 @@ class QuantumBackedButler(LimitedButler):
         self.storageClasses = storageClasses
         self._dataset_types: Mapping[str, DatasetType] = {}
         self._metrics = metrics if metrics is not None else ButlerMetrics()
+        self._database = database
         if dataset_types is not None:
             self._dataset_types = dataset_types
         self._datastore.set_retrieve_dataset_type_method(self._retrieve_dataset_type)
@@ -321,7 +326,7 @@ class QuantumBackedButler(LimitedButler):
             Metrics object for gathering butler statistics.
         """
         butler_config = ButlerConfig(config, searchPaths=search_paths)
-        datastore, _ = instantiate_standalone_datastore(
+        datastore, database = instantiate_standalone_datastore(
             butler_config, dimensions, filename, OpaqueManagerClass, BridgeManagerClass
         )
 
@@ -342,8 +347,13 @@ class QuantumBackedButler(LimitedButler):
             storageClasses=storageClasses,
             dataset_types=dataset_types,
             metrics=metrics,
+            database=database,
         )
 
+    def close(self) -> None:
+        if self._database is not None:
+            self._database.dispose()
+
     def _retrieve_dataset_type(self, name: str) -> DatasetType | None:
         """Return DatasetType defined in registry given dataset type name."""
         return self._dataset_types.get(name)

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/_utilities/thread_safe_cache.py

@@ -76,3 +76,16 @@ class ThreadSafeCache(Generic[TKey, TValue]):
         """
         with self._mutex:
             return self._cache.setdefault(key, value)
+
+    def clear(self) -> dict[TKey, TValue]:
+        """Clear the cache.
+
+        Returns
+        -------
+        old_cache : `dict`
+            The values that were contained in the cache prior to clearing it.
+        """
+        with self._mutex:
+            old = self._cache
+            self._cache = {}
+            return old

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/cli/cmd/commands.py

@@ -33,6 +33,7 @@ from typing import Any
 import click
 
 from ... import script
+from ..._butler import Butler
 from ..opt import (
     collection_argument,
     collection_type_option,
@@ -487,9 +488,11 @@ def remove_dataset_type(*args: Any, **kwargs: Any) -> None:
 @options_file_option()
 def query_datasets(**kwargs: Any) -> None:
     """List the datasets in a repository."""
-    for table in script.QueryDatasets(**kwargs).getTables():
-        print("")
-        table.pprint_all()
+    repo = kwargs.pop("repo")
+    with Butler.from_config(repo, writeable=False) as butler:
+        for table in script.QueryDatasets(butler=butler, **kwargs).getTables():
+            print("")
+            table.pprint_all()
     print("")
 
 

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/configs/datastores/formatters.yaml

@@ -93,8 +93,9 @@ MultipleCellCoadd: lsst.cell_coadds.CellCoaddFitsFormatter
 NNModelPackagePayload: lsst.meas.transiNet.modelPackages.NNModelPackageFormatter
 Timespan: lsst.daf.butler.formatters.json.JsonFormatter
 RegionTimeInfo: lsst.daf.butler.formatters.json.JsonFormatter
-QPEnsemble: lsst.meas.pz.qp_formatter.QPFormatter
-PZModel: lsst.meas.pz.model_formatter.ModelFormatter
+QPEnsemble: lsst.meas.photoz.base.qp_formatter.QPFormatter
+PZModel: lsst.meas.photoz.base.model_formatter.ModelFormatter
+PhotozModel: lsst.meas.photoz.base.model_formatter.ModelFormatter
 VisitBackgroundModel: lsst.daf.butler.formatters.json.JsonFormatter
 VignettingCorrection: lsst.ts.observatory.control.utils.extras.vignetting_storage.VignettingCorrectionFormatter
 SSPAuxiliaryFile: lsst.pipe.tasks.sspAuxiliaryFile.SSPAuxiliaryFileFormatter

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/configs/datastores/writeRecipes.yaml

@@ -12,19 +12,19 @@ lsst.obs.base.formatters.fitsExposure.StandardFitsImageFormatterBase: &StandardF
     variance:
       <<: *losslessOptions
 
-  # Basic lossy (quantizing) compression
-  lossyBasic: &lossyBasic
-    image: &lossyBasicOptions
+  # Lossy (quantizing) compression with noise sigma subdivided into 16.
+  lossy16:
+    image: &lossy16Options
       algorithm: RICE_1
       quantization:
         dither: SUBTRACTIVE_DITHER_2
         scaling: STDEV_MASKED
-        mask_planes: ["NO_DATA"]
-        level: 10.0
+        mask_planes: ["NO_DATA", "INTRP"]
+        level: 16.0
     mask:
       <<: *losslessOptions
     variance:
-      <<: *lossyBasicOptions
+      <<: *lossy16Options
 
   # Set the default
   default:

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/configs/storageClasses.yaml

@@ -433,6 +433,8 @@ storageClasses:
     pytype: qp.Ensemble
   PZModel:
     pytype: rail.core.model.Model
+  PhotozModel:
+    pytype: rail.core.model.Model
   VisitBackgroundModel:
     pytype: lsst.drp.tasks.fit_visit_background.VisitBackgroundModel
   VignettingCorrection:

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/direct_butler/_direct_butler.py

@@ -45,6 +45,7 @@ import uuid
 import warnings
 from collections import Counter, defaultdict
 from collections.abc import Collection, Iterable, Iterator, MutableMapping, Sequence
+from functools import partial
 from types import EllipsisType
 from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple, TextIO, cast
 
@@ -160,9 +161,9 @@ class DirectButler(Butler):  # numpydoc ignore=PR02
         # dependency-inversion trick. This is not used by regular butler,
         # but we do not have a way to distinguish regular butler from execution
         # butler.
-        self._datastore.set_retrieve_dataset_type_method(self._retrieve_dataset_type)
+        self._datastore.set_retrieve_dataset_type_method(partial(_retrieve_dataset_type, registry))
 
-        self._registry_shim = RegistryShim(self)
+        self._closed = False
 
         return self
 
@@ -250,6 +251,18 @@ class DirectButler(Butler):  # numpydoc ignore=PR02
             metrics=metrics,
         )
 
+    def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            self._registry.close()
+            # Cause exceptions to be raised if a user attempts to use the
+            # instance after closing it.  Without this, Butler would still
+            # work after being closed because of implementation details
+            # of SqlAlchemy, but this may not continue to be the case in the
+            # future and we don't want users to get in the habit of doing this.
+            self._registry = _BUTLER_CLOSED_INSTANCE
+            self._datastore = _BUTLER_CLOSED_INSTANCE
+
     GENERATION: ClassVar[int] = 3
     """This is a Generation 3 Butler.
 
@@ -258,13 +271,6 @@ class DirectButler(Butler):  # numpydoc ignore=PR02
     code.
     """
 
-    def _retrieve_dataset_type(self, name: str) -> DatasetType | None:
-        """Return DatasetType defined in registry given dataset type name."""
-        try:
-            return self.get_dataset_type(name)
-        except MissingDatasetTypeError:
-            return None
-
     @classmethod
     def _unpickle(
         cls,
@@ -2530,7 +2536,7 @@ class DirectButler(Butler):  # numpydoc ignore=PR02
         are accessible only via `Registry` methods. Eventually these methods
         will be replaced by equivalent `Butler` methods.
         """
-        return self._registry_shim
+        return RegistryShim(self)
 
     @property
     def dimensions(self) -> DimensionUniverse:
@@ -2574,22 +2580,14 @@ class DirectButler(Butler):  # numpydoc ignore=PR02
     accessible only via `SqlRegistry` methods.
     """
 
-    datastore: Datastore
-    """The object that manages actual dataset storage (`Datastore`).
-
-    Direct user access to the datastore should rarely be necessary; the primary
-    exception is the case where a `Datastore` implementation provides extra
-    functionality beyond what the base class defines.
-    """
-
     storageClasses: StorageClassFactory
     """An object that maps known storage class names to objects that fully
     describe them (`StorageClassFactory`).
     """
 
-    _registry_shim: RegistryShim
-    """Shim object to provide a legacy public interface for querying via the
-    the ``registry`` property.
+    _closed: bool
+    """`True` if close() has already been called on this instance; `False`
+    otherwise.
     """
 
 
@@ -2614,3 +2612,19 @@ def _to_uuid(id: DatasetId | str) -> uuid.UUID:
         return id
     else:
         return uuid.UUID(id)
+
+
+class _ButlerClosed:
+    def __getattr__(self, name: str) -> Any:
+        raise RuntimeError("Attempted to use a Butler instance which has been closed.")
+
+
+_BUTLER_CLOSED_INSTANCE: Any = _ButlerClosed()
+
+
+def _retrieve_dataset_type(registry: SqlRegistry, name: str) -> DatasetType | None:
+    """Return DatasetType defined in registry given dataset type name."""
+    try:
+        return registry.getDatasetType(name)
+    except MissingDatasetTypeError:
+        return None

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/formatters/parquet.py

@@ -49,13 +49,14 @@ __all__ = (
 )
 
 import collections.abc
+import contextlib
 import itertools
 import json
 import logging
 import re
-from collections.abc import Iterable, Sequence
+from collections.abc import Generator, Iterable, Sequence
 from fnmatch import fnmatchcase
-from typing import TYPE_CHECKING, Any, cast
+from typing import IO, TYPE_CHECKING, Any, cast
 
 import pyarrow as pa
 import pyarrow.parquet as pq
@@ -84,6 +85,16 @@ TARGET_ROW_GROUP_BYTES = 1_000_000_000
 ASTROPY_PANDAS_INDEX_KEY = "lsst::arrow::astropy_pandas_index"
 
 
+@contextlib.contextmanager
+def generic_open(path: str, fs: AbstractFileSystem | None) -> Generator[IO]:
+    if fs is None:
+        with open(path, "rb") as fh:
+            yield fh
+    else:
+        with fs.open(path) as fh:
+            yield fh
+
+
 class ParquetFormatter(FormatterV2):
     """Interface for reading and writing Arrow Table objects to and from
     Parquet files.
@@ -120,7 +131,8 @@ class ParquetFormatter(FormatterV2):
         component: str | None = None,
         expected_size: int = -1,
     ) -> Any:
-        schema = pq.read_schema(path, filesystem=fs)
+        with generic_open(path, fs) as handle:
+            schema = pq.read_schema(handle)
 
         schema_names = ["ArrowSchema", "DataFrameSchema", "ArrowAstropySchema", "ArrowNumpySchema"]
 
@@ -133,13 +145,13 @@ class ParquetFormatter(FormatterV2):
             if b"lsst::arrow::rowcount" in schema.metadata:
                 return int(schema.metadata[b"lsst::arrow::rowcount"])
 
-            temp_table = pq.read_table(
-                path,
-                filesystem=fs,
-                columns=[schema.names[0]],
-                use_threads=False,
-                use_pandas_metadata=False,
-            )
+            with generic_open(path, fs) as handle:
+                temp_table = pq.read_table(
+                    handle,
+                    columns=[schema.names[0]],
+                    use_threads=False,
+                    use_pandas_metadata=False,
+                )
 
             return len(temp_table[schema.names[0]])
 
@@ -148,7 +160,7 @@ class ParquetFormatter(FormatterV2):
             par_columns = self.file_descriptor.parameters.pop("columns", None)
             if par_columns:
                 has_pandas_multi_index = False
-                if b"pandas" in schema.metadata:
+                if schema.metadata and b"pandas" in schema.metadata:
                     md = json.loads(schema.metadata[b"pandas"])
                     if len(md["column_indexes"]) > 1:
                         has_pandas_multi_index = True
@@ -184,13 +196,13 @@ class ParquetFormatter(FormatterV2):
                 )
 
         metadata = schema.metadata if schema.metadata is not None else {}
-        arrow_table = pq.read_table(
-            path,
-            filesystem=fs,
-            columns=par_columns,
-            use_threads=False,
-            use_pandas_metadata=(b"pandas" in metadata),
-        )
+        with generic_open(path, fs) as handle:
+            arrow_table = pq.read_table(
+                handle,
+                columns=par_columns,
+                use_threads=False,
+                use_pandas_metadata=(b"pandas" in metadata),
+            )
 
         return arrow_table
 

{lsst_daf_butler-29.2025.4700 → lsst_daf_butler-29.2025.4900}/python/lsst/daf/butler/logging.py

@@ -537,6 +537,9 @@ class ButlerLogRecords(MutableSequence[ButlerLogRecord]):
         if cls._generic_startswith(startdata, "["):
             # This is a JSON array of records.
             return _ButlerLogRecordsModelV1
+        elif cls._generic_startswith(startdata, cls.STREAMING_EXTRA_DELIMITER):
+            # This is an empty log file with a log record per line format.
+            return None
         elif not cls._generic_startswith(startdata, "{"):
             # Limit the length of string reported in error message in case
             # this is an enormous file.
@@ -570,9 +573,12 @@ class ButlerLogRecords(MutableSequence[ButlerLogRecord]):
         """
         first_line = stream.readline()
 
+        empty_stream = False
         if not first_line:
             # Empty file, return zero records.
             return cls.from_records([])
+        elif cls._generic_startswith(first_line, cls.STREAMING_EXTRA_DELIMITER):
+            empty_stream = True
 
         model_type = cls._detect_model(first_line)
 
@@ -583,13 +589,17 @@ class ButlerLogRecords(MutableSequence[ButlerLogRecord]):
             return model_type.model_validate_json(all).wrap(cls)
 
         # A stream of records with one record per line.
-        records = [ButlerLogRecord.model_validate_json(first_line)]
-        for line in stream:
-            line = line.rstrip()
-            if cls._generic_startswith(line, "###EXTRA###"):
-                break
-            elif line:  # skip blank lines
-                records.append(ButlerLogRecord.model_validate_json(line))
+        if not empty_stream:
+            records = [ButlerLogRecord.model_validate_json(first_line)]
+            for line in stream:
+                line = line.rstrip()
+                if cls._generic_startswith(line, cls.STREAMING_EXTRA_DELIMITER):
+                    break
+                elif line:  # skip blank lines
+                    records.append(ButlerLogRecord.model_validate_json(line))
+        else:
+            # No records but might have extra metadata.
+            records = []
         extra_data = stream.read()
         if extra_data:
             extra = pydantic_core.from_json(extra_data)