RepoExportContext

class lsst.daf.butler.RepoExportContext(registry: SqlRegistry, datastore: Datastore, backend: RepoExportBackend, *, directory: ResourcePathExpression | None = None, transfer: str | None = None)

Bases: object

Public interface for exporting a subset of a data repository.

Instances of this class are obtained by calling Butler.export as the value returned by that context manager:

with butler.export(filename="export.yaml") as export:
    export.saveDataIds(...)
    export.saveDatasets(...)
Parameters:
registrySqlRegistry

Registry to export from.

datastoreDatastore

Datastore to export from.

backendRepoExportBackend

Implementation class for a particular export file format.

directoryResourcePathExpression, optional

Directory to pass to Datastore.export. Can be None to use the current working directory.

transferstr, optional

Transfer mode to pass to Datastore.export.

Methods Summary

saveCollection(name)

Export the given collection.

saveDataIds(dataIds, *[, elements])

Export the dimension records associated with one or more data IDs.

saveDatasets(refs, *[, elements, rewrite])

Export one or more datasets.

saveDimensionData(element, records)

Export the given dimension records associated with one or more data IDs.

Methods Documentation

saveCollection(name: str) None

Export the given collection.

Parameters:
namestr

Name of the collection.

Notes

RUN collections are also exported automatically when any dataset referencing them is exported. They may also be explicitly exported this method to export the collection with no datasets. Duplicate exports of collections are ignored.

Exporting a TAGGED or CALIBRATION collection will cause its associations with exported datasets to also be exported, but it does not export those datasets automatically.

Exporting a CHAINED collection does not automatically export its child collections; these must be explicitly exported or already be present in the repository they are being imported into.

saveDataIds(dataIds: Iterable[DataCoordinate], *, elements: Iterable[str | DimensionElement] | None = None) None

Export the dimension records associated with one or more data IDs.

Parameters:
dataIdsiterable of DataCoordinate

Data IDs to export. For large numbers of data IDs obtained by calls to Registry.queryDataIds, it will be much more efficient if these are expanded to include records (i.e. DataCoordinate.hasRecords returns True) prior to the call to saveDataIds via e.g. Registry.queryDataIds(...).expanded().

elementsiterable of DimensionElement or str, optional

Dimension elements whose records should be exported. If None, records for all dimensions will be exported.

saveDatasets(refs: Iterable[DatasetRef], *, elements: Iterable[str | DimensionElement] | None = None, rewrite: Callable[[FileDataset], FileDataset] | None = None) None

Export one or more datasets.

This automatically exports any DatasetType, RUN collections, and dimension records associated with the datasets.

Parameters:
refsiterable of DatasetRef

References to the datasets to export. Their DatasetRef.id attributes must not be None. Duplicates are automatically ignored. Nested data IDs must have DataCoordinate.hasRecords return True. If any reference is to a component dataset, the parent will be exported instead.

elementsiterable of DimensionElement or str, optional

Dimension elements whose records should be exported; this is forwarded to saveDataIds when exporting the data IDs of the given datasets.

rewritecallable, optional

A callable that takes a single FileDataset argument and returns a modified FileDataset. This is typically used to rewrite the path generated by the datastore. If None, the FileDataset returned by Datastore.export will be used directly.

Notes

At present, this only associates datasets with RUN collections. Other collections will be included in the export in the future (once Registry provides a way to look up that information).

saveDimensionData(element: str | DimensionElement, records: Iterable[dict | DimensionRecord]) None

Export the given dimension records associated with one or more data IDs.

Parameters:
elementstr or DimensionElement

DimensionElement or str indicating the logical table these records are from.

recordsIterable [ DimensionRecord or dict ]

Records to export, as an iterable containing DimensionRecord or dict instances.