Turns CSS blocks into style attributes
Project description
premailer
=========
[](https://travis-ci.org/peterbe/premailer)
[](https://coveralls.io/r/peterbe/premailer?branch=master)
Python versions
---------------
Our [tox.ini](https://github.com/peterbe/premailer/blob/master/tox.ini) makes sure premailer works in:
* Python 2.6
* Python 2.7
* Python 3.3
* Python 3.4
* 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
<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
<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.
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>
... <h1 style="font-weight:bolder">Peter</h1>
... <p>Hej</p>
... </html>
... """)
<html>
<head></head>
<body>
<h1 style="font-weight:bolder; border:1px solid black">Peter</h1>
<p style="color:red">Hej</p>
</body>
</html>
For 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 his 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
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
<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
<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/')`.
Ignore certain `<style>` or `<link>` tags
-----------------------------------------
Suppose you have a style tag that you don't want to have processed and
transformed you can simply set a data attribute on the tag like:
```html
<head>
<style>/* this gets processed */</style>
<style data-premailer="ignore">/* this gets ignored */</style>
</head>
```
That tag gets completely ignored except when the HTML is processed, the
attribute `data-premailer` is removed.
It works equally for a `<link>` tag like:
```html
<head>
<link rel="stylesheet" href="foo.css" data-premailer="ignore">
</head>
```
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`
Running tests with tox
----------------------
To run `tox` you don't need to have all available Python versions installed because it will only work on those you have. To use `tox` first install it:
pip install tox
Then simply start it with:
tox
=========
[](https://travis-ci.org/peterbe/premailer)
[](https://coveralls.io/r/peterbe/premailer?branch=master)
Python versions
---------------
Our [tox.ini](https://github.com/peterbe/premailer/blob/master/tox.ini) makes sure premailer works in:
* Python 2.6
* Python 2.7
* Python 3.3
* Python 3.4
* 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
<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
<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.
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>
... <h1 style="font-weight:bolder">Peter</h1>
... <p>Hej</p>
... </html>
... """)
<html>
<head></head>
<body>
<h1 style="font-weight:bolder; border:1px solid black">Peter</h1>
<p style="color:red">Hej</p>
</body>
</html>
For 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 his 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
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
<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
<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/')`.
Ignore certain `<style>` or `<link>` tags
-----------------------------------------
Suppose you have a style tag that you don't want to have processed and
transformed you can simply set a data attribute on the tag like:
```html
<head>
<style>/* this gets processed */</style>
<style data-premailer="ignore">/* this gets ignored */</style>
</head>
```
That tag gets completely ignored except when the HTML is processed, the
attribute `data-premailer` is removed.
It works equally for a `<link>` tag like:
```html
<head>
<link rel="stylesheet" href="foo.css" data-premailer="ignore">
</head>
```
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`
Running tests with tox
----------------------
To run `tox` you don't need to have all available Python versions installed because it will only work on those you have. To use `tox` first install it:
pip install tox
Then simply start it with:
tox
Release 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
premailer-2.8.0.tar.gz
(12.1 kB
view details)
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
premailer-2.8.0-py3-none-any.whl
(14.8 kB
view details)
premailer-2.8.0-py2-none-any.whl
(14.8 kB
view details)
File details
Details for the file premailer-2.8.0.tar.gz.
File metadata
- Download URL: premailer-2.8.0.tar.gz
- Upload date:
- Size: 12.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
28891727f34d46a23b0fee59b4c21b9fd2ad68e1c06c25c11e5b68b4dd898098
|
|
| MD5 |
6f170029c2fa1b80a080f7a177d2b243
|
|
| BLAKE2b-256 |
80a422d34475e83256b7f53e266837c2627db9b646fb5a12d048d4fce368bb10
|
File details
Details for the file premailer-2.8.0-py3-none-any.whl.
File metadata
- Download URL: premailer-2.8.0-py3-none-any.whl
- Upload date:
- Size: 14.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
216113fa55ec54e115a48e1cbb66633e07af078227ecc0952a9e894fe6a29bb1
|
|
| MD5 |
1f41b5a023f9064cd0522d70241ecca9
|
|
| BLAKE2b-256 |
3d529d4b2f21ee4bb6c254d631fc8932f47e7e8c9eea1ab4bdff83f8fd37d15e
|
File details
Details for the file premailer-2.8.0-py2-none-any.whl.
File metadata
- Download URL: premailer-2.8.0-py2-none-any.whl
- Upload date:
- Size: 14.8 kB
- Tags: Python 2
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
884f0d16c98ebd77714f0c731ccfcaaf8380721b95ef4b17ef3181d52760fb91
|
|
| MD5 |
7027eb96fd7ded466164548fd2f285d9
|
|
| BLAKE2b-256 |
7af3f4e17c947232292d31b592f8fbdbd6becab25a43223f387c0feaf9e046b9
|
