WorksQuery class

class habanero.WorksQuery(cr=None)[source]

Query builder for the Crossref API’s works endpoint.

Iterating over an instance (for item in q) yields individual work records as dict[str, Any]. Calling execute() returns the raw Crossref API response as dict[str, Any] (the full envelope including message, status, etc.). Calling count() returns an int. Calling url() returns a str.

All builder methods (query(), filter(), sort(), order(), select(), facet(), limit(), cursor()) return a new WorksQuery instance — the original is never mutated.

Return type:: WorksQuery

Usage:

from habanero import Crossref, WorksQuery
cr = Crossref()
q = WorksQuery(cr)

# chain methods, nothing fires yet
(
  q.query("climate change")
    .query(author="Hansen")
    .query(publisher_name="plos")
    .filter(from_pub_date="2010", has_funder="true")
    .sort("published")
    .order("desc")
    .select("DOI", "title", "author", "published")
    .limit(50)
)

# inspect before fetching
print(q)         # WorksQuery({...params...})
print(q.url)     # https://api.crossref.org/works?query=...

# get count without pulling records
print(q.count()) # e.g. 12483

# pull records — fires the request here
for item in q:
    print(item["DOI"], item.get("title"))

# or execute manually
q.execute()

# instances are immutable, so each call returns a new instance
# so you can chain calls without modifying the original instance
# compare the two modifications of the `base` query
base = WorksQuery(cr).query("zika").filter(from_pub_date="2020")
base.sort("published").order("asc")
base.sort("published").order("desc")