pyalex 0.13__py3-none-any.whl → 0.15__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,13 @@ from pyalex.api import Publisher
 from pyalex.api import Publishers
 from pyalex.api import Source
 from pyalex.api import Sources
-from pyalex.api import Venue
-from pyalex.api import Venues
+from pyalex.api import Subfield
+from pyalex.api import Subfields
+from pyalex.api import Topic
+from pyalex.api import Topics
 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
 
@@ -37,14 +44,21 @@ __all__ = [
     "Funders",
     "Publishers",
     "Publisher",
-    "Venues",
-    "Venue",
     "Institutions",
     "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.13'
-__version_tuple__ = version_tuple = (0, 13)
+__version__ = version = '0.15'
+__version_tuple__ = version_tuple = (0, 15)

pyalex/api.py

@@ -23,7 +23,7 @@ class AlexConfig(dict):
 config = AlexConfig(
     email=None,
     api_key=None,
-    user_agent="pyalex/" + __version__,
+    user_agent="pyalex/{__version__}",
     openalex_url="https://api.openalex.org",
     max_retries=0,
     retry_backoff_factor=0.1,
@@ -31,12 +31,28 @@ config = AlexConfig(
 )
 
 
+def _quote_oa_value(v):
+    """Prepare a value for the OpenAlex API.
+
+    Applies URL encoding to strings and converts booleans to lowercase strings.
+    """
+
+    # workaround for bug https://groups.google.com/u/1/g/openalex-users/c/t46RWnzZaXc
+    if isinstance(v, bool):
+        return str(v).lower()
+
+    if isinstance(v, str):
+        return quote_plus(v)
+
+    return v
+
+
 def _flatten_kv(d, prefix=""):
     if isinstance(d, dict):
         t = []
         for k, v in d.items():
             if isinstance(v, list):
-                t.extend([f"{prefix}.{k}:{i}" for i in v])
+                t.extend([f"{prefix}.{k}:{_quote_oa_value(i)}" for i in v])
             else:
                 new_prefix = f"{prefix}.{k}" if prefix else f"{k}"
                 x = _flatten_kv(v, prefix=new_prefix)
@@ -44,10 +60,7 @@ def _flatten_kv(d, prefix=""):
 
         return ",".join(t)
     else:
-        # workaround for bug https://groups.google.com/u/1/g/openalex-users/c/t46RWnzZaXc
-        d = str(d).lower() if isinstance(d, bool) else d
-
-        return f"{prefix}:{d}"
+        return f"{prefix}:{_quote_oa_value(d)}"
 
 
 def _params_merge(params, add_params):
@@ -198,7 +211,12 @@ 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():
+            return (
+                f"{config.openalex_url}/autocomplete/{self.__class__.__name__.lower()}"
+            )
+        else:
+            return f"{config.openalex_url}/{self.__class__.__name__.lower()}"
 
     def __getattr__(self, key):
         if key == "groupby":
@@ -219,7 +237,7 @@ class BaseOpenAlex:
             return self._get_multi_items(record_id)
 
         return self._get_from_url(
-            self._full_collection_name() + "/" + record_id, return_meta=False
+            f"{self._full_collection_name()}/{record_id}", return_meta=False
         )
 
     @property
@@ -232,15 +250,14 @@ class BaseOpenAlex:
             if v is None:
                 pass
             elif isinstance(v, list):
-                v_quote = [quote_plus(q) for q in v]
-                l_params.append(k + "=" + ",".join(v_quote))
+                l_params.append("{}={}".format(k, ",".join(map(_quote_oa_value, v))))
             elif k in ["filter", "sort"]:
-                l_params.append(k + "=" + _flatten_kv(v))
+                l_params.append(f"{k}={_flatten_kv(v)}")
             else:
-                l_params.append(k + "=" + quote_plus(str(v)))
+                l_params.append(f"{k}={_quote_oa_value(v)}")
 
         if l_params:
-            return self._full_collection_name() + "?" + "&".join(l_params)
+            return "{}?{}".format(self._full_collection_name(), "&".join(l_params))
 
         return self._full_collection_name()
 
@@ -286,11 +303,12 @@ 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):
         if method == "cursor":
+            if self.params.get("sample"):
+                raise ValueError("method should be 'page' when using sample")
             value = cursor
         elif method == "page":
             value = page
@@ -343,6 +361,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
 
@@ -397,12 +420,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):
@@ -421,26 +468,46 @@ class Funders(BaseOpenAlex):
     resource_class = Funder
 
 
