feat: add support for paper title search (#90)

danielnsilva · danielnsilva · commit 3a3f7974f828 · 2024-07-13T21:55:57.000Z
Resolves: #90
diff --git a/semanticscholar/AsyncSemanticScholar.py b/semanticscholar/AsyncSemanticScholar.py
@@ -397,8 +397,9 @@ async def search_paper(
                 min_citation_count: int = None,
                 limit: int = 100,
                 bulk: bool = False,
-                sort: str = None
-            ) -> PaginatedResults:
+                sort: str = None,
+                match_title: bool = False
+            ) -> Union[PaginatedResults, Paper]:
         '''Search for papers by keyword. Performs a search query based on the \
             S2 search relevance algorithm, or a bulk retrieval of basic paper \
             data without search relevance (if bulk=True). Paper relevance \
@@ -439,8 +440,11 @@ async def search_paper(
                <field>:<order> format, where "field" is either paperId, \
                publicationDate, or citationCount, and "order" is asc \
                (ascending) or desc (descending).
+        :param bool match_title: (optional) retrieve a single paper whose \
+               title best matches the given query.
         :returns: query results.
-        :rtype: :class:`semanticscholar.PaginatedResults.PaginatedResults`
+        :rtype: :class:`semanticscholar.PaginatedResults.PaginatedResults` or \
+            :class:`semanticscholar.Paper.Paper`
         '''
 
         if limit < 1 or limit > 100:
@@ -461,6 +465,12 @@ async def search_paper(
             warnings.warn(
                 'The sort parameter is only used when bulk=True.')
 
+        if match_title:
+            url += '/match'
+            if bulk:
+                raise ValueError(
+                    'The match_title parameter is not allowed when bulk=True.')
+
         query += f'&year={year}' if year else ''
 
         if publication_types:
@@ -504,7 +514,7 @@ async def search_paper(
                 max_results=max_results
             )
 
-        return results
+        return results if not match_title else results[0]
 
     async def get_author(
                 self,
diff --git a/semanticscholar/SemanticScholar.py b/semanticscholar/SemanticScholar.py
@@ -298,8 +298,9 @@ def search_paper(
                 min_citation_count: int = None,
                 limit: int = 100,
                 bulk: bool = False,
-                sort: str = None
-            ) -> PaginatedResults:
+                sort: str = None,
+                match_title: bool = False
+            ) -> Union[PaginatedResults, Paper]:
         '''Search for papers by keyword. Performs a search query based on the \
             S2 search relevance algorithm, or a bulk retrieval of basic paper \
             data without search relevance (if bulk=True). Paper relevance \
@@ -340,8 +341,11 @@ def search_paper(
                <field>:<order> format, where "field" is either paperId, \
                publicationDate, or citationCount, and "order" is asc \
                (ascending) or desc (descending).
+        :param bool match_title: (optional) retrieve a single paper whose \
+               title best matches the given query.
         :returns: query results.
-        :rtype: :class:`semanticscholar.PaginatedResults.PaginatedResults`
+        :rtype: :class:`semanticscholar.PaginatedResults.PaginatedResults` or \
+            :class:`semanticscholar.Paper.Paper`
         '''
 
         loop = asyncio.get_event_loop()
@@ -358,7 +362,8 @@ def search_paper(
                 min_citation_count=min_citation_count,
                 limit=limit,
                 bulk=bulk,
-                sort=sort
+                sort=sort,
+                match_title=match_title
                 )
         )
 
