api module

This module implement low level classes to access Zenodo API. The only class intended to users use is APIResponseError, that can be used to capture errors from API requests.

Examples

Make sure to run the examples in Zenodo’s sandbox:

from zen import Zenodo
# Create an instance of Zenodo with a base URL and token
zen = Zenodo(url=Zenodo.sandbox_url, token='your_access_token')

# List all depositions of the authenticated user
deps = zen.depositions.list(sort="bestmatch", size=10)

# Retrieve the first deposition
dep = zen.depositions.retrieve(deps[0].id)

Note

• Before using this submodule, make sure you have a valid Zenodo account and access token.

• Always refer to the Zenodo API documentation for detailed information about available endpoints and parameters.

• For more information, visit: https://developers.zenodo.org/

exception zen.api.APIResponseError(response: Response)

Bases: Exception

Exception for Zenodo API response errors.

This class encapsulates API response errors and provides a structured way to handle them.

Parameters:

response (Response) – The response object received from the API.

Examples

>>> from zen import Zenodo
>>> from zen.api import APIResponseError

1. Create an instance of Zenodo with a base URL and token

>>> zen = Zenodo(url=Zenodo.sandbox_url, token='wrong_token')

2. Catch APIResponseError

>>> # Will generate an error - Wrong token
>>> try:
...     zen.depositions.list()
... except APIResponseError as e:
...     print('Invalid operation')
Invalid operation

bad_status_codes = {400: {'description': 'Request failed.', 'name': 'Bad Request'}, 401: {'description': 'Request failed, due to an invalid access token.', 'name': 'Unauthorized'}, 403: {'description': 'Request failed, due to missing authorization (e.g. deleting an already submitted upload or missing scopes for your access token).', 'name': 'Forbidden'}, 404: {'description': 'Request failed, due to the resource not being found.', 'name': 'Not Found'}, 405: {'description': 'Request failed, due to unsupported HTTP method.', 'name': 'Method Not Allowed'}, 409: {'description': 'Request failed, due to the current state of the resource (e.g. edit a deposition which is not fully integrated).', 'name': 'Conflict'}, 415: {'description': 'Request failed, due to missing or invalid request header Content-Type.', 'name': 'Unsupported Media Type'}, 422: {'description': 'Resumption tokens are only valid for 2 minutes.', 'name': 'Unprocessable Entity'}, 429: {'description': 'Request failed, due to rate limiting.', 'name': 'Too Many Requests'}, 500: {'description': 'Request failed, due to an internal server error.', 'name': 'Internal Server Error'}}

get_respose_description(response: Response) → str

Returns the description of the error based on the response object.

Parameters:

response (Response) – The response object received from the API.

Returns:

The description of the error.

Return type:

str

class zen.api.APIZenodo(base_url: str, token: str | None = None, params: Dict[str, str] | None = None, headers: Dict[str, str] | None = None)

Bases: object

Interact with Zenodo API.

This class provides methods to interact with various aspects of the Zenodo API, such as licenses, records, depositions, and more.

Parameters:

• base_url (str) – The base URL of the Zenodo API.

• token (Optional[str]=None) – The access token for authorization.

• params (Optional[Dict[str,str]]=None) – Additional params to be included in the API requests.

• headers (Optional[Dict[str,str]]=None) – Additional headers to be included in the API requests.

checksum_deposition_file(file_id: str | Dict, **kwargs) → str

Retrieves the checksum of a specific file of a deposition from the Zenodo API.

Parameters:

• file_id (Union[str,Dict]) – The ID of the file to retrieve the checksum for, or a dictionary containing the file information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The checksum of the file.

Return type:

str

Raises:

APIResponseError – If the response status code indicates an error during the API request.

create_deposition(metadata: Dict[str, Any] | None = None, **kwargs) → Dict

Creates a new deposition on the Zenodo API.

Parameters:

• metadata (Optional[Dict[str,Any]]=None) – The metadata for the new deposition.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the newly created deposition.

Return type:

dict

Raises:

• ValueError – If the metadata parameter is not a dictionary.

• APIResponseError – If the response status code indicates an error during the API request.

create_deposition_file(deposition_id: int | Dict, filename: str, bucket_filename: str | None = None, progress: bool = True, **kwargs) → Dict

Creates a new file for a specific deposition on the Zenodo API.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition to create the file for, or a dictionary containing the deposition information.

• filename (str) – The local file path of the file to upload.

• bucket_filename (str or None) – The desired filename for the file in the deposition’s bucket.

• progress (bool) – Show a progress bar to track the upload?

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the newly created file.

