Coverage for oc_ocdm / graph / entities / bibliographic / responsible_agent.py: 93%
56 statements
« prev ^ index » next coverage.py v7.13.4, created at 2026-03-28 18:52 +0000
1#!/usr/bin/python
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
8# -*- coding: utf-8 -*-
9from __future__ import annotations
11from typing import TYPE_CHECKING
13from oc_ocdm.decorators import accepts_only
15if TYPE_CHECKING:
16 from typing import Optional, List
17 from rdflib import URIRef
18from oc_ocdm.graph.graph_entity import GraphEntity
19from oc_ocdm.graph.entities.bibliographic_entity import BibliographicEntity
22class ResponsibleAgent(BibliographicEntity):
23 """Responsible agent (short: ra): the agent (usually a person or an organisation) having
24 a certain role with respect to a bibliographic resource (e.g. an author of a paper or
25 book, or an editor of a journal)."""
27 def _merge_properties(self, other: GraphEntity, prefer_self: bool) -> None:
28 """
29 The merge operation allows combining two ``ResponsibleAgent`` entities into a single one,
30 by marking the second entity as to be deleted while also copying its data into the current
31 ``ResponsibleAgent``. 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!**
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.
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: ResponsibleAgent
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, ResponsibleAgent)
49 name: Optional[str] = other.get_name()
50 if name is not None:
51 self.has_name(name)
53 given_name: Optional[str] = other.get_given_name()
54 if given_name is not None:
55 self.has_given_name(given_name)
57 family_name: Optional[str] = other.get_family_name()
58 if family_name is not None:
59 self.has_family_name(family_name)
61 related_agents: List[URIRef] = other.get_related_agents()
62 for cur_agent in related_agents:
63 self.has_related_agent(cur_agent)
65 # HAS NAME
66 def get_name(self) -> Optional[str]:
67 """
68 Getter method corresponding to the ``foaf:name`` RDF predicate.
70 :return: The requested value if found, None otherwise
71 """
72 return self._get_literal(GraphEntity.iri_name)
74 @accepts_only('literal')
75 def has_name(self, string: str) -> None:
76 """
77 Setter method corresponding to the ``foaf:name`` RDF predicate.
79 **WARNING: this is a functional property, hence any existing value will be overwritten!**
81 `The name of an agent (for people, usually in the format: given name followed by family
82 name, separated by a space).`
84 :param string: The value that will be set as the object of the property related to this method
85 :type string: str
86 :raises TypeError: if the parameter is of the wrong type
87 :return: None
88 """
89 self.remove_name()
90 self._create_literal(GraphEntity.iri_name, string)
92 def remove_name(self) -> None:
93 """
94 Remover method corresponding to the ``foaf:name`` RDF predicate.
96 :return: None
97 """
98 self.g.remove((self.res, GraphEntity.iri_name, None))
100 # HAS GIVEN NAME
101 def get_given_name(self) -> Optional[str]:
102 """
103 Getter method corresponding to the ``foaf:givenName`` RDF predicate.
105 :return: The requested value if found, None otherwise
106 """
107 return self._get_literal(GraphEntity.iri_given_name)
109 @accepts_only('literal')
110 def has_given_name(self, string: str) -> None:
111 """
112 Setter method corresponding to the ``foaf:givenName`` RDF predicate.
114 **WARNING: this is a functional property, hence any existing value will be overwritten!**
116 `The given name of an agent, if a person.`
118 :param string: The value that will be set as the object of the property related to this method
119 :type string: str
120 :raises TypeError: if the parameter is of the wrong type
121 :return: None
122 """
123 self.remove_given_name()
124 self._create_literal(GraphEntity.iri_given_name, string)
126 def remove_given_name(self) -> None:
127 """
128 Remover method corresponding to the ``foaf:givenName`` RDF predicate.
130 :return: None
131 """
132 self.g.remove((self.res, GraphEntity.iri_given_name, None))
134 # HAS FAMILY NAME
135 def get_family_name(self) -> Optional[str]:
136 """
137 Getter method corresponding to the ``foaf:familyName`` RDF predicate.
139 :return: The requested value if found, None otherwise
140 """
141 return self._get_literal(GraphEntity.iri_family_name)
143 @accepts_only('literal')
144 def has_family_name(self, string: str) -> None:
145 """
146 Setter method corresponding to the ``foaf:familyName`` RDF predicate.
148 **WARNING: this is a functional property, hence any existing value will be overwritten!**
150 `The family name of an agent, if a person.`
152 :param string: The value that will be set as the object of the property related to this method
153 :type string: str
154 :raises TypeError: if the parameter is of the wrong type
155 :return: None
156 """
157 self.remove_family_name()
158 self._create_literal(GraphEntity.iri_family_name, string)
160 def remove_family_name(self) -> None:
161 """
162 Remover method corresponding to the ``foaf:familyName`` RDF predicate.
164 :return: None
165 """
166 self.g.remove((self.res, GraphEntity.iri_family_name, None))
168 # HAS RELATED AGENT
169 def get_related_agents(self) -> List[URIRef]:
170 """
171 Getter method corresponding to the ``dcterms:relation`` RDF predicate.
173 :return: A list containing the requested values if found, None otherwise
174 """
175 uri_list: List[URIRef] = self._get_multiple_uri_references(GraphEntity.iri_relation)
176 return uri_list
178 @accepts_only('thing')
179 def has_related_agent(self, thing_res: URIRef) -> None:
180 """
181 Setter method corresponding to the ``dcterms:relation`` RDF predicate.
183 `An external agent that/who is related in some relevant way with this responsible agent
184 (e.g. for inter-linking purposes).`
186 :param thing_res: The value that will be set as the object of the property related to this method
187 :type thing_res: str
188 :raises TypeError: if the parameter is of the wrong type
189 :return: None
190 """
191 self.g.add((self.res, GraphEntity.iri_relation, thing_res))
193 @accepts_only('thing')
194 def remove_related_agent(self, thing_res: URIRef | None = None) -> None:
195 """
196 Remover method corresponding to the ``dcterms:relation`` RDF predicate.
198 **WARNING: this is a non-functional property, hence, if the parameter
199 is None, any existing value will be removed!**
201 :param thing_res: If not None, the specific object value that will be removed from the property
202 related to this method (defaults to None)
203 :type thing_res: URIRef
204 :raises TypeError: if the parameter is of the wrong type
205 :return: None
206 """
207 if thing_res is not None:
208 self.g.remove((self.res, GraphEntity.iri_relation, thing_res))
209 else:
210 self.g.remove((self.res, GraphEntity.iri_relation, None))