diff --git a/tests/data/test_search_paper_match_title.yaml b/tests/data/test_search_paper_match_title.yaml
@@ -0,0 +1,81 @@
+interactions:
+- request:
+    body: ''
+    headers:
+      accept:
+      - '*/*'
+      accept-encoding:
+      - gzip, deflate
+      connection:
+      - keep-alive
+      host:
+      - api.semanticscholar.org
+      user-agent:
+      - python-httpx/0.27.0
+    method: GET
+    uri: https://api.semanticscholar.org/graph/v1/paper/search/match?query=mining%20association%20rules%20between&fields=abstract,authors,citationCount,citationStyles,corpusId,externalIds,fieldsOfStudy,influentialCitationCount,isOpenAccess,journal,openAccessPdf,paperId,publicationDate,publicationTypes,publicationVenue,referenceCount,s2FieldsOfStudy,title,url,venue,year&offset=0&limit=100
+  response:
+    body:
+      string: '{"data": [{"paperId": "6fe8c5bf8dddaadf10c765133d38dfef5714347f", "externalIds":
+        {"MAG": "2998574808", "DBLP": "conf/sigmod/AgrawalIS93", "DOI": "10.1145/170035.170072",
+        "CorpusId": 490415}, "corpusId": 490415, "publicationVenue": null, "url":
+        "https://www.semanticscholar.org/paper/6fe8c5bf8dddaadf10c765133d38dfef5714347f",
+        "title": "Mining association rules between sets of items in large databases",
+        "abstract": "We are given a large database of customer transactions. Each
+        transaction consists of items purchased by a customer in a visit. We present
+        an efficient algorithm that generates all significant association rules between
+        items in the database. The algorithm incorporates buffer management and novel
+        estimation and pruning techniques. We also present results of applying this
+        algorithm to sales data obtained from a large retailing company, which shows
+        the effectiveness of the algorithm.", "venue": "SIGMOD Conference", "year":
+        1993, "referenceCount": 16, "citationCount": 16127, "influentialCitationCount":
+        1442, "isOpenAccess": true, "openAccessPdf": {"url": "https://dl.acm.org/doi/pdf/10.1145/170036.170072",
+        "status": "BRONZE"}, "fieldsOfStudy": ["Computer Science"], "s2FieldsOfStudy":
+        [{"category": "Computer Science", "source": "external"}, {"category": "Computer
+        Science", "source": "s2-fos-model"}], "publicationTypes": ["JournalArticle",
+        "Book", "Conference"], "publicationDate": "1993-06-01", "journal": {"name":
+        "Proceedings of the 1993 ACM SIGMOD international conference on Management
+        of data"}, "citationStyles": {"bibtex": "@Article{Agrawal1993MiningAR,\n author
+        = {R. Agrawal and T. Imielinski and A. Swami},\n booktitle = {SIGMOD Conference},\n
+        journal = {Proceedings of the 1993 ACM SIGMOD international conference on
+        Management of data},\n title = {Mining association rules between sets of items
+        in large databases},\n year = {1993}\n}\n"}, "authors": [{"authorId": "144947410",
+        "name": "R. Agrawal"}, {"authorId": "1733797", "name": "T. Imielinski"}, {"authorId":
+        "31536502", "name": "A. Swami"}], "matchScore": 109.24948}]}
+
+        '
+    headers:
+      Access-Control-Allow-Origin:
+      - '*'
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '2061'
+      Content-Type:
+      - application/json
+      Date:
+      - Sat, 13 Jul 2024 21:32:29 GMT
+      Via:
+      - 1.1 fb1afad5f0fba8de226916a2cd3f83ca.cloudfront.net (CloudFront)
+      X-Amz-Cf-Id:
+      - TkTBfJ5v8T3RauNr_ArL3gjaNEwKLYLYAcZXicorKKpXJ03i5nVP_w==
+      X-Amz-Cf-Pop:
+      - GRU1-P4
+      X-Cache:
+      - Miss from cloudfront
+      x-amz-apigw-id:
+      - a3rRGG-aPHcEBFQ=
+      x-amzn-Remapped-Connection:
+      - keep-alive
+      x-amzn-Remapped-Content-Length:
+      - '2061'
+      x-amzn-Remapped-Date:
+      - Sat, 13 Jul 2024 21:32:29 GMT
+      x-amzn-Remapped-Server:
+      - gunicorn
+      x-amzn-RequestId:
+      - 98740656-525b-40bc-9d53-4359ddb7ff6d
+    status:
+      code: 200
+      message: OK
+version: 1
diff --git a/tests/data/test_search_paper_match_title_async.yaml b/tests/data/test_search_paper_match_title_async.yaml
@@ -0,0 +1,81 @@
+interactions:
+- request:
+    body: ''
+    headers:
+      accept:
+      - '*/*'
+      accept-encoding:
+      - gzip, deflate
+      connection:
+      - keep-alive
+      host:
+      - api.semanticscholar.org
+      user-agent:
+      - python-httpx/0.27.0
+    method: GET
+    uri: https://api.semanticscholar.org/graph/v1/paper/search/match?query=mining%20association%20rules%20between&fields=abstract,authors,citationCount,citationStyles,corpusId,externalIds,fieldsOfStudy,influentialCitationCount,isOpenAccess,journal,openAccessPdf,paperId,publicationDate,publicationTypes,publicationVenue,referenceCount,s2FieldsOfStudy,title,url,venue,year&offset=0&limit=100
+  response:
+    body:
+      string: '{"data": [{"paperId": "6fe8c5bf8dddaadf10c765133d38dfef5714347f", "externalIds":
+        {"MAG": "2998574808", "DBLP": "conf/sigmod/AgrawalIS93", "DOI": "10.1145/170035.170072",
+        "CorpusId": 490415}, "corpusId": 490415, "publicationVenue": null, "url":
+        "https://www.semanticscholar.org/paper/6fe8c5bf8dddaadf10c765133d38dfef5714347f",
+        "title": "Mining association rules between sets of items in large databases",
+        "abstract": "We are given a large database of customer transactions. Each
+        transaction consists of items purchased by a customer in a visit. We present
+        an efficient algorithm that generates all significant association rules between
+        items in the database. The algorithm incorporates buffer management and novel
+        estimation and pruning techniques. We also present results of applying this
+        algorithm to sales data obtained from a large retailing company, which shows
+        the effectiveness of the algorithm.", "venue": "SIGMOD Conference", "year":
+        1993, "referenceCount": 16, "citationCount": 16127, "influentialCitationCount":
+        1442, "isOpenAccess": true, "openAccessPdf": {"url": "https://dl.acm.org/doi/pdf/10.1145/170036.170072",
+        "status": "BRONZE"}, "fieldsOfStudy": ["Computer Science"], "s2FieldsOfStudy":
+        [{"category": "Computer Science", "source": "external"}, {"category": "Computer
+        Science", "source": "s2-fos-model"}], "publicationTypes": ["JournalArticle",
+        "Book", "Conference"], "publicationDate": "1993-06-01", "journal": {"name":
+        "Proceedings of the 1993 ACM SIGMOD international conference on Management
+        of data"}, "citationStyles": {"bibtex": "@Article{Agrawal1993MiningAR,\n author
+        = {R. Agrawal and T. Imielinski and A. Swami},\n booktitle = {SIGMOD Conference},\n
+        journal = {Proceedings of the 1993 ACM SIGMOD international conference on
+        Management of data},\n title = {Mining association rules between sets of items
+        in large databases},\n year = {1993}\n}\n"}, "authors": [{"authorId": "144947410",
+        "name": "R. Agrawal"}, {"authorId": "1733797", "name": "T. Imielinski"}, {"authorId":
+        "31536502", "name": "A. Swami"}], "matchScore": 109.003174}]}
+
+        '
+    headers:
+      Access-Control-Allow-Origin:
+      - '*'
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '2062'
+      Content-Type:
+      - application/json
+      Date:
+      - Sat, 13 Jul 2024 21:44:41 GMT
+      Via:
+      - 1.1 7d073aa92ff4e68c0fc44a7c7e34e5fc.cloudfront.net (CloudFront)
+      X-Amz-Cf-Id:
+      - u3Dut6TOSHqtN7VWPe4HavgtRmSAs_6Axx2DRSsgVHVpajDaa1dceQ==
+      X-Amz-Cf-Pop:
+      - FOR50-P2
+      X-Cache:
+      - Miss from cloudfront
+      x-amz-apigw-id:
+      - a3tDjFQ0vHcEVyg=
+      x-amzn-Remapped-Connection:
+      - keep-alive
+      x-amzn-Remapped-Content-Length:
+      - '2062'
+      x-amzn-Remapped-Date:
+      - Sat, 13 Jul 2024 21:44:41 GMT
+      x-amzn-Remapped-Server:
+      - gunicorn
+      x-amzn-RequestId:
+      - 1b89b328-6c1f-48a7-963e-ee429d277195
+    status:
+      code: 200
+      message: OK
+version: 1
diff --git a/tests/test_semanticscholar.py b/tests/test_semanticscholar.py
@@ -481,6 +481,18 @@ def test_search_paper_bulk_retrieval_sorted_results_desc(self):
     def test_search_paper_with_relevance_and_sort(self):
         with self.assertWarns(UserWarning):
             self.sch.search_paper('kubernetes', sort='citationCount')