Return type:

dict

Raises:

• ValueError – If the specified file does not exist.

• APIResponseError – If the response status code indicates an error during the API request.

delete_deposition(deposition_id: int | Dict, **kwargs) → None

Deletes a specific deposition from the Zenodo API.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition to delete, or a dictionary containing the deposition information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

None

Raises:

APIResponseError – If the response status code indicates an error during the API request.

delete_deposition_file(file_id: str | Dict, **kwargs) → None

Deletes a specific file of a deposition from the Zenodo API.

Parameters:

• file_id (Union[str,Dict]) – The ID of the file to delete, or a dictionary containing the file information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

None

Raises:

APIResponseError – If the response status code indicates an error during the API request.

discard_deposition(deposition_id: int | Dict, **kwargs) → Dict

Discards changes of a specific deposition on the Zenodo API.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition to discard changes, or a dictionary containing the deposition information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the deposition with the discarded changes.

Return type:

dict

Raises:

APIResponseError – If the response status code indicates an error during the API request.

edit_deposition(deposition_id: int | Dict, **kwargs) → Dict

Sets a specific deposition to the “edit” state on the Zenodo API.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition to set to “edit”, or a dictionary containing the deposition information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the edited deposition.

Return type:

dict

Raises:

APIResponseError – If the response status code indicates an error during the API request.

get_deposition_bucket(deposition_id: int | Dict) → str

Retrieves the bucket URL for a specific deposition on the Zenodo API.

Parameters:

deposition_id (Union[int,Dict]) – The ID of the deposition, or a dictionary containing the deposition information.

Returns:

The URL of the deposition’s bucket.

Return type:

str

Raises:

APIResponseError – If the response status code indicates an error during the API request.

iter_pagination(data: Dict[str, Any], limit: int | None = None, **kwargs) → Iterator[Dict[str, Any]]

Iterates over paginated data from the Zenodo API.

Parameters:

• data (Dict[str,Any]) – The initial page of data from the API response.

• limit (Optional[int]=None) – The maximum number of pages to retrieve.

• **kwargs – Additional keyword arguments for the API request.

Returns:

An iterator that yields each page of data.

Return type:

Iterator[Dict[str,Any]]

Raises:

APIResponseError – If the response status code indicates an error during the API request.

list_deposition_files(deposition_id: int | Dict, **kwargs) → Dict

Retrieves a list of files for a specific deposition from the Zenodo API.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition, or a dictionary containing the deposition information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the list of files.

Return type:

dict

Raises:

APIResponseError – If the response status code indicates an error during the API request.

list_depositions(query_args: Dict[str, Any] | None = None, **kwargs) → Dict

Retrieves a list of depositions from the Zenodo API.

Parameters:

• query_args (Optional[Dict[str,Any]]=None) – Additional query arguments for the API request.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the list of depositions.

Return type:

dict

Raises:

• TypeError – If the query_args parameter is not a dictionary.

• APIResponseError – If the response status code indicates an error during the API request.

list_licenses(query_args: Dict[str, Any] | None = None, **kwargs) → Dict

Retrieves a list of licenses entries.

Parameters:

• query_args (Optional[Dict[str,Any]]=None) – Additional query arguments for the API request.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the list of licenses entries.

Return type:

dict

Raises:

• TypeError – If the query_args parameter is not a dictionary.

• APIResponseError – If the response status code indicates an error during the API request.

list_records(query_args: Dict[str, Any] | None = None, **kwargs) → Dict

Retrieves a list of records from the Zenodo API.

Parameters:

• query_args (Optional[Dict[str,Any]]=None) – Additional query arguments for the API request.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the list of records.

Return type:

dict

Raises:

• TypeError – If the query_args parameter is not a dictionary.

• APIResponseError – If the response status code indicates an error during the API request.

new_version_deposition(deposition_id: int | Dict, **kwargs) → Dict

Creates a new version of a specific deposition on the Zenodo API. Unlike Zenodo API, this function returns the new version of the deposition.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition to create a new version of, or a dictionary containing the deposition information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the newly created version of the deposition.

Return type:

dict

Raises:

APIResponseError – If the response status code indicates an error during the API request.

publish_deposition(deposition_id: int | Dict, **kwargs) → Dict

Publishes a specific deposition on the Zenodo API.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition to publish, or a dictionary containing the deposition information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the published deposition.

Return type:

dict

Raises:

APIResponseError – If the response status code indicates an error during the API request.

property request: _APIRequest

retrieve_deposition(deposition_id: int | Dict, **kwargs) → Dict

