pyalex 0.15__tar.gz → 0.16__tar.gz

{pyalex-0.15 → pyalex-0.16}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.6.0
+  rev: v5.0.0
   hooks:
   - id: trailing-whitespace
   - id: end-of-file-fixer
@@ -8,7 +8,7 @@ repos:
   - id: check-yaml
   - id: check-added-large-files
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.5.7
+  rev: v0.8.3
   hooks:
   - id: ruff
     args: [--fix]

{pyalex-0.15 → pyalex-0.16}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pyalex
-Version: 0.15
+Version: 0.16
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
@@ -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()
@@ -378,11 +377,27 @@ Works()["W2023271753"].ngrams()
 ```
 
 
+### Serialize
+
+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)
+
+with open(Path("works.json")) as f:
+    works = [Work(w) for w in json.load(f)]
+```
+
 ## Code snippets
 
 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
@@ -393,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
@@ -451,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.15 → pyalex-0.16}/README.md

@@ -102,7 +102,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
 ```
 
@@ -115,7 +115,6 @@ Works().random()
 Authors().random()
 Sources().random()
 Institutions().random()
-Concepts().random()
 Topics().random()
 Publishers().random()
 Funders().random()
@@ -354,11 +353,27 @@ Works()["W2023271753"].ngrams()
 ```
 
 
+### Serialize
+
+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)
+
+with open(Path("works.json")) as f:
+    works = [Work(w) for w in json.load(f)]
+```
+
 ## Code snippets
 
 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
@@ -369,6 +384,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
@@ -427,6 +449,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.15 → pyalex-0.16}/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'
-__version_tuple__ = version_tuple = (0, 15)
+__version__ = version = '0.16'
+__version_tuple__ = version_tuple = (0, 16)

{pyalex-0.15 → pyalex-0.16}/pyalex/api.py

@@ -23,7 +23,7 @@ class AlexConfig(dict):
 config = AlexConfig(
     email=None,
     api_key=None,
-    user_agent="pyalex/{__version__}",
+    user_agent=f"pyalex/{__version__}",
     openalex_url="https://api.openalex.org",
     max_retries=0,
     retry_backoff_factor=0.1,
@@ -31,6 +31,32 @@ config = AlexConfig(
 )
 
 
+class or_(dict):
+    pass
+
+
+class _LogicalExpression:
+    token = None
+
+    def __init__(self, value):
+        self.value = value
+
+    def __str__(self) -> str:
+        return f"{self.token}{self.value}"
+
+
+class not_(_LogicalExpression):
+    token = "!"
+
+
+class gt_(_LogicalExpression):
+    token = ">"
+
+
+class lt_(_LogicalExpression):
+    token = "<"
+
+
 def _quote_oa_value(v):
     """Prepare a value for the OpenAlex API.
 
@@ -41,30 +67,40 @@ def _quote_oa_value(v):
     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="+"):
+    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():
+    for k in add_params.keys():
         if (
             k in params
             and isinstance(params[k], dict)
@@ -113,6 +149,18 @@ def invert_abstract(inv_index):
         return " ".join(map(lambda x: x[0], sorted(l_inv, key=lambda x: x[1])))
 
 
+def _wrap_values_nested_dict(d, func):
+    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):
     pass
 
@@ -207,9 +255,6 @@ class BaseOpenAlex:
     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 (
@@ -234,10 +279,14 @@ class BaseOpenAlex:
 
     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.filter_or(openalex_id=record_id).get(per_page=len(record_id))
 
         return self._get_from_url(
-            f"{self._full_collection_name()}/{record_id}", return_meta=False
+            f"{self._full_collection_name()}/{_quote_oa_value(record_id)}",
+            return_meta=False,
         )
 
     @property
@@ -322,7 +371,10 @@ class BaseOpenAlex:
     def random(self):
         return self.__getitem__("random")
 
-    def _add_params(self, argument, new_params):
+    def _add_params(self, argument, new_params, raise_if_exists=False):
+        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):
@@ -336,6 +388,25 @@ class BaseOpenAlex:
         self._add_params("filter", kwargs)
         return self
 
+    def filter_and(self, **kwargs):
+        return self.filter(**kwargs)
+
+    def filter_or(self, **kwargs):
+        self._add_params("filter", or_(kwargs), raise_if_exists=False)
+        return self
+
+    def filter_not(self, **kwargs):
+        self._add_params("filter", _wrap_values_nested_dict(kwargs, not_))
+        return self
+
+    def filter_gt(self, **kwargs):
+        self._add_params("filter", _wrap_values_nested_dict(kwargs, gt_))
+        return self
+
+    def filter_lt(self, **kwargs):
+        self._add_params("filter", _wrap_values_nested_dict(kwargs, lt_))
+        return self
+
     def search_filter(self, **kwargs):
         self._add_params("filter", {f"{k}.search": v for k, v in kwargs.items()})
         return self

{pyalex-0.15 → pyalex-0.16}/pyalex.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pyalex
-Version: 0.15
+Version: 0.16
 Summary: Python interface to the OpenAlex database
 Author-email: Jonathan de Bruin <jonathandebruinos@gmail.com>
 License: MIT
@@ -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()
@@ -378,11 +377,27 @@ Works()["W2023271753"].ngrams()
 ```
 
 
