pyalex 0.12__py3-none-any.whl → 0.14__py3-none-any.whl

pyalex/__init__.py

@@ -9,6 +9,10 @@ from pyalex.api import Author
 from pyalex.api import Authors
 from pyalex.api import Concept
 from pyalex.api import Concepts
+from pyalex.api import Domain
+from pyalex.api import Domains
+from pyalex.api import Field
+from pyalex.api import Fields
 from pyalex.api import Funder
 from pyalex.api import Funders
 from pyalex.api import Institution
@@ -19,10 +23,15 @@ from pyalex.api import Publisher
 from pyalex.api import Publishers
 from pyalex.api import Source
 from pyalex.api import Sources
+from pyalex.api import Subfield
+from pyalex.api import Subfields
+from pyalex.api import Topic
+from pyalex.api import Topics
 from pyalex.api import Venue
 from pyalex.api import Venues
 from pyalex.api import Work
 from pyalex.api import Works
+from pyalex.api import autocomplete
 from pyalex.api import config
 from pyalex.api import invert_abstract
 
@@ -43,8 +52,17 @@ __all__ = [
     "Institution",
     "Concepts",
     "Concept",
+    "Domains",
+    "Domain",
+    "Fields",
+    "Field",
+    "Subfields",
+    "Subfield",
+    "Topics",
+    "Topic",
     "People",
     "Journals",
+    "autocomplete",
     "config",
     "invert_abstract",
 ]

pyalex/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.12'
-__version_tuple__ = version_tuple = (0, 12)
+__version__ = version = '0.14'
+__version_tuple__ = version_tuple = (0, 14)

pyalex/api.py

@@ -3,6 +3,7 @@ import warnings
 from urllib.parse import quote_plus
 
 import requests
+from requests.auth import AuthBase
 from urllib3.util import Retry
 
 try:
