Turns CSS blocks into style attributes
Project description
Looking for sponsors
This project is actively looking for corporate sponsorship. If you want to help making this an active project consider pinging Peter and we can talk about putting up logos and links to your company.
Python versions
Our tox.ini makes sure premailer works in:
Python 3.4
Python 3.5
Python 3.6
Python 3.7
Python 3.8
PyPy
Turns CSS blocks into style attributes
When you send HTML emails you can’t use style tags but instead you have to put inline style attributes on every element. So from this:
<html>
<style type="text/css">
h1 { border:1px solid black }
p { color:red;}
</style>
<h1 style="font-weight:bolder">Peter</h1>
<p>Hej</p>
</html>You want this:
<html>
<h1 style="font-weight:bolder; border:1px solid black">Peter</h1>
<p style="color:red">Hej</p>
</html>premailer does this. It parses an HTML page, looks up style blocks and parses the CSS. It then uses the lxml.html parser to modify the DOM tree of the page accordingly.
Warning! By default, premailer will attempt to download any external stylesheets by URL over the Internet. If you want to prevent this you can use the allow_network=False option.
Getting started
If you haven’t already done so, install premailer first:
$ pip install premailer
Next, the most basic use is to use the shortcut function, like this:
>>> from premailer import transform
>>> print(transform("""
... <html>
... <style type="text/css">
... h1 { border:1px solid black }
... p { color:red;}
... p::first-letter { float:left; }
... </style>
... <style type="text/css" data-premailer="ignore">
... h1 { color:blue; }
... </style>
... <h1 style="font-weight:bolder">Peter</h1>
... <p>Hej</p>
... </html>
... """))
<html>
<head>
<style type="text/css">p::first-letter {float:left}</style>
<style type="text/css">
h1 { color:blue; }
</style>
</head>
<body>
<h1 style="border:1px solid black; font-weight:bolder">Peter</h1>
<p style="color:red">Hej</p>
</body>
</html>The transform shortcut function transforms the given HTML using the defaults for all options:
base_url=None, # Optional URL prepended to all relative links (both stylesheets and internal)
disable_link_rewrites=False, # Allow link rewrites (e.g. using base_url)
preserve_internal_links=False, # Do not preserve links to named anchors when using base_url
preserve_inline_attachments=True, # Preserve links with cid: scheme when base_url is specified
preserve_handlebar_syntax=False # Preserve handlebar syntax from being encoded
exclude_pseudoclasses=True, # Ignore pseudoclasses when processing styles
keep_style_tags=False, # Discard original style tag
include_star_selectors=False, # Ignore star selectors when processing styles
remove_classes=False, # Leave class attributes on HTML elements
capitalize_float_margin=False, # Do not capitalize float and margin properties
strip_important=True, # Remove !important from property values
external_styles=None, # Optional list of URLs to load and parse
css_text=None, # Optional CSS text to parse
method="html", # Parse input as HTML (as opposed to "xml")
base_path=None, # Optional base path to stylesheet in your file system
disable_basic_attributes=None, # Optional list of attribute names to preserve on HTML elements
disable_validation=False, # Validate CSS when parsing it with cssutils
cache_css_parsing=True, # Do cache parsed output for CSS
cssutils_logging_handler=None, # See "Capturing logging from cssutils" below
cssutils_logging_level=None,
disable_leftover_css=False, # Output CSS that was not inlined into the HEAD
align_floating_images=True, # Add align attribute for floated images
remove_unset_properties=True # Remove CSS properties if their value is unset when merged
allow_network=True # allow network access to fetch linked css files
allow_insecure_ssl=False # Don't allow unverified SSL certificates for external links
allow_loading_external_files=False # Allow loading any non-HTTP external file URL
session=None # Session used for http requests - supply your own for caching or to provide authenticationFor more advanced options, check out the code of the Premailer class and all its options in its constructor.
You can also use premailer from the command line by using its main module.
$ python -m premailer -h
usage: python -m premailer [options]
optional arguments:
-h, --help show this help message and exit
-f [INFILE], --file [INFILE]
Specifies the input file. The default is stdin.
-o [OUTFILE], --output [OUTFILE]
Specifies the output file. The default is stdout.
--base-url BASE_URL
--remove-internal-links PRESERVE_INTERNAL_LINKS
Remove links that start with a '#' like anchors.
--exclude-pseudoclasses
Pseudo classes like p:last-child', p:first-child, etc
--preserve-style-tags
Do not delete <style></style> tags from the html
document.
--remove-star-selectors
All wildcard selectors like '* {color: black}' will be
removed.
--remove-classes Remove all class attributes from all elements
--strip-important Remove '!important' for all css declarations.
--method METHOD The type of html to output. 'html' for HTML, 'xml' for
XHTML.
--base-path BASE_PATH
The base path for all external stylsheets.
--external-style EXTERNAL_STYLES
The path to an external stylesheet to be loaded.
--disable-basic-attributes DISABLE_BASIC_ATTRIBUTES
Disable provided basic attributes (comma separated)
--disable-validation Disable CSSParser validation of attributes and values
--pretty Pretty-print the outputted HTML.
--allow-insecure-ssl Skip SSL certificate verification for external URLs.
--allow-loading-external-files Allow opening any non-HTTP external file URL.
A basic example:
$ python -m premailer --base-url=http://google.com/ -f newsletter.html
<html>
<head><style>.heading { color:red; }</style></head>
<body><h1 class="heading" style="color:red"><a href="http://google.com/">Title</a></h1></body>
</html>
The command line interface supports standard input.
$ echo '<style>.heading { color:red; }</style><h1 class="heading"><a href="/">Title</a></h1>' | python -m premailer --base-url=http://google.com/
<html>
<head><style>.heading { color:red; }</style></head>
<body><h1 class="heading" style="color:red"><a href="http://google.com/">Title</a></h1></body>
</html>
Turning relative URLs into absolute URLs
Another thing premailer can do for you is to turn relative URLs (e.g. “/some/page.html” into “http://www.peterbe.com/some/page.html”). It does this to all href and src attributes that don’t have a :// part in it. For example, turning this:
<html>
<body>
<a href="/">Home</a>
<a href="page.html">Page</a>
<a href="http://crosstips.org">External</a>
<img src="/folder/">Folder</a>
</body>
</html>Into this:
<html>
<body>
<a href="http://www.peterbe.com/">Home</a>
<a href="http://www.peterbe.com/page.html">Page</a>
<a href="http://crosstips.org">External</a>
<img src="http://www.peterbe.com/folder/">Folder</a>
</body>
</html>by using transform('...', base_url='http://www.peterbe.com/').
HTML attributes created additionally
Certain HTML attributes are also created on the HTML if the CSS contains any ones that are easily translated into HTML attributes. For example, if you have this CSS: td { background-color:#eee; } then this is transformed into style="background-color:#eee" and as an HTML attribute bgcolor="#eee".
Having these extra attributes basically as a “back up” for really shit email clients that can’t even take the style attributes. A lot of professional HTML newsletters such as Amazon’s use this. You can disable some attributes in disable_basic_attributes.
Capturing logging from cssutils
cssutils is the library that premailer uses to parse CSS. It will use the python logging module to mention all issues it has with parsing your CSS. If you want to capture this, you have to pass in cssutils_logging_handler and cssutils_logging_level (optional). For example like this:
>>> import logging
>>> import premailer
>>> from io import StringIO
>>> mylog = StringIO()
>>> myhandler = logging.StreamHandler(mylog)
>>> p = premailer.Premailer(
... cssutils_logging_handler=myhandler,
... cssutils_logging_level=logging.INFO
... )
>>> result = p.transform("""
... <html>
... <style type="text/css">
... @keyframes foo { from { opacity: 0; } to { opacity: 1; } }
... </style>
... <p>Hej</p>
... </html>
... """)
>>> mylog.getvalue()
'CSSStylesheet: Unknown @rule found. [2:1: @keyframes]\n'If execution speed is on your mind
If execution speed is important, it’s very plausible that you’re not just converting 1 HTML document but a lot of HTML documents. Then, the first thing you should do is avoid using the premailer.transform function because it creates a Premailer class instance every time.
# WRONG WAY!
from premailer import transform
for html_string in get_html_documents():
transformed = transform(html_string, base_url=MY_BASE_URL)
# do something with 'transformed'Instead…
# RIGHT WAY
from premailer import Premailer
instance = Premailer(base_url=MY_BASE_URL)
for html_string in get_html_documents():
transformed = instance.transform(html_string)
# do something with 'transformed'Another thing to watch out for when you’re reusing the same imported Python code and reusing it is that internal memoize function caches might build up. The environment variable to control is PREMAILER_CACHE_MAXSIZE. This parameter requires a little bit of fine-tuning and calibration if your workload is really big and memory even becomes an issue.
Advanced options
Below are some advanced configuration options that probably doesn’t matter for most people with regular load.
Choosing the cache implementation
By default, premailer uses LFUCache to cache selectors, styles and parsed CSS strings. If LFU doesn’t serve your purpose, it is possible to switch to an alternate implementation using below environment variables.
PREMAILER_CACHE: Can be LRU, LFU or TTL. Default is LFU.
PREMAILER_CACHE_MAXSIZE: Maximum no. of items to be stored in cache. Defaults to 128.
PREMAILER_CACHE_TTL: Time to live for cache entries. Only applicable for TTL cache. Defaults to 1 hour.
Getting coding
First clone the code and create whatever virtualenv you need, then run:
pip install -e ".[dev]"Then to run the tests, run:
toxThis will run the whole test suite for every possible version of Python it can find on your system. To run the tests more incrementally, open up the tox.ini and see how it works.
Code style is all black
All code has to be formatted with Black and the best tool for checking this is therapist since it can help you run all, help you fix things, and help you make sure linting is passing before you git commit. This project also uses flake8 to check other things Black can’t check.
To check linting with tox use:
tox -e lintTo install the therapist pre-commit hook simply run:
therapist installWhen you run therapist run it will only check the files you’ve touched. To run it for all files use:
therapist run --use-tracked-filesAnd to fix all/any issues run:
therapist run --use-tracked-files --fixRelease history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file premailer-3.10.0.tar.gz.
File metadata
- Download URL: premailer-3.10.0.tar.gz
- Upload date:
- Size: 24.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.46.0 CPython/3.8.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | d1875a8411f5dc92b53ef9f193db6c0f879dc378d618e0ad292723e388bfe4c2 |
|
| MD5 | 62583a53e167e2b35e5d1dc500554197 |
|
| BLAKE2b-256 | a36fe49bd31941eff2987076383fa6d811eb785a28f498f5bb131e981bd71e13 |
File details
Details for the file premailer-3.10.0-py2.py3-none-any.whl.
File metadata
- Download URL: premailer-3.10.0-py2.py3-none-any.whl
- Upload date:
- Size: 19.5 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.46.0 CPython/3.8.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 021b8196364d7df96d04f9ade51b794d0b77bcc19e998321c515633a2273be1a |
|
| MD5 | e75019baaed983e693f922b5bd216ec2 |
|
| BLAKE2b-256 | b1074e8d94f94c7d41ca5ddf8a9695ad87b888104e2fd41a35546c1dc9ca74ac |
