Skip to main content

Django Browserless

Django Browserless is a package that offers Django and Django REST framework views for generating PDFs from any URL using browserless.

Table of Contents

Features

  • Generate a PDF from any URL
  • Support for both Django and Django REST framework views
  • Custom authentication mechanism for secure PDF generation
  • Configurable browserless options

Requirements

  • Python 3.8+
  • Django 4.2+
  • Django REST framework 3.12+

Getting started

Install using pip

python -m pip install django-browserless

Add django_browserless to your INSTALLED_APPS in your Django settings:

INSTALLED_APPS = [
    ...
    "django_browserless",
]

Add BROWSERLESS to your settings and fill in your browserless API token:

BROWSERLESS = {
    "API_TOKEN": "your-api-token",
}

Add PDF generation view to your urls.py, either using a Django view:

from django_browserless.views.django_views import url_to_pdf
...
urlpatterns = [
   ...
    path("pdf/", url_to_pdf),
]

You can now generate a PDF from any URL, e.g.:

curl -XPOST -d 'url=http://example.com filename=example.pdf' 'http://localhost/pdf/'

Or a Django REST framework view:

from django_browserless.views.drf_views import UrlToPdf
...
urlpatterns = [
   ...
    path("pdf/", UrlToPdf.as_view()),
]

You can now generate a PDF from any URL, e.g.:

curl -XPOST -H "Content-type: application/json" -d 'url=http://example.com filename=example.pdf' 'http://localhost/pdf/'

Generating PDFs from views requiring authentication

If PDF generation needs to access any authenticated views in your project, you must configure browserless to authenticate these calls.

For Django views you must use the browserless_authenticated decorator, e.g.:

from django.contrib.auth.decorators import login_required
from django.http import HttpResponse
from django_browserless.auth.authenticators import browserless_authenticated


@browserless_authenticated
@login_required
def authenticated_view(request):
    return HttpResponse(f"Hello {request.user.username}!")

For Django REST framework views you must use the BrowserlessAuthentication authentication class, e.g. (assuming you're using DRF token authentication):

from rest_framework.authentication import TokenAuthentication
from rest_framework.permissions import IsAuthenticated
from rest_framework.views import APIView


class AuthenticatedAPIView(APIView):
    authentication_classes = [TokenAuthentication, BrowserlessAuthentication]
    permission_classes = [IsAuthenticated]

    def get(self, request):
        return HttpResponse(f"Hello {request.user.username}!")

Using from Python code

Apart from the views that can be called from the frontend django-browserless can also be used directly from Python code on the backend.

from django_browserless import pdf

pdf_content = pdf.from_url(url="http://example.com")

# A user can be specified if browserless need to call views that require authentication:
pdf_content = pdf.from_url(url="https://project.tld/export/", as_user_id=1)

# Browserless options can also be passed as a dictionary:
pdf_content = pdf.from_url(
    url="https://example.com", browserless_options={"landscape": True}
)

Specifying browserless options

You can specify any option supported by browserless for PDF generation (through its request body option field). They will be merged with the default options (see Default browserless timeout) using the browserless_options field in your request body, e.g.:

{
    "url": "http://example.com",
    "filename": "example.pdf",
    "browserless_options": {
        "landscape": true,
        "displayHeaderFooter": true
    }
}

Additional configuration options

Authentication timeout

In case browserless call views from your project that require authentication, this is the lifetime of the authentication credentials used by browserless (30 seconds by default, see How it works for more details):

BROWSERLESS = {
    "DEFAULT_AUTH_TIMEOUT": 30,  # seconds
}

Default browserless timeout

Timeout for generating a PDF (30 seconds by default):

BROWSERLESS = {
    "DEFAULT_AUTH_TIMEOUT": 30,  # seconds
}

Default PDF generation options

Default browserless PDF generation options, see browserless documentation:

BROWSERLESS = {
    "DEFAULT_PDF_OPTIONS": {
        "options": {
            "landscape": False,
            "displayHeaderFooter": False,
            "printBackground": True,
            "format": "A4",
        },
        "gotoOptions": {"waitUntil": "networkidle0"},
    },
}

How it works

At its core, django-browserless consists in two parts:

  • A thin wrapper around the browserless PDF HTTP API.
  • A custom authentication mechanism that allow browserless to impersonate the user's who requested the PDF generation.

Indeed, more often than not, the page to turn into a PDF contains user-specific content and requires authentication. However, as browserless is a 3rd-party service, it is not authenticated as the user who requested the PDF generation.

django-browserless addresses this issue using a custom, time-limited authentication mechanism. Here is how it is implemented:

  • Whenever a page is requested to be turned into a PDF, a random secret is generated, associated with request's user and page, and stored for a short period of time. In a typical production setup with multiple Python processes that don't share memory, the required data must be accessible to all processes. This leaves the database and the global cache as the most straightforward options. The global cache is faster and has a built-in expiration time mechanism so it's used rather than the database.
  • The random secret is shared with Browserless as an extra HTTP header that will be added to all requests that browserless will automatically send with all the requests to this page.
  • The views called by browserless extract the random secret from the request and check it against the ones stored in the global cache. If there is a match, the user associated with the secret is attached to the request.

Metadata

Release files for django-browserless 0.1.1

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

Source distribution (sdist)

Source distribution for django-browserless 0.1.1
File Size Uploaded Provenance Actions
django_browserless-0.1.1.tar.gz 11.4 kB Without provenance Details for django_browserless-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-browserless 0.1.1
File Interpreter ABI Platform Actions
django_browserless-0.1.1-py3-none-any.whl Python 3 none any Details for django_browserless-0.1.1-py3-none-any.whl

Total release size: 25.4 kB

Release files / django_browserless-0.1.1.tar.gz

Download URL django_browserless-0.1.1.tar.gz
Size 11.4 kB
Tags Source
SHA-256 checksum
How to use checksums
67841fbeb94df257d53451ba692c2d944e9faf9e962394f0ad4b67d82e941e67
BLAKE2b-256 checksum
How to use checksums
b96dd59e2509820b7d0a5b132158f536a83a4ab27198801a8e7d0d9f054f5082
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.12.4 Darwin/23.5.0

Release files / django_browserless-0.1.1-py3-none-any.whl

Download URL django_browserless-0.1.1-py3-none-any.whl
Size 13.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a663c7893c795de7c8444008196995d818a0aa5929c1f2f946171bbd41928ba6
BLAKE2b-256 checksum
How to use checksums
4e9be8b4ddc03f80bd4e88b5f219c8685a455132f062c3db5ceee340fd79c91e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.8.3 CPython/3.12.4 Darwin/23.5.0

Security for django-browserless 0.1.1

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.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page