pyalex 0.11__py3-none-any.whl → 0.13__py3-none-any.whl

pyalex/_version.py

@@ -1,4 +1,16 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
-__version__ = version = '0.11'
-__version_tuple__ = version_tuple = (0, 11)
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.13'
+__version_tuple__ = version_tuple = (0, 13)

pyalex/api.py

@@ -3,6 +3,8 @@ import warnings
 from urllib.parse import quote_plus
 
 import requests
+from requests.auth import AuthBase
+from urllib3.util import Retry
 
 try:
     from pyalex._version import __version__
@@ -18,13 +20,19 @@ class AlexConfig(dict):
         return super().__setitem__(key, value)
 
 
-config = AlexConfig(email=None, api_key=None, openalex_url="https://api.openalex.org")
+config = AlexConfig(
+    email=None,
+    api_key=None,
+    user_agent="pyalex/" + __version__,
+    openalex_url="https://api.openalex.org",
+    max_retries=0,
+    retry_backoff_factor=0.1,
+    retry_http_codes=[429, 500, 503],
+)
 
 
 def _flatten_kv(d, prefix=""):
-
     if isinstance(d, dict):
-
         t = []
         for k, v in d.items():
             if isinstance(v, list):
@@ -36,7 +44,6 @@ def _flatten_kv(d, prefix=""):
 
         return ",".join(t)
     else:
-
         # workaround for bug https://groups.google.com/u/1/g/openalex-users/c/t46RWnzZaXc
         d = str(d).lower() if isinstance(d, bool) else d
 
@@ -44,7 +51,6 @@ def _flatten_kv(d, prefix=""):
 
 
 def _params_merge(params, add_params):
