pyalex 0.17__py3-none-any.whl → 0.19__py3-none-any.whl

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 = None

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.dist-info → pyalex-0.19.dist-info}/METADATA

@@ -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.19.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyalex/__init__.py,sha256=upMXti6aJF6lz8J4EbdnQa13GhJzFGre7fnS_tj8NOw,1539
+pyalex/_version.py,sha256=lc7e3Va7b6LwW9-6o0HxJBuB54_pZOZmQ9I6QHKL8AQ,701
+pyalex/api.py,sha256=_g42dO3hkeKUQR3uXjLcAPAj3zxuT190Z2_jyH3p3Es,27769
+pyalex-0.19.dist-info/licenses/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
+pyalex-0.19.dist-info/METADATA,sha256=mawFYplV4A8N7p4lR0zVHGFT2ZRRNZ16bcVDUSX9ddU,16197
+pyalex-0.19.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyalex-0.19.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
+pyalex-0.19.dist-info/RECORD,,

{pyalex-0.17.dist-info → pyalex-0.19.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (76.0.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pyalex-0.17.dist-info/RECORD

@@ -1,8 +0,0 @@
-pyalex/__init__.py,sha256=upMXti6aJF6lz8J4EbdnQa13GhJzFGre7fnS_tj8NOw,1539
-pyalex/_version.py,sha256=t3d5dJC864lqQ-TUIs6gpWRp7YVH04dI08mpFt6wvR0,508
-pyalex/api.py,sha256=05clKZlIcH7g7G5d7tELxrfUIyyzdPKwbRinZ1Pliy4,26783
-pyalex-0.17.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
-pyalex-0.17.dist-info/METADATA,sha256=3K3i_n7uMyF91DfrwFI5t0X5jaYD8lD2HcySMNHcfbg,14208
-pyalex-0.17.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
-pyalex-0.17.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
-pyalex-0.17.dist-info/RECORD,,