pyalex 0.19__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

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

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

@@ -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.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.19.dist-info → pyalex-0.20.dist-info}/WHEEL

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

pyalex-0.19.dist-info/RECORD

@@ -1,8 +0,0 @@
-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,,