datacite 1.4.1__py3-none-any.whl

datacite/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2015, 2016 CERN.
+# SPDX-FileCopyrightText: 2026 Graz University of Technology.
+# SPDX-FileCopyrightText: 2026 TU Wien.
+# SPDX-License-Identifier: BSD-3-Clause
+
+
+"""Python API wrapper for the DataCite API."""
+
+from .client import DataCiteMDSClient
+from .rest_client import DataCiteRESTClient
+
+__version__ = "1.4.1"
+
+__all__ = ("DataCiteMDSClient", "DataCiteRESTClient", "__version__")

datacite/client.py

@@ -0,0 +1,183 @@
+# SPDX-FileCopyrightText: 2015 CERN.
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Python API client wrapper for the DataCite Metadata Store API.
+
+API documentation is available at
+https://support.datacite.org/docs/mds-api-guide.
+"""
+
+import requests
+
+from .errors import DataCiteError
+from .request import DataCiteRequest
+
+HTTP_OK = requests.codes["ok"]
+HTTP_CREATED = requests.codes["created"]
+
+
+class DataCiteMDSClient(object):
+    """DataCite MDS API client wrapper.
+
+    Warning: The DataCite MDS API is being maintained but is no longer actively
+    developed.
+    """
+
+    def __init__(
+        self, username, password, prefix, test_mode=False, url=None, timeout=None
+    ):
+        """Initialize the API client wrapper.
+
+        :param username: DataCite username.
+        :param password: DataCite password.
+        :param prefix: DOI prefix (or CFG_DATACITE_DOI_PREFIX).
+        :param test_mode: use test URL when True
+        :param url: DataCite API base URL.
+        :param timeout: Connect and read timeout in seconds. Specify a tuple
+            (connect, read) to specify each timeout individually.
+        """
+        self.username = username
+        self.password = password
+        self.prefix = prefix
+
+        if test_mode:
+            self.api_url = "https://mds.test.datacite.org/"
+        else:
+            self.api_url = url or "https://mds.datacite.org/"
+
+        if not self.api_url.endswith("/"):
+            self.api_url += "/"
+
+        self.timeout = timeout
+
+    def __repr__(self):
+        """Create string representation of object."""
+        return "<DataCiteMDSClient: {0}>".format(self.username)
+
+    def _create_request(self):
+        """Create a new Request object."""
+        return DataCiteRequest(
+            base_url=self.api_url,
+            username=self.username,
+            password=self.password,
+            timeout=self.timeout,
+        )
+
+    def doi_get(self, doi):
+        """Get the URL where the resource pointed by the DOI is located.
+
+        :param doi: DOI name of the resource.
+        """
+        request = self._create_request()
+        resp = request.get("doi/" + doi)
+        if resp.status_code == HTTP_OK:
+            return resp.text
+        else:
+            raise DataCiteError.factory(resp.status_code, resp.text)
+
+    def doi_post(self, new_doi, location):
+        """Mint new DOI.
+
+        :param new_doi: DOI name for the new resource.
+        :param location: URL where the resource is located.
+        :return: "CREATED" or "HANDLE_ALREADY_EXISTS".
+        """
+        headers = {"Content-Type": "text/plain;charset=UTF-8"}
+        # Use \r\n for HTTP client data.
+        body = "\r\n".join(["doi=%s" % new_doi, "url=%s" % location])
+
+        request = self._create_request()
+        resp = request.post("doi", body=body, headers=headers)
+
+        if resp.status_code == HTTP_CREATED:
+            return resp.text
+        else:
+            raise DataCiteError.factory(resp.status_code, resp.text)
+
+    def metadata_get(self, doi):
+        """Get the XML metadata associated to a DOI name.
+
+        :param doi: DOI name of the resource.
+        """
+        headers = {"Accept": "application/xml", "Accept-Encoding": "UTF-8"}
+
+        request = self._create_request()
+        resp = request.get("metadata/" + doi, headers=headers)
+
+        if resp.status_code == HTTP_OK:
+            return resp.text
+        else:
+            raise DataCiteError.factory(resp.status_code, resp.text)
+
+    def metadata_post(self, metadata):
+        """Set new metadata for an existing DOI.
+
+        Metadata should follow the DataCite Metadata Schema:
+        http://schema.datacite.org/
+
+        :param metadata: XML format of the metadata.
+        :return: "CREATED" or "HANDLE_ALREADY_EXISTS"
+        """
+        headers = {
+            "Content-Type": "application/xml;charset=UTF-8",
+        }
+
+        request = self._create_request()
+        resp = request.post("metadata", body=metadata, headers=headers)
+
+        if resp.status_code == HTTP_CREATED:
+            return resp.text
+        else:
+            raise DataCiteError.factory(resp.status_code, resp.text)
+
+    def metadata_delete(self, doi):
+        """Mark as 'inactive' the metadata set of a DOI resource.
+
+        :param doi: DOI name of the resource.
+        :return: "OK"
+        """
+        request = self._create_request()
+        resp = request.delete("metadata/" + doi)
+
+        if resp.status_code == HTTP_OK:
+            return resp.text
+        else:
+            raise DataCiteError.factory(resp.status_code, resp.text)
+
+    def media_get(self, doi):
+        """Get list of pairs of media type and URLs associated with a DOI.
+
+        :param doi: DOI name of the resource.
+        """
+        request = self._create_request()
+        resp = request.get("media/" + doi)
+
+        if resp.status_code == HTTP_OK:
+            values = {}
+            for line in resp.text.splitlines():
+                mimetype, url = line.split("=", 1)
+                values[mimetype] = url
+            return values
+        else:
+            raise DataCiteError.factory(resp.status_code, resp.text)
+
+    def media_post(self, doi, media):
+        """Add/update media type/urls pairs to a DOI.
+
+        Standard domain restrictions check will be performed.
+
+        :param media: Dictionary of (mime-type, URL) key/value pairs.
+        :return: "OK"
+        """
+        headers = {"Content-Type": "text/plain;charset=UTF-8"}
+
+        # Use \r\n for HTTP client data.
+        body = "\r\n".join(["%s=%s" % (k, v) for k, v in media.items()])
+
+        request = self._create_request()
+        resp = request.post("media/" + doi, body=body, headers=headers)
+
+        if resp.status_code == HTTP_OK:
+            return resp.text
+        else:
+            raise DataCiteError.factory(resp.status_code, resp.text)

datacite/errors.py

@@ -0,0 +1,99 @@
+# SPDX-FileCopyrightText: 2015 CERN.
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Errors for the DataCite API.
+
+MDS error responses will be converted into an exception from this module.
+Connection issues raises :py:exc:`datacite.errors.HttpError` while DataCite
+MDS error responses raises a subclass of
+:py:exc:`datacite.errors.DataCiteError`.
+"""
+
+
+class HttpError(Exception):
+    """Exception raised when a connection problem happens."""
+
+
+class DataCiteError(Exception):
+    """Exception raised when the server returns a known HTTP error code.
+
+    Known HTTP error codes include:
+
+    * 204 No Content
+    * 400 Bad Request
+    * 401 Unauthorized
+    * 403 Forbidden
+    * 404 Not Found
+    * 410 Gone (deleted)
+    """
+
+    @staticmethod
+    def factory(err_code, *args):
+        """Create exceptions through a Factory based on the HTTP error code."""
+        if err_code == 204:
+            return DataCiteNoContentError(*args)
+        elif err_code == 400:
+            return DataCiteBadRequestError(*args)
+        elif err_code == 401:
+            return DataCiteUnauthorizedError(*args)
+        elif err_code == 403:
+            return DataCiteForbiddenError(*args)
+        elif err_code == 404:
+            return DataCiteNotFoundError(*args)
+        elif err_code == 410:
+            return DataCiteGoneError(*args)
+        elif err_code == 412:
+            return DataCitePreconditionError(*args)
+        else:
+            return DataCiteServerError(*args)
+
+
+class DataCiteServerError(DataCiteError):
+    """An internal server error happened on the DataCite end. Try later.
+
+    Base class for all 5XX-related HTTP error codes.
+    """
+
+
+class DataCiteRequestError(DataCiteError):
+    """A DataCite request error. You made an invalid request.
+
+    Base class for all 4XX-related HTTP error codes as well as 204.
+    """
+
+
+class DataCiteNoContentError(DataCiteRequestError):
+    """DOI is known to MDS, but not resolvable.
+
+    This might be due to handle's latency.
+    """
+
+
+class DataCiteBadRequestError(DataCiteRequestError):
+    """Bad request error.
+
+    Bad requests can include e.g. invalid XML, wrong domain, wrong prefix.
+    Request body must be exactly two lines: DOI and URL
+    One or more of the specified mime-types or urls are invalid (e.g. non
+    supported mimetype, not allowed url domain, etc.)
+    """
+
+
+class DataCiteUnauthorizedError(DataCiteRequestError):
+    """Bad username or password."""
+
+
+class DataCiteForbiddenError(DataCiteRequestError):
+    """Login problem, dataset belongs to another party or quota exceeded."""
+
+
+class DataCiteNotFoundError(DataCiteRequestError):
+    """DOI does not exist in the database."""
+
+
+class DataCiteGoneError(DataCiteRequestError):
+    """Requested dataset was marked inactive (using DELETE method)."""
+
+
+class DataCitePreconditionError(DataCiteRequestError):
+    """Metadata must be uploaded first."""

