Coverage for oc_ocdm/graph/entities/bibliographic/bibliographic_reference.py: 53%
55 statements
« prev ^ index » next coverage.py v6.5.0, created at 2025-05-30 22:05 +0000
1#!/usr/bin/python
2# -*- coding: utf-8 -*-
3# Copyright (c) 2016, Silvio Peroni <essepuntato@gmail.com>
4#
5# Permission to use, copy, modify, and/or distribute this software for any purpose
6# with or without fee is hereby granted, provided that the above copyright notice
7# and this permission notice appear in all copies.
8#
9# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
10# REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
11# FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
12# OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
13# DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
14# ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
15# SOFTWARE.
16from __future__ import annotations
18from typing import TYPE_CHECKING
20from oc_ocdm.decorators import accepts_only
22if TYPE_CHECKING:
23 from typing import Optional, List
24 from rdflib import URIRef
25 from oc_ocdm.graph.entities.bibliographic.reference_annotation import ReferenceAnnotation
26 from oc_ocdm.graph.entities.bibliographic.bibliographic_resource import BibliographicResource
27from oc_ocdm.graph.graph_entity import GraphEntity
28from oc_ocdm.graph.entities.bibliographic_entity import BibliographicEntity
31class BibliographicReference(BibliographicEntity):
32 """Bibliographic reference (short: be): the particular textual bibliographic reference,
33 usually occurring in the reference list (and denoted by one or more in-text reference
34 pointers within the text of a citing bibliographic resource), that references another
35 bibliographic resource.
36 """
38 @accepts_only('be')
39 def merge(self, other: BibliographicReference) -> None:
40 """
41 The merge operation allows combining two ``BibliographicReference`` entities into a single one,
42 by marking the second entity as to be deleted while also copying its data into the current
43 ``BibliographicReference``. Moreover, every triple from the containing ``GraphSet`` referring to the second
44 entity gets "redirected" to the current entity: **every other reference contained inside a
45 different source (e.g. a triplestore) must be manually handled by the user!**
47 In case of functional properties, values from the current entity get overwritten
48 by those coming from the second entity while, in all other cases, values from the
49 second entity are simply appended to those of the current entity. In this context,
50 ``rdfs:label`` is considered as a functional property, while ``rdf:type`` is not.
52 :param other: The entity which will be marked as to be deleted and whose properties will
53 be merged into the current entity.
54 :type other: BibliographicReference
55 :raises TypeError: if the parameter is of the wrong type
56 :return: None
57 """
58 super(BibliographicReference, self).merge(other)
60 content: Optional[str] = other.get_content()
61 if content is not None:
62 self.has_content(content)
64 annotations_list: List[ReferenceAnnotation] = other.get_annotations()
65 for cur_annotation in annotations_list:
66 self.has_annotation(cur_annotation)
68 referenced_br: Optional[BibliographicResource] = other.get_referenced_br()
69 if referenced_br is not None:
70 self.references_br(referenced_br)
72 # HAS BIBLIOGRAPHIC REFERENCE TEXT
73 def get_content(self) -> Optional[str]:
74 """
75 Getter method corresponding to the ``c4o:hasContent`` RDF predicate.
77 :return: The requested value if found, None otherwise
78 """
79 return self._get_literal(GraphEntity.iri_has_content)
81 @accepts_only('literal')
82 def has_content(self, string: str) -> None:
83 """
84 Setter method corresponding to the ``c4o:hasContent`` RDF predicate.
86 **WARNING: this is a functional property, hence any existing value will be overwritten!**
88 `The literal text of a bibliographic reference occurring in the reference list (or
89 elsewhere) within a bibliographic resource, that references another bibliographic
90 resource. The reference text should be recorded “as given” in the citing bibliographic
91 resource, including any errors (e.g. mis-spellings of authors’ names, or changes from
92 “β” in the original published title to “beta” in the reference text) or omissions (e.g.
93 omission of the title of the referenced bibliographic resource, or omission of sixth and
94 subsequent authors’ names, as required by certain publishers), and in whatever format
95 it has been made available. For instance, the reference text can be either as plain text
96 or as a block of XML.`
98 :param string: The value that will be set as the object of the property related to this method
99 :type string: str
100 :raises TypeError: if the parameter is of the wrong type
101 :return: None
102 """
103 self.remove_content()
104 self._create_literal(GraphEntity.iri_has_content, string)
106 def remove_content(self) -> None:
107 """
108 Remover method corresponding to the ``c4o:hasContent`` RDF predicate.
110 :return: None
111 """
112 self.g.remove((self.res, GraphEntity.iri_has_content, None))
114 # HAS ANNOTATION (ReferenceAnnotation)
115 def get_annotations(self) -> List[ReferenceAnnotation]:
116 """
117 Getter method corresponding to the ``oco:hasAnnotation`` RDF predicate.
119 :return: A list containing the requested values if found, None otherwise
120 """
121 uri_list: List[URIRef] = self._get_multiple_uri_references(GraphEntity.iri_has_annotation, 'an')
122 result: List[ReferenceAnnotation] = []
123 for uri in uri_list:
124 result.append(self.g_set.add_an(self.resp_agent, self.source, uri))
125 return result
127 @accepts_only('an')
128 def has_annotation(self, an_res: ReferenceAnnotation) -> None:
129 """
130 Setter method corresponding to the ``oco:hasAnnotation`` RDF predicate.
132 `An annotation characterizing the related citation, in terms of its citation function (the
133 reason for that citation).`
135 :param an_res: The value that will be set as the object of the property related to this method
136 :type an_res: ReferenceAnnotation
137 :raises TypeError: if the parameter is of the wrong type
138 :return: None
139 """
140 self.g.add((self.res, GraphEntity.iri_has_annotation, an_res.res))
142 @accepts_only('an')
143 def remove_annotation(self, an_res: ReferenceAnnotation = None) -> None:
144 """
145 Remover method corresponding to the ``oco:hasAnnotation`` RDF predicate.
147 **WARNING: this is a non-functional property, hence, if the parameter
148 is None, any existing value will be removed!**
150 :param an_res: If not None, the specific object value that will be removed from the property
151 related to this method (defaults to None)
152 :type an_res: ReferenceAnnotation
153 :raises TypeError: if the parameter is of the wrong type
154 :return: None
155 """
156 if an_res is not None:
157 self.g.remove((self.res, GraphEntity.iri_has_annotation, an_res.res))
158 else:
159 self.g.remove((self.res, GraphEntity.iri_has_annotation, None))
161 # REFERENCES (BibliographicResource)
162 def get_referenced_br(self) -> Optional[BibliographicResource]:
163 """
164 Getter method corresponding to the ``biro:references`` RDF predicate.
166 :return: The requested value if found, None otherwise
167 """
168 uri: Optional[URIRef] = self._get_uri_reference(GraphEntity.iri_references, 'br')
169 if uri is not None:
170 return self.g_set.add_br(self.resp_agent, self.source, uri)
172 @accepts_only('br')
173 def references_br(self, br_res: BibliographicResource) -> None:
174 """
175 Setter method corresponding to the ``biro:references`` RDF predicate.
177 **WARNING: this is a functional property, hence any existing value will be overwritten!**
179 `The bibliographic reference that cites this bibliographic resource.`
181 :param br_res: The value that will be set as the object of the property related to this method
182 :type br_res: BibliographicResource
183 :raises TypeError: if the parameter is of the wrong type
184 :return: None
185 """
186 self.remove_referenced_br()
187 self.g.add((self.res, GraphEntity.iri_references, br_res.res))
189 def remove_referenced_br(self) -> None:
190 """
191 Remover method corresponding to the ``biro:references`` RDF predicate.
193 :return: None
194 """
195 self.g.remove((self.res, GraphEntity.iri_references, None))