Retrieves a specific deposition from the Zenodo API.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition to retrieve, or a dictionary containing the deposition information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the deposition information.

Return type:

dict

Raises:

APIResponseError – If the response status code indicates an error during the API request.

retrieve_deposition_file(file_id: str | Dict, **kwargs) → Dict

Retrieves a specific file of a deposition from the Zenodo API.

Parameters:

• file_id (Union[str,Dict]) – The ID of the file to retrieve, or a dictionary containing the file information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the file information.

Return type:

dict

Raises:

APIResponseError – If the response status code indicates an error during the API request.

retrieve_license(license_id: str, **kwargs) → Dict

Retrieves a specific license entry from the Zenodo API.

Parameters:

• license_id (str) – The ID of the license to retrieve.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the license entry information.

Return type:

dict

Raises:

APIResponseError – If the response status code indicates an error during the API request.

retrieve_record(record_id: int | Dict, **kwargs) → Dict

Retrieves a specific record from the Zenodo API.

Parameters:

• record_id (Union[int,Dict]) – The ID of the record to retrieve, or a dictionary containing the record information.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the record information.

Return type:

dict

Raises:

APIResponseError – If the response status code indicates an error during the API request.

sort_deposition_files(deposition_id: int | Dict, file_id_list: List[str | Dict], **kwargs) → Dict

Sorts the files of a specific deposition on the Zenodo API.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition to sort the files for, or a dictionary containing the deposition information.

• file_id_list (list) – The list of file IDs in the desired order.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the sorted deposition files.

Return type:

dict

Raises:

• ValueError – If the file_id_list parameter is not a list.

• APIResponseError – If the response status code indicates an error during the API request.

update_deposition(deposition_id: int | Dict, metadata: Dict[str, Any], **kwargs) → Dict

Updates a specific deposition on the Zenodo API.

Parameters:

• deposition_id (Union[int,Dict]) – The ID of the deposition to update, or a dictionary containing the deposition information.

• metadata (Dict[str,Any]) – The updated metadata for the deposition.

• **kwargs – Additional keyword arguments for the API request.

Returns:

The response JSON containing the updated deposition.

Return type:

dict

Raises:

• ValueError – If the metadata parameter is not a dictionary.

• APIResponseError – If the response status code indicates an error during the API request.

url_token(url: str, **kwargs) → str

Returns a provided base url with the Zenodo API token as a query string parameter.

Parameters:

• url (str) – The URL to send the GET request to.

• **kwargs – Additional keyword arguments for the GET request.

Returns:

The URL with ‘access_token=<token>’ parameter in the query string.

Return type:

str

class zen.api.Depositions(api: Zenodo)

Bases: object

Managing depositions on the Zenodo API.

The Depositions class simplifies interactions with the Zenodo API. It is utilized to give an intuitive way to explore Zenodo API depositions, making it easier to retrieve, filter, and work with deposition data.

It is used by the Zenodo class to perform various Zenodo API operations, such as listing depositions, retrieving specific depositions, and facilitating advanced searches based on different criteria.

Parameters:

api (Zenodo) – The Zenodo instance used to interact with Zenodo API.

Examples

1. Accessing the instance of the Deposition class:

>>> from zen import Zenodo
>>> zen = Zenodo(url=Zenodo.sandbox_url, api_token='your_api_token')
>>> zen.depositions  # Instance of class Depositions

2. Retrieving a list of depositions that match a specific query:

>>> zen.depositions.list(q="title:(My title)", sort="bestmatch", size=10)

3. Creating a new deposition on Zenodo:

>>> new_dep = zen.depositions.create()  # Empty metadata

4. Retrieving an existing Zenodo deposition by ID:

>>> existing_dep = zen.depositions.retrieve(new_dep.id)
>>> new_dep.discard()  # Cancel deposition creation

create(metadata: Metadata | Dict[str, Any] | None = None) → Deposition

Creates a new deposition on the Zenodo API.

Parameters:

• local (str) – The path to a JSON file where the local dataset will be stored to or read from.

• metadata (Optional[Union[MetaGeneric,Dict[str,Any]]]=None) – The metadata for the new deposition.

Returns:

A Deposition object representing the newly created deposition.

Return type:

Deposition

Raises:

None –

list(q: str | None = None, status: str | None = None, sort: str | None = None, size: int | None = None, all_versions: bool | None = None) → List[Deposition]

Retrieve a list of depositions from Zenodo.

This method searches depositions associated with current Zenodo account (determined by the Zenodo token). It provides a streamlined way to query and filter depositions based on specific criteria, including search terms, status, sorting options, and the maximum number of depositions to retrieve.

