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

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.15.1'
-__version_tuple__ = version_tuple = (0, 15, 1)
+__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)
 
@@ -31,40 +52,129 @@ 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):
+        self.value = value
+
+    def __str__(self) -> str:
+        return f"{self.token}{self.value}"
+
+
+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 = "<"
+
+
 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
     if isinstance(v, bool):
         return str(v).lower()
 
+    if isinstance(v, _LogicalExpression) and isinstance(v.value, str):
+        v.value = quote_plus(v.value)
+        return v
+
     if isinstance(v, str):
         return quote_plus(v)
 
     return v
 
 
-def _flatten_kv(d, prefix=""):
+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")
+
     if isinstance(d, dict):
+        logical_subd = "|" if isinstance(d, or_) else logical
+
         t = []
         for k, v in d.items():
-            if isinstance(v, list):
-                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)
-                t.append(x)
+            x = _flatten_kv(
+                v, prefix=f"{prefix}.{k}" if prefix else f"{k}", logical=logical_subd
+            )
+            t.append(x)
 
         return ",".join(t)
+    elif isinstance(d, list):
+        list_str = logical.join([f"{_quote_oa_value(i)}" for i in d])
+        return f"{prefix}:{list_str}"
     else:
         return f"{prefix}:{_quote_oa_value(d)}"
 
 
 def _params_merge(params, add_params):
-    for k, _v in add_params.items():
+    """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
             and isinstance(params[k], dict)
@@ -92,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(
@@ -108,20 +225,108 @@ 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)
+        elif isinstance(v, list):
+            d[k] = [func(i) for i in v]
+        else:
+            d[k] = func(v)
+
+    return d
+
+
 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
 
@@ -157,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):
@@ -202,74 +406,102 @@ 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 _get_multi_items(self, record_list):
-        return self.filter(openalex_id="|".join(record_list)).get()
-
-    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)
 
     def __getitem__(self, record_id):
         if isinstance(record_id, list):
-            return self._get_multi_items(record_id)
+            if len(record_id) > 100:
+                raise ValueError("OpenAlex does not support more than 100 ids")
 
-        return self._get_from_url(
-            f"{self._full_collection_name()}/{record_id}", return_meta=False
-        )
+            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)
+
+        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.
+
+        The URL doens't include the identification, authentication,
+        and pagination parameters.
 
-        if l_params:
-            return "{}?{}".format(self._full_collection_name(), "&".join(l_params))
 
-        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)
@@ -280,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")
@@ -320,9 +581,30 @@ class BaseOpenAlex:
         )
 
     def random(self):
+        """Get a random result.
+
+        Returns
+        -------
+        OpenAlexEntity
+            Random result.
+        """
         return self.__getitem__("random")
 
-    def _add_params(self, argument, new_params):
+    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")
+
         if self.params is None:
             self.params = {argument: new_params}
         elif argument in self.params and isinstance(self.params[argument], dict):
@@ -333,44 +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"])
@@ -378,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"
 
@@ -385,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.",
@@ -494,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):
@@ -506,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.15.1.dist-info → pyalex-0.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pyalex
-Version: 0.15.1
+Version: 0.17
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
@@ -17,10 +17,10 @@ License-File: LICENSE
 Requires-Dist: requests
 Requires-Dist: urllib3
 Provides-Extra: lint
-Requires-Dist: ruff ; extra == 'lint'
+Requires-Dist: ruff; extra == "lint"
 Provides-Extra: test
-Requires-Dist: pytest ; extra == 'test'
-Requires-Dist: pytest-xdist ; 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">
@@ -126,7 +126,7 @@ Works()["W2741809807"]["open_access"]
 The previous works also for Authors, Sources, Institutions, Concepts and Topics
 
 ```python
-Authors()["A2887243803"]
+Authors()["A5027479191"]
 Authors()["https://orcid.org/0000-0002-4297-0502"]  # same
 ```
 
@@ -139,7 +139,6 @@ Works().random()
 Authors().random()
 Sources().random()
 Institutions().random()
-Concepts().random()
 Topics().random()
 Publishers().random()
 Funders().random()
@@ -183,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}
 ```
 
@@ -383,6 +382,10 @@ Works()["W2023271753"].ngrams()
 All results from PyAlex can be serialized. For example, save the results to a JSON file:
 
 ```python
+import json
+from pathlib import Path
+from pyalex import Work
+
 with open(Path("works.json"), "w") as f:
     json.dump(Works().get(), f)
 
@@ -394,7 +397,7 @@ with open(Path("works.json")) as f:
 
 A list of awesome use cases of the OpenAlex dataset.
 
-### Cited publications (referenced works)
+### Cited publications (works referenced by this paper, outgoing citations)
 
 ```python
 from pyalex import Works
@@ -405,6 +408,13 @@ w = Works()["W2741809807"]
 Works()[w["referenced_works"]]
 ```
 
+### Citing publications (other works that reference this paper, incoming citations)
+
+```python
+from pyalex import Works
+Works().filter(cites="W2741809807").get()
+```
+
 ### Get works of a single author
 
 ```python
@@ -463,6 +473,7 @@ R users can use the excellent [OpenAlexR](https://github.com/ropensci/openalexR)
 
 > This library is a community contribution. The authors of this Python library aren't affiliated with OpenAlex.
 
+This library is maintained by [J535D165](https://github.com/J535D165) and [PeterLombaers](https://github.com/PeterLombaers).
 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
+[issue tracker](/issues) is a good starting point. You can also reach out via
 [jonathandebruinos@gmail.com](mailto:jonathandebruinos@gmail.com).

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.15.1.dist-info → pyalex-0.17.dist-info}/WHEEL

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

pyalex-0.15.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-pyalex/__init__.py,sha256=52XK8om6IVD1Yiq_HYOCR6PUY56sPRHutGM03NOrGMQ,1467
-pyalex/_version.py,sha256=po5_rvCFTU8xU9IC56wyK0-zfBgz_U4xX6CO2mv9Mzs,413
-pyalex/api.py,sha256=JTOx0P037IOhhYVAigQO5uPsd1HMQC-SM3wny0_52uU,13236
-pyalex-0.15.1.dist-info/LICENSE,sha256=Mhf5MImRYP06a1EPVJCpkpTstOOEfGajN3T_Fz4izMg,1074
-pyalex-0.15.1.dist-info/METADATA,sha256=JSa8cKcjZUZ-lDo28WyuFN1GHEEWUHWLvSLaKh3IP10,13859
-pyalex-0.15.1.dist-info/WHEEL,sha256=Mdi9PDNwEZptOjTlUcAth7XJDFtKrHYaQMPulZeBCiQ,91
-pyalex-0.15.1.dist-info/top_level.txt,sha256=D0An8hWy9e0xPhTaT6K-yuJKVeVV3bYGxZ6Y-v2WXSU,7
-pyalex-0.15.1.dist-info/RECORD,,