datacite/jsonutils.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2016 CERN.
+# SPDX-FileCopyrightText: 2025 Graz University of Technology.
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""JSON utilities."""
+
+import json
+
+from jsonresolver.contrib.jsonschema import RefResolverBase
+from jsonschema.validators import validator_for
+
+
+def validator_factory(schema_filename):
+    """Provide a JSON schema validator for a given schema file."""
+    with open(schema_filename, "r") as fp:
+        schema = json.load(fp)
+
+    validator_cls = validator_for(schema)
+    validator_cls.check_schema(schema)
+
+    return validator_cls(
+        schema, resolver=RefResolverBase("file:{}".format(schema_filename), schema)
+    )

datacite/request.py

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: 2015-2018 CERN.
+# SPDX-FileCopyrightText: 2018 Center for Open Science.
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Module for making requests to the DataCite API."""
+
+import ssl
+
+import requests
+from requests.auth import HTTPBasicAuth
+from requests.exceptions import RequestException
+
+from .errors import HttpError
+
+
+class DataCiteRequest(object):
+    """Helper class for making requests.
+
+    :param base_url: Base URL for all requests.
+    :param username: HTTP Basic Authentication Username
+    :param password: HTTP Basic Authentication Password
+    :param default_params: A key/value-mapping which will be converted into a
+        query string on all requests.
+    :param timeout: Connect and read timeout in seconds. Specify a tuple
+        (connect, read) to specify each timeout individually.
+    """
+
+    def __init__(
+        self,
+        base_url=None,
+        username=None,
+        password=None,
+        default_params=None,
+        timeout=None,
+    ):
+        """Initialize request object."""
+        self.base_url = base_url
+        self.username = username
+        self.password = password.encode("utf8")
+        self.default_params = default_params or {}
+        self.timeout = timeout
+
+    def request(self, url, method="GET", body=None, params=None, headers=None):
+        """Make a request.
+
+        If the request was successful (i.e no exceptions), you can find the
+        HTTP response code in self.code and the response body in self.value.
+
+        :param url: Request URL (relative to base_url if set)
+        :param method: Request method (GET, POST, DELETE) supported
+        :param body: Request body
+        :param params: Request parameters
+        :param headers: Request headers
+        """
+        params = params or {}
+        headers = headers or {}
+
+        self.data = None
+        self.code = None
+
+        if self.default_params:
+            params.update(self.default_params)
+
+        if self.base_url:
+            url = self.base_url + url
+
+        if body and isinstance(body, str):
+            body = body.encode("utf-8")
+
+        request_func = getattr(requests, method.lower())
+        kwargs = dict(
+            auth=HTTPBasicAuth(self.username, self.password),
+            params=params,
+            headers=headers,
+        )
+
+        if method == "POST":
+            kwargs["data"] = body
+        if method == "PUT":
+            kwargs["data"] = body
+        if self.timeout is not None:
+            kwargs["timeout"] = self.timeout
+
+        try:
+            return request_func(url, **kwargs)
+        except RequestException as e:
+            raise HttpError(e)
+        except ssl.SSLError as e:
+            raise HttpError(e)
+
+    def get(self, url, params=None, headers=None):
+        """Make a GET request."""
+        return self.request(url, params=params, headers=headers)
+
+    def post(self, url, body=None, params=None, headers=None):
+        """Make a POST request."""
+        return self.request(
+            url, method="POST", body=body, params=params, headers=headers
+        )
+
+    def put(self, url, body=None, params=None, headers=None):
+        """Make a PUT request."""
+        return self.request(
+            url, method="PUT", body=body, params=params, headers=headers
+        )
+
+    def delete(self, url, params=None, headers=None):
+        """Make a DELETE request."""
+        return self.request(url, method="DELETE", params=params, headers=headers)