feat: get details about a paper's references

semanticscholar/BaseReference.py

@@ -0,0 +1,59 @@
+from semanticscholar.Paper import Paper
+from semanticscholar.SemanticScholarObject import SemanticScholarObject
+
+
+class BaseReference(SemanticScholarObject):
+    '''
+    Base class for both Citation and Reference classes.
+    '''
+
+    FIELDS = [
+        'contexts',
+        'intents',
+        'isInfluential'
+    ]
+
+    def __init__(self, data: dict) -> None:
+        super().__init__()
+        self._contexts = None
+        self._intents = None
+        self._isInfluential = None
+        self._paper = None
+        self._init_attributes(data)
+
+    @property
+    def contexts(self) -> list:
+        '''
+        :type: :class:`list`
+        '''
+        return self._contexts
+
+    @property
+    def intents(self) -> list:
+        '''
+        :type: :class:`list`
+        '''
+        return self._intents
+
+    @property
+    def isInfluential(self) -> bool:
+        '''
+        :type: :class:`bool`
+        '''
+        return self._isInfluential
+
+    @property
+    def paper(self) -> Paper:
+        '''
+        :type: :class:`semanticscholar.Paper.Paper`
+        '''
+        return self._paper
+
+    def _init_attributes(self, data: dict) -> None:
+        self._data = data
+        if 'contexts' in data:
+            self._contexts = data['contexts']
+        if 'intents' in data:
+            self._intents = data['intents']
+        if 'isInfluential' in data:
+            self._isInfluential = data['isInfluential']

semanticscholar/PaginatedResults.py

@@ -14,9 +14,9 @@ def __init__(
                 requester: ApiRequester,
                 data_type: Any,
                 url: str,
-                query: str,
-                fields: str,
-                limit: int,
+                query: str = None,
+                fields: str = None,
+                limit: int = None,
                 headers: dict = None
             ) -> None:
 
@@ -84,10 +84,9 @@ def __getitem__(self, key: int) -> Any:
         return self._items[key]
 
     def __has_next_page(self) -> bool:
-        has_any_result = self._total > 0
         has_more_results = (self._offset + self._limit) == self._next
         under_limit = (self._offset + self._limit) < 9999
-        return has_any_result and has_more_results and under_limit
+        return has_more_results and under_limit
 
     def __get_next_page(self) -> list:
 
@@ -100,7 +99,7 @@ def __get_next_page(self) -> list:
             )
 
         self._data = results['data']
-        self._total = results['total']
+        self._total = results['total'] if 'total' in results else 0
         self._offset = results['offset']
         self._next = results['next'] if 'next' in results else 0
 
@@ -114,7 +113,7 @@ def __get_next_page(self) -> list:
 
     def __build_params(self) -> None:
 
-        self._parameters = f'query={self._query}'
+        self._parameters = f'query={self._query}' if self._query else ''
 
         fields = ','.join(self._fields)
         self._parameters += f'&fields={fields}'

semanticscholar/Reference.py

@@ -0,0 +1,13 @@
+from semanticscholar.Paper import Paper
+from semanticscholar.BaseReference import BaseReference
+
+
+class Reference(BaseReference):
+    '''
+    This class abstracts a reference.
+    '''
+
+    def __init__(self, data: dict) -> None:
+        super().__init__(data)
+        if 'citedPaper' in data:
+            self._paper = Paper(data['citedPaper'])

semanticscholar/SemanticScholar.py

@@ -3,8 +3,10 @@
 
 from semanticscholar.ApiRequester import ApiRequester
 from semanticscholar.Author import Author
+from semanticscholar.BaseReference import BaseReference
 from semanticscholar.PaginatedResults import PaginatedResults
 from semanticscholar.Paper import Paper
+from semanticscholar.Reference import Reference
 
 
 class SemanticScholar:
@@ -153,6 +155,51 @@ def get_papers(
 
         return papers
 
+    def get_paper_references(
+                self,
+                paper_id: str,
+                fields: list = None,
+                limit: int = 1000
+            ) -> PaginatedResults:
+        '''Get details about a paper's references
+
+        :calls: `POST /paper/{paper_id}/references \
+            <https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data\
+            /operation/get_graph_get_paper_references>`_
+
+        :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 list fields: (optional) list of the fields to be returned.
+        :param int limit: (optional) maximum number of results to return\
+               (must be <= 1000).
+        '''
+
+        if limit < 1 or limit > 1000:
+            raise ValueError(
+                'The limit parameter must be between 1 and 1000 inclusive.')
+
+        if not fields:
+            fields = BaseReference.FIELDS + Paper.SEARCH_FIELDS
+
+        url = f'{self.api_url}/paper/{paper_id}/references'
+
+        results = PaginatedResults(
+                requester=self._requester,
+                data_type=Reference,
+                url=url,
+                fields=fields,
+                limit=limit
+            )
+
+        return results
+
     def search_paper(
                 self,
                 query: str,

tests/data/Reference.json

@@ -0,0 +1 @@
+{"contexts": ["Other VAElike approaches exist [12, 22] but are less closely related to our method."], "intents": ["result"], "isInfluential": false, "citedPaper": {"paperId": "018300f5f0e679cee5241d9c69c8d88e00e8bf31", "externalIds": {"MAG": "2122262818", "ArXiv": "1402.0030", "DBLP": "conf/icml/MnihG14", "CorpusId": 1981188}, "corpusId": 1981188, "publicationVenue": {"id": "fc0a208c-acb7-47dc-a0d4-af8190e21d29", "name": "International Conference on Machine Learning", "type": "conference", "alternate_names": ["ICML", "Int Conf Mach Learn"], "url": "https://icml.cc/"}, "url": "https://www.semanticscholar.org/paper/018300f5f0e679cee5241d9c69c8d88e00e8bf31", "title": "Neural Variational Inference and Learning in Belief Networks", "abstract": "Highly expressive directed latent variable models, such as sigmoid belief networks, are difficult to train on large datasets because exact inference in them is intractable and none of the approximate inference methods that have been applied to them scale well. We propose a fast non-iterative approximate inference method that uses a feedforward network to implement efficient exact sampling from the variational posterior. The model and this inference network are trained jointly by maximizing a variational lower bound on the log-likelihood. Although the naive estimator of the inference network gradient is too high-variance to be useful, we make it practical by applying several straightforward model-independent variance reduction techniques. Applying our approach to training sigmoid belief networks and deep autoregressive networks, we show that it outperforms the wake-sleep algorithm on MNIST and achieves state-of-the-art results on the Reuters RCV1 document dataset.", "venue": "International Conference on Machine Learning", "year": 2014, "referenceCount": 34, "citationCount": 662, "influentialCitationCount": 89, "isOpenAccess": false, "openAccessPdf": null, "fieldsOfStudy": ["Computer Science", "Mathematics"], "s2FieldsOfStudy": [{"category": "Computer Science", "source": "external"}, {"category": "Mathematics", "source": "external"}, {"category": "Computer Science", "source": "s2-fos-model"}], "publicationTypes": ["JournalArticle", "Conference"], "publicationDate": "2014-01-31", "journal": {"volume": "abs/1402.0030", "name": "ArXiv"}, "authors": [{"authorId": "1714004", "name": "A. Mnih"}, {"authorId": "144717963", "name": "Karol Gregor"}]}}