| Name | wc-html2pdf JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | HTML to PDF conversion utilities. |
| upload_time | 2024-06-17 09:49:41 |
| maintainer | None |
| docs_url | None |
| author | WebCase |
| requires_python | >=3.6 |
| license | MIT 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"
}
