<NME> README.md
<BEF> # arxiv.py [![Python 3.6](https://img.shields.io/badge/python-3.7-blue.svg)](https://www.python.org/downloads/release/python-370/) [![PyPI](https://img.shields.io/pypi/v/arxiv)](https://pypi.org/project/arxiv/) [![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/lukasschwab/arxiv.py/python-lint-test/master)](https://github.com/lukasschwab/arxiv.py/actions?query=branch%3Amaster)

Python wrapper for [the arXiv API](http://arxiv.org/help/api/index).

## Quick links

+ [Full package documentation](http://lukasschwab.me/arxiv.py/index.html)
+ [Example: fetching results](#example-fetching-results): the most common usage.
+ [Example: downloading papers](#example-downloading-papers)
+ [Example: fetching results with a custom client](#example-fetching-results-with-a-custom-client)

## About arXiv

[arXiv](http://arxiv.org/) 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

```bash
$ pip install arxiv
```

In your Python script, include the line

```python
import arxiv
```
### Query

```python
arxiv.query(query="",
            id_list=[],
            max_results=None,
            start = 0,
            sort_by="relevance",
            sort_order="descending",
            prune=True,
            iterative=False,
            max_chunk_results=1000)
```

| **Argument**   | **Type**        | **Default**    |
+ `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 `Result`s.

#### Example: fetching results

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

```python
import arxiv


+ `id_list`: list of arXiv record IDs (typically of the format `"0710.5765v1"`).

+ `max_results`: the maximum number of results returned by the query.

+ `start`: the offset of the first returned object from the arXiv query results.

  print(result.title)
```

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

```python
import arxiv

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

### Result

# Keyword queries
arxiv.query(query="quantum", max_results=100)
# Multi-field queries
arxiv.query(query="au:balents_leon AND cat:cond-mat.str-el")
# Get single record by ID
arxiv.query(id_list=["1707.08567"])
# Get multiple records by ID
arxiv.query(id_list=["1707.08567", "1707.08567"])

# Get interator over query results
result = arxiv.query(query="quantum", max_chunk_results=10, iterative=True)
for paper in result():
   print(paper)
```

For a more detailed description of the interaction between `query` and `id_list`, see [this section of the arXiv documentation](https://arxiv.org/help/api/user-manual#search_query_and_id_list).

### Download article PDF or source tarfile


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:

```python
import arxiv

paper = next(arxiv.Search(id_list=["1605.08386v1"]).results())
# Download the archive to the PWD with a default filename.
paper.download_source()

```python
import arxiv
# Query for a paper of interest, then download
paper = arxiv.query(id_list=["1707.08567"])[0]
arxiv.download(paper)
# You can skip the query step if you have the paper info!
paper2 = {"pdf_url": "http://arxiv.org/pdf/1707.08567v1",
          "title": "The Paper Title"}
arxiv.download(paper2)

# Download the gzipped tar file
arxiv.download(paper,prefer_source_tarfile=True)

# Returns the object id
def custom_slugify(obj):
    return obj.get('id').split('/')[-1]

# Download with a specified slugifier function
arxiv.download(paper, slugify=custom_slugify)
```

## Contributors
+ `delay_seconds`: the number of seconds to wait between requests for pages. [arXiv's Terms of Use](https://arxiv.org/help/api/tou) 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(...)`:

```python
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.

```pycon
>>> 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
```

<MSG> Tidy README documentation

<DFF> @@ -29,15 +29,17 @@ import arxiv
 ### Query
 
 ```python
-arxiv.query(query="",
-            id_list=[],
-            max_results=None,
-            start = 0,
-            sort_by="relevance",
-            sort_order="descending",
-            prune=True,
-            iterative=False,
-            max_chunk_results=1000)
+arxiv.query(
+  query="",
+  id_list=[],
+  max_results=None,
+  start = 0,
+  sort_by="relevance",
+  sort_order="descending",
+  prune=True,
+  iterative=False,
+  max_chunk_results=1000
+)
 ```
 
 | **Argument**   | **Type**        | **Default**    |
@@ -57,7 +59,7 @@ arxiv.query(query="",
 
 + `id_list`: list of arXiv record IDs (typically of the format `"0710.5765v1"`).
 
-+ `max_results`: the maximum number of results returned by the query.
++ `max_results`: the maximum number of results returned by the query. Note: if this is unset amd `iterative=False`, the call to `query` can take a long time to resolve.
 
 + `start`: the offset of the first returned object from the arXiv query results.
 
@@ -78,20 +80,29 @@ import arxiv
 
 # Keyword queries
 arxiv.query(query="quantum", max_results=100)
+
 # Multi-field queries
 arxiv.query(query="au:balents_leon AND cat:cond-mat.str-el")
+
 # Get single record by ID
 arxiv.query(id_list=["1707.08567"])
+
 # Get multiple records by ID
 arxiv.query(id_list=["1707.08567", "1707.08567"])
 
-# Get interator over query results
-result = arxiv.query(query="quantum", max_chunk_results=10, iterative=True)
+# Get an interator over query results
+result = arxiv.query(
+  query="quantum",
+  max_chunk_results=10,
+  max_results=100,
+  iterative=True
+)
+
 for paper in result():
    print(paper)
 ```
 
-For a more detailed description of the interaction between `query` and `id_list`, see [this section of the arXiv documentation](https://arxiv.org/help/api/user-manual#search_query_and_id_list).
+For a more detailed description of the interaction between the `query` and `id_list` arguments, see [this section of the arXiv documentation](https://arxiv.org/help/api/user-manual#search_query_and_id_list).
 
 ### Download article PDF or source tarfile
 
@@ -116,23 +127,21 @@ arxiv.arxiv.download(obj, dirpath='./', slugify=slugify, prefer_source_tarfile=F
 
 ```python
 import arxiv
-# Query for a paper of interest, then download
+
+# Query for a paper of interest, then download it.
 paper = arxiv.query(id_list=["1707.08567"])[0]
 arxiv.download(paper)
-# You can skip the query step if you have the paper info!
+
+# You can skip the query step if you have the paper info.
 paper2 = {"pdf_url": "http://arxiv.org/pdf/1707.08567v1",
           "title": "The Paper Title"}
 arxiv.download(paper2)
 
-# Download the gzipped tar file
-arxiv.download(paper,prefer_source_tarfile=True)
-
-# Returns the object id
-def custom_slugify(obj):
-    return obj.get('id').split('/')[-1]
+# Use prefer_source_tarfile to download the gzipped tar file.
+arxiv.download(paper, prefer_source_tarfile=True)
 
-# Download with a specified slugifier function
-arxiv.download(paper, slugify=custom_slugify)
+# Override the default filename format by defining a slugify function.
+arxiv.download(paper, slugify=lambda paper: paper.get('id').split('/')[-1])
 ```
 
 ## Contributors

Tidy README documentation