+### Serialize
+
+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)
+
+with open(Path("works.json")) as f:
+    works = [Work(w) for w in json.load(f)]
+```
+
 ## Code snippets
 
 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
@@ -393,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
@@ -451,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.15 → pyalex-0.16}/tests/test_pyalex.py

@@ -117,7 +117,12 @@ def test_multi_works():
     # the work to extract the referenced works of
     w = Works()["W2741809807"]
 
-    assert len(Works()[w["referenced_works"]]) == 25
+    assert len(Works()[w["referenced_works"]]) >= 38
+
+    assert (
+        len(Works().filter_or(openalex_id=w["referenced_works"]).get(per_page=100))
+        >= 38
+    )
 
 
 def test_works_multifilter():
@@ -204,13 +209,17 @@ def test_referenced_works():
     # the work to extract the referenced works of
     w = Works()["W2741809807"]
 
-    _, m = (
+    w_new, m = (
         Works()
         .filter(openalex_id="|".join(w["referenced_works"]))
-        .get(return_meta=True)
+        .get(return_meta=True, per_page=100)
     )
 
-    assert m["count"] == len(w["referenced_works"])
+    assert set([w["id"] for w in w_new]).difference(set(w["referenced_works"])) == set()
+    # assert set(w["referenced_works"]).difference(set([w["id"] for w in w_new]))
+    #  == set()
+
+    assert m["count"] < len(w["referenced_works"])
 
 
 @pytest.mark.xfail()
@@ -244,12 +253,25 @@ def test_serializable(tmpdir):
         assert "W4238809453" in json.load(f)["id"]
 
 
+def test_serializable_list(tmpdir):
+    with open(Path(tmpdir, "test.json"), "w") as f:
+        json.dump(Works().get(), f)
+
+    with open(Path(tmpdir, "test.json")) as f:
+        works = [Work(w) for w in json.load(f)]
+
+    assert len(works) == 25
+    assert all(isinstance(w, Work) for w in works)
+
+
+@pytest.mark.skip("This test is not working due to unavailable API.")
 def test_ngrams_without_metadata():
     r = Works()["W2023271753"].ngrams(return_meta=False)
 
     assert len(r) == 1068
 
 
+@pytest.mark.skip("This test is not working due to unavailable API.")
 def test_ngrams_with_metadata():
     r, meta = Works()["W2023271753"].ngrams(return_meta=True)
 
@@ -261,33 +283,80 @@ def test_random_publishers():
 
 
 def test_and_operator():
-    # https://github.com/J535D165/pyalex/issues/11
-    url = "https://api.openalex.org/works?filter=institutions.country_code:tw,institutions.country_code:hk,institutions.country_code:us,publication_year:2022"
+    urls = [
+        "https://api.openalex.org/works?filter=institutions.country_code:tw,institutions.country_code:hk,institutions.country_code:us,publication_year:2022",
+        "https://api.openalex.org/works?filter=institutions.country_code:tw+hk+us,publication_year:2022",
+    ]
 
     assert (
-        url
-        == Works()
+        Works()
         .filter(
             institutions={"country_code": ["tw", "hk", "us"]}, publication_year=2022
         )
         .url
+        in urls
     )
     assert (
-        url
-        == Works()
+        Works()
         .filter(institutions={"country_code": "tw"})
         .filter(institutions={"country_code": "hk"})
         .filter(institutions={"country_code": "us"})
         .filter(publication_year=2022)
         .url
+        in urls
     )
     assert (
-        url
-        == Works()
+        Works()
         .filter(institutions={"country_code": ["tw", "hk"]})
         .filter(institutions={"country_code": "us"})
         .filter(publication_year=2022)
         .url
+        in urls
+    )
+
+
+def test_or_operator():
+    assert (
+        Works()
+        .filter_or(
+            institutions={"country_code": ["tw", "hk", "us"]}, publication_year=2022
+        )
+        .url
+        == "https://api.openalex.org/works?filter=institutions.country_code:tw|hk|us,publication_year:2022"
+    )
+
+
+def test_not_operator():
+    assert (
+        Works()
+        .filter_not(institutions={"country_code": "us"})
+        .filter(publication_year=2022)
+        .url
+        == "https://api.openalex.org/works?filter=institutions.country_code:!us,publication_year:2022"
+    )
+
+
+def test_not_operator_list():
+    assert (
+        Works()
+        .filter_not(institutions={"country_code": ["tw", "hk", "us"]})
+        .filter(publication_year=2022)
+        .url
+        == "https://api.openalex.org/works?filter=institutions.country_code:!tw+!hk+!us,publication_year:2022"
+    )
+
+
+@pytest.mark.skip("Wait for feedback on issue by OpenAlex")
+def test_combined_operators():
+    # works:
+    # https://api.openalex.org/works?filter=publication_year:>2022,publication_year:!2023
+
+    # doesn't work
+    # https://api.openalex.org/works?filter=publication_year:>2022+!2023
+
+    assert (
+        Works().filter_gt(publication_year=2022).filter_not(publication_year=2023).url
+        == "https://api.openalex.org/works?filter=publication_year:>2022+!2023"
     )
 
 
@@ -342,11 +411,10 @@ def test_filter_urlencoding():
     )
 
 
-@pytest.mark.skip("This test is not working due to inconsistencies in the API.")
 def test_urlencoding_list():
     assert (
         Works()
-        .filter(
+        .filter_or(
             doi=[
                 "https://doi.org/10.1207/s15327809jls0703&4_2",
                 "https://doi.org/10.1001/jama.264.8.944b",