LlamaIndex Readers Integration: PrintFriendly

LlamaIndex reader for the PrintFriendly API. Give it web page addresses and it returns each article as a Document of clean Markdown, without ads, menus, cookie banners or other clutter.

Install

pip install -U llama-index-readers-printfriendly

Get an API key

Get a free key at printfriendly.com/me/api-key. The free plan includes 100 documents a month and needs no card. Paid plans include more.

export PRINTFRIENDLY_API_KEY="your key"

Or pass it in code with api_key="...".

To check that a key works without using a document, call the free usage endpoint. It is never counted:

curl -H "Authorization: Bearer $PRINTFRIENDLY_API_KEY" https://api.printfriendly.com/v2/usage

Usage

from llama_index.readers.printfriendly import PrintFriendlyReader

reader = PrintFriendlyReader()  # reads PRINTFRIENDLY_API_KEY
documents = reader.load_data(
    urls=[
        "https://en.wikipedia.org/wiki/Eclipse",
        "https://en.wikipedia.org/wiki/Solar_eclipse",
    ]
)

print(documents[0].text[:200])
print(documents[0].metadata)
# {'source': 'https://en.wikipedia.org/wiki/Eclipse',
#  'title': 'Eclipse - Wikipedia',
#  'site': 'en.wikipedia.org',
#  'author': 'Contributors to Wikimedia projects',
#  'date': '2001-11-02',
#  'excerpt': 'Totality during the solar eclipse of August 11, 1999, ...',
#  'image': 'https://thumb.wikimedia.org/wikipedia/commons/thumb/0/0d/Umbra01.svg/330px-Umbra01.svg.png?...',
#  'word_count': 5097}

Load lazily, one page at a time:

for document in reader.lazy_load_data(urls=urls):
    print(document.metadata["title"])

Or asynchronously (uses httpx.AsyncClient):

documents = await reader.aload_data(urls=urls)

Pages are read one after another, in the order you gave them.

Build an index

from llama_index.core import VectorStoreIndex

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
print(query_engine.query("What is a total solar eclipse?"))

Each Document has the page URL as its doc_id. Loading the same page again and passing it through an IngestionPipeline with a docstore updates the stored copy instead of adding a second one.

The noisy metadata (source, image, word_count, excerpt) is excluded from the text that gets embedded, so embeddings are about the page and not about its URL. title, site, author and date stay in. The LLM sees source, title, site, author, date and excerpt.

Options

load_data, lazy_load_data, aload_data and alazy_load_data take urls: one address or a list. Each must be an http or https address.

Metadata

A field the page does not have is left out, not set to None.

Errors, retries and limits

Every failure raises PrintFriendlyError:

from llama_index.readers.printfriendly import PrintFriendlyError

try:
    documents = reader.load_data(urls=urls)
except PrintFriendlyError as error:
    print(error.code)  # for example "fetch_failed" or "quota_exceeded"
    print(error.retryable)  # whether trying again can work
    print(error.request_id)  # quote this to PrintFriendly support

• Rate limits. Free keys allow 10 requests a minute. On a 429 the reader waits for the time in Retry-After and tries again, up to max_retries times. If the API asks for more than 60 seconds, the reader raises instead of blocking.
• Retryable errors. Errors the API marks retryable (a page that timed out, for example) are retried with a short backoff, up to max_retries times. A dropped connection is retried too. A read timeout is not, because the document may already have been counted.
• Everything else raises at once, with the API's error code and message: invalid_parameters, fetch_failed, parse_failed, content_blocked, render_failed and so on.
• continue_on_failure=True skips pages that fail one by one. Key and plan errors (api_key_required, invalid_api_key, subscription_inactive, limit_exceeded, quota_exceeded) still raise, because every later page would fail the same way.
• Billing. Only a successful read counts as a document on your plan. Failed reads are free. The plan limit comes back as quota_exceeded with an upgrade_url.

See the API reference for every code.

Development

The project uses uv.

make test        # unit tests, no network
make lint        # ruff, mypy, codespell
make live_test   # the real API; needs PRINTFRIENDLY_API_KEY and reads two pages

The tests mock the HTTP layer with respx, as LlamaIndex asks of integrations, and run with network access switched off. Coverage is above 90%. make live_test uses two documents of your plan and is skipped without the key.

Links

• PrintFriendly API
• API reference (OpenAPI)
• Support

License

MIT. See LICENSE.