Parameters:

• q (Optional[str]=None) – The Elasticsearch query to filter the depositions.

• status (Optional[str]=None) – The status of the depositions to filter. See status_options attribute for supported options.

• sort (Optional[str]=None) – The field to sort the depositions by. See sort_options attribute for supported options.

• size (Optional[int]=None) – The maximum number of depositions to retrieve.

• all_versions (Optional[bool]=None) – Whether to include all versions of the depositions.

Returns:

A list of Deposition objects representing the retrieved depositions.

Return type:

List[Deposition]

retrieve(deposition: Deposition | Dict[str, Any] | int) → Deposition

Retrieves a specific deposition from the Zenodo API.

Parameters:

deposition (Union[Deposition,Dict[str,Any],int]) – The ID of the deposition to retrieve, or a dictionary containing the deposition information.

Returns:

A Deposition object representing the retrieved deposition.

Return type:

Deposition

sort_options = ['bestmatch', '-bestmatch', 'mostrecent', '-mostrecent']

status_options = ['draft', 'published']

class zen.api.License(data: Dict[str, Any])

Bases: dict

class zen.api.Licenses(api: Zenodo)

Bases: object

Interacting with licenses on the Zenodo API.

The Vocabularies class implements vocabularies endpoint of the Zenodo API. This class is used by the Zenodo class to perform vocabularies queries on Zenodo API.

Parameters:

api (Zenodo) – The Zenodo instance used to interact with Zenodo API.

Examples

1. Accessing the instance of the Licenses class:

>>> from zen import Zenodo
>>> zen = Zenodo(url=Zenodo.sandbox_url, api_token='your_api_token')
>>> zen.vocabularies  # Instance of class Vocabularies

2. Retrieving a list of licenses that match a specific query:

>>> zen.vocabularies.list(type='licenses', q='cc', size=25, page=2)

3. Retrieving a Zenodo license:

>>> zen.vocabularies.retrieve(type='license', id='cc-zero')

list(q: str | None = None, page: int | None = None, size: int | None = None) → LicensesPage

Retrieve a list of licenses from Zenodo.

This method searches licenses registered in Zenodo. It provides a streamlined way to query and filter licenses based on specific criteria, including search terms, and the maximum number of licenses per page, and the page number to retrieve.

Parameters:

• q (Optional[str]=None) – The Elasticsearch query to filter the licenses.

• page (Optional[int]=None) – The page number of pagination.

• size (Optional[int]=None) – The maximum number of licenses to retrieve per page.

Returns:

The first page of the licenses list.

Return type:

LicensesPage

retrieve(license: Dict[str, Any] | int) → License

Retrieves a specific license from the Zenodo API.

Parameters:

license (Union[Deposition,Dict[str,Any],int]) – The ID of the license to retrieve, or a dictionary containing the license information.

Returns:

A License object representing the retrieved license.

Return type:

License

class zen.api.LicensesPage(page: Dict[str, Any], api: Zenodo)

Bases: _PagedData

class zen.api.Zenodo(url: str = 'https://zenodo.org', token: str | None = None, headers: Dict[str, str] | None = None)

Bases: object

Interact with the Zenodo API.

The Zenodo class provides a Python interface for interacting with the Zenodo API, allowing the user to create and manage depositions, access records, and retrieve license information. The class organization resembles the API endpoints, making it easy to work with various Zenodo functionalities:

• depositions property: Access the depositions endpoint. This is represented by Depositions class. Using this instance, users can manage depositions, create new ones, and retrieve existing ones.

• records property: Retrieve detailed information about Zenodo records, making it easy to access, update, and manipulate metadata and content of records.

• licenses property: Access information about licenses available on Zenodo vocabulary.

Parameters:

• url (str) – The base URL of the Zenodo API.

• token (Optional[str]=None) – The access token for making authenticated requests to the Zenodo API.

• headers (Optional[Dict[str,str]]=None) – Additional headers to include in API requests.

Examples

You can use the Zenodo class to interact with the Zenodo API:

1. Initialize Zenodo with your access token:

>>> zen = Zenodo(url=Zenodo.sandbox_url, token='your_access_token')

2. Access the depositions endpoint to list depositions:

>>> deposition_list = zen.depositions.list(status='published')

property api: APIZenodo

The internal API object.

property depositions: Depositions

The depositions endpoint.

property licenses

The licenses endpoint.

max_deposition_files = 100

max_storage_size = 50000000000

property records

The records endpoint.

sandbox_url = 'https://sandbox.zenodo.org'

url = 'https://zenodo.org'