Coverage for python/lsst/daf/butler/_butler_collections.py: 100%

13 statements  

« prev     ^ index     » next       coverage.py v7.4.4, created at 2024-04-18 09:54 +0000

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/>. 

27 

28from __future__ import annotations 

29 

30__all__ = ("ButlerCollections",) 

31 

32from abc import ABC, abstractmethod 

33from collections.abc import Iterable 

34 

35 

36class ButlerCollections(ABC): 

37 """Methods for working with collections stored in the Butler.""" 

38 

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. 

42 

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. 

45 

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. 

53 

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. 

62 

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() 

71 

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. 

75 

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. 

78 

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. 

86 

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. 

95 

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() 

104 

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. 

110 

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. 

119 

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. 

128 

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() 

137 

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. 

143 

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. 

152 

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. 

159 

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()