arxiv.py

Python wrapper for the arXiv API.

Quick links

Full package documentation
Example: fetching results: the most common usage.
Example: downloading papers
Example: fetching results with a custom client

About arXiv

arXiv is a project by the Cornell University Library that provides open access to 1,000,000+ articles in Physics, Mathematics, Computer Science, Quantitative Biology, Quantitative Finance, and Statistics.

Usage

Installation

$ pip install arxiv

In your Python script, include the line

import arxiv

Search

A Search specifies a search of arXiv's database.

arxiv.Search(
  query: str = "",
  id_list: List[str] = [],
  max_results: float = float('inf'),
  sort_by: SortCriterion = SortCriterion.Relevance,
  sort_order: SortOrder = SortOrder.Descending
)

query: an arXiv query string. Advanced query formats are documented in the arXiv API User Manual.
id_list: list of arXiv record IDs (typically of the format "0710.5765v1"). See the arXiv API User's Manual for documentation of the interaction between query and id_list.
max_results: The maximum number of results to be returned in an execution of this search. To fetch every result available, set max_results=float('inf') (default); to fetch up to 10 results, set max_results=10. The API's limit is 300,000 results.
sort_by: The sort criterion for results: relevance, lastUpdatedDate, or submittedDate.
sort_order: The sort order for results: 'descending' or 'ascending'.

To fetch arXiv records matching a Search, use search.results() or (Client).results(search) to get a generator yielding Results.

Example: fetching results

Print the titles fo the 10 most recent articles related to the keyword "quantum:"

import arxiv

search = arxiv.Search(
  query = "quantum",
  max_results = 10,
  sort_by = arxiv.SortCriterion.SubmittedDate
)

for result in search.results():
  print(result.title)

Fetch and print the title of the paper with ID "1605.08386v1:"

import arxiv

search = arxiv.Search(id_list=["1605.08386v1"])
paper = next(search.results())
print(paper.title)

Result

The Result objects yielded by (Search).results() include metadata about each paper and some helper functions for downloading their content.

The meaning of the underlying raw data is documented in the arXiv API User Manual: Details of Atom Results Returned.

result.entry_id: A url http://arxiv.org/abs/{id}.
result.updated: When the result was last updated.
result.published: When the result was originally published.
result.title: The title of the result.
result.authors: The result's authors, as arxiv.Authors.
result.summary: The result abstract.
result.comment: The authors' comment if present.
result.journal_ref: A journal reference if present.
result.doi: A URL for the resolved DOI to an external resource if present.
result.primary_category: The result's primary arXiv category. See arXiv: Category Taxonomy.
result.categories: All of the result's categories. See arXiv: Category Taxonomy.
result.links: Up to three URLs associated with this result, as arxiv.Links.
result.pdf_url: A URL for the result's PDF if present. Note: this URL also appears among result.links.

They also expose helper methods for downloading papers: (Result).download_pdf() and (Result).download_source().

Example: downloading papers

To download a PDF of the paper with ID "1605.08386v1," run a Search and then use (Result).download_pdf():

import arxiv

paper = next(arxiv.Search(id_list=["1605.08386v1"]).results())
# Download the PDF to the PWD with a default filename.
paper.download_pdf()
# Download the PDF to the PWD with a custom filename.
paper.download_pdf(filename="downloaded-paper.pdf")
# Download the PDF to a specified directory with a custom filename.
paper.download_pdf(dirpath="./mydir", filename="downloaded-paper.pdf")

The same interface is available for downloading .tar.gz files of the paper source:

import arxiv

paper = next(arxiv.Search(id_list=["1605.08386v1"]).results())
# Download the archive to the PWD with a default filename.
paper.download_source()
# Download the archive to the PWD with a custom filename.
paper.download_source(filename="downloaded-paper.tar.gz")
# Download the archive to a specified directory with a custom filename.
paper.download_source(dirpath="./mydir", filename="downloaded-paper.tar.gz")

Client

A Client specifies a strategy for fetching results from arXiv's API; it obscures pagination and retry logic.

For most use cases the default client should suffice. You can construct it explicitly with arxiv.Client(), or use it via the (Search).results() method.

arxiv.Client(
  page_size: int = 100,
  delay_seconds: int = 3,
  num_retries: int = 3
)

page_size: the number of papers to fetch from arXiv per page of results. Smaller pages can be retrieved faster, but may require more round-trips. The API's limit is 2000 results.
delay_seconds: the number of seconds to wait between requests for pages. arXiv's Terms of Use ask that you "make no more than one request every three seconds."
num_retries: The number of times the client will retry a request that fails, either with a non-200 HTTP status code or with an unexpected number of results given the search parameters.

Example: fetching results with a custom client

(Search).results() uses the default client settings. If you want to use a client you've defined instead of the defaults, use (Client).results(...):

import arxiv

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

# Prints 1000 titles before needing to make another request.
for result in big_slow_client.results(arxiv.Search(query="quantum")):
  print(result.title)

Example: logging

To inspect this package's network behavior and API logic, configure an INFO-level logger.

>>> import logging, arxiv
>>> logging.basicConfig(level=logging.INFO)
>>> paper = next(arxiv.Search(id_list=["1605.08386v1"]).results())
INFO:arxiv.arxiv:Requesting 100 results at offset 0
INFO:arxiv.arxiv:Requesting page of results
INFO:arxiv.arxiv:Got first page; 1 of inf results available

Metadata

Release files for arxiv 1.4.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for arxiv 1.4.4
File	Size	Uploaded	Provenance
arxiv-1.4.4.tar.gz	17.0 kB	Apr 11, 2023	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for arxiv 1.4.4
File	Interpreter	ABI	Platform	Reset
arxiv-1.4.4-py3-none-any.whl 12.0 kB Apr 11, 2023 Without provenance	Python 3	none	any	Details

Total release size: 29.1 kB

Release files / arxiv-1.4.4.tar.gz

Download URL	arxiv-1.4.4.tar.gz
Size	17.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`7ac914375e64357f058d6a6bcccf2cdb00aeed86ef4650ca7151867bd09df199`
BLAKE2b-256 checksum How to use checksums	`174bf7944b90de3a9d42e6a19c05dd1e953247f89720846dddab3e89397b548b`
Upload date	Apr 11, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.12.1 pkginfo/1.4.2 requests/2.20.0 setuptools/41.4.0 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/2.7.17`

Release files / arxiv-1.4.4-py3-none-any.whl

Download URL	arxiv-1.4.4-py3-none-any.whl
Size	12.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ca2224ebc4c6e23a0917db7704b6c2748520f9c3f15a2780f7f4c5794ec1788b`
BLAKE2b-256 checksum How to use checksums	`feef3bbf32d851268b41a5c5b63adceae01e39f5a3630a8a6a487ba61b4edcad`
Upload date	Apr 11, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/1.12.1 pkginfo/1.4.2 requests/2.20.0 setuptools/41.4.0 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/2.7.17`

Security for arxiv 1.4.4

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.