Skip to main content

Crate arxiv_client

Crate arxiv_client 

Source
Expand description

An async client for the arXiv API.

arXiv exposes one route, /api/query, which answers with an Atom feed. A request asks for a Search expression, a list of ArticleIds, or both; everything else is paging and sorting.

§Usage

§Create an Arxiv client

let client = Arxiv::builder().build()?;

arXiv has no api key and no polite pool, but it does ask callers to identify themselves and to pace their requests. ArxivBuilder::contact does the first, and the client does the second on its own – requests are serialized and spaced three seconds apart unless ArxivBuilder::interval says otherwise.

let client = Arxiv::builder().contact("you@example.com").build()?;

§Search

let feed = client
    .search(
        Search::category("cs.LG")
            .and(Search::title("attention"))
            .into_query()
            .max_results(20)
            .sort_by(SortBy::SubmittedDate),
    )
    .await?;

for entry in &feed.entries {
    println!("{} {}", entry.id, entry.title);
}

Free form text is read as a search of every field, which is the common case:

let feed = client.search("quantum error correction").await?;

§Get one article

let entry = client.entry("1706.03762").await?;

println!("{}", entry.title);
println!("{}", entry.to_bibtex());

§Page through a whole result set

Arxiv::paginate returns an iterator over pages, threading start forward and pacing the requests. arXiv serves at most Query::MAX_RESULTS per request and stops answering past Query::MAX_REACHABLE, so a search that has to reach further than that has to be split into narrower ones.

use arxiv_client::{Arxiv, AsyncIterator, Entry, Search};
let client = Arxiv::builder().contact("you@example.com").build()?;

let mut pages = client.paginate(Search::category("cs.LG").into_query());
let mut all: Vec<Entry> = Vec::new();
while let Some(page) = pages.next().await {
    all.extend(page?.entries);
}

Which can be flattened to the entries themselves:

use arxiv_client::{Arxiv, AsyncIterator, Search};
let mut entries = client
    .paginate(Search::category("cs.LG").into_query())
    .into_entry_iter();

while let Some(entry) = entries.next().await {
    println!("{}", entry?.id);
}

Modules§

limit
client side rate limiting Client side rate limiting.
query
provides the types to construct a request The one request arXiv’s api takes, and the pieces it is built from.
response
provides the response types of the arXiv api The types arXiv’s Atom feed is read into.

Structs§

ArticleId
An arXiv article identifier, in either of the two forms arXiv has used.
Arxiv
A client for the arXiv api.
ArxivBuilder
An ArxivBuilder can be used to create an Arxiv with additional config.
Author
One credited author.
Category
A subject category, e.g. cs.LG or cond-mat.str-el.
Entry
One article.
EntryIterator
Yields individual Entry items across the paged Feeds.
Feed
One page of results.
Link
A link an entry carries: its abstract page, its pdf, or its resolved DOI.
PageIterator
Pages through a query’s whole result set, one Feed at a time.
Query
One request to arXiv’s /api/query route.

Enums§

DateField
A date arXiv can narrow a search to a range of.
Error
All different error types this crate uses.
Field
A field of arXiv’s metadata that a term can be matched against.
Op
How two searches are combined.
Search
A search_query expression.
SortBy
What the results are ordered by.
SortOrder
Which end of the ordering comes first.

Constants§

POLITE_INTERVAL
The gap arXiv’s user manual asks for between two requests, and what an Arxiv leaves unless told otherwise.

Traits§

AsyncIterator
The async iterator trait implemented by PageIterator and EntryIterator.

Functions§

unwrap_lines
Joins the lines arXiv wrapped a title or an abstract across, keeping the blank lines that separate paragraphs.

Type Aliases§

Result
A type alias for handling errors throughout this crate.