@@ -22,6 +23,7 @@ class AlexConfig(dict):
 config = AlexConfig(
     email=None,
     api_key=None,
+    user_agent="pyalex/" + __version__,
     openalex_url="https://api.openalex.org",
     max_retries=0,
     retry_backoff_factor=0.1,
@@ -160,6 +162,32 @@ class Paginator:
         return results
 
 
+class OpenAlexAuth(AuthBase):
+    """OpenAlex auth class based on requests auth
+
+    Includes the email, api_key and user-agent headers.
+
+    arguments:
+        config: an AlexConfig object
+
+    """
+
+    def __init__(self, config):
+        self.config = config
+
+    def __call__(self, r):
+        if self.config.api_key:
+            r.headers["Authorization"] = f"Bearer {self.config.api_key}"
+
+        if self.config.email:
+            r.headers["From"] = self.config.email
+
+        if self.config.user_agent:
+            r.headers["User-Agent"] = self.config.user_agent
+
+        return r
+
+
 class BaseOpenAlex:
     """Base class for OpenAlex objects."""
 
@@ -170,7 +198,11 @@ class BaseOpenAlex:
         return self.filter(openalex_id="|".join(record_list)).get()
 
     def _full_collection_name(self):
-        return config.openalex_url + "/" + self.__class__.__name__.lower()
+        if self.params is not None and "q" in self.params.keys():
+            base_url = config.openalex_url + "/autocomplete/"
+            return base_url + self.__class__.__name__.lower()
+        else:
+            return config.openalex_url + "/" + self.__class__.__name__.lower()
 
     def __getattr__(self, key):
         if key == "groupby":
@@ -222,13 +254,7 @@ class BaseOpenAlex:
         return m["count"]
 
     def _get_from_url(self, url, return_meta=False):
-        params = {"api_key": config.api_key} if config.api_key else {}
-
-        res = _get_requests_session().get(
-            url,
-            headers={"User-Agent": "pyalex/" + __version__, "email": config.email},
-            params=params,
-        )
+        res = _get_requests_session().get(url, auth=OpenAlexAuth(config))
 
         # handle query errors
         if res.status_code == 403:
@@ -264,7 +290,6 @@ class BaseOpenAlex:
         self._add_params("per-page", per_page)
         self._add_params("page", page)
         self._add_params("cursor", cursor)
-
         return self._get_from_url(self.url, return_meta=return_meta)
 
     def paginate(self, method="cursor", page=1, per_page=None, cursor="*", n_max=10000):
@@ -321,6 +346,11 @@ class BaseOpenAlex:
         self._add_params("select", s)
         return self
 
+    def autocomplete(self, s, **kwargs):
+        """autocomplete the string s, for a specific type of entity"""
+        self._add_params("q", s)
+        return self.get(**kwargs)
+
 
 # The API
 
@@ -334,11 +364,9 @@ class Work(OpenAlexEntity):
 
     def ngrams(self, return_meta=False):
         openalex_id = self["id"].split("/")[-1]
+        n_gram_url = f"{config.openalex_url}/works/{openalex_id}/ngrams"
 
-        res = _get_requests_session().get(
-            f"{config.openalex_url}/works/{openalex_id}/ngrams",
-            headers={"User-Agent": "pyalex/" + __version__, "email": config.email},
-        )
+        res = _get_requests_session().get(n_gram_url, auth=OpenAlexAuth(config))
         res.raise_for_status()
         results = res.json()
 
@@ -377,12 +405,36 @@ class Institutions(BaseOpenAlex):
     resource_class = Institution
 
 
-class Concept(OpenAlexEntity):
+class Domain(OpenAlexEntity):
     pass
 
 
-class Concepts(BaseOpenAlex):
-    resource_class = Concept
+class Domains(BaseOpenAlex):
+    resource_class = Domain
+
+
+class Field(OpenAlexEntity):
+    pass
+
+
+class Fields(BaseOpenAlex):
+    resource_class = Field
+
+
+class Subfield(OpenAlexEntity):
+    pass
+
+
+class Subfields(BaseOpenAlex):
+    resource_class = Subfield
+
+
+class Topic(OpenAlexEntity):
+    pass
+
+
+class Topics(BaseOpenAlex):
+    resource_class = Topic
 
 
 class Publisher(OpenAlexEntity):
@@ -401,6 +453,21 @@ class Funders(BaseOpenAlex):
     resource_class = Funder
 
 
+class Autocomplete(OpenAlexEntity):
+    pass
+
+
+class autocompletes(BaseOpenAlex):
+    """Class to autocomplete without being based on the type of entity"""
+
+    resource_class = Autocomplete
+
+    def __getitem__(self, key):
+        return self._get_from_url(
+            config.openalex_url + "/autocomplete" + "?q=" + key, return_meta=False
+        )
+
+
 def Venue(*args, **kwargs):  # deprecated
     # warn about deprecation
     warnings.warn(
@@ -423,6 +490,30 @@ def Venues(*args, **kwargs):  # deprecated
     return Sources(*args, **kwargs)
 
 
+class Concept(OpenAlexEntity):
+    # warn about deprecation
+    warnings.warn(
+        "Concept is deprecated by OpenAlex and replaced by topics.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+
+class Concepts(BaseOpenAlex):
+    # warn about deprecation
+    warnings.warn(
+        "Concepts is deprecated by OpenAlex and replaced by topics.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    resource_class = Concept
+
+
+def autocomplete(s):
+    """autocomplete with any type of entity"""
+    return autocompletes()[s]
+
+
 # aliases
 People = Authors
 Journals = Sources

{pyalex-0.12.dist-info → pyalex-0.14.dist-info}/METADATA

@@ -1,18 +1,17 @@
 Metadata-Version: 2.1
 Name: pyalex
-Version: 0.12
+Version: 0.14
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.6
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests
@@ -21,6 +20,7 @@ Provides-Extra: lint
 Requires-Dist: ruff ; extra == 'lint'
 Provides-Extra: test
 Requires-Dist: pytest ; extra == 'test'
+Requires-Dist: pytest-xdist ; extra == 'test'
 
 <p align="center">
   <img alt="PyAlex - a Python wrapper for OpenAlex" src="https://github.com/J535D165/pyalex/raw/main/pyalex_repocard.svg">
@@ -30,6 +30,7 @@ Requires-Dist: pytest ; extra == 'test'
 
 ![PyPI](https://img.shields.io/pypi/v/pyalex) [![DOI](https://zenodo.org/badge/557541347.svg)](https://zenodo.org/badge/latestdoi/557541347)
 
+
 PyAlex is a Python library for [OpenAlex](https://openalex.org/). OpenAlex is
 an index of hundreds of millions of interconnected scholarly papers, authors,
 institutions, and more. OpenAlex offers a robust, open, and free [REST API](https://docs.openalex.org/) to extract, aggregate, or search scholarly data.
@@ -46,7 +47,7 @@ The following features of OpenAlex are currently supported by PyAlex:
 - [x] Select fields
 - [x] Sample
 - [x] Pagination
-- [ ] [Autocomplete endpoint](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities)
+- [x] Autocomplete endpoint
 - [x] N-grams
 - [x] Authentication
 
@@ -60,7 +61,7 @@ We aim to cover the entire API, and we are looking for help. We are welcoming Pu
 
 ## Installation
 
-PyAlex requires Python 3.6 or later.
+PyAlex requires Python 3.8 or later.
 
 ```sh
 pip install pyalex
@@ -68,10 +69,10 @@ pip install pyalex
 
 ## Getting started
 
-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), [Concepts](https://docs.openalex.org/api-entities/concepts), [Publishers](https://docs.openalex.org/api-entities/publishers), and [Funders](https://docs.openalex.org/api-entities/funders).
+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, Concepts, Publishers, Funders
+from pyalex import Works, Authors, Sources, Institutions, Topics, Publishers, Funders
 ```
 
 ### The polite pool
@@ -86,9 +87,21 @@ import pyalex
 pyalex.config.email = "mail@example.com"
 ```
 
+### 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
+from pyalex import config
+
+config.max_retries = 0
+config.retry_backoff_factor = 0.1
+config.retry_http_codes = [429, 500, 503]
+```
+
 ### Get single entity
 
-Get a single Work, Author, Source, Institution, Concept, Publisher or Funder from OpenAlex by the
+Get a single Work, Author, Source, Institution, Concept, Topic, Publisher or Funder from OpenAlex by the
 OpenAlex ID, or by DOI or ROR.
 
 ```python
@@ -110,7 +123,7 @@ Works()["W2741809807"]["open_access"]
 {'is_oa': True, 'oa_status': 'gold', 'oa_url': 'https://doi.org/10.7717/peerj.4375'}
 ```
 
-The previous works also for Authors, Venues, Institutions and Concepts
+The previous works also for Authors, Venues, Institutions, Concepts and Topics
 
 ```python
 Authors()["A2887243803"]
@@ -119,7 +132,7 @@ Authors()["https://orcid.org/0000-0002-4297-0502"]  # same
 
 #### Get random
 
-Get a [random Work, Author, Source, Institution, Concept, Publisher or Funder](https://docs.openalex.org/how-to-use-the-api/get-single-entities/random-result).
+Get a [random Work, Author, Source, Institution, Concept, Topic, Publisher or Funder](https://docs.openalex.org/how-to-use-the-api/get-single-entities/random-result).
 
 ```python
 Works().random()
@@ -127,6 +140,7 @@ Authors().random()
 Sources().random()
 Institutions().random()
 Concepts().random()
+Topics().random()
 Publishers().random()
 Funders().random()
 ```
@@ -169,7 +183,7 @@ Works().count()
 For lists of entities, you can return the result as well as the metadata. By default, only the results are returned.
 
 ```python
-results, meta = Concepts().get(return_meta=True)
+results, meta = Topics().get(return_meta=True)
 ```
 
 ```python
@@ -328,6 +342,32 @@ for page in pager:
 ```
 
 
+### Autocomplete
+
+OpenAlex reference: [Autocomplete entities](https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/autocomplete-entities).
+
+Autocomplete a string:
+```python
+from pyalex import autocomplete
+
+autocomplete("stockholm resilience centre")
+```
+
+Autocomplete a string to get a specific type of entities:
+```python
+from pyalex import Institutions
+
+Institutions().autocomplete("stockholm resilience centre")
+```
+
+You can also use the filters to autocomplete:
+```python
+from pyalex import Works
+
+r = Works().filter(publication_year=2023).autocomplete("planetary boundaries")
+```
+
+
 ### Get N-grams
 
 OpenAlex reference: [Get N-grams](https://docs.openalex.org/api-entities/works/get-n-grams).
@@ -412,6 +452,8 @@ R users can use the excellent [OpenAlexR](https://github.com/ropensci/openalexR)
 
 ## Contact
 
+> This library is a community contribution. The authors of this Python library aren't affiliated with OpenAlex.
+
 Feel free to reach out with questions, remarks, and suggestions. The
 [issue tracker](/issues) is a good starting point. You can also email me at
 [jonathandebruinos@gmail.com](mailto:jonathandebruinos@gmail.com).

pyalex-0.14.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyalex/__init__.py,sha256=EL6oh0vQdSNyvsrxFFgmDn-P_Dgev1IYpP-WiLBxjS8,1553
+pyalex/_version.py,sha256=lmFPHiet63Bn9h104yd9q0T6i7C2c0WCbizqrpAtSuk,408
+pyalex/api.py,sha256=whUv8TbnW968wlR8U4O-lWsaFHRgW0Ham0cznbR3Zlc,13212
+pyalex-0.14.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
+pyalex-0.14.dist-info/METADATA,sha256=3bjn78df3VlosFCcseDGs5tfTUIAgCStI_uGjqHT69w,13777
+pyalex-0.14.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+pyalex-0.14.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
+pyalex-0.14.dist-info/RECORD,,

{pyalex-0.12.dist-info → pyalex-0.14.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.2)
+Generator: bdist_wheel (0.43.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pyalex-0.12.dist-info/RECORD

@@ -1,8 +0,0 @@
-pyalex/__init__.py,sha256=UrEW9s9NbULtmmnYUUgfbrDujleV8XQLiMRYGdRnm9M,1137
-pyalex/_version.py,sha256=eOKjFr4-OgtTmAgooUIWvbplNekszFVZVHe7TLPOdeU,408
-pyalex/api.py,sha256=lmbJaU3GCwi2ZNeshQV0dFXK-j83A08q1yjuVdeEKeM,11193
-pyalex-0.12.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
-pyalex-0.12.dist-info/METADATA,sha256=JVSzitj9HrRO7us_49vrDWCYIVLe7QtvRNIGGk0tQQU,12632
-pyalex-0.12.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
-pyalex-0.12.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
-pyalex-0.12.dist-info/RECORD,,