| Name | django-chromepdf JSON |
| Version |
1.7.4
JSON |
| download |
| home_page | None |
| Summary | A small Python 3 library that uses Selenium and Google Chrome to convert HTML into a PDF. |
| upload_time | 2024-11-04 15:08:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | ~=3.6 |
| license | BSD |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ChromePDF
## Overview
ChromePDF is a small Python 3 library that uses [Selenium](https://pypi.org/project/selenium/) and Google Chrome to convert HTML into a PDF. This is accomplished by using Chrome's `Page.printToPDF` DevTools command.
ChromePDF provides a function that accepts an html string, plus a dict of page parameters, and other settings, and returns the bytes containing a PDF:
```
pdf_bytes = generate_pdf(html_string, pdf_kwargs, **kwargs)
```
As of version 1.4, ChromePDF can also be run from the command line.
```
python -m chromepdf generate-pdf --chrome-path=/usr/bin/google-chrome path/to/input.html path/to/output.pdf
```
Because it renders via Chrome, it supports a wide range of CSS and HTML tags that should display the same as if you used Chrome to view the HTML itself.
ChromePDF can take advantage of [Django](https://pypi.org/project/Django/) settings for configuration, but Django is not a required dependency.
Official ChromePDF releases [are available on PyPI](https://pypi.org/project/django-chromepdf/).
## Installation
**1. Install ChromePDF via pip.**
The latest version can be installed via PyPI. This will also install Selenium, the only direct dependency (Selenium versions 3 and 4 are supported; 3 will be used if already present, otherwise will install 4).
You may view the [Changelog](CHANGELOG.md) for a list of all ChromePDF version changes. ChromePDF uses [semantic versioning](https://semver.org/) for its release numbering. You are encouraged to pin your requirements to a Major.Minor version in a manner that will also receive Bugfix updates like so:
```
pip install django-chromepdf~=1.7.4
```
**2. Set the location of your Chrome executable.** This can be done in one of two ways:
* In your Django settings, set `CHROMEPDF['CHROME_PATH']` to the full path of the executable (E.G., `r'C:\Program Files (x86)\Google\...\chrome.exe'`)
* OR, pass `chrome_path` as a keyword argument to the `generate_pdf()` function.
## About Chromedrivers
A chromedriver executable is necessary to interface between Selenium and Chrome. ChromePDF will automatically check the version of your Chrome binary and download the required chromedriver [from the Chrome website](https://chromedriver.chromium.org/downloads) if it doesn't exist, into your `site-packages/chromepdf/chromedrivers/` folder. If the Chrome binary ever gets upgraded, ChromePDF will realize this and download the required driver for it.
You may disable these automatic downloads in the following way:
* In your Django settings, set `CHROMEPDF['CHROMEDRIVER_DOWNLOADS']` to False
* OR, pass a `chromedriver_downloads=False` argument to `generate_pdf()`
You may also specify a chromedriver path manually. This is recommended if you disable downloads:
* In your Django settings, set `CHROMEPDF['CHROMEDRIVER_PATH']` to the full path of the executable (E.G., `r'C:\Users\myuser\...\chromedriver_win32\chromedriver.exe'`)
* OR, pass a `chromedriver_path` argument to `generate_pdf()` containing the path.
* OR, if both of the above are not set, and you've disabled downloads, and if your chromedriver is in your `PATH` environment variable, then Selenium should be able to find it automatically.
## Example: `generate_pdf()`
Note: `generate_pdf()` cannot include external files including CSS. You must include all your CSS within `<style>` tags or as inline styles.
```python
# NOTE: This example assumes that you've set Django's settings.CHROMEPDF['CHROME_PATH'] = '(path to your Chrome instance)'
from chromepdf import generate_pdf
with open('myfile.html','r') as f:
html_string = f.read()
pdf_kwargs = {
'paperFormat': 'A4',
'marginTop': '2.5cm',
'marginLeft': '2cm',
'marginRight': '2cm',
'marginBottom': '3.5cm',
'displayHeaderFooter': True,
'headerTemplate': '',
'footerTemplate': '''
<div style='font-size: 12px; width: 100%; padding: 0; padding-left: 2cm; padding-bottom: 1cm; margin: 0; '>
Page <span class='pageNumber'></span> of <span class='totalPages'></span>
</div>
''',
}
pdf_bytes = generate_pdf(html_string, pdf_kwargs)
with open('myfile.pdf', 'wb') as file:
file.write(pdf_bytes)
```
## Example: Command-Line Usage
ChromePDF can generate PDFs from the command-line. This method will not rely on Django settings. Example syntax:
```
# Convert file.html into file.pdf and place in the same directory
python -m chromepdf generate-pdf path/to/file.html [kwargs]
# Convert file.html and place the output PDF file at a specific path.
python -m chromepdf generate-pdf path/to/file.html path/to/output.pdf [kwargs]
```
Keyword arguments for command-line usage are almost identical to `generate_pdf()` keyword arguments:
```
--chrome-path=path/to/google-chrome
--chromedriver-path=path/to/chromedriver
--chromedriver-downloads=0 # 0 or 1
--chrome-args="--arg1 --arg2" # Always use quotes to avoid misinterpreting as commands.
--pdf-kwargs-json=path/to/file.json # JSON file containing a dict of values to pass to pdf_kwargs
```
The recommended usage is to pass a `--chrome-path`, and let ChromePDF handle the chromedriver downloads automatically.
```
python -m chromepdf generate-pdf --chrome-path=/usr/bin/google-chrome path/to/file.html path/to/output.pdf
```
The command will have a return code of zero on success, and nonzero on failure.
## Django Settings
You can specify default settings in your Django settings file, if desired, via a `CHROMEPDF` settings. Anything passed via the `pdf_kwargs` argument will override the `PDF_KWARGS` settings.
```python
# settings.__init__.py
CHROMEPDF = {
'CHROME_PATH': r'C:\Program Files (x86)\Google\...\chrome.exe',
'CHROME_ARGS': [], # Optional list of command-line argument strings to pass to Chrome when rendering a PDF.
'CHROMEDRIVER_PATH': None, # will rely on downloads instead
'CHROMEDRIVER_DOWNLOADS': True, # automatically download the correct chromedriver for the chrome path
'PDF_KWARGS': {
'paperFormat': 'A4',
'marginTop': '2.5cm',
'marginLeft': '2cm',
'marginRight': '2cm',
'marginBottom': '3.5cm',
}
}
```
## PDF_KWARGS Options
The `pdf_kwargs` argument to `generate_pdf()` lets you specify all the arguments for Chrome's `Page.printToPDF` API. Its API can be viewed here:
[Page.printToPDF API](https://chromedevtools.github.io/devtools-protocol/1-3/Page/#method-printToPDF) (url is funky. If you get a 404, try reloading/refreshing)
Some shortcut parameters are provided by `generate_pdf()` for convenience. Here is a list of all the options:
Layout:
* **scale**: Scale of the PDF. Default `1`.
* **landscape**: `True` to use landscape mode. Default `False`.
Page Dimensions:
* **paperWidth**: Width of the paper, in inches. Can also use some CSS string values, like `'30cm'`. Default: `8.5`
* **paperHeight**: Height of the paper, in inches. Can also use some CSS string values, like `'30cm'`. Default: `11`
* **paperFormat**: A string indicating a paper size format, such as `'letter'` or `'A4'`. Case-insensitive. This will override `paperWidth` and `paperHeight`. Not part of `Page.printToPDF` API. Provided for convenience.
Content:
* **displayHeaderFooter**: `True` to display header and footer. Default `False`.
* **headerTemplate**: HTML containing the header for all pages. Default is an empty string. You may pass html tags with specific classes in order to insert values. For example, `<span class='title'></span>` would insert the the title.
* date: formatted print date
* title: document title
* url: document location
* pageNumber: current page number
* totalPages: total pages in the document
* **footerTemplate**: HTML containing the footer for all pages. Default is an empty string. You may pass html tags with specific classes in order to insert values (same as above)
* **printBackground**: `True` to print background graphics. Default `False`.
Margins:
* **margin**: Shortcut used to set all four margin values at once. Not part of `Page.printToPDF` API. Provided for convenience.
* **marginTop**: Top margin. Default: `'1cm'`
* **marginBottom**: Bottom margin. Default: `'1cm'`
* **marginLeft**: Left margin. Default: `'1cm'`
* **marginRight**: Right margin. Default: `'1cm'`
Page Ranges:
* **pageRanges**: String indicating page ranges to use. Example: `'1-5, 8, 11-13'`
* **ignoreInvalidPageRanges**: If `True`, will silently ignore invalid 'pageRanges' values. Default `False`.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-chromepdf",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.6",
"maintainer_email": "Andrew Kukwa <kukwaa@imsweb.com>",
"keywords": null,
"author": null,
"author_email": "Andrew Kukwa <kukwaa@imsweb.com>",
"download_url": "https://files.pythonhosted.org/packages/c4/61/0734845d6cdfc612a42363c9c918d63905757cec3df2985437eacc7d246a/django-chromepdf-1.7.4.tar.gz",
"platform": null,
"description": "# ChromePDF\n\n## Overview\n\nChromePDF is a small Python 3 library that uses [Selenium](https://pypi.org/project/selenium/) and Google Chrome to convert HTML into a PDF. This is accomplished by using Chrome's `Page.printToPDF` DevTools command.\n\nChromePDF provides a function that accepts an html string, plus a dict of page parameters, and other settings, and returns the bytes containing a PDF:\n\n```\npdf_bytes = generate_pdf(html_string, pdf_kwargs, **kwargs)\n```\n\nAs of version 1.4, ChromePDF can also be run from the command line.\n\n```\npython -m chromepdf generate-pdf --chrome-path=/usr/bin/google-chrome path/to/input.html path/to/output.pdf\n```\n\nBecause it renders via Chrome, it supports a wide range of CSS and HTML tags that should display the same as if you used Chrome to view the HTML itself.\n\nChromePDF can take advantage of [Django](https://pypi.org/project/Django/) settings for configuration, but Django is not a required dependency.\n\nOfficial ChromePDF releases [are available on PyPI](https://pypi.org/project/django-chromepdf/).\n\n## Installation\n\n**1. Install ChromePDF via pip.**\n\nThe latest version can be installed via PyPI. This will also install Selenium, the only direct dependency (Selenium versions 3 and 4 are supported; 3 will be used if already present, otherwise will install 4). \n\nYou may view the [Changelog](CHANGELOG.md) for a list of all ChromePDF version changes. ChromePDF uses [semantic versioning](https://semver.org/) for its release numbering. You are encouraged to pin your requirements to a Major.Minor version in a manner that will also receive Bugfix updates like so:\n```\npip install django-chromepdf~=1.7.4\n```\n\n**2. Set the location of your Chrome executable.** This can be done in one of two ways:\n\n* In your Django settings, set `CHROMEPDF['CHROME_PATH']` to the full path of the executable (E.G., `r'C:\\Program Files (x86)\\Google\\...\\chrome.exe'`)\n* OR, pass `chrome_path` as a keyword argument to the `generate_pdf()` function.\n\n## About Chromedrivers\n\nA chromedriver executable is necessary to interface between Selenium and Chrome. ChromePDF will automatically check the version of your Chrome binary and download the required chromedriver [from the Chrome website](https://chromedriver.chromium.org/downloads) if it doesn't exist, into your `site-packages/chromepdf/chromedrivers/` folder. If the Chrome binary ever gets upgraded, ChromePDF will realize this and download the required driver for it.\n\nYou may disable these automatic downloads in the following way:\n* In your Django settings, set `CHROMEPDF['CHROMEDRIVER_DOWNLOADS']` to False\n* OR, pass a `chromedriver_downloads=False` argument to `generate_pdf()`\n\nYou may also specify a chromedriver path manually. This is recommended if you disable downloads:\n* In your Django settings, set `CHROMEPDF['CHROMEDRIVER_PATH']` to the full path of the executable (E.G., `r'C:\\Users\\myuser\\...\\chromedriver_win32\\chromedriver.exe'`)\n* OR, pass a `chromedriver_path` argument to `generate_pdf()` containing the path.\n* OR, if both of the above are not set, and you've disabled downloads, and if your chromedriver is in your `PATH` environment variable, then Selenium should be able to find it automatically.\n\n## Example: `generate_pdf()`\nNote: `generate_pdf()` cannot include external files including CSS. You must include all your CSS within `<style>` tags or as inline styles.\n\n```python\n# NOTE: This example assumes that you've set Django's settings.CHROMEPDF['CHROME_PATH'] = '(path to your Chrome instance)'\nfrom chromepdf import generate_pdf \n\nwith open('myfile.html','r') as f:\n html_string = f.read()\n \npdf_kwargs = {\n 'paperFormat': 'A4',\n 'marginTop': '2.5cm',\n 'marginLeft': '2cm',\n 'marginRight': '2cm',\n 'marginBottom': '3.5cm',\n 'displayHeaderFooter': True,\n 'headerTemplate': '',\n 'footerTemplate': '''\n <div style='font-size: 12px; width: 100%; padding: 0; padding-left: 2cm; padding-bottom: 1cm; margin: 0; '>\n Page <span class='pageNumber'></span> of <span class='totalPages'></span>\n </div>\n ''',\n}\npdf_bytes = generate_pdf(html_string, pdf_kwargs)\n\nwith open('myfile.pdf', 'wb') as file:\n file.write(pdf_bytes)\n```\n\n## Example: Command-Line Usage\nChromePDF can generate PDFs from the command-line. This method will not rely on Django settings. Example syntax:\n```\n# Convert file.html into file.pdf and place in the same directory\npython -m chromepdf generate-pdf path/to/file.html [kwargs]\n\n# Convert file.html and place the output PDF file at a specific path.\npython -m chromepdf generate-pdf path/to/file.html path/to/output.pdf [kwargs]\n```\nKeyword arguments for command-line usage are almost identical to `generate_pdf()` keyword arguments:\n```\n--chrome-path=path/to/google-chrome\n--chromedriver-path=path/to/chromedriver\n--chromedriver-downloads=0 # 0 or 1\n--chrome-args=\"--arg1 --arg2\" # Always use quotes to avoid misinterpreting as commands. \n--pdf-kwargs-json=path/to/file.json # JSON file containing a dict of values to pass to pdf_kwargs\n```\nThe recommended usage is to pass a `--chrome-path`, and let ChromePDF handle the chromedriver downloads automatically.\n```\npython -m chromepdf generate-pdf --chrome-path=/usr/bin/google-chrome path/to/file.html path/to/output.pdf\n```\nThe command will have a return code of zero on success, and nonzero on failure.\n\n## Django Settings\n\nYou can specify default settings in your Django settings file, if desired, via a `CHROMEPDF` settings. Anything passed via the `pdf_kwargs` argument will override the `PDF_KWARGS` settings.\n```python\n# settings.__init__.py\n\nCHROMEPDF = {\n 'CHROME_PATH': r'C:\\Program Files (x86)\\Google\\...\\chrome.exe',\n 'CHROME_ARGS': [], # Optional list of command-line argument strings to pass to Chrome when rendering a PDF.\n 'CHROMEDRIVER_PATH': None, # will rely on downloads instead\n 'CHROMEDRIVER_DOWNLOADS': True, # automatically download the correct chromedriver for the chrome path\n 'PDF_KWARGS': {\n 'paperFormat': 'A4',\n 'marginTop': '2.5cm',\n 'marginLeft': '2cm',\n 'marginRight': '2cm',\n 'marginBottom': '3.5cm',\n }\n}\n```\n\n\n## PDF_KWARGS Options\n\nThe `pdf_kwargs` argument to `generate_pdf()` lets you specify all the arguments for Chrome's `Page.printToPDF` API. Its API can be viewed here:\n\n[Page.printToPDF API](https://chromedevtools.github.io/devtools-protocol/1-3/Page/#method-printToPDF) (url is funky. If you get a 404, try reloading/refreshing)\n\nSome shortcut parameters are provided by `generate_pdf()` for convenience. Here is a list of all the options:\n\nLayout:\n* **scale**: Scale of the PDF. Default `1`.\n* **landscape**: `True` to use landscape mode. Default `False`.\n\nPage Dimensions:\n* **paperWidth**: Width of the paper, in inches. Can also use some CSS string values, like `'30cm'`. Default: `8.5`\n* **paperHeight**: Height of the paper, in inches. Can also use some CSS string values, like `'30cm'`. Default: `11`\n* **paperFormat**: A string indicating a paper size format, such as `'letter'` or `'A4'`. Case-insensitive. This will override `paperWidth` and `paperHeight`. Not part of `Page.printToPDF` API. Provided for convenience.\n\nContent:\n* **displayHeaderFooter**: `True` to display header and footer. Default `False`.\n* **headerTemplate**: HTML containing the header for all pages. Default is an empty string. You may pass html tags with specific classes in order to insert values. For example, `<span class='title'></span>` would insert the the title.\n * date: formatted print date \n * title: document title \n * url: document location \n * pageNumber: current page number \n * totalPages: total pages in the document \n* **footerTemplate**: HTML containing the footer for all pages. Default is an empty string. You may pass html tags with specific classes in order to insert values (same as above)\n* **printBackground**: `True` to print background graphics. Default `False`.\n\nMargins:\n* **margin**: Shortcut used to set all four margin values at once. Not part of `Page.printToPDF` API. Provided for convenience.\n* **marginTop**: Top margin. Default: `'1cm'`\n* **marginBottom**: Bottom margin. Default: `'1cm'`\n* **marginLeft**: Left margin. Default: `'1cm'`\n* **marginRight**: Right margin. Default: `'1cm'`\n\nPage Ranges:\n* **pageRanges**: String indicating page ranges to use. Example: `'1-5, 8, 11-13'`\n* **ignoreInvalidPageRanges**: If `True`, will silently ignore invalid 'pageRanges' values. Default `False`.\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "A small Python 3 library that uses Selenium and Google Chrome to convert HTML into a PDF.",
"version": "1.7.4",
"project_urls": {
"changelog": "https://github.com/imsweb/django-chromepdf/blob/master/CHANGELOG.md",
"homepage": "https://github.com/imsweb/django-chromepdf",
"repository": "https://github.com/imsweb/django-chromepdf"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bc35740e37a605a2b94249dab6103b059cdbbfd4c5328c9737dfb173f5072583",
"md5": "e3daf54a83bf9a5d7a49ec9c71e68580",
"sha256": "752d8a3375e2d6e691044e83b3fce302d719f91135a22ce81ec9f4bfc8d2a511"
},
"downloads": -1,
"filename": "django_chromepdf-1.7.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3daf54a83bf9a5d7a49ec9c71e68580",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.6",
"size": 25748,
"upload_time": "2024-11-04T15:08:12",
"upload_time_iso_8601": "2024-11-04T15:08:12.039936Z",
"url": "https://files.pythonhosted.org/packages/bc/35/740e37a605a2b94249dab6103b059cdbbfd4c5328c9737dfb173f5072583/django_chromepdf-1.7.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c4610734845d6cdfc612a42363c9c918d63905757cec3df2985437eacc7d246a",
"md5": "086228ca84d7bb53e47222a3d9fcd362",
"sha256": "8450c3e497609d0b0333408bf79f2af6e098dd36a8224f61375dbccee1163ed2"
},
"downloads": -1,
"filename": "django-chromepdf-1.7.4.tar.gz",
"has_sig": false,
"md5_digest": "086228ca84d7bb53e47222a3d9fcd362",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.6",
"size": 26091,
"upload_time": "2024-11-04T15:08:13",
"upload_time_iso_8601": "2024-11-04T15:08:13.408744Z",
"url": "https://files.pythonhosted.org/packages/c4/61/0734845d6cdfc612a42363c9c918d63905757cec3df2985437eacc7d246a/django-chromepdf-1.7.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-04 15:08:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "imsweb",
"github_project": "django-chromepdf",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-chromepdf"
}
