pyalex 0.19__tar.gz → 0.20__tar.gz

{pyalex-0.19 → pyalex-0.20}/.gitignore

@@ -1,5 +1,7 @@
 pyalex/_version.py
 
+.vscode/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

{pyalex-0.19 → pyalex-0.20}/.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
   - id: check-yaml
   - id: check-added-large-files
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.9.7
+  rev: v0.15.0
   hooks:
   - id: ruff
     args: [--fix]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyalex
-Version: 0.19
+Version: 0.20
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
@@ -39,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
@@ -50,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.
@@ -59,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
@@ -74,40 +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>"
 ```
 
-### Standards
+For more information, see the [OpenAlex Rate limits and authentication documentation](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication).
 
-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
+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
@@ -172,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
@@ -420,6 +492,10 @@ 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.
@@ -498,20 +574,21 @@ 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]
 ```
 
-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 → pyalex-0.20}/README.md

@@ -13,7 +13,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
@@ -24,7 +35,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.
@@ -33,6 +44,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
@@ -48,40 +60,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>"
 ```
 
-### Standards
+For more information, see the [OpenAlex Rate limits and authentication documentation](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication).
 
-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
+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
@@ -146,6 +169,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
@@ -394,6 +466,10 @@ 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.
@@ -472,20 +548,21 @@ 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]
 ```
 
-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 → pyalex-0.20}/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-0.19 → pyalex-0.20}/pyalex/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.19'
-__version_tuple__ = version_tuple = (0, 19)
+__version__ = version = '0.20'
+__version_tuple__ = version_tuple = (0, 20)
 
-__commit_id__ = commit_id = 'ga8267859b'
+__commit_id__ = commit_id = 'ga78ef7e47'

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

@@ -874,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."""
 
@@ -918,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."""
@@ -1033,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.19 → pyalex-0.20}/pyalex.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyalex
-Version: 0.19
+Version: 0.20
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
@@ -39,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
@@ -50,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.
@@ -59,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
@@ -74,40 +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>"
 ```
 
-### Standards
+For more information, see the [OpenAlex Rate limits and authentication documentation](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication).
 
-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
+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
@@ -172,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
@@ -420,6 +492,10 @@ 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.
@@ -498,20 +574,21 @@ 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]
 ```
 
-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 → pyalex-0.20}/tests/test_paging.py

@@ -1,3 +1,6 @@
+import os
+from functools import wraps
+
 import pytest
 
 import pyalex
@@ -7,10 +10,39 @@ from pyalex.api import Paginator
 pyalex.config.max_retries = 10
 
 
+def requires_api_key(reason="OpenAlex requires authentication for this operation"):
+    """Decorator for API Key requirement.
+
+    Decorator that skips test if OPENALEX_API_KEY is not set, and
+    sets it for the test.
+    """
+
+    def decorator(func):
+        @pytest.mark.skipif(
+            not os.environ.get("OPENALEX_API_KEY"),
+            reason=reason,
+        )
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            api_key = os.environ.get("OPENALEX_API_KEY")
+            original_api_key = pyalex.config.api_key
+            try:
+                pyalex.config.api_key = api_key
+                return func(*args, **kwargs)
+            finally:
+                pyalex.config.api_key = original_api_key
+
+        return wrapper
+
+    return decorator
+
+
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 def test_cursor_no_filter():
     assert len(list(pyalex.Works().paginate(per_page=200, n_max=1000))) == 5
 
 
+@requires_api_key(reason="OpenAlex requires authentication for search_filter queries")
 def test_cursor():
     query = Authors().search_filter(display_name="einstein")
 
@@ -33,6 +65,7 @@ def test_cursor():
     assert len(results) > 200
 
 
+@requires_api_key(reason="OpenAlex requires authentication for search_filter queries")
 def test_page():
     query = Authors().search_filter(display_name="einstein")
 
@@ -54,6 +87,7 @@ def test_page():
     assert len(results) > 200
 
 
