wc-html2pdf


Namewc-html2pdf JSON
Version 0.1.0 PyPI version JSON
download
home_pageNone
SummaryHTML to PDF conversion utilities.
upload_time2024-06-17 09:49:41
maintainerNone
docs_urlNone
authorWebCase
requires_python>=3.6
licenseMIT License
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # WebCase HTML to PDF converter

Message sender to different channels.

## Installation

```sh
pip install wc-html2pdf
```

## Usage

The core part of library is a `Converter`.

- `Converter.from_content` - Method that will return path to generated pdf file from string content.
- `Converter.from_file` - Method that deals the same but for either file object or file path.

Just inherit from `wc_html2pdf.converters.Converter` and implement those 2 methods if you need a custom one.

Builtins:

### WeasyPrint converter

Converter that uses [WeasyPrint](https://weasyprint.org/) library.

```python
from wc_html2pdf.converters.weasyprint import WeasyPrintConverter

converter = WeasyPrintConverter()
```

It requires to `pip install weasyprint` package only. 

In docker environment it might also be required to install:

```bash
apt-get install libpango-1.0-0 libpangoft2-1.0-0 -y --no-install-recommends
```

It's lightweight, it's relatively fast and supports most css features in basic implementation.

Try to use it first, before turn your head to chromium.

### Chromium converter

It uses chromium browser in headless mode to generate pdf.

```python
from wc_html2pdf.converters.chromium import ChromiumConverter

converter = ChromiumConverter(
  # Optional. This is the default value:
  bin_path='/usr/bin/chromium',
  # Command line flags for a headless chrome execution.
  # Pass None to use the default ones.
  options=None,
)
```

So either google chrome or chromium browser must be installed in your system/docker environment. Like so:

Chromium:

```bash
apt-get install -y --no-install-recommends chromium
```

Google chrome:

```bash
apt-get install -y --no-install-recommends \
  ca-certificates \
  apt-transport-https \
  wget \
  gnupg \
  && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
  && echo "deb [arch=amd64] https://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google.list \
  && apt-get update \
  && apt-get install -y --no-install-recommends \
  google-chrome-stable
```

## Django

There is a contrib module for usage with django framework. It provides a view to generate pdf from template and small template utilities to make that a bit easier.

### Installation

In `settings.py`:

```python
INSTALLED_APPS += [
  'wc_html2pdf.contrib.django',
]
```

### Usage

Just add template mixin and your template will turn into pdf:

```python
from wc_html2pdf.contrib.django.views import HTML2PDFTemplateResponseMixin
from wc_html2pdf.converters.chromium import ChromiumConverter
from wc_html2pdf.contrib.django.url_getters import (
  PathUrlGetter, AbsoluteUrlGetter,
)


class MyView:
  pass


class MyPDFView(HTML2PDFTemplateResponseMixin, MyView):
  # Your html template.
  template_name = 'my-doc.html'
  # Resulting file name:
  pdf_filename = 'my-doc.pdf'
  # Converter can be set statically or by rewriting `get_pdf_converter` method.
  pdf_converter = ChromiumConverter() # or any other converter.
  # Whether response with inline pdf or as a auto-downloadable attachment
  pdf_attachment = True
  # This one is special. This is a class that will transform urls to static 
  # resources or media objects tha way that fits your server/converter.
  # `PathUrlGetter` is for cases when converter have access to local filesystem
  # and all urls will be in form of `file:///absolute/path/to/file.css`.
  pdf_url_getter = PathUrlGetter()

  # And `AbsoluteUrlGetter` is for cases when static resources should be
  # accessed by http;
  # Those converters are very simple and you may write your own in couple of 
  # minutes.
  # Converter will be available in template context as `pdf_url_converter`.
  # But there are utilities that will use it, so you don't have to.
  def get_pdf_url_getter(self):
    return AbsoluteUrlGetter(self.request.build_absolute_uri('/'))


# For debugging purposes you may want to see the resulting html without 
# turning it to pdf document, but with all changes that url_converter 
# have done.
# For that you may do the following:


# Rewrite response to omit pdf generation step:
class HTMLResponse(HTML2PDFTemplateResponseMixin.response_class):
  @property
  def rendered_content(self):
    return self.source_content


# And use that response 
class MyPDFPreviewView(MyPDFView):
  # So changing the response class in view will result in plain html rendering.
  response_class = HTMLResponse
  content_type = 'text/html; charset=utf-8'
  pdf_filename = None
  pdf_attachment = False
  # Here you may redefine url getter, for example:
  pdf_url_getter = AbsoluteUrlGetter('http://localhost')
```

#### Templates

For a default django templates:

```jinja
{% load html2pdf %}

<!-- Same as django's `static` tag. -->
{% html2pdf_static 'static-path.css' %}

<!-- For uploads/media you should also use a special tag.  -->
{% html2pdf_media obj.upload.url %}
```

For "jinja" templates there is an extension: `wc_html2pdf.contrib.django.jinja.extensions.HTML2PDFUrlGetterExtension`. That will add 2 global functions with the same functionality:

```jinja
<!-- Static path transformer: -->
{{ html2pdf_static('static-path.css') }}

<!-- Uploads path transformer: -->
{{ html2pdf_media(obj.upload.url) }}
```
# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.1.0]
Initial version.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "wc-html2pdf",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": null,
    "keywords": null,
    "author": "WebCase",
    "author_email": "info@webcase.studio",
    "download_url": "https://files.pythonhosted.org/packages/11/8b/ff2b8adef2a0a6925b998ad6526f5eff84f24a4cc384612086751deea06c/wc-html2pdf-0.1.0.tar.gz",
    "platform": null,
    "description": "# WebCase HTML to PDF converter\n\nMessage sender to different channels.\n\n## Installation\n\n```sh\npip install wc-html2pdf\n```\n\n## Usage\n\nThe core part of library is a `Converter`.\n\n- `Converter.from_content` - Method that will return path to generated pdf file from string content.\n- `Converter.from_file` - Method that deals the same but for either file object or file path.\n\nJust inherit from `wc_html2pdf.converters.Converter` and implement those 2 methods if you need a custom one.\n\nBuiltins:\n\n### WeasyPrint converter\n\nConverter that uses [WeasyPrint](https://weasyprint.org/) library.\n\n```python\nfrom wc_html2pdf.converters.weasyprint import WeasyPrintConverter\n\nconverter = WeasyPrintConverter()\n```\n\nIt requires to `pip install weasyprint` package only. \n\nIn docker environment it might also be required to install:\n\n```bash\napt-get install libpango-1.0-0 libpangoft2-1.0-0 -y --no-install-recommends\n```\n\nIt's lightweight, it's relatively fast and supports most css features in basic implementation.\n\nTry to use it first, before turn your head to chromium.\n\n### Chromium converter\n\nIt uses chromium browser in headless mode to generate pdf.\n\n```python\nfrom wc_html2pdf.converters.chromium import ChromiumConverter\n\nconverter = ChromiumConverter(\n  # Optional. This is the default value:\n  bin_path='/usr/bin/chromium',\n  # Command line flags for a headless chrome execution.\n  # Pass None to use the default ones.\n  options=None,\n)\n```\n\nSo either google chrome or chromium browser must be installed in your system/docker environment. Like so:\n\nChromium:\n\n```bash\napt-get install -y --no-install-recommends chromium\n```\n\nGoogle chrome:\n\n```bash\napt-get install -y --no-install-recommends \\\n  ca-certificates \\\n  apt-transport-https \\\n  wget \\\n  gnupg \\\n  && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \\\n  && echo \"deb [arch=amd64] https://dl.google.com/linux/chrome/deb/ stable main\" > /etc/apt/sources.list.d/google.list \\\n  && apt-get update \\\n  && apt-get install -y --no-install-recommends \\\n  google-chrome-stable\n```\n\n## Django\n\nThere is a contrib module for usage with django framework. It provides a view to generate pdf from template and small template utilities to make that a bit easier.\n\n### Installation\n\nIn `settings.py`:\n\n```python\nINSTALLED_APPS += [\n  'wc_html2pdf.contrib.django',\n]\n```\n\n### Usage\n\nJust add template mixin and your template will turn into pdf:\n\n```python\nfrom wc_html2pdf.contrib.django.views import HTML2PDFTemplateResponseMixin\nfrom wc_html2pdf.converters.chromium import ChromiumConverter\nfrom wc_html2pdf.contrib.django.url_getters import (\n  PathUrlGetter, AbsoluteUrlGetter,\n)\n\n\nclass MyView:\n  pass\n\n\nclass MyPDFView(HTML2PDFTemplateResponseMixin, MyView):\n  # Your html template.\n  template_name = 'my-doc.html'\n  # Resulting file name:\n  pdf_filename = 'my-doc.pdf'\n  # Converter can be set statically or by rewriting `get_pdf_converter` method.\n  pdf_converter = ChromiumConverter() # or any other converter.\n  # Whether response with inline pdf or as a auto-downloadable attachment\n  pdf_attachment = True\n  # This one is special. This is a class that will transform urls to static \n  # resources or media objects tha way that fits your server/converter.\n  # `PathUrlGetter` is for cases when converter have access to local filesystem\n  # and all urls will be in form of `file:///absolute/path/to/file.css`.\n  pdf_url_getter = PathUrlGetter()\n\n  # And `AbsoluteUrlGetter` is for cases when static resources should be\n  # accessed by http;\n  # Those converters are very simple and you may write your own in couple of \n  # minutes.\n  # Converter will be available in template context as `pdf_url_converter`.\n  # But there are utilities that will use it, so you don't have to.\n  def get_pdf_url_getter(self):\n    return AbsoluteUrlGetter(self.request.build_absolute_uri('/'))\n\n\n# For debugging purposes you may want to see the resulting html without \n# turning it to pdf document, but with all changes that url_converter \n# have done.\n# For that you may do the following:\n\n\n# Rewrite response to omit pdf generation step:\nclass HTMLResponse(HTML2PDFTemplateResponseMixin.response_class):\n  @property\n  def rendered_content(self):\n    return self.source_content\n\n\n# And use that response \nclass MyPDFPreviewView(MyPDFView):\n  # So changing the response class in view will result in plain html rendering.\n  response_class = HTMLResponse\n  content_type = 'text/html; charset=utf-8'\n  pdf_filename = None\n  pdf_attachment = False\n  # Here you may redefine url getter, for example:\n  pdf_url_getter = AbsoluteUrlGetter('http://localhost')\n```\n\n#### Templates\n\nFor a default django templates:\n\n```jinja\n{% load html2pdf %}\n\n<!-- Same as django's `static` tag. -->\n{% html2pdf_static 'static-path.css' %}\n\n<!-- For uploads/media you should also use a special tag.  -->\n{% html2pdf_media obj.upload.url %}\n```\n\nFor \"jinja\" templates there is an extension: `wc_html2pdf.contrib.django.jinja.extensions.HTML2PDFUrlGetterExtension`. That will add 2 global functions with the same functionality:\n\n```jinja\n<!-- Static path transformer: -->\n{{ html2pdf_static('static-path.css') }}\n\n<!-- Uploads path transformer: -->\n{{ html2pdf_media(obj.upload.url) }}\n```\n# Changelog\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n## [0.1.0]\nInitial version.\n",
    "bugtrack_url": null,
    "license": "MIT License",
    "summary": "HTML to PDF conversion utilities.",
    "version": "0.1.0",
    "project_urls": null,
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "118bff2b8adef2a0a6925b998ad6526f5eff84f24a4cc384612086751deea06c",
                "md5": "c2436872d7364c0bf67d6944eaa0b85f",
                "sha256": "0fc28e5d51f12950fa4a96346c8bea6096c69553dc74dfe0ea99d883fc83b79d"
            },
            "downloads": -1,
            "filename": "wc-html2pdf-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "c2436872d7364c0bf67d6944eaa0b85f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 12070,
            "upload_time": "2024-06-17T09:49:41",
            "upload_time_iso_8601": "2024-06-17T09:49:41.925085Z",
            "url": "https://files.pythonhosted.org/packages/11/8b/ff2b8adef2a0a6925b998ad6526f5eff84f24a4cc384612086751deea06c/wc-html2pdf-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-06-17 09:49:41",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "wc-html2pdf"
}
        
Elapsed time: 0.24061s