-
     for k, _v in add_params.items():
         if (
             k in params
@@ -72,8 +78,23 @@ def _params_merge(params, add_params):
             params[k] = add_params[k]
 
 
-def invert_abstract(inv_index):
+def _get_requests_session():
+    # create an Requests Session with automatic retry:
+    requests_session = requests.Session()
+    retries = Retry(
+        total=config.max_retries,
+        backoff_factor=config.retry_backoff_factor,
+        status_forcelist=config.retry_http_codes,
+        allowed_methods={"GET"},
+    )
+    requests_session.mount(
+        "https://", requests.adapters.HTTPAdapter(max_retries=retries)
+    )
+
+    return requests_session
+
 
+def invert_abstract(inv_index):
     if inv_index is not None:
         l_inv = [(w, p) for w, pos in inv_index.items() for p in pos]
         return " ".join(map(lambda x: x[0], sorted(l_inv, key=lambda x: x[1])))
@@ -84,126 +105,102 @@ class QueryError(ValueError):
 
 
 class OpenAlexEntity(dict):
-
     pass
 
 
-class Work(OpenAlexEntity):
-    """OpenAlex work object."""
+class Paginator:
+    VALUE_CURSOR_START = "*"
+    VALUE_NUMBER_START = 1
 
-    def __getitem__(self, key):
+    def __init__(
+        self, endpoint_class, method="cursor", value=None, per_page=None, n_max=None
+    ):
+        self.method = method
+        self.endpoint_class = endpoint_class
+        self.value = value
+        self.per_page = per_page
+        self.n_max = n_max
 
-        if key == "abstract":
-            return invert_abstract(self["abstract_inverted_index"])
+        self._next_value = value
 
-        return super().__getitem__(key)
+    def __iter__(self):
+        self.n = 0
 
-    def ngrams(self, return_meta=False):
+        return self
 
-        openalex_id = self["id"].split("/")[-1]
+    def _is_max(self):
+        if self.n_max and self.n >= self.n_max:
+            return True
+        return False
 
-        res = requests.get(
-            f"{config.openalex_url}/works/{openalex_id}/ngrams",
-            headers={"User-Agent": "pyalex/" + __version__, "email": config.email},
-        )
-        res.raise_for_status()
-        results = res.json()
+    def __next__(self):
+        if self._next_value is None or self._is_max():
+            raise StopIteration
 
-        # return result and metadata
-        if return_meta:
-            return results["ngrams"], results["meta"]
+        if self.method == "cursor":
+            pagination_params = {"cursor": self._next_value}
+        elif self.method == "page":
+            pagination_params = {"page": self._next_value}
         else:
-            return results["ngrams"]
-
-
-class Author(OpenAlexEntity):
-    pass
-
-
-class Source(OpenAlexEntity):
-    pass
-
-
-class Institution(OpenAlexEntity):
-    pass
-
-
-class Concept(OpenAlexEntity):
-    pass
-
-
-class Publisher(OpenAlexEntity):
-    pass
-
-
-class Funder(OpenAlexEntity):
-    pass
-
-# deprecated
+            raise ValueError()
 
+        results, meta = self.endpoint_class.get(
+            return_meta=True, per_page=self.per_page, **pagination_params
+        )
 
-def Venue(*args, **kwargs):
-
-    # warn about deprecation
-    warnings.warn(
-        "Venue is deprecated. Use Sources instead.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
+        if self.method == "cursor":
+            self._next_value = meta["next_cursor"]
 
-    return Source(*args, **kwargs)
+        if self.method == "page":
+            if len(results) > 0:
+                self._next_value = meta["page"] + 1
+            else:
+                self._next_value = None
 
+        self.n = self.n + len(results)
 
-class CursorPaginator:
-    def __init__(self, alex_class=None, per_page=None, cursor="*", n_max=None):
+        return results
 
-        self.alex_class = alex_class
-        self.per_page = per_page
-        self.cursor = cursor
-        self.n_max = n_max
 
-    def __iter__(self):
+class OpenAlexAuth(AuthBase):
+    """OpenAlex auth class based on requests auth
 
-        self.n = 0
+    Includes the email, api_key and user-agent headers.
 
-        return self
+    arguments:
+        config: an AlexConfig object
 
-    def __next__(self):
+    """
 
-        if self.n_max and self.n >= self.n_max:
-            raise StopIteration
+    def __init__(self, config):
+        self.config = config
 
-        r, m = self.alex_class.get(
-            return_meta=True, per_page=self.per_page, cursor=self.cursor
-        )
+    def __call__(self, r):
+        if self.config.api_key:
+            r.headers["Authorization"] = f"Bearer {self.config.api_key}"
 
-        if m["next_cursor"] is None:
-            raise StopIteration
+        if self.config.email:
+            r.headers["From"] = self.config.email
 
-        self.n = self.n + len(r)
-        self.cursor = m["next_cursor"]
+        if self.config.user_agent:
+            r.headers["User-Agent"] = self.config.user_agent
 
         return r
 
 
 class BaseOpenAlex:
-
     """Base class for OpenAlex objects."""
 
     def __init__(self, params=None):
-
         self.params = params
 
     def _get_multi_items(self, record_list):
-
         return self.filter(openalex_id="|".join(record_list)).get()
 
     def _full_collection_name(self):
-
         return config.openalex_url + "/" + self.__class__.__name__.lower()
 
     def __getattr__(self, key):
-
         if key == "groupby":
             raise AttributeError(
                 "Object has no attribute 'groupby'. " "Did you mean 'group_by'?"
@@ -218,31 +215,20 @@ class BaseOpenAlex:
         return getattr(self, key)
 
     def __getitem__(self, record_id):
-
         if isinstance(record_id, list):
             return self._get_multi_items(record_id)
 
-        url = self._full_collection_name() + "/" + record_id
-        params = {"api_key": config.api_key} if config.api_key else {}
-        res = requests.get(
-            url,
-            headers={"User-Agent": "pyalex/" + __version__, "email": config.email},
-            params=params,
+        return self._get_from_url(
+            self._full_collection_name() + "/" + record_id, return_meta=False
         )
-        res.raise_for_status()
-        res_json = res.json()
-
-        return self.resource_class(res_json)
 
     @property
     def url(self):
-
         if not self.params:
             return self._full_collection_name()
 
         l_params = []
         for k, v in self.params.items():
-
             if v is None:
                 pass
             elif isinstance(v, list):
@@ -263,39 +249,29 @@ class BaseOpenAlex:
 
         return m["count"]
 
-    def get(self, return_meta=False, page=None, per_page=None, cursor=None):
-
-        if per_page is not None and (per_page < 1 or per_page > 200):
-            raise ValueError("per_page should be a number between 1 and 200.")
-
-        self._add_params("per-page", per_page)
-        self._add_params("page", page)
-        self._add_params("cursor", cursor)
-
-        params = {"api_key": config.api_key} if config.api_key else {}
-        res = requests.get(
-            self.url,
-            headers={"User-Agent": "pyalex/" + __version__, "email": config.email},
-            params=params,
-        )
+    def _get_from_url(self, url, return_meta=False):
+        res = _get_requests_session().get(url, auth=OpenAlexAuth(config))
 
         # handle query errors
         if res.status_code == 403:
-            res_json = res.json()
             if (
-                isinstance(res_json["error"], str)
-                and "query parameters" in res_json["error"]
+                isinstance(res.json()["error"], str)
+                and "query parameters" in res.json()["error"]
             ):
-                raise QueryError(res_json["message"])
-        res.raise_for_status()
+                raise QueryError(res.json()["message"])
 
+        res.raise_for_status()
         res_json = res.json()
 
         # group-by or results page
-        if "group-by" in self.params:
+        if self.params and "group-by" in self.params:
             results = res_json["group_by"]
-        else:
+        elif "results" in res_json:
             results = [self.resource_class(ent) for ent in res_json["results"]]
+        elif "id" in res_json:
+            results = self.resource_class(res_json)
+        else:
+            raise ValueError("Unknown response format")
 
         # return result and metadata
         if return_meta:
@@ -303,31 +279,32 @@ class BaseOpenAlex:
         else:
             return results
 
-    def paginate(self, per_page=None, cursor="*", n_max=10000):
-        """Used for paging results of large responses using cursor paging.
+    def get(self, return_meta=False, page=None, per_page=None, cursor=None):
+        if per_page is not None and (per_page < 1 or per_page > 200):
+            raise ValueError("per_page should be a number between 1 and 200.")
+
+        self._add_params("per-page", per_page)
+        self._add_params("page", page)
+        self._add_params("cursor", cursor)
 
-        OpenAlex offers two methods for paging: basic paging and cursor paging.
-        Both methods are supported by PyAlex, although cursor paging seems to be
-        easier to implement and less error-prone.
+        return self._get_from_url(self.url, return_meta=return_meta)
 
-        Args:
-            per_page (_type_, optional): Entries per page to return. Defaults to None.
-            cursor (str, optional): _description_. Defaults to "*".
-            n_max (int, optional): Number of max results (not pages) to return.
-                Defaults to 10000.
+    def paginate(self, method="cursor", page=1, per_page=None, cursor="*", n_max=10000):
+        if method == "cursor":
+            value = cursor
+        elif method == "page":
+            value = page
+        else:
+            raise ValueError("Method should be 'cursor' or 'page'")
 
-        Returns:
-            CursorPaginator: Iterator to use for returning and processing each page
-            result in sequence.
-        """
-        return CursorPaginator(self, per_page=per_page, cursor=cursor, n_max=n_max)
+        return Paginator(
+            self, method=method, value=value, per_page=per_page, n_max=n_max
+        )
 
     def random(self):
-
         return self.__getitem__("random")
 
     def _add_params(self, argument, new_params):
-
         if self.params is None:
             self.params = {argument: new_params}
         elif argument in self.params and isinstance(self.params[argument], dict):
@@ -338,74 +315,124 @@ class BaseOpenAlex:
         logging.debug("Params updated:", self.params)
 
     def filter(self, **kwargs):
-
         self._add_params("filter", kwargs)
         return self
 
     def search_filter(self, **kwargs):
-
         self._add_params("filter", {f"{k}.search": v for k, v in kwargs.items()})
         return self
 
     def sort(self, **kwargs):
-
         self._add_params("sort", kwargs)
         return self
 
     def group_by(self, group_key):
-
         self._add_params("group-by", group_key)
         return self
 
     def search(self, s):
-
         self._add_params("search", s)
         return self
 
     def sample(self, n, seed=None):
-
         self._add_params("sample", n)
         self._add_params("seed", seed)
         return self
 
     def select(self, s):
-
         self._add_params("select", s)
         return self
 
 
+# The API
+
+
+class Work(OpenAlexEntity):
+    def __getitem__(self, key):
+        if key == "abstract":
+            return invert_abstract(self["abstract_inverted_index"])
+
+        return super().__getitem__(key)
+
+    def ngrams(self, return_meta=False):
+        openalex_id = self["id"].split("/")[-1]
+        n_gram_url = f"{config.openalex_url}/works/{openalex_id}/ngrams"
+
+        res = _get_requests_session().get(n_gram_url, auth=OpenAlexAuth(config))
+        res.raise_for_status()
+        results = res.json()
+
+        # return result and metadata
+        if return_meta:
+            return results["ngrams"], results["meta"]
+        else:
+            return results["ngrams"]
+
+
 class Works(BaseOpenAlex):
     resource_class = Work
 
 
+class Author(OpenAlexEntity):
+    pass
+
+
 class Authors(BaseOpenAlex):
     resource_class = Author
 
 
+class Source(OpenAlexEntity):
+    pass
+
+
 class Sources(BaseOpenAlex):
     resource_class = Source
 
 
+class Institution(OpenAlexEntity):
+    pass
+
+
 class Institutions(BaseOpenAlex):
     resource_class = Institution
 
 
+class Concept(OpenAlexEntity):
+    pass
+
+
 class Concepts(BaseOpenAlex):
     resource_class = Concept
 
 
+class Publisher(OpenAlexEntity):
+    pass
+
+
 class Publishers(BaseOpenAlex):
     resource_class = Publisher
 
 
+class Funder(OpenAlexEntity):
+    pass
+
+
 class Funders(BaseOpenAlex):
     resource_class = Funder
 
-# deprecated
 
+def Venue(*args, **kwargs):  # deprecated
+    # warn about deprecation
+    warnings.warn(
+        "Venue is deprecated. Use Sources instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    return Source(*args, **kwargs)
 
-def Venues(*args, **kwargs):
 
+def Venues(*args, **kwargs):  # deprecated
     # warn about deprecation
     warnings.warn(
         "Venues is deprecated. Use Sources instead.",

{pyalex-0.11.dist-info → pyalex-0.13.dist-info}/METADATA

@@ -1,24 +1,26 @@
 Metadata-Version: 2.1
 Name: pyalex
-Version: 0.11
+Version: 0.13
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
-Requires-Python: >=3.6
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests
+Requires-Dist: urllib3
 Provides-Extra: lint
 Requires-Dist: ruff ; extra == 'lint'
 Provides-Extra: test
 Requires-Dist: pytest ; extra == 'test'
+Requires-Dist: pytest-xdist ; extra == 'test'
 
 <p align="center">
   <img alt="PyAlex - a Python wrapper for OpenAlex" src="https://github.com/J535D165/pyalex/raw/main/pyalex_repocard.svg">
@@ -28,6 +30,9 @@ Requires-Dist: pytest ; extra == 'test'
 
 ![PyPI](https://img.shields.io/pypi/v/pyalex) [![DOI](https://zenodo.org/badge/557541347.svg)](https://zenodo.org/badge/latestdoi/557541347)
 
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/J535D165/pyalex/badge)](https://securityscorecards.dev/viewer/?uri=github.com/J535D165/pyalex)
+
+
 PyAlex is a Python library for [OpenAlex](https://openalex.org/). OpenAlex is
 an index of hundreds of millions of interconnected scholarly papers, authors,
 institutions, and more. OpenAlex offers a robust, open, and free [REST API](https://docs.openalex.org/) to extract, aggregate, or search scholarly data.
@@ -58,7 +63,7 @@ We aim to cover the entire API, and we are looking for help. We are welcoming Pu
 
 ## Installation
 
-PyAlex requires Python 3.6 or later.
+PyAlex requires Python 3.8 or later.
 
 ```sh
 pip install pyalex
@@ -282,29 +287,50 @@ Works().filter(institutions={"country_code": "fr|gb"}).get()
 
 #### Paging
 
-OpenAlex offers two methods for paging: [basic paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#basic-paging) and [cursor paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#cursor-paging). Both methods are supported by
-PyAlex, although cursor paging seems to be easier to implement and less error-prone.
+OpenAlex offers two methods for paging: [basic (offset) paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#basic-paging) and [cursor paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#cursor-paging). Both methods are supported by PyAlex.
 
-##### Basic paging
+##### Cursor paging (default)
 
-See limitations of [basic paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#basic-paging) in the OpenAlex documentation.
-It's relatively easy to implement basic paging with PyAlex, however it is
-advised to use the built-in pager based on cursor paging.
+Use the method `paginate()` to paginate results. Each returned page is a list
+of records, with a maximum of `per_page` (default 25). By default,
+`paginate`s argument `n_max` is set to 10000. Use `None` to retrieve all
+results.
 
-##### Cursor paging
+```python
+from pyalex import Authors
 
-Use `paginate()` for paging results. By default, `paginate`s argument `n_max`
-is set to 10000. Use `None` to retrieve all results.
+pager = Authors().search_filter(display_name="einstein").paginate(per_page=200)
+
+for page in pager:
+    print(len(page))
+```
+
+> Looking for an easy method to iterate the records of a pager?
 
 ```python
+from itertools import chain
 from pyalex import Authors
 
-pager = Authors().search_filter(display_name="einstein").paginate(per_page=200)
+query = Authors().search_filter(display_name="einstein")
+
+for record in chain(*query.paginate(per_page=200)):
+    print(record["id"])
+```
+
+##### Basic paging
+
+See limitations of [basic paging](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/paging#basic-paging) in the OpenAlex documentation.
+
+```python
+from pyalex import Authors
+
+pager = Authors().search_filter(display_name="einstein").paginate(method="page", per_page=200)
 
 for page in pager:
     print(len(page))
 ```
 
+
 ### Get N-grams
 
 OpenAlex reference: [Get N-grams](https://docs.openalex.org/api-entities/works/get-n-grams).
@@ -389,6 +415,8 @@ R users can use the excellent [OpenAlexR](https://github.com/ropensci/openalexR)
 
 ## Contact
 
+> This library is a community contribution. The authors of this Python library aren't affiliated with OpenAlex.
+
 Feel free to reach out with questions, remarks, and suggestions. The
 [issue tracker](/issues) is a good starting point. You can also email me at
 [jonathandebruinos@gmail.com](mailto:jonathandebruinos@gmail.com).

pyalex-0.13.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyalex/__init__.py,sha256=UrEW9s9NbULtmmnYUUgfbrDujleV8XQLiMRYGdRnm9M,1137
+pyalex/_version.py,sha256=4Ti_UJ2UR2LyAc9zW9aeUVpFeq-DXxy65V2wynOuCi0,408
+pyalex/api.py,sha256=vefNV54OG1daTrKHSDq9Jcy4JhiYi0HSP3GsEzA47uk,11633
+pyalex-0.13.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
+pyalex-0.13.dist-info/METADATA,sha256=vMMbnCUgNUaw99XlqucQZMfZsOZWrXXJOmRpPJsTdSU,12916
+pyalex-0.13.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
+pyalex-0.13.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
+pyalex-0.13.dist-info/RECORD,,

{pyalex-0.11.dist-info → pyalex-0.13.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.40.0)
+Generator: bdist_wheel (0.41.3)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pyalex-0.11.dist-info/RECORD

@@ -1,8 +0,0 @@
-pyalex/__init__.py,sha256=UrEW9s9NbULtmmnYUUgfbrDujleV8XQLiMRYGdRnm9M,1137
-pyalex/_version.py,sha256=BAt_8Sc_nk9NuW3Q0g_MC0YGwpwY1603ia-96CY7p1k,157
-pyalex/api.py,sha256=h0eNgT8LAhubqkzE0WkwXTGzagpstRkJenW_zSrOR0Y,10396
-pyalex-0.11.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
-pyalex-0.11.dist-info/METADATA,sha256=9tloa1HKweAmPNz3LQ0Z2AuBsEg294AVH2aK9YF3G-U,12202
-pyalex-0.11.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-pyalex-0.11.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
-pyalex-0.11.dist-info/RECORD,,