Coverage for python/lsst/dax/apdb/apdbMetadata.py: 100%

15 statements  

« prev     ^ index     » next       coverage.py v7.5.0, created at 2024-05-01 10:44 +0000

1# This file is part of dax_apdb. 

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 program is free software: you can redistribute it and/or modify 

10# it under the terms of the GNU General Public License as published by 

11# the Free Software Foundation, either version 3 of the License, or 

12# (at your option) any later version. 

13# 

14# This program is distributed in the hope that it will be useful, 

15# but WITHOUT ANY WARRANTY; without even the implied warranty of 

16# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

17# GNU General Public License for more details. 

18# 

19# You should have received a copy of the GNU General Public License 

20# along with this program. If not, see <http://www.gnu.org/licenses/>. 

21 

22from __future__ import annotations 

23 

24__all__ = ["ApdbMetadata"] 

25 

26from abc import ABC, abstractmethod 

27from collections.abc import Generator 

28 

29 

30class ApdbMetadata(ABC): 

31 """Interface for accessing APDB metadata. 

32 

33 Metadata is a collection of key/value items usually stored in a special 

34 table in the database. This abstract interface provides methods for 

35 accessing and modifying it. 

36 """ 

37 

38 @abstractmethod 

39 def get(self, key: str, default: str | None = None) -> str | None: 

40 """Retrieve value of a given metadata record. 

41 

42 Parameters 

43 ---------- 

44 key : `str` 

45 Metadata key, arbitrary non-empty string. 

46 default : `str`, optional 

47 Default value returned when key does not exist, can be string 

48 or `None`. 

49 

50 Returns 

51 ------- 

52 value : `str` or `None` 

53 Metadata value, if key does not exist then ``default`` is returned. 

54 """ 

55 raise NotImplementedError() 

56 

57 @abstractmethod 

58 def set(self, key: str, value: str, *, force: bool = False) -> None: 

59 """Set value for a given metadata record. 

60 

61 Parameters 

62 ---------- 

63 key : `str` 

64 Metadata key, arbitrary non-empty string. 

65 value : `str` 

66 New metadata value, an arbitrary string. Due to deficiencies of 

67 some database engines we are not allowing empty strings to be 

68 stored in the database, and ``value`` cannot be an empty string. 

69 force : `bool`, optional 

70 Controls handling of existing metadata. With default `False` 

71 value an exception is raised if ``key`` already exists, if `True` 

72 is passed then value of the existing key will be updated. 

73 

74 Raises 

75 ------ 

76 KeyError 

77 Raised if key already exists but ``force`` option is false. 

78 ValueError 

79 Raised if key or value parameters are empty. 

80 """ 

81 raise NotImplementedError() 

82 

83 @abstractmethod 

84 def delete(self, key: str) -> bool: 

85 """Delete metadata record. 

86 

87 Parameters 

88 ---------- 

89 key : `str` 

90 Metadata key, arbitrary non-empty string. 

91 

92 Returns 

93 ------- 

94 existed : `bool` 

95 `True` is returned if attribute existed before it was deleted. 

96 """ 

97 raise NotImplementedError() 

98 

99 @abstractmethod 

100 def items(self) -> Generator[tuple[str, str], None, None]: 

101 """Iterate over records and yield their keys and values. 

102 

103 Yields 

104 ------ 

105 key : `str` 

106 Metadata key. 

107 value : `str` 

108 Corresponding metadata value. 

109 """ 

110 raise NotImplementedError() 

111 

112 @abstractmethod 

113 def empty(self) -> bool: 

114 """Check whether attributes set is empty. 

115 

116 Returns 

117 ------- 

118 empty : `bool` 

119 `True` if there are no any attributes defined. `True` is also 

120 returned if metadata table is missing. 

121 """ 

122 raise NotImplementedError()