+    
+    @test_vcr.use_cassette
+    def test_search_paper_match_title(self):
+        query = 'mining association rules between'
+        expected_title = ('Mining association rules between sets of items in '
+                          'large databases')
+        paper = self.sch.search_paper(query, match_title=True)
+        self.assertEqual(paper.title, expected_title)
+
+    def test_search_paper_match_title_and_bulk_retrieval(self):
+        with self.assertRaises(ValueError):
+            self.sch.search_paper('test', match_title=True, bulk=True)
 
     @test_vcr.use_cassette
     def test_search_author(self):
@@ -924,6 +936,18 @@ async def test_search_paper_with_relevance_and_sort_async(self):
         with self.assertWarns(UserWarning):
             await self.sch.search_paper('kubernetes', sort='citationCount')
 
+    @test_vcr.use_cassette
+    async def test_search_paper_match_title_async(self):
+        query = 'mining association rules between'
+        expected_title = ('Mining association rules between sets of items in '
+                          'large databases')
+        paper = await self.sch.search_paper(query, match_title=True)
+        self.assertEqual(paper.title, expected_title)
+
+    async def test_search_paper_match_title_and_bulk_retrieval_async(self):
+        with self.assertRaises(ValueError):
+            await self.sch.search_paper('test', match_title=True, bulk=True)
+
     @test_vcr.use_cassette
     async def test_search_author_async(self):
         data = await self.sch.search_author('turing')
