Coverage for python/lsst/daf/butler/_butler_collections.py: 100%
13 statements
« prev ^ index » next coverage.py v7.5.1, created at 2024-05-11 03:15 -0700
« prev ^ index » next coverage.py v7.5.1, created at 2024-05-11 03:15 -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__ = ("ButlerCollections",)
32from abc import ABC, abstractmethod
33from collections.abc import Iterable
36class ButlerCollections(ABC):
37 """Methods for working with collections stored in the Butler."""
39 @abstractmethod
40 def extend_chain(self, parent_collection_name: str, child_collection_names: str | Iterable[str]) -> None:
41 """Add children to the end of a CHAINED collection.
43 If any of the children already existed in the chain, they will be moved
44 to the new position at the end of the chain.
46 Parameters
47 ----------
48 parent_collection_name : `str`
49 The name of a CHAINED collection to which we will add new children.
50 child_collection_names : `~collections.abc.Iterable` [ `str ` ] | `str`
51 A child collection name or list of child collection names to be
52 added to the parent.
54 Raises
55 ------
56 MissingCollectionError
57 If any of the specified collections do not exist.
58 CollectionTypeError
59 If the parent collection is not a CHAINED collection.
60 CollectionCycleError
61 If this operation would create a collection cycle.
63 Notes
64 -----
65 If this function is called within a call to ``Butler.transaction``, it
66 will hold a lock that prevents other processes from modifying the
67 parent collection until the end of the transaction. Keep these
68 transactions short.
69 """
70 raise NotImplementedError()
72 @abstractmethod
73 def prepend_chain(self, parent_collection_name: str, child_collection_names: str | Iterable[str]) -> None:
74 """Add children to the beginning of a CHAINED collection.
76 If any of the children already existed in the chain, they will be moved
77 to the new position at the beginning of the chain.
79 Parameters
80 ----------
81 parent_collection_name : `str`
82 The name of a CHAINED collection to which we will add new children.
83 child_collection_names : `~collections.abc.Iterable` [ `str ` ] | `str`
84 A child collection name or list of child collection names to be
85 added to the parent.
87 Raises
88 ------
89 MissingCollectionError
90 If any of the specified collections do not exist.
91 CollectionTypeError
92 If the parent collection is not a CHAINED collection.
93 CollectionCycleError
94 If this operation would create a collection cycle.
96 Notes
97 -----
98 If this function is called within a call to ``Butler.transaction``, it
99 will hold a lock that prevents other processes from modifying the
100 parent collection until the end of the transaction. Keep these
101 transactions short.
102 """
103 raise NotImplementedError()
105 @abstractmethod
106 def redefine_chain(
107 self, parent_collection_name: str, child_collection_names: str | Iterable[str]
108 ) -> None:
109 """Replace the contents of a CHAINED collection with new children.
111 Parameters
112 ----------
113 parent_collection_name : `str`
114 The name of a CHAINED collection to which we will assign new
115 children.
116 child_collection_names : `~collections.abc.Iterable` [ `str ` ] | `str`
117 A child collection name or list of child collection names to be
118 added to the parent.
120 Raises
121 ------
122 MissingCollectionError
123 If any of the specified collections do not exist.
124 CollectionTypeError
125 If the parent collection is not a CHAINED collection.
126 CollectionCycleError
127 If this operation would create a collection cycle.
129 Notes
130 -----
131 If this function is called within a call to ``Butler.transaction``, it
132 will hold a lock that prevents other processes from modifying the
133 parent collection until the end of the transaction. Keep these
134 transactions short.
135 """
136 raise NotImplementedError()
138 @abstractmethod
139 def remove_from_chain(
140 self, parent_collection_name: str, child_collection_names: str | Iterable[str]
141 ) -> None:
142 """Remove children from a CHAINED collection.
144 Parameters
145 ----------
146 parent_collection_name : `str`
147 The name of a CHAINED collection from which we will remove
148 children.
149 child_collection_names : `~collections.abc.Iterable` [ `str ` ] | `str`
150 A child collection name or list of child collection names to be
151 removed from the parent.
153 Raises
154 ------
155 MissingCollectionError
156 If any of the specified collections do not exist.
157 CollectionTypeError
158 If the parent collection is not a CHAINED collection.
160 Notes
161 -----
162 If this function is called within a call to ``Butler.transaction``, it
163 will hold a lock that prevents other processes from modifying the
164 parent collection until the end of the transaction. Keep these
165 transactions short.
166 """
167 raise NotImplementedError()