From 3ef890b58c7a603a688d7d8534fa2d33f2f1236b Mon Sep 17 00:00:00 2001 From: Daniel Silva Date: Sun, 1 Dec 2024 15:59:35 +0000 Subject: [PATCH] docs(docstrings): remove backslashes to fix formatting issues --- semanticscholar/ApiRequester.py | 7 +- semanticscholar/AsyncSemanticScholar.py | 154 +++++++++++++----------- semanticscholar/SemanticScholar.py | 154 +++++++++++++----------- 3 files changed, 170 insertions(+), 145 deletions(-) diff --git a/semanticscholar/ApiRequester.py b/semanticscholar/ApiRequester.py index 6b3d3a7..c47027c 100644 --- a/semanticscholar/ApiRequester.py +++ b/semanticscholar/ApiRequester.py @@ -19,8 +19,8 @@ class ApiRequester: def __init__(self, timeout, retry: bool = True) -> None: ''' - :param float timeout: an exception is raised \ - if the server has not issued a response for timeout seconds. + :param float timeout: an exception is raised + if the server has not issued a response for timeout seconds. :param bool retry: enable retry mode. ''' self.timeout = timeout @@ -76,7 +76,8 @@ async def get_data_async( headers: dict, payload: dict = None ) -> Union[dict, List[dict]]: - '''Get data from Semantic Scholar API + ''' + Get data from Semantic Scholar API :param str url: absolute URL to API endpoint. :param str parameters: the parameters to add in the URL. diff --git a/semanticscholar/AsyncSemanticScholar.py b/semanticscholar/AsyncSemanticScholar.py index 6892281..e94ef51 100644 --- a/semanticscholar/AsyncSemanticScholar.py +++ b/semanticscholar/AsyncSemanticScholar.py @@ -35,8 +35,8 @@ def __init__( retry: bool = True, ) -> None: ''' - :param float timeout: (optional) an exception is raised\ - if the server has not issued a response for timeout seconds. + :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 debug: (optional) enable debug mode. @@ -124,13 +124,14 @@ async def get_paper( paper_id: str, fields: list = None ) -> Paper: - '''Paper lookup + ''' + Paper lookup :calls: `GET /graph/v1/paper/{paper_id} \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, \ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -165,13 +166,14 @@ async def get_papers( fields: list = None, return_not_found: bool = False ) -> Union[List[Paper], Tuple[List[Paper], List[str]]]: - '''Get details for multiple papers at once + ''' + Get details for multiple papers at once :calls: `POST /graph/v1/paper/batch \ `_ - :param str paper_ids: list of IDs (must be <= 500) - S2PaperId,\ + :param str paper_ids: list of IDs (must be <= 500) - S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -181,13 +183,13 @@ async def get_papers( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param bool return_not_found: (optional) flag to include not found IDs\ - in the return, except for IDs in URL: format. + :param bool return_not_found: (optional) flag to include not found IDs + in the return, except for IDs in URL: format. :returns: papers data, and optionally list of IDs not found. - :rtype: :class:`List` of :class:`semanticscholar.Paper.Paper`\ - or :class:`Tuple` [:class:`List` of\ - :class:`semanticscholar.Paper.Paper`,\ - :class:`List` of :class:`str`] + :rtype: :class:`List` of :class:`semanticscholar.Paper.Paper` + or :class:`Tuple` [:class:`List` of + :class:`semanticscholar.Paper.Paper`, + :class:`List` of :class:`str`] :raises: BadQueryParametersException: if no paper was found. ''' @@ -251,13 +253,14 @@ async def get_paper_authors( fields: list = None, limit: int = 100 ) -> PaginatedResults: - '''Get details about a paper's authors + ''' + Get details about a paper's authors :calls: `POST /graph/v1/paper/{paper_id}/authors \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -267,7 +270,7 @@ async def get_paper_authors( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of results to return\ + :param int limit: (optional) maximum number of results to return (must be <= 1000). ''' @@ -298,13 +301,14 @@ async def get_paper_citations( fields: list = None, limit: int = 100 ) -> PaginatedResults: - '''Get details about a paper's citations + ''' + Get details about a paper's citations :calls: `POST /graph/v1/paper/{paper_id}/citations \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -314,7 +318,7 @@ async def get_paper_citations( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of results to return\ + :param int limit: (optional) maximum number of results to return (must be <= 1000). ''' @@ -344,13 +348,14 @@ async def get_paper_references( fields: list = None, limit: int = 100 ) -> PaginatedResults: - '''Get details about a paper's references + ''' + Get details about a paper's references :calls: `POST /graph/v1/paper/{paper_id}/references \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -360,7 +365,7 @@ async def get_paper_references( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of results to return\ + :param int limit: (optional) maximum number of results to return (must be <= 1000). ''' @@ -400,50 +405,51 @@ async def search_paper( 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 \ - search is the default behavior and returns up to 1,000 results. \ - Bulk retrieval instead returns up to 10,000,000 results (1,000 \ - in each page). + ''' + 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 + search is the default behavior and returns up to 1,000 results. + Bulk retrieval instead returns up to 10,000,000 results (1,000 + in each page). :calls: `GET /graph/v1/paper/search \ - `_ + `_ :calls: `GET /graph/v1/paper/search/bulk \ - `_ + `_ :param str query: plain-text search query string. - :param str year: (optional) restrict results to the given range of \ + :param str year: (optional) restrict results to the given range of publication year. - :param list publication_type: (optional) restrict results to the given \ + :param list publication_type: (optional) restrict results to the given publication type list. - :param bool open_access_pdf: (optional) restrict results to papers \ + :param bool open_access_pdf: (optional) restrict results to papers with public PDFs. :param list venue: (optional) restrict results to the given venue list. - :param list fields_of_study: (optional) restrict results to given \ + :param list fields_of_study: (optional) restrict results to given field-of-study list, using the s2FieldsOfStudy paper field. :param list fields: (optional) list of the fields to be returned. - :param str publication_date_or_year: (optional) restrict results to \ - the given range of publication date in the format \ - :, where dates are in the format \ + :param str publication_date_or_year: (optional) restrict results to + the given range of publication date in the format + :, where dates are in the format YYYY-MM-DD, YYYY-MM, or YYYY. - :param int min_citation_count: (optional) restrict results to papers \ + :param int min_citation_count: (optional) restrict results to papers with at least the given number of citations. - :param int limit: (optional) maximum number of results to return \ + :param int limit: (optional) maximum number of results to return (must be <= 100). - :param bool bulk: (optional) bulk retrieval of basic paper data \ - without search relevance (ignores the limit parameter if True \ + :param bool bulk: (optional) bulk retrieval of basic paper data + without search relevance (ignores the limit parameter if True and returns up to 1,000 results in each page). - :param str sort: (optional) sorts results (only if bulk=True) using \ - : format, where "field" is either paperId, \ - publicationDate, or citationCount, and "order" is asc \ + :param str sort: (optional) sorts results (only if bulk=True) using + : 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 \ + :param bool match_title: (optional) retrieve a single paper whose title best matches the given query. :returns: query results. - :rtype: :class:`semanticscholar.PaginatedResults.PaginatedResults` or \ + :rtype: :class:`semanticscholar.PaginatedResults.PaginatedResults` or :class:`semanticscholar.Paper.Paper` ''' @@ -521,7 +527,8 @@ async def get_author( author_id: str, fields: list = None ) -> Author: - '''Author lookup + ''' + Author lookup :calls: `GET /graph/v1/author/{author_id} \ Union[List[Author], Tuple[List[Author], List[str]]]: - '''Get details for multiple authors at once + ''' + Get details for multiple authors at once :calls: `POST /graph/v1/author/batch \ PaginatedResults: - '''Get details about a author's papers + ''' + Get details about a author's papers :calls: `POST /graph/v1/paper/{author_id}/papers \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -617,7 +626,7 @@ async def get_author_papers( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of results to return\ + :param int limit: (optional) maximum number of results to return (must be <= 1000). ''' @@ -647,7 +656,8 @@ async def search_author( fields: list = None, limit: int = 100 ) -> PaginatedResults: - '''Search for authors by name + ''' + Search for authors by name :calls: `GET /graph/v1/author/search \ List[Paper]: - '''Get recommended papers for a single positive example. + ''' + Get recommended papers for a single positive example. :calls: `GET /recommendations/v1/papers/forpaper/{paper_id} \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -707,10 +718,10 @@ async def get_recommended_papers( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of recommendations to \ - return (must be <= 500). - :param str pool_from: (optional) which pool of papers to recommend \ - from. Must be either "recent" or "all-cs". + :param int limit: (optional) maximum number of recommendations to + return (must be <= 500). + :param str pool_from: (optional) which pool of papers to recommend + from. Must be either "recent" or "all-cs". :returns: list of recommendations. :rtype: :class:`List` of :class:`semanticscholar.Paper.Paper` ''' @@ -744,19 +755,20 @@ async def get_recommended_papers_from_lists( fields: list = None, limit: int = 100 ) -> List[Paper]: - '''Get recommended papers for lists of positive and negative examples. + ''' + Get recommended papers for lists of positive and negative examples. :calls: `POST /recommendations/v1/papers/ \ `_ - :param list positive_paper_ids: list of paper IDs \ - that the returned papers should be related to. - :param list negative_paper_ids: (optional) list of paper IDs \ - that the returned papers should not be related to. + :param list positive_paper_ids: list of paper IDs + that the returned papers should be related to. + :param list negative_paper_ids: (optional) list of paper IDs + that the returned papers should not be related to. :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of recommendations to \ - return (must be <= 500). + :param int limit: (optional) maximum number of recommendations to + return (must be <= 500). :returns: list of recommendations. :rtype: :class:`List` of :class:`semanticscholar.Paper.Paper` ''' diff --git a/semanticscholar/SemanticScholar.py b/semanticscholar/SemanticScholar.py index 198f8ee..be6c406 100644 --- a/semanticscholar/SemanticScholar.py +++ b/semanticscholar/SemanticScholar.py @@ -22,8 +22,8 @@ def __init__( retry: bool = True, ) -> None: ''' - :param float timeout: (optional) an exception is raised\ - if the server has not issued a response for timeout seconds. + :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 debug: (optional) enable debug mode. @@ -100,13 +100,14 @@ def get_paper( paper_id: str, fields: list = None ) -> Paper: - '''Paper lookup + ''' + Paper lookup :calls: `GET /graph/v1/paper/{paper_id} \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, \ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -137,13 +138,14 @@ def get_papers( fields: list = None, return_not_found: bool = False ) -> Union[List[Paper], Tuple[List[Paper], List[str]]]: - '''Get details for multiple papers at once + ''' + Get details for multiple papers at once :calls: `POST /graph/v1/paper/batch \ `_ - :param str paper_ids: list of IDs (must be <= 500) - S2PaperId,\ + :param str paper_ids: list of IDs (must be <= 500) - S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -153,13 +155,13 @@ def get_papers( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param bool return_not_found: (optional) flag to include not found IDs\ - in the return, except for IDs in URL: format. + :param bool return_not_found: (optional) flag to include not found IDs + in the return, except for IDs in URL: format. :returns: papers data, and optionally list of IDs not found. - :rtype: :class:`List` of :class:`semanticscholar.Paper.Paper`\ - or :class:`Tuple` [:class:`List` of\ - :class:`semanticscholar.Paper.Paper`,\ - :class:`List` of :class:`str`] + :rtype: :class:`List` of :class:`semanticscholar.Paper.Paper` + or :class:`Tuple` [:class:`List` of + :class:`semanticscholar.Paper.Paper`, + :class:`List` of :class:`str`] :raises: BadQueryParametersException: if no paper was found. ''' @@ -180,13 +182,14 @@ def get_paper_authors( fields: list = None, limit: int = 100 ) -> PaginatedResults: - '''Get details about a paper's authors + ''' + Get details about a paper's authors :calls: `POST /graph/v1/paper/{paper_id}/authors \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -196,7 +199,7 @@ def get_paper_authors( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of results to return\ + :param int limit: (optional) maximum number of results to return (must be <= 1000). ''' @@ -217,13 +220,14 @@ def get_paper_citations( fields: list = None, limit: int = 100 ) -> PaginatedResults: - '''Get details about a paper's citations + ''' + Get details about a paper's citations :calls: `POST /graph/v1/paper/{paper_id}/citations \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -233,7 +237,7 @@ def get_paper_citations( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of results to return\ + :param int limit: (optional) maximum number of results to return (must be <= 1000). ''' @@ -254,13 +258,14 @@ def get_paper_references( fields: list = None, limit: int = 100 ) -> PaginatedResults: - '''Get details about a paper's references + ''' + Get details about a paper's references :calls: `POST /graph/v1/paper/{paper_id}/references \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -270,7 +275,7 @@ def get_paper_references( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of results to return\ + :param int limit: (optional) maximum number of results to return (must be <= 1000). ''' @@ -301,50 +306,51 @@ def search_paper( 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 \ - search is the default behavior and returns up to 1,000 results. \ - Bulk retrieval instead returns up to 10,000,000 results (1,000 \ - in each page). + ''' + 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 + search is the default behavior and returns up to 1,000 results. + Bulk retrieval instead returns up to 10,000,000 results (1,000 + in each page). :calls: `GET /graph/v1/paper/search \ - `_ + `_ :calls: `GET /graph/v1/paper/search/bulk \ - `_ + `_ :param str query: plain-text search query string. - :param str year: (optional) restrict results to the given range of \ + :param str year: (optional) restrict results to the given range of publication year. - :param list publication_type: (optional) restrict results to the given \ + :param list publication_type: (optional) restrict results to the given publication type list. - :param bool open_access_pdf: (optional) restrict results to papers \ + :param bool open_access_pdf: (optional) restrict results to papers with public PDFs. :param list venue: (optional) restrict results to the given venue list. - :param list fields_of_study: (optional) restrict results to given \ + :param list fields_of_study: (optional) restrict results to given field-of-study list, using the s2FieldsOfStudy paper field. :param list fields: (optional) list of the fields to be returned. - :param str publication_date_or_year: (optional) restrict results to \ - the given range of publication date in the format \ - :, where dates are in the format \ + :param str publication_date_or_year: (optional) restrict results to + the given range of publication date in the format + :, where dates are in the format YYYY-MM-DD, YYYY-MM, or YYYY. - :param int min_citation_count: (optional) restrict results to papers \ + :param int min_citation_count: (optional) restrict results to papers with at least the given number of citations. - :param int limit: (optional) maximum number of results to return \ + :param int limit: (optional) maximum number of results to return (must be <= 100). - :param bool bulk: (optional) bulk retrieval of basic paper data \ - without search relevance (ignores the limit parameter if True \ + :param bool bulk: (optional) bulk retrieval of basic paper data + without search relevance (ignores the limit parameter if True and returns up to 1,000 results in each page). - :param str sort: (optional) sorts results (only if bulk=True) using \ - : format, where "field" is either paperId, \ - publicationDate, or citationCount, and "order" is asc \ + :param str sort: (optional) sorts results (only if bulk=True) using + : 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 \ + :param bool match_title: (optional) retrieve a single paper whose title best matches the given query. :returns: query results. - :rtype: :class:`semanticscholar.PaginatedResults.PaginatedResults` or \ + :rtype: :class:`semanticscholar.PaginatedResults.PaginatedResults` or :class:`semanticscholar.Paper.Paper` ''' @@ -374,7 +380,8 @@ def get_author( author_id: str, fields: list = None ) -> Author: - '''Author lookup + ''' + Author lookup :calls: `GET /graph/v1/author/{author_id} \ Union[List[Author], Tuple[List[Author], List[str]]]: - '''Get details for multiple authors at once + ''' + Get details for multiple authors at once :calls: `POST /graph/v1/author/batch \ PaginatedResults: - '''Get details about a author's papers + ''' + Get details about a author's papers :calls: `POST /graph/v1/paper/{author_id}/papers \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -450,7 +459,7 @@ def get_author_papers( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of results to return\ + :param int limit: (optional) maximum number of results to return (must be <= 1000). ''' @@ -471,7 +480,8 @@ def search_author( fields: list = None, limit: int = 100 ) -> PaginatedResults: - '''Search for authors by name + ''' + Search for authors by name :calls: `GET /graph/v1/author/search \ List[Paper]: - '''Get recommended papers for a single positive example. + ''' + Get recommended papers for a single positive example. :calls: `GET /recommendations/v1/papers/forpaper/{paper_id} \ `_ - :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL,\ + :param str paper_id: S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from: - semanticscholar.org @@ -519,10 +530,10 @@ def get_recommended_papers( - biorxiv.org :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of recommendations to \ - return (must be <= 500). - :param str pool_from: (optional) which pool of papers to recommend \ - from. Must be either "recent" or "all-cs". + :param int limit: (optional) maximum number of recommendations to + return (must be <= 500). + :param str pool_from: (optional) which pool of papers to recommend + from. Must be either "recent" or "all-cs". :returns: list of recommendations. :rtype: :class:`List` of :class:`semanticscholar.Paper.Paper` ''' @@ -546,19 +557,20 @@ def get_recommended_papers_from_lists( fields: list = None, limit: int = 100 ) -> List[Paper]: - '''Get recommended papers for lists of positive and negative examples. + ''' + Get recommended papers for lists of positive and negative examples. :calls: `POST /recommendations/v1/papers/ \ `_ - :param list positive_paper_ids: list of paper IDs \ - that the returned papers should be related to. - :param list negative_paper_ids: (optional) list of paper IDs \ - that the returned papers should not be related to. + :param list positive_paper_ids: list of paper IDs + that the returned papers should be related to. + :param list negative_paper_ids: (optional) list of paper IDs + that the returned papers should not be related to. :param list fields: (optional) list of the fields to be returned. - :param int limit: (optional) maximum number of recommendations to \ - return (must be <= 500). + :param int limit: (optional) maximum number of recommendations to + return (must be <= 500). :returns: list of recommendations. :rtype: :class:`List` of :class:`semanticscholar.Paper.Paper` '''