arxiv.py Python Wrapper

The library follows a three-part pattern:

1. Client: The engine. It manages connection pooling, rate limiting (via delay_seconds), and pagination logic. You should create one client and reuse it for multiple searches.
2. Search: The query definition. It encapsulates what you are looking for (keywords, IDs, sort order) without actually performing the network request.
3. Result: The data. These are the objects yielded by the client's generator. They contain metadata (title, authors, etc.) and URLs for downloading the paper content.

Install the arxiv package using pip or uv:

$ pip install arxiv
# Or
$ uv add arxiv

To inspect API requests, pagination, and network activity, configure the standard Python logging module to the DEBUG level.

import logging, arxiv
logging.basicConfig(level=logging.DEBUG)
client = arxiv.Client()
# Subsequent calls will now log INFO and DEBUG messages

Once you have a Result object, you can access its URLs to download files using standard libraries like urllib.request.

• Use paper.pdf_url for the PDF link.
• Use paper.source_url() for the source tarball link.

import arxiv
from urllib.request import urlretrieve

paper = next(arxiv.Client().results(arxiv.Search(id_list=["1605.08386v1"])))

# Download the PDF.
urlretrieve(paper.pdf_url, "paper.pdf")

# Download the source tarball.
urlretrieve(paper.source_url(), "paper.tar.gz")

The arxiv.Client defines the strategy for fetching results, including pagination and retry logic. Reusing a client instance is recommended to benefit from connection pooling and consistent rate limiting.

Customizable parameters include:

• page_size: Number of results to request per page.
• delay_seconds: Delay between requests to respect rate limits.
• num_retries: Number of retries for failed requests.

import arxiv

big_slow_client = arxiv.Client(
  page_size = 1000,
  delay_seconds = 10.0,
  num_retries = 5
)

for result in big_slow_client.results(arxiv.Search(query="quantum")):
  print(result.title)

The Client class is the primary way to interact with the arXiv API. It manages pagination, retries, and rate-limiting (respecting arXiv's request frequency guidelines). Use Client.results(search) to get an iterator of Result objects.

Key configuration options for Client:

• page_size: Maximum results per API request (default: 100, API limit is 2000).
• delay_seconds: Seconds to wait between requests (default: 3.0, recommended to follow arXiv's 3-second rule).
• num_retries: Number of retries for failed requests (default: 3).

The Search class defines the criteria for an arXiv query. You can search by keyword, limit by specific IDs, and specify sorting.

Parameters:

• query: An unencoded query string (e.g., au:del_maestro AND ti:checkerboard).
• id_list: A list of specific arXiv article IDs to limit the search to.
• max_results: The maximum number of results to return. Set to None to fetch all available results (up to the API limit of 300,000).
• sort_by: A SortCriterion (e.g., Relevance, LastUpdatedDate, SubmittedDate).
• sort_order: A SortOrder (Ascending or Descending).

Each Result object represents an arXiv article and provides several attributes:

• entry_id: The full URL (e.g., https://arxiv.org/abs/2107.05580v1).
• get_short_id(): Returns the identifier without the URL prefix (e.g., 2107.05580v1).
• title: The article title.
• authors: A list of Result.Author objects.
• summary: The article abstract.
• published: The original publication datetime.
• updated: The last update datetime.
• primary_category: The primary arXiv category.
• categories: A list of all associated categories.
• pdf_url: The URL to the PDF version (if available).
• source_url(): Returns a URL for the source tarfile (replaces /pdf/ with /src/ in the PDF URL).

A Result contains nested objects for authors and links:

Authors (Result.Author)

• name: The author's name.
• affiliation: A list of affiliation strings (if provided by arXiv).

Links (Result.Link)

• href: The URL.
• title: The link's title (e.g., "pdf").
• rel: The relationship to the result.

The library defines a hierarchy of exceptions for handling issues during API interaction:

• ArxivError: The base exception for the package.
• HTTPError: Raised when a non-200 status code is encountered. Includes the status code.
• UnexpectedEmptyPageError: Raised when a page that should contain results is empty (often due to arXiv API brittleness). Includes the raw_feed for diagnostics.
• MissingFieldError: Raised if an entry is unparseable due to missing required fields.

When constructing a Search object, use the following enums to control result ordering:

SortCriterion

• Relevance: Sort by query relevance.
• LastUpdatedDate: Sort by the last time the entry was updated.
• SubmittedDate: Sort by the original submission date.

SortOrder

• Ascending
• Descending