+@requires_api_key(reason="OpenAlex requires authentication for search_filter queries")
 def test_paginate_counts():
     r = Authors().search_filter(display_name="einstein").get()
 
@@ -77,34 +111,41 @@ def test_paginate_counts():
     assert r.meta["count"] == n_p_page >= n_p_default == n_p_cursor
 
 
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 def test_paginate_per_page():
     assert all(len(page) <= 10 for page in Authors().paginate(per_page=10, n_max=50))
 
 
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 def test_paginate_per_page_200():
     assert all(len(page) == 200 for page in Authors().paginate(per_page=200, n_max=400))
 
 
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 def test_paginate_per_page_none():
     assert all(len(page) == 25 for page in Authors().paginate(n_max=500))
 
 
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 def test_paginate_per_page_1000():
     with pytest.raises(ValueError):
         assert next(Authors().paginate(per_page=1000))
 
 
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 def test_paginate_per_page_str():
     with pytest.raises(ValueError):
         assert next(Authors().paginate(per_page="100"))
 
 
+@requires_api_key(reason="OpenAlex requires authentication for search_filter queries")
 def test_paginate_instance():
     p_default = Authors().search_filter(display_name="einstein").paginate(per_page=200)
     assert isinstance(p_default, Paginator)
     assert p_default.method == "cursor"
 
 
