Coverage for oc_ocdm / graph / entities / bibliographic / pointer_list.py: 97%

1#!/usr/bin/python 

2 

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

4# 

5# SPDX-License-Identifier: ISC 

6 

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

8from __future__ import annotations 

9 

10from typing import TYPE_CHECKING 

11 

12from oc_ocdm.decorators import accepts_only 

13 

14if TYPE_CHECKING: 

15 from typing import Optional, List 

16 from rdflib import URIRef 

17 from oc_ocdm.graph.entities.bibliographic.reference_pointer import ReferencePointer 

18from oc_ocdm.graph.graph_entity import GraphEntity 

19from oc_ocdm.graph.entities.bibliographic_entity import BibliographicEntity 

20 

21 

22class PointerList(BibliographicEntity): 

23 """Pointer list (short: pl): a textual device (e.g. '[1, 2, 3]' or '[4-9]') which includes a 

24 number of reference pointers denoting the specific bibliographic references to which 

25 the list pertains.""" 

26 

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

28 """ 

29 The merge operation allows combining two ``PointerList`` entities into a single one, 

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

31 ``PointerList``. Moreover, every triple from the containing ``GraphSet`` referring to the second 

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

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

34 

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

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

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

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

39 

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

41 be merged into the current entity. 

42 :type other: PointerList 

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

44 :return: None 

45 """ 

46 super()._merge_properties(other, prefer_self) 

47 assert isinstance(other, PointerList) 

48 

49 content: Optional[str] = self.get_content() 

50 if content is not None: 

51 self.has_content(content) 

52 

53 rp_list: List[ReferencePointer] = other.get_contained_elements() 

54 for cur_rp in rp_list: 

55 self.contains_element(cur_rp) 

56 

57 # HAS POINTER LIST TEXT 

58 def get_content(self) -> Optional[str]: 

59 """ 

60 Getter method corresponding to the ``c4o:hasContent`` RDF predicate. 

61 

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

63 """ 

64 return self._get_literal(GraphEntity.iri_has_content) 

65 

66 @accepts_only('literal') 

67 def has_content(self, string: str) -> None: 

68 """ 

69 Setter method corresponding to the ``c4o:hasContent`` RDF predicate. 

70 

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

72 

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

74 :type string: str 

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

76 :return: None 

77 """ 

78 self.remove_content() 

79 self._create_literal(GraphEntity.iri_has_content, string) 

80 

81 def remove_content(self) -> None: 

82 """ 

83 Remover method corresponding to the ``c4o:hasContent`` RDF predicate. 

84 

85 :return: None 

86 """ 

87 self.g.remove((self.res, GraphEntity.iri_has_content, None)) 

88 

89 # HAS ELEMENT (ReferencePointer) 

90 def get_contained_elements(self) -> List[ReferencePointer]: 

91 """ 

92 Getter method corresponding to the ``co:element`` RDF predicate. 

93 

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

95 """ 

96 uri_list: List[URIRef] = self._get_multiple_uri_references(GraphEntity.iri_has_element, 'rp') 

97 result: List[ReferencePointer] = [] 

98 for uri in uri_list: 

99 result.append(self.g_set.add_rp(self.resp_agent, self.source, uri)) 

100 return result 

101 

102 @accepts_only('rp') 

103 def contains_element(self, rp_res: ReferencePointer) -> None: 

104 """ 

105 Setter method corresponding to the ``co:element`` RDF predicate. 

106 

107 `The in-text reference pointer that is part of the in-text reference pointer list present at 

108 a particular location within the body of the citing work.` 

109 

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

111 :type rp_res: ReferencePointer 

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

113 :return: None 

114 """ 

115 self.g.add((self.res, GraphEntity.iri_has_element, rp_res.res)) 

116 

117 @accepts_only('rp') 

118 def remove_contained_element(self, rp_res: ReferencePointer | None = None) -> None: 

119 """ 

120 Remover method corresponding to the ``co:element`` RDF predicate. 

121 

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

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

124 

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

126 related to this method (defaults to None) 

127 :type rp_res: ReferencePointer 

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

129 :return: None 

130 """ 

131 if rp_res is not None: 

132 self.g.remove((self.res, GraphEntity.iri_has_element, rp_res.res)) 

133 else: 

134 self.g.remove((self.res, GraphEntity.iri_has_element, None))