datacite 1.4.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,329 @@
1
+ # SPDX-FileCopyrightText: 2015 CERN.
2
+ # SPDX-FileCopyrightText: 2020 Caltech.
3
+ # SPDX-FileCopyrightText: 2021 Graz University of Technology.
4
+ # SPDX-License-Identifier: BSD-3-Clause
5
+
6
+ """Python API client wrapper for the DataCite Rest API.
7
+
8
+ API documentation is available at
9
+ https://support.datacite.org/reference/introduction.
10
+ """
11
+
12
+ import json
13
+ import warnings
14
+
15
+ import requests
16
+ from idutils import normalize_doi
17
+
18
+ from .errors import DataCiteError
19
+ from .request import DataCiteRequest
20
+
21
+ HTTP_OK = requests.codes["ok"]
22
+ HTTP_CREATED = requests.codes["created"]
23
+
24
+
25
+ class DataCiteRESTClient(object):
26
+ """DataCite REST API client wrapper."""
27
+
28
+ def __init__(
29
+ self, username, password, prefix, test_mode=False, url=None, timeout=None
30
+ ):
31
+ """Initialize the REST client wrapper.
32
+
33
+ :param username: DataCite username.
34
+ :param password: DataCite password.
35
+ :param prefix: DOI prefix (or CFG_DATACITE_DOI_PREFIX).
36
+ :param test_mode: use test URL when True
37
+ :param url: DataCite API base URL.
38
+ :param timeout: Connect and read timeout in seconds. Specify a tuple
39
+ (connect, read) to specify each timeout individually.
40
+ """
41
+ self.username = str(username)
42
+ self.password = str(password)
43
+ self.prefix = str(prefix)
44
+
45
+ if test_mode:
46
+ self.api_url = "https://api.test.datacite.org/"
47
+ else:
48
+ self.api_url = url or "https://api.datacite.org/"
49
+
50
+ if not self.api_url.endswith("/"):
51
+ self.api_url += "/"
52
+
53
+ self.timeout = timeout
54
+
55
+ def __repr__(self):
56
+ """Create string representation of object."""
57
+ return "<DataCiteRESTClient: {0}>".format(self.username)
58
+
59
+ def _create_request(self):
60
+ """Create a new Request object."""
61
+ return DataCiteRequest(
62
+ base_url=self.api_url,
63
+ username=self.username,
64
+ password=self.password,
65
+ timeout=self.timeout,
66
+ )
67
+
68
+ def doi_get(self, doi):
69
+ """Get the URL where the resource pointed by the DOI is located.
70
+
71
+ :param doi: DOI name of the resource.
72
+ """
73
+ warn_msg = "The method is deprecated in favour of get_doi"
74
+ warnings.warn(warn_msg, DeprecationWarning)
75
+ return self.get_doi(doi)
76
+
77
+ def get_doi(self, doi):
78
+ """Get the URL where the resource pointed by the DOI is located.
79
+
80
+ :param doi: DOI name of the resource.
81
+ """
82
+ request = self._create_request()
83
+ resp = request.get("dois/" + doi)
84
+ if resp.status_code == HTTP_OK:
85
+ return resp.json()["data"]["attributes"]["url"]
86
+ else:
87
+ raise DataCiteError.factory(resp.status_code, resp.text)
88
+
89
+ def check_doi(self, doi):
90
+ """Check doi structure.
91
+
92
+ Check that the doi has a form
93
+ 12.12345/123 with the prefix defined
94
+ """
95
+ # If prefix is in doi
96
+ if "/" in doi:
97
+ split = doi.split("/")
98
+ prefix = split[0]
99
+ if prefix != self.prefix:
100
+ # Provided a DOI with the wrong prefix
101
+ raise ValueError(
102
+ "Wrong DOI {0} prefix provided, it should be "
103
+ "{1} as defined in the rest client".format(prefix, self.prefix)
104
+ )
105
+ else:
106
+ doi = "{prefix}/{doi}".format(prefix=self.prefix, doi=doi)
107
+ return normalize_doi(doi)
108
+
109
+ def post_doi(self, data):
110
+ """Post a new JSON payload to DataCite."""
111
+ headers = {"content-type": "application/vnd.api+json"}
112
+ body = {"data": data}
113
+ request = self._create_request()
114
+ resp = request.post("dois", body=json.dumps(body), headers=headers)
115
+ if resp.status_code == HTTP_CREATED:
116
+ return resp.json()["data"]["id"]
117
+ else:
118
+ raise DataCiteError.factory(resp.status_code, resp.text)
119
+
120
+ def put_doi(self, doi, data):
121
+ """Put a JSON payload to DataCite for an existing DOI."""
122
+ headers = {"content-type": "application/vnd.api+json"}
123
+ body = {"data": data}
124
+ request = self._create_request()
125
+ url = "dois/" + doi
126
+ resp = request.put(url, body=json.dumps(body), headers=headers)
127
+ if resp.status_code == HTTP_OK:
128
+ return resp.json()["data"]["attributes"]
129
+ else:
130
+ raise DataCiteError.factory(resp.status_code, resp.text)
131
+
132
+ def draft_doi(self, metadata=None, doi=None):
133
+ """Create a draft doi.
134
+
135
+ A draft DOI can be deleted
136
+
137
+ If doi is not provided, DataCite
138
+ will automatically create a DOI with a random,
139
+ recommended DOI suffix
140
+
141
+ :param metadata: metadata for the DOI
142
+ :param doi: DOI (e.g. 10.123/456)
143
+ :return:
144
+ """
145
+ data = {"attributes": {}}
146
+ if metadata:
147
+ data["attributes"] = metadata
148
+ data["attributes"]["prefix"] = self.prefix
149
+ if doi:
150
+ doi = self.check_doi(doi)
151
+ data["attributes"]["doi"] = doi
152
+ return self.post_doi(data)
153
+
154
+ def update_url(self, doi, url):
155
+ """Update the url of a doi.
156
+
157
+ :param url: URL where the doi will resolve.
158
+ :param doi: DOI (e.g. 10.123/456)
159
+ :return:
160
+ """
161
+ doi = self.check_doi(doi)
162
+ data = {"attributes": {"url": url}}
163
+
164
+ result = self.put_doi(doi, data)
165
+ return result["url"]
166
+
167
+ def delete_doi(self, doi):
168
+ """Delete a doi.
169
+
170
+ This will only work for draft dois
171
+
172
+ :param doi: DOI (e.g. 10.123/456)
173
+ :return:
174
+ """
175
+ request = self._create_request()
176
+ resp = request.delete("dois/" + doi)
177
+
178
+ if resp.status_code != 204:
179
+ raise DataCiteError.factory(resp.status_code, resp.text)
180
+
181
+ def public_doi(self, metadata, url, doi=None):
182
+ """Create a public doi.
183
+
184
+ This DOI will be public and cannot be deleted
185
+
186
+ If doi is not provided, DataCite
187
+ will automatically create a DOI with a random,
188
+ recommended DOI suffix
189
+
190
+ Metadata should follow the DataCite Metadata Schema:
191
+ http://schema.datacite.org/
192
+
193
+ :param metadata: JSON format of the metadata.
194
+ :param doi: DOI (e.g. 10.123/456)
195
+ :param url: URL where the doi will resolve.
196
+ :return:
197
+ """
198
+ data = {"attributes": metadata}
199
+ data["attributes"]["prefix"] = self.prefix
200
+ data["attributes"]["event"] = "publish"
201
+ data["attributes"]["url"] = url
202
+ if doi:
203
+ doi = self.check_doi(doi)
204
+ data["attributes"]["doi"] = doi
205
+
206
+ return self.post_doi(data)
207
+
208
+ def update_doi(self, doi, metadata=None, url=None):
209
+ """Update the metadata or url for a DOI.
210
+
211
+ :param url: URL where the doi will resolve.
212
+ :param metadata: JSON format of the metadata.
213
+ :return:
214
+ """
215
+ data = {"attributes": {}}
216
+ doi = self.check_doi(doi)
217
+ data["attributes"]["doi"] = doi
218
+ if metadata:
219
+ data["attributes"] = metadata
220
+ if url:
221
+ data["attributes"]["url"] = url
222
+
223
+ return self.put_doi(doi, data)
224
+
225
+ def private_doi(self, metadata, url, doi=None):
226
+ """Publish a doi in a registered state.
227
+
228
+ A DOI generated by this method will
229
+ not be found in DataCite Search
230
+
231
+ This DOI cannot be deleted
232
+
233
+ If doi is not provided, DataCite
234
+ will automatically create a DOI with a random,
235
+ recommended DOI suffix
236
+
237
+ Metadata should follow the DataCite Metadata Schema:
238
+ http://schema.datacite.org/
239
+
240
+ :param metadata: JSON format of the metadata.
241
+ :return:
242
+ """
243
+ data = {"attributes": metadata}
244
+ data["attributes"]["prefix"] = self.prefix
245
+ data["attributes"]["event"] = "register"
246
+ data["attributes"]["url"] = url
247
+ if doi:
248
+ doi = self.check_doi(doi)
249
+ data["attributes"]["doi"] = doi
250
+
251
+ return self.post_doi(data)
252
+
253
+ def hide_doi(self, doi):
254
+ """Hide a previously registered DOI.
255
+
256
+ This DOI will no
257
+ longer be found in DataCite Search
258
+
259
+ :param doi: DOI to hide e.g. 10.12345/1.
260
+ :return:
261
+ """
262
+ data = {"attributes": {"event": "hide"}}
263
+ if doi:
264
+ doi = self.check_doi(doi)
265
+ data["attributes"]["doi"] = doi
266
+
267
+ return self.put_doi(doi, data)
268
+
269
+ def show_doi(self, doi):
270
+ """Show a previously registered DOI.
271
+
272
+ This DOI will be found in DataCite Search
273
+
274
+ :param doi: DOI to hide e.g. 10.12345/1.
275
+ :return:
276
+ """
277
+ data = {"attributes": {"event": "publish"}}
278
+ if doi:
279
+ doi = self.check_doi(doi)
280
+ data["attributes"]["doi"] = doi
281
+
282
+ return self.put_doi(doi, data)
283
+
284
+ def metadata_get(self, doi):
285
+ """Get the JSON metadata associated to a DOI name.
286
+
287
+ :param doi: DOI name of the resource.
288
+ """
289
+ warn_msg = "The method is deprecated in favour of get_metadata"
290
+ warnings.warn(warn_msg, DeprecationWarning)
291
+ return self.get_metadata(doi)
292
+
293
+ def get_metadata(self, doi):
294
+ """Get the JSON metadata associated to a DOI name.
295
+
296
+ :param doi: DOI name of the resource.
297
+ """
298
+ """Put a JSON payload to DataCite for an existing DOI."""
299
+ headers = {"content-type": "application/vnd.api+json"}
300
+ request = self._create_request()
301
+ resp = request.get("dois/" + doi, headers=headers)
302
+
303
+ if resp.status_code == HTTP_OK:
304
+ return resp.json()["data"]["attributes"]
305
+ else:
306
+ raise DataCiteError.factory(resp.status_code, resp.text)
307
+
308
+ def media_get(self, doi):
309
+ """Get list of pairs of media type and URLs associated with a DOI.
310
+
311
+ :param doi: DOI name of the resource.
312
+ """
313
+ warn_msg = "The method is deprecated in favour of get_media"
314
+ warnings.warn(warn_msg, DeprecationWarning)
315
+ return self.get_media(doi)
316
+
317
+ def get_media(self, doi):
318
+ """Get list of pairs of media type and URLs associated with a DOI.
319
+
320
+ :param doi: DOI name of the resource.
321
+ """
322
+ headers = {"content-type": "application/vnd.api+json"}
323
+ request = self._create_request()
324
+ resp = request.get("dois/" + doi, headers=headers)
325
+
326
+ if resp.status_code == HTTP_OK:
327
+ return resp.json()["relationships"]["media"]
328
+ else:
329
+ raise DataCiteError.factory(resp.status_code, resp.text)