Add native support for expressions via filters

[J535D165]

New

Add support for non-nested lists (e.g. list openalex_id's)

The following example didn't work before.

        Works()
        .filter(
            doi=[
                "https://doi.org/10.1207/s15327809jls0703&4_2",
                "https://doi.org/10.1001/jama.264.8.944b",
            ]
        )
        .count()

However, this results 0 in the latest API after this fix. This is because all lists are AND lists. There is no builtin OR list, which is needed for this example.

Add support for OR lists

This PR introduces the OR filter. This filter makes all arguments passed OR arguments if they contain multiple values.

        Works()
        .filter_or(
            doi=[
                "https://doi.org/10.1207/s15327809jls0703&4_2",
                "https://doi.org/10.1001/jama.264.8.944b",
            ]
        )
        .count()
        == 2

Add support for NOT, >, <

It's even better; there are also filter_not, filter_gt, and filter_lt. For example:

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"

Get 100 items in single call

Getting multiple items via OpenAlex keys now returns a maximum of 100 results (instead of 25).

Works()[id1, id2, ..., id100]

Issue in OpenAlex REST API

For URL readability, PyAlex separates multi-valued keys with the AND token (+). OpenAlex supports this as described in https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists#intersection-and. The alternative is to use repeating filters as described in the docs.

This works fine for basic filters but is inconsistent for more complex queries. For example, let's search for publications after 2021 but exclude 2023. This is straightforward:

https://api.openalex.org/works?filter=publication_year:>2021,publication_year:!2023

However, the alternative (preferred by PyAlex) doesn't work:

https://api.openalex.org/works?filter=publication_year:>2021+!2023

raises {"error":"Invalid query parameters error.","message":"Value for param publication_year must be a number."}

Last time I looked, OpenAlex used Flask for the REST API. Flask offers support for repeated arguments, but Flask might not natively support the +.

PyAlex will fail now on this:

Works().filter_gt(publication_year=2021).filter_not(publication_year=2023).url
    == "https://api.openalex.org/works?filter=publication_year:>2021+!2023"

TODO

• Add docs
• Wait for OpenAlex to fix this, or move to repeated filters.

[J535D165]

I don't think OpenAlex plans to fix the issue shared in this PR. I will merge this PR so that we can move forward with some other changes.