Coverage for oc_ocdm/graph/entities/bibliographic/responsible_agent.py: 61%
59 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
25from oc_ocdm.graph.graph_entity import GraphEntity
26from oc_ocdm.graph.entities.bibliographic_entity import BibliographicEntity
29class ResponsibleAgent(BibliographicEntity):
30 """Responsible agent (short: ra): the agent (usually a person or an organisation) having
31 a certain role with respect to a bibliographic resource (e.g. an author of a paper or
32 book, or an editor of a journal)."""
34 @accepts_only('ra')
35 def merge(self, other: ResponsibleAgent) -> None:
36 """
37 The merge operation allows combining two ``ResponsibleAgent`` entities into a single one,
38 by marking the second entity as to be deleted while also copying its data into the current
39 ``ResponsibleAgent``. Moreover, every triple from the containing ``GraphSet`` referring to the second
40 entity gets "redirected" to the current entity: **every other reference contained inside a
41 different source (e.g. a triplestore) must be manually handled by the user!**
43 In case of functional properties, values from the current entity get overwritten
44 by those coming from the second entity while, in all other cases, values from the
45 second entity are simply appended to those of the current entity. In this context,
46 ``rdfs:label`` is considered as a functional property, while ``rdf:type`` is not.
48 :param other: The entity which will be marked as to be deleted and whose properties will
49 be merged into the current entity.
50 :type other: ResponsibleAgent
51 :raises TypeError: if the parameter is of the wrong type
52 :return: None
53 """
54 super(ResponsibleAgent, self).merge(other)
56 name: Optional[str] = other.get_name()
57 if name is not None:
58 self.has_name(name)
60 given_name: Optional[str] = other.get_given_name()
61 if given_name is not None:
62 self.has_given_name(given_name)
64 family_name: Optional[str] = other.get_family_name()
65 if family_name is not None:
66 self.has_family_name(family_name)
68 related_agents: List[URIRef] = other.get_related_agents()
69 for cur_agent in related_agents:
70 self.has_related_agent(cur_agent)
72 # HAS NAME
73 def get_name(self) -> Optional[str]:
74 """
75 Getter method corresponding to the ``foaf:name`` RDF predicate.
77 :return: The requested value if found, None otherwise
78 """
79 return self._get_literal(GraphEntity.iri_name)
81 @accepts_only('literal')
82 def has_name(self, string: str) -> None:
83 """
84 Setter method corresponding to the ``foaf:name`` RDF predicate.
86 **WARNING: this is a functional property, hence any existing value will be overwritten!**
88 `The name of an agent (for people, usually in the format: given name followed by family
89 name, separated by a space).`
91 :param string: The value that will be set as the object of the property related to this method
92 :type string: str
93 :raises TypeError: if the parameter is of the wrong type
94 :return: None
95 """
96 self.remove_name()
97 self._create_literal(GraphEntity.iri_name, string)
99 def remove_name(self) -> None:
100 """
101 Remover method corresponding to the ``foaf:name`` RDF predicate.
103 :return: None
104 """
105 self.g.remove((self.res, GraphEntity.iri_name, None))
107 # HAS GIVEN NAME
108 def get_given_name(self) -> Optional[str]:
109 """
110 Getter method corresponding to the ``foaf:givenName`` RDF predicate.
112 :return: The requested value if found, None otherwise
113 """
114 return self._get_literal(GraphEntity.iri_given_name)
116 @accepts_only('literal')
117 def has_given_name(self, string: str) -> None:
118 """
119 Setter method corresponding to the ``foaf:givenName`` RDF predicate.
121 **WARNING: this is a functional property, hence any existing value will be overwritten!**
123 `The given name of an agent, if a person.`
125 :param string: The value that will be set as the object of the property related to this method
126 :type string: str
127 :raises TypeError: if the parameter is of the wrong type
128 :return: None
129 """
130 self.remove_given_name()
131 self._create_literal(GraphEntity.iri_given_name, string)
133 def remove_given_name(self) -> None:
134 """
135 Remover method corresponding to the ``foaf:givenName`` RDF predicate.
137 :return: None
138 """
139 self.g.remove((self.res, GraphEntity.iri_given_name, None))
141 # HAS FAMILY NAME
142 def get_family_name(self) -> Optional[str]:
143 """
144 Getter method corresponding to the ``foaf:familyName`` RDF predicate.
146 :return: The requested value if found, None otherwise
147 """
148 return self._get_literal(GraphEntity.iri_family_name)
150 @accepts_only('literal')
151 def has_family_name(self, string: str) -> None:
152 """
153 Setter method corresponding to the ``foaf:familyName`` RDF predicate.
155 **WARNING: this is a functional property, hence any existing value will be overwritten!**
157 `The family name of an agent, if a person.`
159 :param string: The value that will be set as the object of the property related to this method
160 :type string: str
161 :raises TypeError: if the parameter is of the wrong type
162 :return: None
163 """
164 self.remove_family_name()
165 self._create_literal(GraphEntity.iri_family_name, string)
167 def remove_family_name(self) -> None:
168 """
169 Remover method corresponding to the ``foaf:familyName`` RDF predicate.
171 :return: None
172 """
173 self.g.remove((self.res, GraphEntity.iri_family_name, None))
175 # HAS RELATED AGENT
176 def get_related_agents(self) -> List[URIRef]:
177 """
178 Getter method corresponding to the ``dcterms:relation`` RDF predicate.
180 :return: A list containing the requested values if found, None otherwise
181 """
182 uri_list: List[URIRef] = self._get_multiple_uri_references(GraphEntity.iri_relation)
183 return uri_list
185 @accepts_only('thing')
186 def has_related_agent(self, thing_res: URIRef) -> None:
187 """
188 Setter method corresponding to the ``dcterms:relation`` RDF predicate.
190 `An external agent that/who is related in some relevant way with this responsible agent
191 (e.g. for inter-linking purposes).`
193 :param thing_res: The value that will be set as the object of the property related to this method
194 :type thing_res: str
195 :raises TypeError: if the parameter is of the wrong type
196 :return: None
197 """
198 self.g.add((self.res, GraphEntity.iri_relation, thing_res))
200 @accepts_only('thing')
201 def remove_related_agent(self, thing_res: URIRef = None) -> None:
202 """
203 Remover method corresponding to the ``dcterms:relation`` RDF predicate.
205 **WARNING: this is a non-functional property, hence, if the parameter
206 is None, any existing value will be removed!**
208 :param thing_res: If not None, the specific object value that will be removed from the property
209 related to this method (defaults to None)
210 :type thing_res: URIRef
211 :raises TypeError: if the parameter is of the wrong type
212 :return: None
213 """
214 if thing_res is not None:
215 self.g.remove((self.res, GraphEntity.iri_relation, thing_res))
216 else:
217 self.g.remove((self.res, GraphEntity.iri_relation, None))