API Reference

ArxivClient

The main class for interacting with the arXiv API. Provides methods for searching papers and downloading PDFs.

Basic Usage

from aioarxiv.client.arxiv_client import ArxivClient


async def foo():
    async with ArxivClient() as client:
        # Search by query
        result = await client.search("quantum computing")

        # Search by IDs
        result = await client.search(id_list=["2103.00020", "2103.00021"])

        # Download papers
        await client.download_search_result(result)

Constructor

from typing import Optional
from aioarxiv.config import ArxivConfig
from aioarxiv.utils.session import SessionManager
from pathlib import Path


def __init__(
        config: Optional[ArxivConfig] = None,
        session_manager: Optional[SessionManager] = None,
        *,
        enable_downloader: bool = False,
        download_dir: Optional[Path] = None,
) -> None: ...

Parameters

config: Optional[ArxivConfig] - Custom configuration for the client
session_manager: Optional[SessionManager] - Custom session manager
enable_downloader: bool - Whether to enable the paper downloader
download_dir: Optional[Path] - Directory path for downloading papers

Methods

search()

Search arXiv papers via either a keyword query or arXiv ID list.

from typing import Optional, overload
from aioarxiv.models import SearchResult, SortCriterion, SortOrder


@overload
async def search(
        query: str,
        id_list: None = None,
        max_results: Optional[int] = None,
        sort_by: Optional[SortCriterion] = None,
        sort_order: Optional[SortOrder] = None,
        start: Optional[int] = None,
) -> SearchResult: ...


@overload
async def search(
        query: None = None,
        id_list: list[str] = ...,
        max_results: Optional[int] = None,
        sort_by: Optional[SortCriterion] = None,
        sort_order: Optional[SortOrder] = None,
        start: Optional[int] = None,
) -> SearchResult: ...

Parameters

query: Optional[str] - Keyword-based query string
id_list: Optional[list[str]] - List of arXiv IDs to retrieve
max_results: Optional[int] - Maximum number of results to return
sort_by: Optional[SortCriterion] - Criterion to sort results by
sort_order: Optional[SortOrder] - Order of sorting
start: Optional[int] - Starting index for results

Returns

SearchResult - Object containing search results and metadata

download_paper()

Download a single paper from arXiv.

from typing import Optional
from aioarxiv.models import Paper


async def download_paper(
        paper: Paper,
        filename: Optional[str] = None,
) -> Optional[None]: ...

Parameters

paper: Paper - Paper object containing download information
filename: Optional[str] - Custom filename for the downloaded paper

Returns

Optional[None] - None if downloader is disabled

download_search_result()

Download all papers from a search result.

from typing import Optional
from aioarxiv.models import SearchResult
from aioarxiv.client.downloader import DownloadTracker


async def download_search_result(
        search_result: SearchResult,
) -> Optional[DownloadTracker]: ...

Parameters

search_result: SearchResult - Search result containing papers to download

Returns

Optional[DownloadTracker] - Download tracker if downloader is enabled

Enums

SortCriterion

from enum import Enum


class SortCriterion(str, Enum):
    RELEVANCE = "relevance"
    LAST_UPDATED = "lastUpdatedDate"
    SUBMITTED = "submittedDate"

SortOrder

from enum import Enum


class SortOrder(str, Enum):
    ASCENDING = "ascending"
    DESCENDING = "descending"

Models

SearchResult

Contains search results and metadata.

Attributes

id: UUID4 - Result identifier
papers: list[Paper] - List of papers in the result
total_result: int - Total number of matching papers
page: int - Current page number
has_next: bool - Whether more results are available
query_params: SearchParams - Search parameters used
metadata: Metadata - Search operation metadata

Paper

Represents an arXiv paper.

Attributes

info: BasicInfo - Basic paper information
doi: Optional[str] - Digital Object Identifier
journal_ref: Optional[str] - Journal reference
pdf_url: Optional[HttpUrl] - URL for PDF download
comment: Optional[str] - Author comments

Error Handling

The client may raise the following exceptions:

HTTPException: For HTTP request errors
QueryBuildError: For search query construction errors
PaperDownloadException: For paper download failures
ValidationException: For data validation errors

Context Manager Support

The client supports async context management:

from aioarxiv.client.arxiv_client import ArxivClient


async def foo():
    async with ArxivClient() as client:
        result = await client.search("quantum computing")

Last modified: 03 April 2025