pyalex 0.18__py3-none-any.whl → 0.20__py3-none-any.whl

pyalex/__init__.py

@@ -7,6 +7,8 @@ except ImportError:
 
 from pyalex.api import Author
 from pyalex.api import Authors
+from pyalex.api import Award
+from pyalex.api import Awards
 from pyalex.api import Concept
 from pyalex.api import Concepts
 from pyalex.api import Domain
@@ -18,6 +20,8 @@ from pyalex.api import Funders
 from pyalex.api import Institution
 from pyalex.api import Institutions
 from pyalex.api import Journals
+from pyalex.api import Keyword
+from pyalex.api import Keywords
 from pyalex.api import OpenAlexResponseList
 from pyalex.api import People
 from pyalex.api import Publisher
@@ -35,6 +39,8 @@ from pyalex.api import config
 from pyalex.api import invert_abstract
 
 __all__ = [
+    "Award",
+    "Awards",
     "Works",
     "Work",
     "Authors",
@@ -57,6 +63,8 @@ __all__ = [
     "Subfield",
     "Topics",
     "Topic",
+    "Keywords",
+    "Keyword",
     "People",
     "Journals",
     "autocomplete",

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.18'
-__version_tuple__ = version_tuple = (0, 18)
+__version__ = version = '0.20'
+__version_tuple__ = version_tuple = (0, 20)
+
+__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.
@@ -437,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):
@@ -512,14 +516,20 @@ class BaseOpenAlex:
         if session is None:
             session = _get_requests_session()
 
+        logger.debug(f"Requesting URL: {url}")
+
         res = session.get(url, auth=OpenAlexAuth(config))
 
-        if res.status_code == 403:
+        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()
@@ -626,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.
@@ -864,9 +874,88 @@ class BaseOpenAlex:
             return resp_list
 
 
+class BaseContent:
+    """Class representing content in OpenAlex."""
+
+    def __init__(self, key):
+        self.key = key
+
+    def __repr__(self):
+        return f"Content(key='{self.key}')"
+
+    @property
+    def url(self):
+        """Get the URL for the content.
+
+        Returns
+        -------
+        str
+            URL for the content.
+        """
+        return f"https://content.openalex.org/works/{self.key}"
+
+    def get(self):
+        """Get the content
+
+        Returns
+        -------
+        bytes
+            Content of the request.
+        """
+        content_url = f"https://content.openalex.org/works/{self.key}"
+
+        res = _get_requests_session().get(
+            content_url, auth=OpenAlexAuth(config), allow_redirects=True
+        )
+        res.raise_for_status()
+        return res.content
+
+    def download(self, filepath):
+        """Download the content to a file.
+
+        Parameters
+        ----------
+        filepath : str
+            Path to save the content.
+        """
+
+        with open(filepath, "wb") as f:
+            f.write(self.get())
+
+
 # The API
 
 
+class PDF(BaseContent):
+    """Class representing a PDF content in OpenAlex."""
+
+    @property
+    def url(self):
+        """Get the URL for the content.
+
+        Returns
+        -------
+        str
+            URL for the content.
+        """
+        return f"https://content.openalex.org/works/{self.key}.pdf"
+
+
+class TEI(BaseContent):
+    """Class representing a TEI content in OpenAlex."""
+
+    @property
+    def url(self):
+        """Get the URL for the content.
+
+        Returns
+        -------
+        str
+            URL for the content.
+        """
+        return f"https://content.openalex.org/works/{self.key}.grobid-xml"
+
+
 class Work(OpenAlexEntity):
     """Class representing a work entity in OpenAlex."""
 
@@ -908,6 +997,28 @@ class Work(OpenAlexEntity):
         else:
             return resp_list
 
+    @property
+    def pdf(self):
+        """Get the PDF content for the work.
+
+        Returns
+        -------
+        PDF
+            PDF content object.
+        """
+        return PDF(self["id"].split("/")[-1])
+
+    @property
+    def tei(self):
+        """Get the TEI content for the work.
+
+        Returns
+        -------
+        TEI
+            TEI content object.
+        """
+        return TEI(self["id"].split("/")[-1])
+
 
 class Works(BaseOpenAlex):
     """Class representing a collection of work entities in OpenAlex."""
@@ -1023,6 +1134,30 @@ class Funders(BaseOpenAlex):
     resource_class = Funder
 
 
+class Award(OpenAlexEntity):
+    """Class representing an award entity in OpenAlex."""
+
+    pass
+
+
+class Awards(BaseOpenAlex):
+    """Class representing a collection of award entities in OpenAlex."""
+
+    resource_class = Award
+
+
+class Keyword(OpenAlexEntity):
+    """Class representing a keyword entity in OpenAlex."""
+
+    pass
+
+
+class Keywords(BaseOpenAlex):
+    """Class representing a collection of keyword entities in OpenAlex."""
+
+    resource_class = Keyword
+
+
 class Autocomplete(OpenAlexEntity):
     """Class representing an autocomplete entity in OpenAlex."""
 

{pyalex-0.18.dist-info → pyalex-0.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: pyalex
-Version: 0.18
+Version: 0.20
 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">
@@ -37,7 +39,18 @@ institutions, and more. OpenAlex offers a robust, open, and free [REST API](http
 PyAlex is a lightweight and thin Python interface to this API. PyAlex tries to
 stay as close as possible to the design of the original service.
 
-The following features of OpenAlex are currently supported by PyAlex:
+The following entities of OpenAlex are currently supported by PyAlex:
+
+- [x] Work
+- [x] Author
+- [x] Source
+- [x] Institution
+- [x] Concept
+- [x] Topic
+- [x] Publisher
+- [x] Funder
+
+Including the following functionality:
 
 - [x] Get single entities
 - [x] Filter entities
@@ -48,7 +61,7 @@ The following features of OpenAlex are currently supported by PyAlex:
 - [x] Sample
 - [x] Pagination
 - [x] Autocomplete endpoint
-- [x] N-grams
+- [x] N-grams [Deprecated by OpenAlex]
 - [x] Authentication
 
 We aim to cover the entire API, and we are looking for help. We are welcoming Pull Requests.
@@ -57,6 +70,7 @@ We aim to cover the entire API, and we are looking for help. We are welcoming Pu
 
 - **Pipe operations** - PyAlex can handle multiple operations in a sequence. This allows the developer to write understandable queries. For examples, see [code snippets](#code-snippets).
 - **Plaintext abstracts** - OpenAlex [doesn't include plaintext abstracts](https://docs.openalex.org/api-entities/works/work-object#abstract_inverted_index) due to legal constraints. PyAlex can convert the inverted abstracts into [plaintext abstracts on the fly](#get-abstract).
+- **Fetch content in PDF and TEI format** - Retrieve full-text content from OpenAlex in PDF or TEI XML formats. See [fetching content](#fetch-content-in-pdf-and-tei-format).
 - **Permissive license** - OpenAlex data is CC0 licensed :raised_hands:. PyAlex is published under the MIT license.
 
 ## Installation
@@ -72,36 +86,51 @@ pip install pyalex
 PyAlex offers support for all [Entity Objects](https://docs.openalex.org/api-entities/entities-overview): [Works](https://docs.openalex.org/api-entities/works), [Authors](https://docs.openalex.org/api-entities/authors), [Sources](https://docs.openalex.org/api-entities/sourcese), [Institutions](https://docs.openalex.org/api-entities/institutions), [Topics](https://docs.openalex.org/api-entities/topics), [Publishers](https://docs.openalex.org/api-entities/publishers), and [Funders](https://docs.openalex.org/api-entities/funders).
 
 ```python
-from pyalex import Works, Authors, Sources, Institutions, Topics, Publishers, Funders
+from pyalex import (
+  Works,
+  Authors,
+  Sources,
+  Institutions,
+  Topics,
+  Keywords,
+  Publishers,
+  Funders,
+  Awards,
+  Concepts,
+)
 ```
 
-### The polite pool
+### Rate limits and authentication [Changed!]
 
-[The polite pool](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool) has much
-faster and more consistent response times. To get into the polite pool, you
-set your email:
+**⚠️ API Key Required**: Starting February 13, 2026, an API key is **required** to use the OpenAlex API. API keys are free!
 
-```python
-import pyalex
+The OpenAlex API uses a credit-based rate limiting system. Different endpoint types consume different amounts of credits per request:
 
-pyalex.config.email = "mail@example.com"
-```
+- **Without API key**: 100 credits per day (testing/demos only)
+- **With free API key**: 100,000 credits per day
+- **Singleton requests** (e.g., `/works/W123`): Free (0 credits)
+- **List requests** (e.g., `/works?filter=...`): 1 credit each
 
-### Max retries
+All users are limited to a maximum of 100 requests per second.
 
-By default, PyAlex will raise an error at the first failure when querying the OpenAlex API. You can set `max_retries` to a number higher than 0 to allow PyAlex to retry when an error occurs. `retry_backoff_factor` is related to the delay between two retry, and `retry_http_codes` are the HTTP error codes that should trigger a retry.
+#### Get an API Key
+
+1. Create a free account at [openalex.org](https://openalex.org/)
+2. Go to [openalex.org/settings/api](https://openalex.org/settings/api) to get your API key
+3. Configure PyAlex with your key:
 
 ```python
-from pyalex import config
+import pyalex
 
-config.max_retries = 0
-config.retry_backoff_factor = 0.1
-config.retry_http_codes = [429, 500, 503]
+pyalex.config.api_key = "<YOUR_API_KEY>"
 ```
 
+For more information, see the [OpenAlex Rate limits and authentication documentation](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication).
+
+
 ### Get single entity
 
-Get a single Work, Author, Source, Institution, Concept, Topic, Publisher or Funder from OpenAlex by the
+Get a single Work, Author, Source, Institution, Concept, Topic, Publisher, Funders or Awards from OpenAlex by the
 OpenAlex ID, or by DOI or ROR.
 
 ```python
@@ -144,6 +173,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:
@@ -164,6 +195,55 @@ w["abstract"]
 
 Please respect the legal constraints when using this feature.
 
+#### Fetch content in PDF and TEI format
+
+OpenAlex reference: [Get content](https://docs.openalex.org/how-to-use-the-api/get-content)
+
+Only for Works. Retrieve the full-text content of a work in PDF or TEI (Text Encoding Initiative) XML format, if available.
+
+```python
+from pyalex import Works
+
+# Get a work
+w = Works()["W4412002745"]
+
+# Access the PDF content
+pdf_content = w.pdf.get()
+
+# Or access the TEI content
+tei_content = w.tei.get()
+```
+
+You can also download the content directly to a file:
+
+```python
+from pyalex import Works
+
+w = Works()["W4412002745"]
+
+# Download PDF to a file
+w.pdf.download("document.pdf")
+
+# Download TEI to a file
+w.tei.download("document.xml")
+```
+
+You can also get the URL of the content without downloading it:
+
+```python
+from pyalex import Works
+
+w = Works()["W4412002745"]
+
+# Get the URL of the PDF
+pdf_url = w.pdf.url
+
+# Get the URL of the TEI
+tei_url = w.tei.url
+```
+
+Note: Content availability depends on the publisher's open access policies and licensing agreements.
+
 ### Get lists of entities
 
 ```python
@@ -215,6 +295,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 +355,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)
@@ -393,10 +492,33 @@ with open(Path("works.json")) as f:
     works = [Work(w) for w in json.load(f)]
 ```
 
+## Standards
+
+OpenAlex uses standard [ISO_3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes.
+
 ## Code snippets
 
 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 +545,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
@@ -449,16 +574,19 @@ Works() \
 
 ```
 
-## Experimental
 
-### Authentication
+## Troubleshooting
 
-OpenAlex experiments with authenticated requests at the moment. Authenticate your requests with
+### Max retries
+
+By default, PyAlex will raise an error at the first failure when querying the OpenAlex API. You can set `max_retries` to a number higher than 0 to allow PyAlex to retry when an error occurs. `retry_backoff_factor` is related to the delay between two retry, and `retry_http_codes` are the HTTP error codes that should trigger a retry.
 
 ```python
-import pyalex
+from pyalex import config
 
-pyalex.config.api_key = "<MY_KEY>"
+config.max_retries = 0
+config.retry_backoff_factor = 0.1
+config.retry_http_codes = [429, 500, 503]
 ```
 
 ## Alternatives

pyalex-0.20.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyalex/__init__.py,sha256=WlhyaRF8dXjCM7jzr9kiEcXMYLtD33lcXkZi-WNdcC0,1719
+pyalex/_version.py,sha256=p-gqOONSPfi625BzXHIXfHuTTii-Zx-jV6poH7i3Jb8,701
+pyalex/api.py,sha256=szLCHR3xTZrOaO45Fq1ShQk1nNdDB3OdgpIoyTXOyLY,30383
+pyalex-0.20.dist-info/licenses/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
+pyalex-0.20.dist-info/METADATA,sha256=YXv_LXlaV5vEF7qrge1Ln28pFx_IqVoMmixFcce5_mU,18133
+pyalex-0.20.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+pyalex-0.20.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
+pyalex-0.20.dist-info/RECORD,,

{pyalex-0.18.dist-info → pyalex-0.20.dist-info}/WHEEL

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

pyalex-0.18.dist-info/RECORD

@@ -1,8 +0,0 @@
-pyalex/__init__.py,sha256=upMXti6aJF6lz8J4EbdnQa13GhJzFGre7fnS_tj8NOw,1539
-pyalex/_version.py,sha256=nGXfO1OzooW799_WlgmJZ-ipD8H1pUPrej1lNW4Um9M,508
-pyalex/api.py,sha256=R5hDwrSlzmc3yia85DRF27DWJWpSw4b7DPqnUU_hGmw,27408
-pyalex-0.18.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
-pyalex-0.18.dist-info/METADATA,sha256=GLWXRsSB6K9B5wAQpyHF1CCgJac9Sd6yvpcuZMHDWAg,14208
-pyalex-0.18.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
-pyalex-0.18.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
-pyalex-0.18.dist-info/RECORD,,