SemanticScholar.py

import warnings
from typing import List

from semanticscholar.ApiRequester import ApiRequester
from semanticscholar.Author import Author
from semanticscholar.PaginatedResults import PaginatedResults
from semanticscholar.Paper import Paper


class SemanticScholar:
    '''
    Main class to retrieve data from Semantic Scholar Graph API
    '''

    DEFAULT_API_URL = 'https://api.semanticscholar.org/graph/v1'
    DEFAULT_PARTNER_API_URL = 'https://partner.semanticscholar.org/graph/v1'

    auth_header = {}

    def __init__(
                self,
                timeout: int = 10,
                api_key: str = None,
                api_url: str = None,
                graph_api: bool = True
            ) -> None:
        '''
        :param float timeout: (optional) an exception is raised
        if the server has not issued a response for timeout seconds.
        :param str api_key: (optional) private API key.
        :param str api_url: (optional) custom API url.
        :param bool graph_api: (optional) whether use new Graph API.
        '''

        if api_url:
            self.api_url = api_url
        else:
            self.api_url = self.DEFAULT_API_URL

        if api_key:
            self.auth_header = {'x-api-key': api_key}
            if not api_url:
                self.api_url = self.DEFAULT_PARTNER_API_URL

        if not graph_api:
            warnings.warn(
                'graph_api parameter is deprecated and will be disabled ' +
                'in the future', DeprecationWarning)
            self.api_url = self.api_url.replace('/graph', '')

        self._timeout = timeout
        self._requester = ApiRequester(self._timeout)

    @property
    def timeout(self) -> int:
        '''
        :type: :class:`int`
        '''
        return self._timeout

    @timeout.setter
    def timeout(self, timeout: int) -> None:
        '''
        :param int timeout:
        '''
        self._timeout = timeout
        self._requester.timeout = timeout

    def get_paper(
                self,
                paper_id: str,
                include_unknown_refs: bool = False,
                fields: list = None
            ) -> Paper:
        '''Paper lookup

        :calls: `GET https://api.semanticscholar.org/graph/v1/paper/{paper_id} \
            <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data/ \
            operation/get_graph_get_paper>`_

        :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, \
               PMID, PMCID, or URL from:

               - semanticscholar.org
               - arxiv.org
               - aclweb.org
               - acm.org
               - biorxiv.org

        :param bool include_unknown_refs: (optional) include non referenced \
               paper.
        :param list fields: (optional) list of the fields to be returned.
        :returns: paper data
        :rtype: :class:`Paper`
        :raises: ObjectNotFoundExeception: if Paper ID not found.
        '''

        if not fields:
            fields = Paper.FIELDS

        url = f'{self.api_url}/paper/{paper_id}'

        fields = ','.join(fields)
        parameters = f'&fields={fields}'
        if include_unknown_refs:
            warnings.warn(
                'include_unknown_refs parameter is deprecated and will be disabled ' +
                'in the future', DeprecationWarning)
            parameters += '&include_unknown_references=true'

        data = self._requester.get_data(url, parameters, self.auth_header)
        paper = Paper(data)

        return paper

    def get_papers(
                self,
                paper_ids: List[str],
                fields: list = None
            ) -> List[Paper]:
        '''Get details for multiple papers at once

        :calls: `POST https://api.semanticscholar.org/graph/v1/paper/batch\
            <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data/\
            operation/post_graph_get_papers>`_

        :param str paper_ids: list of IDs (must be <= 1000) - S2PaperId,\
            CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from:

            - semanticscholar.org
            - arxiv.org
            - aclweb.org
            - acm.org
            - biorxiv.org

        :param list fields: (optional) list of the fields to be returned.
        :returns: papers data
        :rtype: :class:`List` of :class:`Paper`
        :raises: BadQueryParametersException: if no paper was found.
        '''

        if not fields:
            fields = Paper.SEARCH_FIELDS

        url = f'{self.api_url}/paper/batch'

        fields = ','.join(fields)
        parameters = f'&fields={fields}'

        payload = { "ids": paper_ids }

        data = self._requester.get_data(
            url, parameters, self.auth_header, payload)
        papers = [Paper(item) for item in data]

        return papers

    def search_paper(
                self,
                query: str,
                year: str = None,
                fields_of_study: list = None,
                fields: list = None,
                limit: int = 100
            ) -> PaginatedResults:
        '''Search for papers by keyword

        :calls: `GET https://api.semanticscholar.org/graph/v1/paper/search \
            <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data/ \
            operation/get_graph_get_paper_search>`_

        :param str query: plain-text search query string.
        :param str year: restrict results to the given range of \
               publication year.
        :param str fields_of_study: restrict results to given field-of-study, \
               using the s2FieldsOfStudy paper field.
        :param list fields: (optional) list of the fields to be returned.
        :param int limit: (optional) maximum number of results to return \
               (must be <= 100).
        :returns: query results.
        :rtype: :class:`PaginatedResults`
        '''

        if not fields:
            fields = Paper.SEARCH_FIELDS

        url = f'{self.api_url}/paper/search'

        query += f'&year={year}' if year else ''
        if fields_of_study:
            fields_of_study = ','.join(fields_of_study)
            query += f'&fields_of_study={fields_of_study}'

        results = PaginatedResults(
                self._requester,
                Paper,
                url,
                query,
                fields,
                limit,
                self.auth_header
            )

        return results

    def get_author(
                self,
                author_id: str,
                fields: list = None
            ) -> Author:
        '''Author lookup

        :calls: `GET https://api.semanticscholar.org/graph/v1/author/\
            {author_id} <https://api.semanticscholar.org/api-docs/\
            graph#tag/Author-Data/operation/get_graph_get_author>`_

        :param str author_id: S2AuthorId.
        :returns: author data
        :rtype: :class:`Author`
        :raises: ObjectNotFoundExeception: if Author ID not found.
        '''

        if not fields:
            fields = Author.FIELDS

        url = f'{self.api_url}/author/{author_id}'

        fields = ','.join(fields)
        parameters = f'&fields={fields}'

        data = self._requester.get_data(url, parameters, self.auth_header)
        author = Author(data)

        return author

    def get_authors(
                self,
                author_ids: List[str],
                fields: list = None
            ) -> List[Author]:
        '''Get details for multiple authors at once

        :calls: `POST https://api.semanticscholar.org/graph/v1/author/batch\
            <https://api.semanticscholar.org/api-docs/graph#tag/Author-Data/\
            operation/get_graph_get_author>`_

        :param str author_ids: list of S2AuthorId (must be <= 1000).
        :returns: author data
        :rtype: :class:`List` of :class:`Author`
        :raises: BadQueryParametersException: if no author was found.
        '''

        if not fields:
            fields = Author.SEARCH_FIELDS

        url = f'{self.api_url}/author/batch'

        fields = ','.join(fields)
        parameters = f'&fields={fields}'

        payload = { "ids": author_ids }

        data = self._requester.get_data(
            url, parameters, self.auth_header, payload)
        authors = [Author(item) for item in data]

        return authors

    def search_author(
                self,
                query: str,
                fields: list = None,
                limit: int = 1000
            ) -> PaginatedResults:
        '''Search for authors by name

        :calls: `GET https://api.semanticscholar.org/graph/v1/author/search\
            <https://api.semanticscholar.org/api-docs/graph#tag/Author-Data/\
            operation/get_graph_get_author_search>`_

        :param str query: plain-text search query string.
        :param list fields: (optional) list of the fields to be returned.
        :param int limit: (optional) maximum number of results to return \
               (must be <= 1000).
        :returns: query results.
        :rtype: :class:`PaginatedResults`
        '''

        if not fields:
            fields = Author.SEARCH_FIELDS

        url = f'{self.api_url}/author/search'

        results = PaginatedResults(
                self._requester,
                Author,
                url,
                query,
                fields,
                limit,
                self.auth_header
            )

        return results

    def paper(self, paper_id: str, include_unknown_refs: bool = False) -> dict:
        '''Paper lookup

        :calls: `GET https://api.semanticscholar.org/graph/v1/paper/{paper_id} \
            <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data/ \
            operation/get_graph_get_paper>`_

        :param str paper_id: S2PaperId, DOI or ArXivId.
        :param float timeout: an exception is raised \
               if the server has not issued a response for timeout seconds.
        :param bool include_unknown_refs: (optional) include non \
               referenced paper.
        :returns: paper data or empty :class:`dict` if not found.
        :rtype: :class:`dict`

        .. deprecated:: 0.3.0
           Use :func:`get_paper` instead
        '''

        warnings.warn(
            "paper() is deprecated and will be disabled in the future," +
            " use get_paper() instead.",
            DeprecationWarning)

        data = self.get_paper(paper_id, include_unknown_refs)

        return data.raw_data

    def author(self, paper_id: str) -> dict:
        '''Author lookup

        :calls: `GET https://api.semanticscholar.org/graph/v1/author/\
            {author_id} <https://api.semanticscholar.org/api-docs/\
            graph#tag/Author-Data/operation/get_graph_get_author>`_

        :param str paper_id: S2AuthorId.
        :returns: author data or empty :class:`dict` if not found.
        :rtype: :class:`dict`

        .. deprecated:: 0.3.0
           Use :func:`get_author` instead
        '''

        warnings.warn(
            "author() is deprecated and will be disabled in the future," +
            " use get_author() instead.",
            DeprecationWarning)

        data = self.get_author(paper_id)

        return data.raw_data