Coverage for oc_ds_converter / oc_idmanager / base.py: 64%

1# SPDX-FileCopyrightText: 2023 Arianna Moretti <arianna.moretti4@unibo.it> 

2# SPDX-FileCopyrightText: 2023-2026 Arcangelo Massari <arcangelo.massari@unibo.it> 

3# 

4# SPDX-License-Identifier: ISC 

5 

6 

7from abc import ABCMeta, abstractmethod 

8 

9 

10class IdentifierManager(metaclass=ABCMeta): 

11 """This is the interface that must be implemented by any identifier manager 

12 for a particular identifier scheme. It provides the signatures of the methods 

13 for checking the validity of an identifier and for normalising it.""" 

14 

15 _headers: dict[str, str] 

16 

17 def __init__(self, **params: object) -> None: 

18 """Identifier manager constructor.""" 

19 for key in params: 

20 setattr(self, key, params[key]) 

21 

22 self._headers = { 

23 "User-Agent": "Identifier Manager / OpenCitations Indexes " 

24 "(http://opencitations.net; mailto:contact@opencitations.net)" 

25 } 

26 

27 def is_valid( 

28 self, id_string: str, get_extra_info: bool = False 

29 ) -> bool | tuple[bool, dict[str, str | bool]]: 

30 """Returns true if the id is valid, false otherwise. 

31 

32 Args: 

33 id_string (str): id to check 

34 get_extra_info (bool, optional): True to get a dictionary with additional info about the id 

35 Returns: 

36 bool: True if the id is valid, False otherwise. 

37 dict : a dictionary with additional information, if required (get_extra_info=True) 

38 

39 """ 

40 return True 

41 

42 def validated_as_id(self, id_string: str) -> bool | None: 

43 return None 

44 

45 @abstractmethod 

46 def normalise(self, id_string: str, include_prefix: bool = False) -> str | None: 

47 """Returns the id normalized. 

48 

49 Args: 

50 id_string (str): the id to normalize 

51 include_prefix (bool, optional): indicates if include the prefix. Defaults to False. 

52 Returns: 

53 str: normalized id 

54 """ 

55 pass 

56 

57 def check_digit(self, id_string: str) -> bool: 

58 """Returns True, if the check digit on the id_string passes (this does not mean that the id is also registered). 

59 Not all id types have a check digit 

60 

61 Args: 

62 id_string (str): the id to check 

63 Returns: 

64 bool: true if id_string passes the check digit of the specific id type 

65 """ 

66 return True 

67 

68 def syntax_ok(self, id_string: str) -> bool: 

69 """Returns True if the syntax of the id string is correct, False otherwise. 

70 

71 Args: 

72 id_string (str): the id string to check 

73 Returns: 

74 bool: True if the id syntax is correct, False otherwise. 

75 """ 

76 return True 

77 

78 def exists( 

79 self, 

80 id_string: str, 

81 get_extra_info: bool = False, 

82 allow_extra_api: str | None = None, 

83 ) -> bool | tuple[bool, dict[str, str | bool]]: 

84 """Returns True if the id exists, False otherwise. 

85 Not all child classes check id existence because of API policies 

86 

87 Args: 

88 id_string (str): the id string for the api request 

89 get_extra_info (bool, optional): True to get a dictionary with additional info about the id 

90 allow_extra_api (list or None, optional): This optional list is supposed to contain the strings of 

91 the names of the enabled APIs to call in case the primary one does not provide all the 

92 required information. The default value assigned to this parameter is None, and in case 

93 the list is not defined, only the primary API is used to retrieve information. 

94 Returns: 

95 bool: True if the id exists (is registered), False otherwise. 

96 dict : a dictionary with additional information, if required 

97 """ 

98 return True 

99 

100 def extra_info( 

101 self, 

102 api_response: dict[str, object], 

103 choose_api: str | None = None, 

104 info_dict: dict[str, object] | None = None, 

105 ) -> dict[str, object]: 

106 """Returns a dictionary with extra info about the id, if available. 

107 Not all child classes check id existence because of API policies 

108 

109 Args: 

110 api_response (json or string): the api response of the api request 

111 choose_api (string or None, optional): the string of the name of the API from whose response 

112 the information is to be extracted. The default value is None, and the default 

113 behavior in case no string is defined is trying to extract the required extra 

114 information from an API response provided by the primary API only. When this 

115 method is called by the method exists, the value of the choose_api parameter 

116 is supposed to be either one of the strings in the allow_extra_api list or None. 

117 info_dict (dict, optional): a dictionary (empty by default) containing pre-processed 

118 information, so to avoid retrieving the same data twice from different APIs. 

119 Returns: 

120 dict: A dictionary with additional information about the id, if provided by the API. 

121 """ 

122 return {"value": True}