pyalex 0.17__tar.gz → 0.19__tar.gz

{pyalex-0.17 → pyalex-0.19}/.github/workflows/python-package.yml

@@ -16,6 +16,8 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
+    - name: Set OPENALEX_API_KEY from secret
+      run: echo "OPENALEX_API_KEY=${{ secrets.OPENALEX_API_KEY }}" >> $GITHUB_ENV
     - name: Install package and dependencies
       run: |
         python -m pip install --upgrade pip

{pyalex-0.17 → pyalex-0.19}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: pyalex
-Version: 0.17
+Version: 0.19
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
@@ -21,6 +21,8 @@ Requires-Dist: ruff; extra == "lint"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-xdist; extra == "test"
+Requires-Dist: dotenv; extra == "test"
+Dynamic: license-file
 
 <p align="center">
   <img alt="PyAlex - a Python wrapper for OpenAlex" src="https://github.com/J535D165/pyalex/raw/main/pyalex_repocard.svg">
@@ -99,6 +101,10 @@ config.retry_backoff_factor = 0.1
 config.retry_http_codes = [429, 500, 503]
 ```
 
+### Standards
+
+OpenAlex uses standard [ISO_3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes.
+
 ### Get single entity
 
 Get a single Work, Author, Source, Institution, Concept, Topic, Publisher or Funder from OpenAlex by the
@@ -144,6 +150,8 @@ Publishers().random()
 Funders().random()
 ```
 
