Coverage for python/lsst/daf/butler/remote_butler/_ref_utils.py: 0%
53 statements
« prev ^ index » next coverage.py v7.15.2, created at 2026-08-13 02:56 -0700
1# This file is part of daf_butler.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (http://www.lsst.org).
6# See the COPYRIGHT file at the top-level directory of this distribution
7# for details of code ownership.
8#
9# This software is dual licensed under the GNU General Public License and also
10# under a 3-clause BSD license. Recipients may choose which of these licenses
11# to use; please see the files gpl-3.0.txt and/or bsd_license.txt,
12# respectively. If you choose the GPL option then the following text applies
13# (but note that there is still no warranty even if you opt for BSD instead):
14#
15# This program is free software: you can redistribute it and/or modify
16# it under the terms of the GNU General Public License as published by
17# the Free Software Foundation, either version 3 of the License, or
18# (at your option) any later version.
19#
20# This program is distributed in the hope that it will be useful,
21# but WITHOUT ANY WARRANTY; without even the implied warranty of
22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23# GNU General Public License for more details.
24#
25# You should have received a copy of the GNU General Public License
26# along with this program. If not, see <http://www.gnu.org/licenses/>.
28from __future__ import annotations
30__all__ = (
31 "apply_storage_class_override",
32 "get_component_override",
33 "make_read_ref",
34 "normalize_dataset_type_name",
35 "simplify_dataId",
36 "split_dataset_type_name",
37)
39from pydantic import TypeAdapter
41from .._dataset_ref import DatasetRef
42from .._dataset_type import DatasetType, get_dataset_type_name
43from .._storage_class import StorageClass
44from ..dimensions import DataCoordinate, DataId, DataIdValue, SerializedDataId
45from .server_models import DatasetTypeName
47_SERIALIZED_DATA_ID_TYPE_ADAPTER = TypeAdapter(SerializedDataId)
50def apply_storage_class_override(
51 ref: DatasetRef,
52 original_dataset_ref_or_type: DatasetRef | DatasetType | str,
53 explicit_storage_class: StorageClass | str | None,
54) -> DatasetRef:
55 """Return a DatasetRef with its storage class overridden to match the
56 StorageClass supplied by the user as input to one of the search functions.
58 Parameters
59 ----------
60 ref : `DatasetRef`
61 The ref to which we will apply the StorageClass override.
62 original_dataset_ref_or_type : `DatasetRef` | `DatasetType` | `str`
63 The ref or type that was input to the search, which may contain a
64 storage class override.
65 explicit_storage_class : `StorageClass` | `str` | `None`
66 A storage class that the user explicitly requested as an override.
67 """
68 if explicit_storage_class is not None:
69 return ref.overrideStorageClass(explicit_storage_class)
71 # If the caller provided a DatasetRef or DatasetType, they may have
72 # overridden the storage class on it, and we need to propagate that to the
73 # output.
74 dataset_type = _extract_dataset_type(original_dataset_ref_or_type)
75 if dataset_type is not None:
76 return ref.overrideStorageClass(dataset_type.storageClass)
78 return ref
81def make_read_ref(
82 registry_ref: DatasetRef,
83 original_dataset_ref_or_type: DatasetRef | DatasetType | str,
84 explicit_storage_class: StorageClass | str | None,
85) -> DatasetRef:
86 """Return the ref describing the dataset the caller asked for.
88 Parameters
89 ----------
90 registry_ref : `DatasetRef`
91 The parent (composite) ref returned by the server, carrying the
92 `StorageClass` from the dataset type definition in the repository.
93 Component dataset types are never sent to the server, so any component
94 has to be re-applied here.
95 original_dataset_ref_or_type : `DatasetRef` | `DatasetType` | `str`
96 The ref or type that was input to the search, which may name a
97 component and may override the storage class.
98 explicit_storage_class : `StorageClass` | `str` | `None`
99 A storage class that the user explicitly requested as an override.
101 Returns
102 -------
103 read_ref : `DatasetRef`
104 The ref describing the component and `StorageClass` that the caller
105 wants returned.
107 Notes
108 -----
109 A read `StorageClass` override can define components that the repository
110 definition does not, so the component is derived from the overridden
111 composite rather than from ``registry_ref`` itself.
112 """
113 component = get_component_override(original_dataset_ref_or_type)
114 if component is None:
115 return apply_storage_class_override(
116 registry_ref, original_dataset_ref_or_type, explicit_storage_class
117 )
119 # Apply any composite storage class override before deriving the component
120 # from it.
121 read_ref = registry_ref
122 dataset_type = _extract_dataset_type(original_dataset_ref_or_type)
123 if dataset_type is not None:
124 if dataset_type.parentStorageClass is not None:
125 read_ref = read_ref.overrideStorageClass(dataset_type.parentStorageClass)
126 read_ref = read_ref.makeComponentRef(component).overrideStorageClass(dataset_type.storageClass)
127 else:
128 # Only a dataset type name was given, so there is no override.
129 read_ref = read_ref.makeComponentRef(component)
130 if explicit_storage_class is not None:
131 read_ref = read_ref.overrideStorageClass(explicit_storage_class)
133 return read_ref
136def normalize_dataset_type_name(datasetTypeOrName: DatasetType | str) -> DatasetTypeName:
137 """Convert DatasetType parameters in the format used by Butler methods
138 to a standardized string name for the REST API.
140 Parameters
141 ----------
142 datasetTypeOrName : `DatasetType` | `str`
143 A DatasetType, or the name of a DatasetType. This union is a common
144 parameter in many `Butler` methods.
145 """
146 return DatasetTypeName(get_dataset_type_name(datasetTypeOrName))
149def split_dataset_type_name(
150 datasetTypeOrName: DatasetType | str,
151) -> tuple[DatasetTypeName, str | None]:
152 """Split a dataset type parameter into a parent dataset type name and an
153 optional component name.
155 Component dataset type names must never be sent to the server -- the
156 server cannot construct a component `DatasetType` unless it has the
157 parent's storage class definition available, and storage classes are
158 often defined by science pipelines packages that are only installed on
159 the client. Callers should request the parent dataset type from the
160 server and re-apply the component on the client side.
162 Parameters
163 ----------
164 datasetTypeOrName : `DatasetType` | `str`
165 A DatasetType, or the name of a DatasetType.
167 Returns
168 -------
169 parent_name : `DatasetTypeName`
170 Name of the parent dataset type, suitable for sending to the server.
171 component : `str` | `None`
172 Component name, or `None` if this is not a component dataset type.
173 """
174 parent_name, component = DatasetType.splitDatasetTypeName(get_dataset_type_name(datasetTypeOrName))
175 return DatasetTypeName(parent_name), component
178def get_component_override(datasetRefOrType: DatasetRef | DatasetType | str) -> str | None:
179 """Return the component name from a ref or dataset type provided by the
180 user, or `None` if it does not refer to a component.
182 Parameters
183 ----------
184 datasetRefOrType : `DatasetRef` | `DatasetType` | `str`
185 A DatasetRef, DatasetType, or name of a DatasetType. This union is a
186 common parameter in many `Butler` methods.
187 """
188 if isinstance(datasetRefOrType, DatasetRef):
189 return datasetRefOrType.datasetType.component()
190 _, component = split_dataset_type_name(datasetRefOrType)
191 return component
194def simplify_dataId(dataId: DataId | None, kwargs: dict[str, DataIdValue]) -> SerializedDataId:
195 """Take a generic Data ID and convert it to a serializable form.
197 Parameters
198 ----------
199 dataId : `dict`, `None`, `DataCoordinate`
200 The data ID to serialize.
201 kwargs : `dict`
202 Additional entries to augment or replace the values in ``dataId``.
204 Returns
205 -------
206 data_id : `SerializedDataId`
207 A serializable form.
208 """
209 if dataId is None:
210 dataId = {}
211 elif isinstance(dataId, DataCoordinate):
212 dataId = dataId.to_simple(minimal=True).dataId
213 else:
214 dataId = dict(dataId)
216 return _SERIALIZED_DATA_ID_TYPE_ADAPTER.validate_python(dataId | kwargs)
219def _extract_dataset_type(datasetRefOrType: DatasetRef | DatasetType | str) -> DatasetType | None:
220 """Return the DatasetType associated with the argument, or None if the
221 argument is not an object that contains a DatasetType object.
223 Parameters
224 ----------
225 datasetRefOrType : `DatasetRef` | `DatasetType` | `str`
226 A DatasetRef, DatasetType, or name of a DatasetType. This union is a
227 common parameter in many `Butler` methods.
228 """
229 if isinstance(datasetRefOrType, DatasetType):
230 return datasetRefOrType
231 elif isinstance(datasetRefOrType, DatasetRef):
232 return datasetRefOrType.datasetType
233 else:
234 return None