Coverage for oc_ocdm / graph / entities / bibliographic / responsible_agent.py: 92%

1#!/usr/bin/python 

2 

3# SPDX-FileCopyrightText: 2020-2022 Simone Persiani <iosonopersia@gmail.com> 

4# SPDX-FileCopyrightText: 2021 Arcangelo Massari <arcangelo.massari@unibo.it> 

5# 

6# SPDX-License-Identifier: ISC 

7 

8# -*- coding: utf-8 -*- 

9from __future__ import annotations 

10 

11from typing import TYPE_CHECKING 

12 

13from triplelite import RDFTerm 

14 

15if TYPE_CHECKING: 

16 from typing import List, Optional 

17from oc_ocdm.graph.entities.bibliographic_entity import BibliographicEntity 

18from oc_ocdm.graph.graph_entity import GraphEntity 

19 

20 

21class ResponsibleAgent(BibliographicEntity): 

22 """Responsible agent (short: ra): the agent (usually a person or an organisation) having 

23 a certain role with respect to a bibliographic resource (e.g. an author of a paper or 

24 book, or an editor of a journal).""" 

25 

26 def _merge_properties(self, other: GraphEntity, prefer_self: bool) -> None: 

27 """ 

28 The merge operation allows combining two ``ResponsibleAgent`` entities into a single one, 

29 by marking the second entity as to be deleted while also copying its data into the current 

30 ``ResponsibleAgent``. Moreover, every triple from the containing ``GraphSet`` referring to the second 

31 entity gets "redirected" to the current entity: **every other reference contained inside a 

32 different source (e.g. a triplestore) must be manually handled by the user!** 

33 

34 In case of functional properties, values from the current entity get overwritten 

35 by those coming from the second entity while, in all other cases, values from the 

36 second entity are simply appended to those of the current entity. In this context, 

37 ``rdfs:label`` is considered as a functional property, while ``rdf:type`` is not. 

38 

39 :param other: The entity which will be marked as to be deleted and whose properties will 

40 be merged into the current entity. 

41 :type other: ResponsibleAgent 

42 :raises TypeError: if the parameter is of the wrong type 

43 :return: None 

44 """ 

45 super()._merge_properties(other, prefer_self) 

46 assert isinstance(other, ResponsibleAgent) 

47 

48 name: Optional[str] = other.get_name() 

49 if name is not None: 

50 self.has_name(name) 

51 

52 given_name: Optional[str] = other.get_given_name() 

53 if given_name is not None: 

54 self.has_given_name(given_name) 

55 

56 family_name: Optional[str] = other.get_family_name() 

57 if family_name is not None: 

58 self.has_family_name(family_name) 

59 

60 related_agents: List[str] = other.get_related_agents() 

61 for cur_agent in related_agents: 

62 self.has_related_agent(cur_agent) 

63 

64 # HAS NAME 

65 def get_name(self) -> Optional[str]: 

66 """ 

67 Getter method corresponding to the ``foaf:name`` RDF predicate. 

68 

69 :return: The requested value if found, None otherwise 

70 """ 

71 return self._get_literal(GraphEntity.iri_name) 

72 

73 def has_name(self, string: str) -> None: 

74 """ 

75 Setter method corresponding to the ``foaf:name`` RDF predicate. 

76 

77 **WARNING: this is a functional property, hence any existing value will be overwritten!** 

78 

79 `The name of an agent (for people, usually in the format: given name followed by family 

80 name, separated by a space).` 

81 

82 :param string: The value that will be set as the object of the property related to this method 

83 :type string: str 

84 :raises TypeError: if the parameter is of the wrong type 

85 :return: None 

86 """ 

87 self.remove_name() 

88 self._create_literal(GraphEntity.iri_name, string) 

89 

90 def remove_name(self) -> None: 

91 """ 

92 Remover method corresponding to the ``foaf:name`` RDF predicate. 

93 

94 :return: None 

95 """ 

96 self.g.remove((self.res, GraphEntity.iri_name, None)) 

97 

98 # HAS GIVEN NAME 

99 def get_given_name(self) -> Optional[str]: 

