pyalex 0.16__py3-none-any.whl → 0.17__py3-none-any.whl

pyalex/__init__.py

@@ -18,6 +18,7 @@ from pyalex.api import Funders
 from pyalex.api import Institution
 from pyalex.api import Institutions
 from pyalex.api import Journals
+from pyalex.api import OpenAlexResponseList
 from pyalex.api import People
 from pyalex.api import Publisher
 from pyalex.api import Publishers
@@ -61,4 +62,5 @@ __all__ = [
     "autocomplete",
     "config",
     "invert_abstract",
+    "OpenAlexResponseList",
 ]

pyalex/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.16'
-__version_tuple__ = version_tuple = (0, 16)
+__version__ = version = '0.17'
+__version_tuple__ = version_tuple = (0, 17)

pyalex/api.py

@@ -1,6 +1,7 @@
 import logging
 import warnings
 from urllib.parse import quote_plus
+from urllib.parse import urlunparse
 
 import requests
 from requests.auth import AuthBase
@@ -13,6 +14,26 @@ except ImportError:
 
 
 class AlexConfig(dict):
+    """Configuration class for OpenAlex API.
+
+    Attributes
+    ----------
+    email : str
+        Email address for API requests.
+    api_key : str
+        API key for authentication.
+    user_agent : str
+        User agent string for API requests.
+    openalex_url : str
+        Base URL for OpenAlex API.
+    max_retries : int
+        Maximum number of retries for API requests.
+    retry_backoff_factor : float
+        Backoff factor for retries.
+    retry_http_codes : list
+        List of HTTP status codes to retry on.
+    """
+
     def __getattr__(self, key):
         return super().__getitem__(key)
 