+Check also [sample](#sample), which does support filters.
+
 #### Get abstract
 
 Only for Works. Request a work from the OpenAlex database:
@@ -215,6 +223,17 @@ Works()
   .get()
 ```
 
+#### Filter on a set of values
+You can filter on a set of values, for example if you want all works from a list of DOI's:
+
+```python
+Works()
+  .filter_or(doi=["10.1016/s0924-9338(99)80239-9", "10.1002/andp.19213690304"])
+  .get()
+```
+
+You can use a maximum of 100 items in the set of values. Also note that OpenAlex allows a maximum URL length of 4096 characters. If you have a big list of identifiers you want to filter on you can run into this limit. It can be helpful to use the short form of the identifiers, so `W2001676859` instead of `https://openalex.org/W2001676859` and `10.1002/andp.19213690304` instead of `https://doi.org/10.1002/andp.19213690304`.
+
 #### Search entities
 
 OpenAlex reference: [The search parameter](https://docs.openalex.org/api-entities/works/search-works)
@@ -264,6 +283,14 @@ OpenAlex reference: [Sample entity lists](https://docs.openalex.org/how-to-use-t
 Works().sample(100, seed=535).get()
 ```
 
+Get 10 random German-based institutions:
+
+```python
+Institutions().filter(country_code="DE").sample(10).get()
+```
+
+Check also [random](#get-random), which does not support filters.
+
 #### Logical expressions
 
 OpenAlex reference: [Logical expressions](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#logical-expressions)
@@ -397,6 +424,25 @@ with open(Path("works.json")) as f:
 
 A list of awesome use cases of the OpenAlex dataset.
 
+### Search author by name and affiliation
+
+This requires searching for the affiliation first, retrieving the affiliation ID, and then searching for the author while filtering for the affiliation:
+
+```python
+from pyalex import Authors, Institutions
+import logging
+
+# Search for the institution
+insts = Institutions().search("MIT").get()
+logging.info(f"{len(insts)} search results found for the institution")
+inst_id = insts[0]["id"].replace("https://openalex.org/", "")
+
+# Search for the author within the institution
+auths = Authors().search("Daron Acemoglu").filter(affiliations={"institution":{"id": inst_id}}).get()
+logging.info(f"{len(auths)} search results found for the author")
+auth = auths[0]
+```
+
 ### Cited publications (works referenced by this paper, outgoing citations)
 
 ```python
@@ -423,6 +469,9 @@ from pyalex import Works
 Works().filter(author={"id": "A2887243803"}).get()
 ```
 
+> [!WARNING]
+> This gets only the first 25 works of the author. To get all of them, see the [paging section](#paging).
+
 ### Dataset publications in the global south
 
 ```python
@@ -461,6 +510,8 @@ import pyalex
 pyalex.config.api_key = "<MY_KEY>"
 ```
 
+If you configure an invalid API key all requests to OpenAlex will fail.
+
 ## Alternatives
 
 R users can use the excellent [OpenAlexR](https://github.com/ropensci/openalexR) library.

{pyalex-0.17 → pyalex-0.19}/README.md

@@ -75,6 +75,10 @@ config.retry_backoff_factor = 0.1
 config.retry_http_codes = [429, 500, 503]
 ```
 
+### Standards
+
+OpenAlex uses standard [ISO_3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes.
+
 ### Get single entity
 
 Get a single Work, Author, Source, Institution, Concept, Topic, Publisher or Funder from OpenAlex by the
@@ -120,6 +124,8 @@ Publishers().random()
 Funders().random()
 ```
 
+Check also [sample](#sample), which does support filters.
+
 #### Get abstract
 
 Only for Works. Request a work from the OpenAlex database:
@@ -191,6 +197,17 @@ Works()
   .get()
 ```
 
+#### Filter on a set of values
+You can filter on a set of values, for example if you want all works from a list of DOI's:
+
+```python
+Works()
+  .filter_or(doi=["10.1016/s0924-9338(99)80239-9", "10.1002/andp.19213690304"])
+  .get()
+```
+
+You can use a maximum of 100 items in the set of values. Also note that OpenAlex allows a maximum URL length of 4096 characters. If you have a big list of identifiers you want to filter on you can run into this limit. It can be helpful to use the short form of the identifiers, so `W2001676859` instead of `https://openalex.org/W2001676859` and `10.1002/andp.19213690304` instead of `https://doi.org/10.1002/andp.19213690304`.
+
 #### Search entities
 
 OpenAlex reference: [The search parameter](https://docs.openalex.org/api-entities/works/search-works)
@@ -240,6 +257,14 @@ OpenAlex reference: [Sample entity lists](https://docs.openalex.org/how-to-use-t
 Works().sample(100, seed=535).get()
 ```
 
+Get 10 random German-based institutions:
+
+```python
+Institutions().filter(country_code="DE").sample(10).get()
+```
+
+Check also [random](#get-random), which does not support filters.
+
 #### Logical expressions
 
 OpenAlex reference: [Logical expressions](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#logical-expressions)
@@ -373,6 +398,25 @@ with open(Path("works.json")) as f:
 
 A list of awesome use cases of the OpenAlex dataset.
 
+### Search author by name and affiliation
+
+This requires searching for the affiliation first, retrieving the affiliation ID, and then searching for the author while filtering for the affiliation:
+
+```python
+from pyalex import Authors, Institutions
+import logging
+
+# Search for the institution
+insts = Institutions().search("MIT").get()
+logging.info(f"{len(insts)} search results found for the institution")
+inst_id = insts[0]["id"].replace("https://openalex.org/", "")
+
+# Search for the author within the institution
+auths = Authors().search("Daron Acemoglu").filter(affiliations={"institution":{"id": inst_id}}).get()
+logging.info(f"{len(auths)} search results found for the author")
+auth = auths[0]
+```
+
 ### Cited publications (works referenced by this paper, outgoing citations)
 
 ```python
@@ -399,6 +443,9 @@ from pyalex import Works
 Works().filter(author={"id": "A2887243803"}).get()
 ```
 
+> [!WARNING]
+> This gets only the first 25 works of the author. To get all of them, see the [paging section](#paging).
+
 ### Dataset publications in the global south
 
 ```python
@@ -437,6 +484,8 @@ import pyalex
 pyalex.config.api_key = "<MY_KEY>"
 ```
 
+If you configure an invalid API key all requests to OpenAlex will fail.
+
 ## Alternatives
 
 R users can use the excellent [OpenAlexR](https://github.com/ropensci/openalexR) library.

{pyalex-0.17 → pyalex-0.19}/pyalex/_version.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '0.17'
-__version_tuple__ = version_tuple = (0, 17)
+__version__ = version = '0.19'
+__version_tuple__ = version_tuple = (0, 19)
+
+__commit_id__ = commit_id = 'ga8267859b'

{pyalex-0.17 → pyalex-0.19}/pyalex/api.py

@@ -12,6 +12,8 @@ try:
 except ImportError:
     __version__ = "0.0.0"
 
+logger = logging.getLogger("pyalex")
+
 
 class AlexConfig(dict):
     """Configuration class for OpenAlex API.
@@ -338,12 +340,12 @@ class Paginator:
         self.value = value
         self.per_page = per_page
         self.n_max = n_max
+        self.n = 0
 
         self._next_value = value
+        self._session = _get_requests_session()
 
     def __iter__(self):
-        self.n = 0
-
         return self
 
     def _is_max(self):
@@ -356,13 +358,22 @@ class Paginator:
             raise StopIteration
 
         if self.method == "cursor":
-            pagination_params = {"cursor": self._next_value}
+            self.endpoint_class._add_params("cursor", self._next_value)
         elif self.method == "page":
-            pagination_params = {"page": self._next_value}
+            self.endpoint_class._add_params("page", self._next_value)
         else:
-            raise ValueError()
+            raise ValueError("Method should be 'cursor' or 'page'")
+
+        if self.per_page is not None and (
+            not isinstance(self.per_page, int)
+            or (self.per_page < 1 or self.per_page > 200)
+        ):
+            raise ValueError("per_page should be a integer between 1 and 200")
 
-        r = self.endpoint_class.get(per_page=self.per_page, **pagination_params)
+        if self.per_page is not None:
+            self.endpoint_class._add_params("per-page", self.per_page)
+
+        r = self.endpoint_class._get_from_url(self.endpoint_class.url, self._session)
 
         if self.method == "cursor":
             self._next_value = r.meta["next_cursor"]
@@ -428,7 +439,9 @@ class BaseOpenAlex:
                 "Object has no attribute 'filter_search'. Did you mean 'search_filter'?"
             )
 
-        return getattr(self, key)
+        raise AttributeError(
+            f"'{self.__class__.__name__}' object has no attribute '{key}'"
+        )
 
     def __getitem__(self, record_id):
         if isinstance(record_id, list):
@@ -499,15 +512,24 @@ class BaseOpenAlex:
         """
         return self.get(per_page=1).meta["count"]
 
-    def _get_from_url(self, url):
-        res = _get_requests_session().get(url, auth=OpenAlexAuth(config))
+    def _get_from_url(self, url, session=None):
+        if session is None:
+            session = _get_requests_session()
+
+        logger.debug(f"Requesting URL: {url}")
 
-        if res.status_code == 403:
+        res = session.get(url, auth=OpenAlexAuth(config))
+
+        if res.status_code == 400:
             if (
                 isinstance(res.json()["error"], str)
                 and "query parameters" in res.json()["error"]
             ):
                 raise QueryError(res.json()["message"])
+        if res.status_code == 401 and "API key" in res.json()["error"]:
+            raise QueryError(
+                f"{res.json()['error']}. Did you configure a valid API key?"
+            )
 
         res.raise_for_status()
         res_json = res.json()
@@ -526,8 +548,10 @@ class BaseOpenAlex:
             raise ValueError("Unknown response format")
 
     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.")
+        if per_page is not None and (
+            not isinstance(per_page, int) or (per_page < 1 or per_page > 200)
+        ):
+            raise ValueError("per_page should be an integer between 1 and 200")
 
         if not isinstance(self.params, (str, list)):
             self._add_params("per-page", per_page)
@@ -568,7 +592,7 @@ class BaseOpenAlex:
             Paginator object.
         """
         if method == "cursor":
-            if self.params.get("sample"):
+            if isinstance(self.params, dict) and self.params.get("sample"):
                 raise ValueError("method should be 'page' when using sample")
             value = cursor
         elif method == "page":
@@ -612,7 +636,7 @@ class BaseOpenAlex:
         else:
             self.params[argument] = new_params
 
-        logging.debug("Params updated:", self.params)
+        logger.debug(f"Params updated: {self.params}")
 
     def filter(self, **kwargs):
         """Add filter parameters to the API request.

{pyalex-0.17 → pyalex-0.19}/pyalex.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: pyalex
-Version: 0.17
+Version: 0.19
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
@@ -21,6 +21,8 @@ Requires-Dist: ruff; extra == "lint"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-xdist; extra == "test"
+Requires-Dist: dotenv; extra == "test"
+Dynamic: license-file
 
 <p align="center">
   <img alt="PyAlex - a Python wrapper for OpenAlex" src="https://github.com/J535D165/pyalex/raw/main/pyalex_repocard.svg">
@@ -99,6 +101,10 @@ config.retry_backoff_factor = 0.1
 config.retry_http_codes = [429, 500, 503]
 ```
 
+### Standards
+
+OpenAlex uses standard [ISO_3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes.
+
 ### Get single entity
 
 Get a single Work, Author, Source, Institution, Concept, Topic, Publisher or Funder from OpenAlex by the
@@ -144,6 +150,8 @@ Publishers().random()
 Funders().random()
 ```
 
+Check also [sample](#sample), which does support filters.
+
 #### Get abstract
 
 Only for Works. Request a work from the OpenAlex database:
@@ -215,6 +223,17 @@ Works()
   .get()
 ```
 
+#### Filter on a set of values
+You can filter on a set of values, for example if you want all works from a list of DOI's:
+
+```python
+Works()
+  .filter_or(doi=["10.1016/s0924-9338(99)80239-9", "10.1002/andp.19213690304"])
+  .get()
+```
+
+You can use a maximum of 100 items in the set of values. Also note that OpenAlex allows a maximum URL length of 4096 characters. If you have a big list of identifiers you want to filter on you can run into this limit. It can be helpful to use the short form of the identifiers, so `W2001676859` instead of `https://openalex.org/W2001676859` and `10.1002/andp.19213690304` instead of `https://doi.org/10.1002/andp.19213690304`.
+
 #### Search entities
 
 OpenAlex reference: [The search parameter](https://docs.openalex.org/api-entities/works/search-works)
@@ -264,6 +283,14 @@ OpenAlex reference: [Sample entity lists](https://docs.openalex.org/how-to-use-t
 Works().sample(100, seed=535).get()
 ```
 
+Get 10 random German-based institutions:
+
+```python
+Institutions().filter(country_code="DE").sample(10).get()
+```
+
+Check also [random](#get-random), which does not support filters.
+
 #### Logical expressions
 
 OpenAlex reference: [Logical expressions](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#logical-expressions)
@@ -397,6 +424,25 @@ with open(Path("works.json")) as f:
 
 A list of awesome use cases of the OpenAlex dataset.
 
+### Search author by name and affiliation
+
+This requires searching for the affiliation first, retrieving the affiliation ID, and then searching for the author while filtering for the affiliation:
+
+```python
+from pyalex import Authors, Institutions
+import logging
+
+# Search for the institution
+insts = Institutions().search("MIT").get()
+logging.info(f"{len(insts)} search results found for the institution")
+inst_id = insts[0]["id"].replace("https://openalex.org/", "")
+
+# Search for the author within the institution
+auths = Authors().search("Daron Acemoglu").filter(affiliations={"institution":{"id": inst_id}}).get()
+logging.info(f"{len(auths)} search results found for the author")
+auth = auths[0]
+```
+
 ### Cited publications (works referenced by this paper, outgoing citations)
 
 ```python
@@ -423,6 +469,9 @@ from pyalex import Works
 Works().filter(author={"id": "A2887243803"}).get()
 ```
 
+> [!WARNING]
+> This gets only the first 25 works of the author. To get all of them, see the [paging section](#paging).
+
 ### Dataset publications in the global south
 
 ```python
@@ -461,6 +510,8 @@ import pyalex
 pyalex.config.api_key = "<MY_KEY>"
 ```
 
+If you configure an invalid API key all requests to OpenAlex will fail.
+
 ## Alternatives
 
 R users can use the excellent [OpenAlexR](https://github.com/ropensci/openalexR) library.

{pyalex-0.17 → pyalex-0.19}/pyalex.egg-info/requires.txt

@@ -7,3 +7,4 @@ ruff
 [test]
 pytest
 pytest-xdist
+dotenv

{pyalex-0.17 → pyalex-0.19}/pyproject.toml

@@ -21,7 +21,7 @@ requires-python = ">=3.8"
 
 [project.optional-dependencies]
 lint = ["ruff"]
-test = ["pytest", "pytest-xdist"]
+test = ["pytest", "pytest-xdist", "dotenv"]
 
 [build-system]
 build-backend = 'setuptools.build_meta'

{pyalex-0.17 → pyalex-0.19}/tests/test_paging.py

@@ -7,6 +7,10 @@ from pyalex.api import Paginator
 pyalex.config.max_retries = 10
 
 
+def test_cursor_no_filter():
+    assert len(list(pyalex.Works().paginate(per_page=200, n_max=1000))) == 5
+
+
 def test_cursor():
     query = Authors().search_filter(display_name="einstein")
 
@@ -73,6 +77,28 @@ def test_paginate_counts():
     assert r.meta["count"] == n_p_page >= n_p_default == n_p_cursor
 
 
+def test_paginate_per_page():
+    assert all(len(page) <= 10 for page in Authors().paginate(per_page=10, n_max=50))
+
+
+def test_paginate_per_page_200():
+    assert all(len(page) == 200 for page in Authors().paginate(per_page=200, n_max=400))
+
+
+def test_paginate_per_page_none():
+    assert all(len(page) == 25 for page in Authors().paginate(n_max=500))
+
+
+def test_paginate_per_page_1000():
+    with pytest.raises(ValueError):
+        assert next(Authors().paginate(per_page=1000))
+
+
+def test_paginate_per_page_str():
+    with pytest.raises(ValueError):
+        assert next(Authors().paginate(per_page="100"))
+
+
 def test_paginate_instance():
     p_default = Authors().search_filter(display_name="einstein").paginate(per_page=200)
     assert isinstance(p_default, Paginator)
@@ -102,3 +128,7 @@ def test_cursor_paging_n_max_none():
 def test_paging_with_sample():
     with pytest.raises(ValueError):
         Authors().sample(1).paginate(method="cursor")
+
+
+def test_paging_next():
+    next(Authors().paginate())

{pyalex-0.17 → pyalex-0.19}/tests/test_pyalex.py

@@ -1,8 +1,11 @@
+import datetime
 import json
+import os
 from pathlib import Path
 
 import pytest
 import requests
+from dotenv import load_dotenv
 from requests import HTTPError
 
 import pyalex
@@ -21,6 +24,9 @@ from pyalex import Works
 from pyalex import autocomplete
 from pyalex.api import QueryError
 
+# Load environment variables from .env file
+load_dotenv()
+
 pyalex.config.max_retries = 10
 
 
@@ -76,6 +82,20 @@ def test_per_page():
     assert len(Works().filter(publication_year=2020).get(per_page=200)) == 200
 
 
+def test_per_page_none():
+    assert len(Works().filter(publication_year=2020).get(per_page=None)) == 25
+
+
+def test_per_page_1000():
+    with pytest.raises(ValueError):
+        Works().filter(publication_year=2020).get(per_page=1000)
+
+
+def test_per_page_str():
+    with pytest.raises(ValueError):
+        Works().filter(publication_year=2020).get(per_page="100")
+
+
 def test_W4238809453_works():
     assert isinstance(Works()["W4238809453"], Work)
     assert Works()["W4238809453"]["doi"] == "https://doi.org/10.1001/jama.264.8.944b"
@@ -205,12 +225,11 @@ def test_referenced_works():
     # the work to extract the referenced works of
     w = Works()["W2741809807"]
 
-    r = Works().filter(openalex_id="|".join(w["referenced_works"])).get()
+    r = Works().filter_or(openalex_id=w["referenced_works"]).get()
 
     assert r.meta["count"] <= len(w["referenced_works"])
 
 
-@pytest.mark.xfail()
 def test_code_examples():
     # /works?filter=institutions.is_global_south:true,type:dataset&group-by=institutions.country_code  # noqa
     # /works?filter=institutions.is_global_south:true,type:dataset&group-by=institutions.country_code&sort=count:desc  # noqa
@@ -366,19 +385,6 @@ def test_subset():
     assert url == Works().select(["id", "doi", "display_name"]).url
 
 
-def test_auth():
-    w_no_auth = Works().get()
-    pyalex.config.email = "pyalex_github_unittests@example.com"
-    pyalex.config.api_key = "my_api_key"
-
-    w_auth = Works().get()
-
-    pyalex.config.email = None
-    pyalex.config.api_key = None
-
-    assert len(w_no_auth) == len(w_auth)
-
-
 def test_autocomplete_works():
     w = Works().filter(publication_year=2023).autocomplete("planetary boundaries")
 
@@ -411,3 +417,25 @@ def test_urlencoding_list():
         .count()
         == 2
     )
+
+
+def test_premium_api_no_valid_key():
+    pyalex.config.email = "pyalex_github_unittests@example.com"
+    pyalex.config.api_key = "my_api_key"
+    with pytest.raises(QueryError):
+        Works().get()
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OPENALEX_API_KEY"),
+    reason="OPENALEX_API_KEY is not set in the environment variables",
+)
+def test_premium_api():
+    # This test requires a valid API key set in the config. If from_updated_date
+    # is set, it should return works updated since the start of the current
+    # year. If no API key is set, it should raise an error.
+    pyalex.config.api_key = os.environ["OPENALEX_API_KEY"]
+
+    Works().filter(from_updated_date=f"{datetime.datetime.now().year}-01-01").get()
+
+    pyalex.config.api_key = None