100 """ 

101 Getter method corresponding to the ``foaf:givenName`` RDF predicate. 

102 

103 :return: The requested value if found, None otherwise 

104 """ 

105 return self._get_literal(GraphEntity.iri_given_name) 

106 

107 def has_given_name(self, string: str) -> None: 

108 """ 

109 Setter method corresponding to the ``foaf:givenName`` RDF predicate. 

110 

111 **WARNING: this is a functional property, hence any existing value will be overwritten!** 

112 

113 `The given name of an agent, if a person.` 

114 

115 :param string: The value that will be set as the object of the property related to this method 

116 :type string: str 

117 :raises TypeError: if the parameter is of the wrong type 

118 :return: None 

119 """ 

120 self.remove_given_name() 

121 self._create_literal(GraphEntity.iri_given_name, string) 

122 

123 def remove_given_name(self) -> None: 

124 """ 

125 Remover method corresponding to the ``foaf:givenName`` RDF predicate. 

126 

127 :return: None 

128 """ 

129 self.g.remove((self.res, GraphEntity.iri_given_name, None)) 

130 

131 # HAS FAMILY NAME 

132 def get_family_name(self) -> Optional[str]: 

133 """ 

134 Getter method corresponding to the ``foaf:familyName`` RDF predicate. 

135 

136 :return: The requested value if found, None otherwise 

137 """ 

138 return self._get_literal(GraphEntity.iri_family_name) 

139 

140 def has_family_name(self, string: str) -> None: 

141 """ 

142 Setter method corresponding to the ``foaf:familyName`` RDF predicate. 

143 

144 **WARNING: this is a functional property, hence any existing value will be overwritten!** 

145 

146 `The family name of an agent, if a person.` 

147 

148 :param string: The value that will be set as the object of the property related to this method 

149 :type string: str 

150 :raises TypeError: if the parameter is of the wrong type 

151 :return: None 

152 """ 

153 self.remove_family_name() 

154 self._create_literal(GraphEntity.iri_family_name, string) 

155 

156 def remove_family_name(self) -> None: 

157 """ 

158 Remover method corresponding to the ``foaf:familyName`` RDF predicate. 

159 

160 :return: None 

161 """ 

162 self.g.remove((self.res, GraphEntity.iri_family_name, None)) 

163 

164 # HAS RELATED AGENT 

165 def get_related_agents(self) -> List[str]: 

166 """ 

167 Getter method corresponding to the ``dcterms:relation`` RDF predicate. 

168 

169 :return: A list containing the requested values if found, None otherwise 

170 """ 

171 uri_list: List[str] = self._get_multiple_uri_references(GraphEntity.iri_relation) 

172 return uri_list 

173 

174 def has_related_agent(self, thing_res: str) -> None: 

175 """ 

176 Setter method corresponding to the ``dcterms:relation`` RDF predicate. 

177 

178 `An external agent that/who is related in some relevant way with this responsible agent 

179 (e.g. for inter-linking purposes).` 

180 

181 :param thing_res: The value that will be set as the object of the property related to this method 

182 :type thing_res: str 

183 :raises TypeError: if the parameter is of the wrong type 

184 :return: None 

185 """ 

186 self.g.add((self.res, GraphEntity.iri_relation, RDFTerm("uri", str(thing_res)))) 

187 

188 def remove_related_agent(self, thing_res: str | None = None) -> None: 

189 """ 

190 Remover method corresponding to the ``dcterms:relation`` RDF predicate. 

191 

192 **WARNING: this is a non-functional property, hence, if the parameter 

193 is None, any existing value will be removed!** 

194 

195 :param thing_res: If not None, the specific object value that will be removed from the property 

196 related to this method (defaults to None) 

197 :type thing_res: URIRef 

198 :raises TypeError: if the parameter is of the wrong type 

199 :return: None 

200 """ 

201 if thing_res is not None: 

202 self.g.remove((self.res, GraphEntity.iri_relation, RDFTerm("uri", str(thing_res)))) 

203 else: 

204 self.g.remove((self.res, GraphEntity.iri_relation, None))