@@ -32,10 +53,22 @@ config = AlexConfig(
 
 
 class or_(dict):
+    """Logical OR expression class."""
+
     pass
 
 
 class _LogicalExpression:
+    """Base class for logical expressions.
+
+    Attributes
+    ----------
+    token : str
+        Token representing the logical operation.
+    value : any
+        Value to be used in the logical expression.
+    """
+
     token = None
 
     def __init__(self, value):
@@ -46,14 +79,20 @@ class _LogicalExpression:
 
 
 class not_(_LogicalExpression):
+    """Logical NOT expression class."""
+
     token = "!"
 
 
 class gt_(_LogicalExpression):
+    """Logical greater than expression class."""
+
     token = ">"
 
 
 class lt_(_LogicalExpression):
+    """Logical less than expression class."""
+
     token = "<"
 
 
@@ -61,6 +100,16 @@ def _quote_oa_value(v):
     """Prepare a value for the OpenAlex API.
 
     Applies URL encoding to strings and converts booleans to lowercase strings.
+
+    Parameters
+    ----------
+    v : any
+        Value to be prepared.
+
+    Returns
+    -------
+    any
+        Prepared value.
     """
 
     # workaround for bug https://groups.google.com/u/1/g/openalex-users/c/t46RWnzZaXc
@@ -78,6 +127,22 @@ def _quote_oa_value(v):
 
 
 def _flatten_kv(d, prefix=None, logical="+"):
+    """Flatten a dictionary into a key-value string for the OpenAlex API.
+
+    Parameters
+    ----------
+    d : dict
+        Dictionary to be flattened.
+    prefix : str, optional
+        Prefix for the keys.
+    logical : str, optional
+        Logical operator to join values.
+
+    Returns
+    -------
+    str
+        Flattened key-value string.
+    """
     if prefix is None and not isinstance(d, dict):
         raise ValueError("prefix should be set if d is not a dict")
 
@@ -100,6 +165,15 @@ def _flatten_kv(d, prefix=None, logical="+"):
 
 
 def _params_merge(params, add_params):
+    """Merge additional parameters into existing parameters.
+
+    Parameters
+    ----------
+    params : dict
+        Existing parameters.
+    add_params : dict
+        Additional parameters to be merged.
+    """
     for k in add_params.keys():
         if (
             k in params
@@ -128,6 +202,13 @@ def _params_merge(params, add_params):
 
 
 def _get_requests_session():
+    """Create a Requests session with automatic retry.
+
+    Returns
+    -------
+    requests.Session
+        Requests session with retry configuration.
+    """
     # create an Requests Session with automatic retry:
     requests_session = requests.Session()
     retries = Retry(
@@ -144,12 +225,38 @@ def _get_requests_session():
 
 
 def invert_abstract(inv_index):
+    """Invert OpenAlex abstract index.
+
+    Parameters
+    ----------
+    inv_index : dict
+        Inverted index of the abstract.
+
+    Returns
+    -------
+    str
+        Inverted abstract.
+    """
     if inv_index is not None:
         l_inv = [(w, p) for w, pos in inv_index.items() for p in pos]
         return " ".join(map(lambda x: x[0], sorted(l_inv, key=lambda x: x[1])))
 
 
 def _wrap_values_nested_dict(d, func):
+    """Apply a function to all values in a nested dictionary.
+
+    Parameters
+    ----------
+    d : dict
+        Nested dictionary.
+    func : function
+        Function to apply to the values.
+
+    Returns
+    -------
+    dict
+        Dictionary with the function applied to the values.
+    """
     for k, v in d.items():
         if isinstance(v, dict):
             d[k] = _wrap_values_nested_dict(v, func)
@@ -162,14 +269,64 @@ def _wrap_values_nested_dict(d, func):
 
 
 class QueryError(ValueError):
+    """Exception raised for errors in the query."""
+
     pass
 
 
 class OpenAlexEntity(dict):
+    """Base class for OpenAlex entities."""
+
     pass
 
 
+class OpenAlexResponseList(list):
+    """A list of OpenAlexEntity objects with metadata.
+
+    Attributes:
+        meta: a dictionary with metadata about the results
+        resource_class: the class to use for each entity in the results
+
+    Arguments:
+        results: a list of OpenAlexEntity objects
+        meta: a dictionary with metadata about the results
+        resource_class: the class to use for each entity in the results
+
+    Returns:
+        a OpenAlexResponseList object
+    """
+
+    def __init__(self, results, meta=None, resource_class=OpenAlexEntity):
+        self.resource_class = resource_class
+        self.meta = meta
+
+        super().__init__([resource_class(ent) for ent in results])
+
+
 class Paginator:
+    """Paginator for OpenAlex API results.
+
+    Attributes
+    ----------
+    VALUE_CURSOR_START : str
+        Starting value for cursor pagination.
+    VALUE_NUMBER_START : int
+        Starting value for page pagination.
+
+    Parameters
+    ----------
+    endpoint_class : class
+        Class of the endpoint to paginate.
+    method : str, optional
+        Pagination method ('cursor' or 'page').
+    value : any, optional
+        Starting value for pagination.
+    per_page : int, optional
+        Number of results per page.
+    n_max : int, optional
+        Maximum number of results.
+    """
+
     VALUE_CURSOR_START = "*"
     VALUE_NUMBER_START = 1
 
@@ -205,32 +362,31 @@ class Paginator:
         else:
             raise ValueError()
 
-        results, meta = self.endpoint_class.get(
-            return_meta=True, per_page=self.per_page, **pagination_params
-        )
+        r = self.endpoint_class.get(per_page=self.per_page, **pagination_params)
 
         if self.method == "cursor":
-            self._next_value = meta["next_cursor"]
+            self._next_value = r.meta["next_cursor"]
 
         if self.method == "page":
-            if len(results) > 0:
-                self._next_value = meta["page"] + 1
+            if len(r) > 0:
+                self._next_value = r.meta["page"] + 1
             else:
                 self._next_value = None
 
-        self.n = self.n + len(results)
+        self.n = self.n + len(r)
 
-        return results
+        return r
 
 
 class OpenAlexAuth(AuthBase):
-    """OpenAlex auth class based on requests auth
-
-    Includes the email, api_key and user-agent headers.
+    """OpenAlex auth class based on requests auth.
 
-    arguments:
-        config: an AlexConfig object
+    Includes the email, api_key, and user-agent headers.
 
+    Parameters
+    ----------
+    config : AlexConfig
+        Configuration object for OpenAlex API.
     """
 
     def __init__(self, config):
@@ -250,29 +406,26 @@ class OpenAlexAuth(AuthBase):
 
 
 class BaseOpenAlex:
-    """Base class for OpenAlex objects."""
+    """Base class for OpenAlex objects.
+
+    Parameters
+    ----------
+    params : dict, optional
+        Parameters for the API request.
+    """
 
     def __init__(self, params=None):
         self.params = params
 
-    def _full_collection_name(self):
-        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":
             raise AttributeError(
-                "Object has no attribute 'groupby'. " "Did you mean 'group_by'?"
+                "Object has no attribute 'groupby'. Did you mean 'group_by'?"
             )
 
         if key == "filter_search":
             raise AttributeError(
-                "Object has no attribute 'filter_search'. "
-                "Did you mean 'search_filter'?"
+                "Object has no attribute 'filter_search'. Did you mean 'search_filter'?"
             )
 
         return getattr(self, key)
@@ -283,42 +436,72 @@ class BaseOpenAlex:
                 raise ValueError("OpenAlex does not support more than 100 ids")
 
             return self.filter_or(openalex_id=record_id).get(per_page=len(record_id))
+        elif isinstance(record_id, str):
+            self.params = record_id
+            return self._get_from_url(self.url)
+        else:
+            raise ValueError("record_id should be a string or a list of strings")
+
+    def _url_query(self):
+        if isinstance(self.params, list):
+            return self.filter_or(openalex_id=self.params)
+        elif isinstance(self.params, dict):
+            l_params = []
+            for k, v in self.params.items():
+                if v is None:
+                    pass
+                elif isinstance(v, list):
+                    l_params.append(
+                        "{}={}".format(k, ",".join(map(_quote_oa_value, v)))
+                    )
+                elif k in ["filter", "sort"]:
+                    l_params.append(f"{k}={_flatten_kv(v)}")
+                else:
+                    l_params.append(f"{k}={_quote_oa_value(v)}")
+
+            if l_params:
+                return "&".join(l_params)
 
-        return self._get_from_url(
-            f"{self._full_collection_name()}/{_quote_oa_value(record_id)}",
-            return_meta=False,
-        )
+        else:
+            return ""
 
     @property
     def url(self):
-        if not self.params:
-            return self._full_collection_name()
-
-        l_params = []
-        for k, v in self.params.items():
-            if v is None:
-                pass
-            elif isinstance(v, list):
-                l_params.append("{}={}".format(k, ",".join(map(_quote_oa_value, v))))
-            elif k in ["filter", "sort"]:
-                l_params.append(f"{k}={_flatten_kv(v)}")
-            else:
-                l_params.append(f"{k}={_quote_oa_value(v)}")
+        """Return the URL for the API request.
 
-        if l_params:
-            return "{}?{}".format(self._full_collection_name(), "&".join(l_params))
+        The URL doens't include the identification, authentication,
+        and pagination parameters.
 
-        return self._full_collection_name()
+
+        Returns
+        -------
+        str
+            URL for the API request.
+        """
+        base_path = self.__class__.__name__.lower()
+
+        if isinstance(self.params, str):
+            path = f"{base_path}/{_quote_oa_value(self.params)}"
+            query = ""
+        else:
+            path = base_path
+            query = self._url_query()
+
+        return urlunparse(("https", "api.openalex.org", path, "", query, ""))
 
     def count(self):
-        _, m = self.get(return_meta=True, per_page=1)
+        """Get the count of results.
 
-        return m["count"]
+        Returns
+        -------
+        int
+            Count of results.
+        """
+        return self.get(per_page=1).meta["count"]
 
-    def _get_from_url(self, url, return_meta=False):
+    def _get_from_url(self, url):
         res = _get_requests_session().get(url, auth=OpenAlexAuth(config))
 
-        # handle query errors
         if res.status_code == 403:
             if (
                 isinstance(res.json()["error"], str)
@@ -329,32 +512,61 @@ class BaseOpenAlex:
         res.raise_for_status()
         res_json = res.json()
 
-        # group-by or results page
         if self.params and "group-by" in self.params:
-            results = res_json["group_by"]
+            return OpenAlexResponseList(
+                res_json["group_by"], res_json["meta"], self.resource_class
+            )
         elif "results" in res_json:
-            results = [self.resource_class(ent) for ent in res_json["results"]]
+            return OpenAlexResponseList(
+                res_json["results"], res_json["meta"], self.resource_class
+            )
         elif "id" in res_json:
-            results = self.resource_class(res_json)
+            return self.resource_class(res_json)
         else:
             raise ValueError("Unknown response format")
 
-        # return result and metadata
-        if return_meta:
-            return results, res_json["meta"]
-        else:
-            return results
-
     def get(self, return_meta=False, page=None, per_page=None, cursor=None):
         if per_page is not None and (per_page < 1 or per_page > 200):
             raise ValueError("per_page should be a number between 1 and 200.")
 
-        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)
+        if not isinstance(self.params, (str, list)):
+            self._add_params("per-page", per_page)
+            self._add_params("page", page)
+            self._add_params("cursor", cursor)
+
+        resp_list = self._get_from_url(self.url)
+
+        if return_meta:
+            warnings.warn(
+                "return_meta is deprecated, call .meta on the result",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return resp_list, resp_list.meta
+        else:
+            return resp_list
 
     def paginate(self, method="cursor", page=1, per_page=None, cursor="*", n_max=10000):
+        """Paginate results from the API.
+
+        Parameters
+        ----------
+        method : str, optional
+            Pagination method ('cursor' or 'page').
+        page : int, optional
+            Page number for pagination.
+        per_page : int, optional
+            Number of results per page.
+        cursor : str, optional
+            Cursor for pagination.
+        n_max : int, optional
+            Maximum number of results.
+
+        Returns
+        -------
+        Paginator
+            Paginator object.
+        """
         if method == "cursor":
             if self.params.get("sample"):
                 raise ValueError("method should be 'page' when using sample")
@@ -369,9 +581,27 @@ class BaseOpenAlex:
         )
 
     def random(self):
+        """Get a random result.
+
+        Returns
+        -------
+        OpenAlexEntity
+            Random result.
+        """
         return self.__getitem__("random")
 
     def _add_params(self, argument, new_params, raise_if_exists=False):
+        """Add parameters to the API request.
+
+        Parameters
+        ----------
+        argument : str
+            Parameter name.
+        new_params : any
+            Parameter value.
+        raise_if_exists : bool, optional
+            Whether to raise an error if the parameter already exists.
+        """
         if raise_if_exists:
             raise NotImplementedError("raise_if_exists is not implemented")
 
@@ -385,63 +615,247 @@ class BaseOpenAlex:
         logging.debug("Params updated:", self.params)
 
     def filter(self, **kwargs):
+        """Add filter parameters to the API request.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Filter parameters.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("filter", kwargs)
         return self
 
     def filter_and(self, **kwargs):
+        """Add AND filter parameters to the API request.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Filter parameters.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         return self.filter(**kwargs)
 
     def filter_or(self, **kwargs):
+        """Add OR filter parameters to the API request.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Filter parameters.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("filter", or_(kwargs), raise_if_exists=False)
         return self
 
     def filter_not(self, **kwargs):
+        """Add NOT filter parameters to the API request.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Filter parameters.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("filter", _wrap_values_nested_dict(kwargs, not_))
         return self
 
     def filter_gt(self, **kwargs):
+        """Add greater than filter parameters to the API request.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Filter parameters.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("filter", _wrap_values_nested_dict(kwargs, gt_))
         return self
 
     def filter_lt(self, **kwargs):
+        """Add less than filter parameters to the API request.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Filter parameters.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("filter", _wrap_values_nested_dict(kwargs, lt_))
         return self
 
     def search_filter(self, **kwargs):
+        """Add search filter parameters to the API request.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Filter parameters.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("filter", {f"{k}.search": v for k, v in kwargs.items()})
         return self
 
     def sort(self, **kwargs):
+        """Add sort parameters to the API request.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Sort parameters.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("sort", kwargs)
         return self
 
     def group_by(self, group_key):
+        """Add group-by parameters to the API request.
+
+        Parameters
+        ----------
+        group_key : str
+            Group-by key.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("group-by", group_key)
         return self
 
     def search(self, s):
+        """Add search parameters to the API request.
+
+        Parameters
+        ----------
+        s : str
+            Search string.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("search", s)
         return self
 
     def sample(self, n, seed=None):
+        """Add sample parameters to the API request.
+
+        Parameters
+        ----------
+        n : int
+            Number of samples.
+        seed : int, optional
+            Seed for sampling.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("sample", n)
         self._add_params("seed", seed)
         return self
 
     def select(self, s):
+        """Add select parameters to the API request.
+
+        Parameters
+        ----------
+        s : str
+            Select string.
+
+        Returns
+        -------
+        BaseOpenAlex
+            Updated object.
+        """
         self._add_params("select", s)
         return self
 
-    def autocomplete(self, s, **kwargs):
-        """autocomplete the string s, for a specific type of entity"""
+    def autocomplete(self, s, return_meta=False):
+        """Return the OpenAlex autocomplete results.
+
+        Parameters
+        ----------
+        s : str
+            String to autocomplete.
+        return_meta : bool, optional
+            Whether to return metadata.
+
+        Returns
+        -------
+        OpenAlexResponseList
+            List of autocomplete results.
+        """
+
         self._add_params("q", s)
-        return self.get(**kwargs)
+
+        resp_list = self._get_from_url(
+            urlunparse(
+                (
+                    "https",
+                    "api.openalex.org",
+                    f"autocomplete/{self.__class__.__name__.lower()}",
+                    "",
+                    self._url_query(),
+                    "",
+                )
+            )
+        )
+
+        if return_meta:
+            warnings.warn(
+                "return_meta is deprecated, call .meta on the result",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return resp_list, resp_list.meta
+        else:
+            return resp_list
 
 
 # The API
 
 
 class Work(OpenAlexEntity):
+    """Class representing a work entity in OpenAlex."""
+
     def __getitem__(self, key):
         if key == "abstract":
             return invert_abstract(self["abstract_inverted_index"])
@@ -449,6 +863,18 @@ class Work(OpenAlexEntity):
         return super().__getitem__(key)
 
     def ngrams(self, return_meta=False):
+        """Get n-grams for the work.
+
+        Parameters
+        ----------
+        return_meta : bool, optional
+            Whether to return metadata.
+
+        Returns
+        -------
+        OpenAlexResponseList
+            List of n-grams.
+        """
         openalex_id = self["id"].split("/")[-1]
         n_gram_url = f"{config.openalex_url}/works/{openalex_id}/ngrams"
 
@@ -456,105 +882,162 @@ class Work(OpenAlexEntity):
         res.raise_for_status()
         results = res.json()
 
-        # return result and metadata
+        resp_list = OpenAlexResponseList(results["ngrams"], results["meta"])
+
         if return_meta:
-            return results["ngrams"], results["meta"]
+            warnings.warn(
+                "return_meta is deprecated, call .meta on the result",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return resp_list, resp_list.meta
         else:
-            return results["ngrams"]
+            return resp_list
 
 
 class Works(BaseOpenAlex):
+    """Class representing a collection of work entities in OpenAlex."""
+
     resource_class = Work
 
 
 class Author(OpenAlexEntity):
+    """Class representing an author entity in OpenAlex."""
+
     pass
 
 
 class Authors(BaseOpenAlex):
+    """Class representing a collection of author entities in OpenAlex."""
+
     resource_class = Author
 
 
 class Source(OpenAlexEntity):
+    """Class representing a source entity in OpenAlex."""
+
     pass
 
 
 class Sources(BaseOpenAlex):
+    """Class representing a collection of source entities in OpenAlex."""
+
     resource_class = Source
 
 
 class Institution(OpenAlexEntity):
+    """Class representing an institution entity in OpenAlex."""
+
     pass
 
 
 class Institutions(BaseOpenAlex):
+    """Class representing a collection of institution entities in OpenAlex."""
+
     resource_class = Institution
 
 
 class Domain(OpenAlexEntity):
+    """Class representing a domain entity in OpenAlex."""
+
     pass
 
 
 class Domains(BaseOpenAlex):
+    """Class representing a collection of domain entities in OpenAlex."""
+
     resource_class = Domain
 
 
 class Field(OpenAlexEntity):
+    """Class representing a field entity in OpenAlex."""
+
     pass
 
 
 class Fields(BaseOpenAlex):
+    """Class representing a collection of field entities in OpenAlex."""
+
     resource_class = Field
 
 
 class Subfield(OpenAlexEntity):
+    """Class representing a subfield entity in OpenAlex."""
+
     pass
 
 
 class Subfields(BaseOpenAlex):
+    """Class representing a collection of subfield entities in OpenAlex."""
+
     resource_class = Subfield
 
 
 class Topic(OpenAlexEntity):
+    """Class representing a topic entity in OpenAlex."""
+
     pass
 
 
 class Topics(BaseOpenAlex):
+    """Class representing a collection of topic entities in OpenAlex."""
+
     resource_class = Topic
 
 
 class Publisher(OpenAlexEntity):
+    """Class representing a publisher entity in OpenAlex."""
+
     pass
 
 
 class Publishers(BaseOpenAlex):
+    """Class representing a collection of publisher entities in OpenAlex."""
+
     resource_class = Publisher
 
 
 class Funder(OpenAlexEntity):
+    """Class representing a funder entity in OpenAlex."""
+
     pass
 
 
 class Funders(BaseOpenAlex):
+    """Class representing a collection of funder entities in OpenAlex."""
+
     resource_class = Funder
 
 
 class Autocomplete(OpenAlexEntity):
+    """Class representing an autocomplete entity in OpenAlex."""
+
     pass
 
 
 class autocompletes(BaseOpenAlex):
-    """Class to autocomplete without being based on the type of entity"""
+    """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
+            urlunparse(
+                (
+                    "https",
+                    "api.openalex.org",
+                    "autocomplete",
+                    "",
+                    f"q={quote_plus(key)}",
+                    "",
+                )
+            )
         )
 
 
 class Concept(OpenAlexEntity):
+    """Class representing a concept entity in OpenAlex."""
+
     def __init__(self, *args, **kwargs):
         warnings.warn(
             "Concept is deprecated by OpenAlex and replaced by topics.",
@@ -565,6 +1048,8 @@ class Concept(OpenAlexEntity):
 
 
 class Concepts(BaseOpenAlex):
+    """Class representing a collection of concept entities in OpenAlex."""
+
     resource_class = Concept
 
     def __init__(self, *args, **kwargs):
@@ -577,7 +1062,18 @@ class Concepts(BaseOpenAlex):
 
 
 def autocomplete(s):
-    """autocomplete with any type of entity"""
+    """Autocomplete with any type of entity.
+
+    Parameters
+    ----------
+    s : str
+        String to autocomplete.
+
+    Returns
+    -------
+    OpenAlexResponseList
+        List of autocomplete results.
+    """
     return autocompletes()[s]
 
 

{pyalex-0.16.dist-info → pyalex-0.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pyalex
-Version: 0.16
+Version: 0.17
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
@@ -182,11 +182,11 @@ 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 = Topics().get(return_meta=True)
+topics = Topics().get()
 ```
 
 ```python
-print(meta)
+print(topics.meta)
 {'count': 65073, 'db_response_time_ms': 16, 'page': 1, 'per_page': 25}
 ```
 

pyalex-0.17.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyalex/__init__.py,sha256=upMXti6aJF6lz8J4EbdnQa13GhJzFGre7fnS_tj8NOw,1539
+pyalex/_version.py,sha256=t3d5dJC864lqQ-TUIs6gpWRp7YVH04dI08mpFt6wvR0,508
+pyalex/api.py,sha256=05clKZlIcH7g7G5d7tELxrfUIyyzdPKwbRinZ1Pliy4,26783
+pyalex-0.17.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
+pyalex-0.17.dist-info/METADATA,sha256=3K3i_n7uMyF91DfrwFI5t0X5jaYD8lD2HcySMNHcfbg,14208
+pyalex-0.17.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
+pyalex-0.17.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
+pyalex-0.17.dist-info/RECORD,,

{pyalex-0.16.dist-info → pyalex-0.17.dist-info}/WHEEL

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

pyalex-0.16.dist-info/RECORD

@@ -1,8 +0,0 @@
-pyalex/__init__.py,sha256=52XK8om6IVD1Yiq_HYOCR6PUY56sPRHutGM03NOrGMQ,1467
-pyalex/_version.py,sha256=5zc7xTIiU-8qDWOhJyQ0RIy_saYu1BECCONIFoa0eLw,508
-pyalex/api.py,sha256=YqVMwNEkg_LQdIVzOSXHe4bRhfNFg_YmCJqG1MoY23Y,14993
-pyalex-0.16.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
-pyalex-0.16.dist-info/METADATA,sha256=7qIHsL5k8LL01z7Yc8_zpuJnGH3Av23THNz4g6QLZWI,14224
-pyalex-0.16.dist-info/WHEEL,sha256=nn6H5-ilmfVryoAQl3ZQ2l8SH5imPWFpm1A5FgEuFV4,91
-pyalex-0.16.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
-pyalex-0.16.dist-info/RECORD,,