-def Venue(*args, **kwargs):  # deprecated
-    # warn about deprecation
-    warnings.warn(
-        "Venue is deprecated. Use Sources instead.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
+class Autocomplete(OpenAlexEntity):
+    pass
 
-    return Source(*args, **kwargs)
 
+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(
+            f"{config.openalex_url}/autocomplete?q={key}", return_meta=False
+        )
+
+
+class Concept(OpenAlexEntity):
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "Concept is deprecated by OpenAlex and replaced by topics.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)
+
+
+class Concepts(BaseOpenAlex):
+    resource_class = Concept
+
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "Concepts is deprecated by OpenAlex and replaced by topics.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)
 
-def Venues(*args, **kwargs):  # deprecated
-    # warn about deprecation
-    warnings.warn(
-        "Venues is deprecated. Use Sources instead.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
 
-    return Sources(*args, **kwargs)
+def autocomplete(s):
+    """autocomplete with any type of entity"""
+    return autocompletes()[s]
 
 
 # aliases

{pyalex-0.13.dist-info → pyalex-0.15.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyalex
-Version: 0.13
+Version: 0.15
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
@@ -30,8 +30,6 @@ Requires-Dist: pytest-xdist ; extra == 'test'
 
 ![PyPI](https://img.shields.io/pypi/v/pyalex) [![DOI](https://zenodo.org/badge/557541347.svg)](https://zenodo.org/badge/latestdoi/557541347)
 
-[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/J535D165/pyalex/badge)](https://securityscorecards.dev/viewer/?uri=github.com/J535D165/pyalex)
-
 
 PyAlex is a Python library for [OpenAlex](https://openalex.org/). OpenAlex is
 an index of hundreds of millions of interconnected scholarly papers, authors,
@@ -49,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
 
@@ -71,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
@@ -89,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
@@ -113,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, Sources, Institutions, Concepts and Topics
 
 ```python
 Authors()["A2887243803"]
@@ -122,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()
@@ -130,6 +140,7 @@ Authors().random()
 Sources().random()
 Institutions().random()
 Concepts().random()
+Topics().random()
 Publishers().random()
 Funders().random()
 ```
@@ -172,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
@@ -331,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).
@@ -404,9 +441,6 @@ pyalex.config.api_key = "<MY_KEY>"
 
 ## Alternatives
 
-[Diophila](https://github.com/smierz/diophila) is a nice Python wrapper for OpenAlex. It takes a slightly
-different approach, especially interesting to those who don't like the pipe operations.
-
 R users can use the excellent [OpenAlexR](https://github.com/ropensci/openalexR) library.
 
 ## License

pyalex-0.15.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyalex/__init__.py,sha256=52XK8om6IVD1Yiq_HYOCR6PUY56sPRHutGM03NOrGMQ,1467
+pyalex/_version.py,sha256=poZz4oZoUd1b8WrBvqHJC0SHzGSqhHsFiUSMJDd_Hcw,408
+pyalex/api.py,sha256=IhqRtjy5LtlYffjaHWxRBmKPSIaaXbGqt8qYhKo9YbE,13235
+pyalex-0.15.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
+pyalex-0.15.dist-info/METADATA,sha256=pkDIkcjUnuqePUCdNdXZeRouKh9p16s5g0N0rcYhXxc,13583
+pyalex-0.15.dist-info/WHEEL,sha256=HiCZjzuy6Dw0hdX5R3LCFPDmFS4BWl8H-8W39XfmgX4,91
+pyalex-0.15.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
+pyalex-0.15.dist-info/RECORD,,

{pyalex-0.13.dist-info → pyalex-0.15.dist-info}/WHEEL

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

pyalex-0.13.dist-info/RECORD

@@ -1,8 +0,0 @@
-pyalex/__init__.py,sha256=UrEW9s9NbULtmmnYUUgfbrDujleV8XQLiMRYGdRnm9M,1137
-pyalex/_version.py,sha256=4Ti_UJ2UR2LyAc9zW9aeUVpFeq-DXxy65V2wynOuCi0,408
-pyalex/api.py,sha256=vefNV54OG1daTrKHSDq9Jcy4JhiYi0HSP3GsEzA47uk,11633
-pyalex-0.13.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
-pyalex-0.13.dist-info/METADATA,sha256=vMMbnCUgNUaw99XlqucQZMfZsOZWrXXJOmRpPJsTdSU,12916
-pyalex-0.13.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
-pyalex-0.13.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
-pyalex-0.13.dist-info/RECORD,,