+@requires_api_key(reason="OpenAlex requires authentication for search_filter queries")
 def test_paginate_cursor_n_max():
     p = (
         Authors()
@@ -115,6 +156,7 @@ def test_paginate_cursor_n_max():
     assert sum(len(page) for page in p) == 400
 
 
+@requires_api_key(reason="OpenAlex requires authentication for search_filter queries")
 def test_cursor_paging_n_max_none():
     p = (
         Authors()
@@ -125,10 +167,12 @@ def test_cursor_paging_n_max_none():
     sum(len(page) for page in p)
 
 
+@requires_api_key(reason="OpenAlex requires authentication for sample queries")
 def test_paging_with_sample():
     with pytest.raises(ValueError):
         Authors().sample(1).paginate(method="cursor")
 
 
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 def test_paging_next():
     next(Authors().paginate())

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

@@ -1,6 +1,7 @@
 import datetime
 import json
 import os
+from functools import wraps
 from pathlib import Path
 
 import pytest
@@ -10,11 +11,13 @@ from requests import HTTPError
 
 import pyalex
 from pyalex import Authors
+from pyalex import Awards
 from pyalex import Concepts
 from pyalex import Domains
 from pyalex import Fields
 from pyalex import Funders
 from pyalex import Institutions
+from pyalex import Keywords
 from pyalex import Publishers
 from pyalex import Sources
 from pyalex import Subfields
@@ -30,12 +33,41 @@ load_dotenv()
 pyalex.config.max_retries = 10
 
 
+def requires_api_key(reason="OpenAlex requires authentication for this operation"):
+    """Decorator for API Key requirement.
+
+    Decorator that skips test if OPENALEX_API_KEY is not set, and
+    sets it for the test.
+    """
+
+    def decorator(func):
+        @pytest.mark.skipif(
+            not os.environ.get("OPENALEX_API_KEY"),
+            reason=reason,
+        )
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            api_key = os.environ.get("OPENALEX_API_KEY")
+            original_api_key = pyalex.config.api_key
+            try:
+                pyalex.config.api_key = api_key
+                return func(*args, **kwargs)
+            finally:
+                pyalex.config.api_key = original_api_key
+
+        return wrapper
+
+    return decorator
+
+
 OPEN_ALEX_ENTITIES = [
     Authors,
+    Awards,
     Domains,
     Fields,
     Funders,
     Institutions,
+    Keywords,
     Publishers,
     Sources,
     Subfields,
@@ -54,43 +86,52 @@ def test_config():
     pyalex.config.api_key = None
 
 
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 @pytest.mark.parametrize("entity", OPEN_ALEX_ENTITIES)
 def test_meta_entities(entity):
     r = entity().get()
     assert r.meta.get("count", False)
 
 
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 @pytest.mark.filterwarnings("ignore:.*deprecated.*:DeprecationWarning")
 def test_meta_entities_deprecated():
     r = Concepts().get()
     assert r.meta.get("count", False)
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_works_params():
     assert len(Works(params={"filter": {"publication_year": "2020"}}).get()) == 25
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_works():
     assert len(Works().filter(publication_year=2020).get()) == 25
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_works_count():
     assert Works().filter(publication_year=2020).count() > 10_000_000
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_per_page():
     assert len(Works().filter(publication_year=2020).get(per_page=200)) == 200
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_per_page_none():
     assert len(Works().filter(publication_year=2020).get(per_page=None)) == 25
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_per_page_1000():
     with pytest.raises(ValueError):
         Works().filter(publication_year=2020).get(per_page=1000)
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_per_page_str():
     with pytest.raises(ValueError):
         Works().filter(publication_year=2020).get(per_page="100")
@@ -128,10 +169,12 @@ def test_work_error():
         Works()["NotAWorkID"]
 
 
+@requires_api_key(reason="OpenAlex requires authentication for random() endpoint")
 def test_random_works():
     assert isinstance(Works().random(), dict)
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_multi_works():
     # the work to extract the referenced works of
     w = Works()["W2741809807"]
@@ -144,6 +187,7 @@ def test_multi_works():
     )
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_works_multifilter():
     r = requests.get(
         "https://api.openalex.org/works?filter=publication_year:2020,is_oa:true"
@@ -174,6 +218,7 @@ def test_works_url():
     assert Works().url == "https://api.openalex.org/works"
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_works_multifilter_meta():
     r1 = Works().filter(publication_year=2020, is_oa=True).get()
     r2 = Works().filter(publication_year=2020).filter(is_oa=True).get()
@@ -181,11 +226,13 @@ def test_works_multifilter_meta():
     assert r1.meta["count"] == r2.meta["count"]
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_query_error():
     with pytest.raises(QueryError):
         Works().filter(publication_year_error=2020).get()
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_data_publications():
     w = (
         Works()
@@ -198,6 +245,7 @@ def test_data_publications():
     assert len(w) > 20
 
 
+@requires_api_key(reason="OpenAlex requires authentication for search queries")
 def test_search():
     w = (
         Works()
@@ -211,6 +259,7 @@ def test_search():
     assert w[0]["doi"] == "https://doi.org/10.1038/s42256-020-00287-7"
 
 
+@requires_api_key(reason="OpenAlex requires authentication for search_filter queries")
 def test_search_filter():
     r = requests.get(
         "https://api.openalex.org/authors?filter=display_name.search:einstein"
@@ -221,6 +270,7 @@ def test_search_filter():
     assert r["meta"]["count"] == a_count
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_referenced_works():
     # the work to extract the referenced works of
     w = Works()["W2741809807"]
@@ -230,6 +280,7 @@ def test_referenced_works():
     assert r.meta["count"] <= len(w["referenced_works"])
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 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
@@ -260,6 +311,7 @@ def test_serializable(tmpdir):
         assert "W4238809453" in json.load(f)["id"]
 
 
+@requires_api_key(reason="OpenAlex requires authentication for unfiltered queries")
 def test_serializable_list(tmpdir):
     with open(Path(tmpdir, "test.json"), "w") as f:
         json.dump(Works().get(), f)
@@ -285,6 +337,7 @@ def test_ngrams_with_metadata():
     assert meta["count"] == 1068
 
 
+@requires_api_key(reason="OpenAlex requires authentication for random() endpoint")
 def test_random_publishers():
     assert isinstance(Publishers().random(), dict)
 
@@ -385,18 +438,23 @@ def test_subset():
     assert url == Works().select(["id", "doi", "display_name"]).url
 
 
+@requires_api_key(
+    reason="OpenAlex requires authentication for filter queries with autocomplete"
+)
 def test_autocomplete_works():
     w = Works().filter(publication_year=2023).autocomplete("planetary boundaries")
 
     assert all(["external_id" in x for x in w])
 
 
+@requires_api_key(reason="OpenAlex requires authentication for autocomplete endpoint")
 def test_autocomplete():
     a = autocomplete("stockholm resilience")
 
     assert all(["external_id" in x for x in a])
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_filter_urlencoding():
     assert Works().filter(doi="10.1207/s15327809jls0703&4_2").count() == 1
     assert (
@@ -405,6 +463,7 @@ def test_filter_urlencoding():
     )
 
 
+@requires_api_key(reason="OpenAlex requires authentication for filter queries")
 def test_urlencoding_list():
     assert (
         Works()
@@ -426,6 +485,40 @@ def test_premium_api_no_valid_key():
         Works().get()
 
 
+def test_unauthenticated_filter_call():
+    """Test that filter/search calls without authentication will fail.
+
+    (post Feb 11, 2025)
+
+    This test documents the expected behavior when OpenAlex enforces their new policy
+    allowing only singleton calls without authentication. Filter and search queries
+    will require an API key.
+
+    Note: This test currently passes the filter call because OpenAlex hasn't yet
+    enforced the restriction. Once the policy is enforced, this test should fail
+    and we'll need to mark it as @requires_api_key instead.
+    """
+    # Ensure no API key is set
+    original_api_key = pyalex.config.api_key
+    pyalex.config.api_key = None
+
+    try:
+        # This should work for now, but will fail once OpenAlex enforces the policy
+        # Singleton calls like Works()["ID"] should still work without auth
+        result = Works()["W2741809807"]
+        assert result["id"] == "https://openalex.org/W2741809807"
+
+        # Filter/search calls will fail once policy is enforced
+        # For now, they still work, so we document the expected future behavior
+        # Once OpenAlex enforces the policy, this should raise an error
+        filter_result = Works().filter(publication_year=2020).get()
+        # If we get here, the policy hasn't been enforced yet
+        assert len(filter_result) > 0
+    finally:
+        # Restore original API key
+        pyalex.config.api_key = original_api_key
+
+
 @pytest.mark.skipif(
     not os.environ.get("OPENALEX_API_KEY"),
     reason="OPENALEX_API_KEY is not set in the environment variables",
@@ -439,3 +532,46 @@ def test_premium_api():
     Works().filter(from_updated_date=f"{datetime.datetime.now().year}-01-01").get()
 
     pyalex.config.api_key = None
+
+
+def test_work_pdf_and_tei_download(tmpdir):
+    """Test downloading PDF and TEI content for a Work.
+
+    This test verifies that:
+    1. A Work object has accessible pdf and tei properties
+    2. PDF and TEI objects have correct URLs
+    3. PDF and TEI content can be retrieved and downloaded to files
+    """
+
+    pyalex.config.api_key = os.environ["OPENALEX_API_KEY"]
+
+    # Get a work
+    work = Works()["W4412002745"]
+
+    # Test that pdf and tei properties return the correct types
+    assert work.pdf is not None
+    assert work.tei is not None
+
+    # Test that PDF has a valid URL
+    pdf_url = work.pdf.url
+    assert pdf_url.endswith(".pdf")
+    assert "content.openalex.org" in pdf_url
+    assert "W4412002745" in pdf_url
+
+    # Test that TEI has a valid URL
+    tei_url = work.tei.url
+    assert "grobid-xml" in tei_url
+    assert "content.openalex.org" in tei_url
+    assert "W4412002745" in tei_url
+
+    # Test downloading PDF content
+    pdf_path = Path(tmpdir) / "test.pdf"
+    work.pdf.download(str(pdf_path))
+    assert pdf_path.exists()
+    assert pdf_path.stat().st_size > 0
+
+    # Test downloading TEI content
+    tei_path = Path(tmpdir) / "test.xml"
+    work.tei.download(str(tei_path))
+    assert tei_path.exists()
+    assert tei_path.stat().st_size > 0