High-performance library for inlining CSS into HTML 'style' attributes
Project description
css_inline
css-inline
inlines CSS into HTML documents, using components from Mozilla's Servo project.
This process is essential for sending HTML emails as you need to use "style" attributes instead of "style" tags.
For instance, the library transforms HTML like this:
<html>
<head>
<title>Test</title>
<style>h1 { color:blue; }</style>
</head>
<body>
<h1>Big Text</h1>
</body>
</html>
into:
<html>
<head>
<title>Test</title>
</head>
<body>
<h1 style="color:blue;">Big Text</h1>
</body>
</html>
- Uses reliable components from Mozilla's Servo
- 10-300x faster than alternatives
- Inlines CSS from
style
andlink
tags - Removes
style
andlink
tags - Resolves external stylesheets (including local files)
- Can process multiple documents in parallel
- Works on Linux, Windows, and macOS
- Supports HTML5 & CSS3
Installation
Install with pip
:
pip install css_inline
Pre-compiled wheels for most popular platforms are provided. If your platform is not supported, you will need a Rust compiler to build this package from source. The minimum supported Rust version is 1.60.
Usage
import css_inline
HTML = """<html>
<head>
<title>Test</title>
<style>h1 { color:blue; }</style>
</head>
<body>
<h1>Big Text</h1>
</body>
</html>"""
inlined = css_inline.inline(HTML)
# HTML becomes this:
#
# <html>
# <head>
# <title>Test</title>
# <style>h1 { color:blue; }</style>
# </head>
# <body>
# <h1 style="color:blue;">Big Text</h1>
# </body>
# </html>
If you want to inline many HTML documents, you can utilize inline_many
that processes the input in parallel.
import css_inline
css_inline.inline_many(["<...>", "<...>"])
inline_many
will spawn threads on the Rust level; thus, you can expect it's running faster than css_inline.inline
via Python's multiprocessing
or threading
modules.
Configuration
For configuration options use the CSSInliner
class:
import css_inline
inliner = css_inline.CSSInliner(keep_style_tags=True)
inliner.inline("...")
keep_style_tags
. Specifies whether to keep "style" tags after inlining. Default:False
keep_link_tags
. Specifies whether to keep "link" tags after inlining. Default:False
base_url
. The base URL used to resolve relative URLs. If you'd like to load stylesheets from your filesystem, use thefile://
scheme. Default:None
load_remote_stylesheets
. Specifies whether remote stylesheets should be loaded. Default:True
extra_css
. Extra CSS to be inlined. Default:None
preallocate_node_capacity
. Advanced. Preallocates capacity for HTML nodes during parsing. This can improve performance when you have an estimate of the number of nodes in your HTML document. Default:32
You can also skip CSS inlining for an HTML tag by adding the data-css-inline="ignore"
attribute to it:
<head>
<title>Test</title>
<style>h1 { color:blue; }</style>
</head>
<body>
<!-- The tag below won't receive additional styles -->
<h1 data-css-inline="ignore">Big Text</h1>
</body>
The data-css-inline="ignore"
attribute also allows you to skip link
and style
tags:
<head>
<title>Test</title>
<!-- Styles below are ignored -->
<style data-css-inline="ignore">h1 { color:blue; }</style>
</head>
<body>
<h1>Big Text</h1>
</body>
If you'd like to load stylesheets from your filesystem, use the file://
scheme:
import css_inline
# styles/email is relative to the current directory
inliner = css_inline.CSSInliner(base_url="file://styles/email/")
inliner.inline("...")
Standards support & restrictions
css-inline
is built on top of html5ever and cssparser and relies on their behavior for HTML & CSS parsing.
- Only HTML 5 is supported, not XHTML.
- Only CSS 3 is supported.
- Only UTF-8 encoding for string representation. Other document encodings are not yet supported.
If you'd like to work around some XHTML compatibility issues like closing empty tags (<hr>
vs. <hr/>
), you can use the following snippet that involves lxml
:
import css_inline
from lxml import html, etree
document = "..." # Your HTML document
inlined = css_inline.inline(document)
tree = html.fromstring(inlined)
inlined = etree.tostring(tree).decode(encoding="utf-8")
Performance
Due to the usage of efficient tooling from Mozilla's Servo project (html5ever
, rust-cssparser
and others) this
library has excellent performance characteristics. In comparison with other Python projects, it is usually >10x faster than the nearest alternative.
For inlining CSS in the html document from the Usage
section above there is the following breakdown in the benchmarks:
css_inline 0.9.0
- 9.72 uspremailer 3.10.0
- 207.95 us (x21.39)toronado 0.1.0
- 1.03 ms (x106.86)inlinestyler 0.2.5
- 1.69 ms (x174.64)pynliner 0.8.0
- 2.05 ms (x211.89)
Realistic email 1:
css_inline 0.9.0
- 262.33 uspremailer 3.10.0
- 2.11 ms (x8.08)toronado 0.1.0
- 25.51 ms (x97.28)inlinestyler 0.2.5
- 4313 ms (x164.43)pynliner 0.8.0
- 72.55 ms (x276.57)
Realistic email 2:
css_inline 0.9.0
- 151.83 uspremailer 3.10.0
- 4.12 ms (x27.18)toronado 0.1.0
-Error: Pseudo-elements are not supported
inlinestyler 0.2.5
- 28.85 ms (x190.03)pynliner 0.8.0
-Error: No match was found
You can take a look at the benchmarks' code at benches/bench.py
file.
The results above were measured with stable rustc 1.70.0
on Python 3.11.0
.
Comparison with other libraries
Besides performance, css-inline
differs from other Python libraries for CSS inlining.
- Generally supports more CSS features than other libraries (for example,
toronado
andpynliner
do not support pseudo-elements); - It has fewer configuration options and not as flexible as
premailer
; - Works on fewer platforms than LXML-based libraries (
premailer
,inlinestyler
,toronado
, and optionallypynliner
); - Does not have debug logs yet;
- Supports only HTML 5.
Python support
css_inline
supports CPython 3.7, 3.8, 3.9, 3.10, 3.11 and PyPy 3.7, 3.8, 3.9.
Extra materials
If you want to know how this library was created & how it works internally, you could take a look at these articles:
License
This project is licensed under the terms of the MIT license.
Project details
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
Built Distributions
Hashes for css_inline-0.10.0-pp39-pypy39_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f6b014ca040c7a80aeab4eca57aaaa906a40d3322879fc1e395d4b08bda3125a |
|
MD5 | ffcb87b8b5985c8718bafde8d7657367 |
|
BLAKE2b-256 | d894b09e4e6af083805cf7dc3a86cf8de0365b792c7d6b96c47d5f67c8a29e13 |
Hashes for css_inline-0.10.0-pp39-pypy39_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d6a4b953c2e9b3746ab6b0e008492e7d087ce6f63c8df4f5fbcac739f30f8f86 |
|
MD5 | 5701056a97db1492f754234778ff8e6e |
|
BLAKE2b-256 | ffc41e02b4ba33d2747af564b3fcae564bc2f7fcc9144eebe876daa6da95a8d5 |
Hashes for css_inline-0.10.0-pp39-pypy39_pp73-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3f94b93c1f591b136df743cd28b46c50a6d6b494eee016798cae462396a22530 |
|
MD5 | 88a0a69fb3c60737770b6db2cc34054a |
|
BLAKE2b-256 | e96cb80b2e7f36dccd52d2d3dc2c790a805c58a2de8ae1fc046502c77ed4065d |
Hashes for css_inline-0.10.0-pp38-pypy38_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0db048f0146db60c075e13e7d45a4bcc45857f9fb60cf41c4c67f3371b6afe5a |
|
MD5 | 13e1424ce27a3c29cf9da7951c884fea |
|
BLAKE2b-256 | 22ace810b284b1fd0f07a1077a84d547e03fb9c466daa2d50b5756ab8e6f7cdb |
Hashes for css_inline-0.10.0-pp38-pypy38_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 068f3dc8853f1a0f92bd026a436eb001e077755edb7515388da290451cbbcb21 |
|
MD5 | 3972838e83f335843d4e279657706708 |
|
BLAKE2b-256 | 304706cd44a4418f16033e740f1b8225fa83f2dcf824dd63f64da38fe02e7834 |
Hashes for css_inline-0.10.0-pp38-pypy38_pp73-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 45a121c9d49a673dd43b20c0facc51d83775e4f12f27bc01cb96d4d7b2857bfe |
|
MD5 | 6db06f1366de3d7358a76e31770cba33 |
|
BLAKE2b-256 | 4bd33085a6f8a987317988d69df49478daedaa18a736270fe30b291649c6f684 |
Hashes for css_inline-0.10.0-pp37-pypy37_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0dc79c6be58b7127211bb608b6c3df4bcf93af7a0241474dfbd32c7c310bc5b1 |
|
MD5 | c7132b7fe9830d14d596eccb7c249313 |
|
BLAKE2b-256 | d62959a10948fb4f32f539c771fd1974a7f9b7f7eeb5d40f73481d0257721f96 |
Hashes for css_inline-0.10.0-pp37-pypy37_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | af7c6893479f1bddc538a52ff3576d8e2bf6749b5d3d1b85d8b8d71336ccf6eb |
|
MD5 | 52dd41933a78f598ba3aae38719ae780 |
|
BLAKE2b-256 | 140196bfcb080f3146a7f33d6a22a8f5db78b4609fe0a9d01dde186a89c8b9e2 |
Hashes for css_inline-0.10.0-pp37-pypy37_pp73-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | af3e6a075a1564d00bd672eadce4b1b0589eb793488cdba5b3bdeabc067cd45c |
|
MD5 | a62f6459dbea3918684ab5b014440b0e |
|
BLAKE2b-256 | d1aa793328179f6e4c2a3f3299c04a15447a6b53e7064a46184df531408d72b8 |
Hashes for css_inline-0.10.0-cp37-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8e0eed15079851379fe7d4189face53f2259e7863c7197d04f6d8572966550b9 |
|
MD5 | 07ddc8d2f7470a9321011b7f938eb7db |
|
BLAKE2b-256 | 28f1d4a0c59977c33bcfb54741a4fcb231e78a70b5d74c96280102c5ef9b23b3 |
Hashes for css_inline-0.10.0-cp37-abi3-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e646bdd9e878a3760372ecd389568b6bc39c6457b3d01b86867779dbb41343b2 |
|
MD5 | 6d60847b8392c06706ce6c0e8c4507d9 |
|
BLAKE2b-256 | 5445d8528499ce29381f85a2b05c3d265bbe26e068cd07e3c0cc08361362b604 |
Hashes for css_inline-0.10.0-cp37-abi3-musllinux_1_2_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 613e5bbc72110efad2912f917a478508e044d3ba029526bf2020b23d121ad499 |
|
MD5 | b462f97cd95979d4ee61c1cf6a7e14b3 |
|
BLAKE2b-256 | 92ba3a374915101d6d4111b852507bc9b0c477d11bdbae159ae026f1faeb98ee |
Hashes for css_inline-0.10.0-cp37-abi3-musllinux_1_2_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2afd5bc750c9623b78569f6a2a54f05b9612ed7543873c3f8027b018a8b5cacf |
|
MD5 | 2326599747932f6e5d14a9e703924398 |
|
BLAKE2b-256 | 86da904bf3a55916b4126bea2a4f2dcbc7cbfe22efbe77aec8a9f969f2cf31cb |
Hashes for css_inline-0.10.0-cp37-abi3-musllinux_1_2_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c19c567012d17a44685b5a9a33a95517f491b0d89445057afd920a90383df004 |
|
MD5 | 115eabb2968aef2cbea61154852d5f0b |
|
BLAKE2b-256 | 9566f489a9a6a6c2e037b8366c0dad60c7674361754800f807f01c951def199b |
Hashes for css_inline-0.10.0-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f6818923cd0295a5ffd74b50fc9918ce2f496edb6e9bef4e115bc32d285be1e3 |
|
MD5 | 23ca68de3b913d68aa17ef39d21de02b |
|
BLAKE2b-256 | f05a15e472258dfba4b7c3484272d1a256dfe5a7a4b113c20bbd946aff83febc |
Hashes for css_inline-0.10.0-cp37-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e5265106976592c1299c9b3770bd93616eda6f606e8dfeec8e08d2384fbed076 |
|
MD5 | 3e977e9df7e7d9a434eb949202304d5e |
|
BLAKE2b-256 | 121ab4f6abd6b7c13da0b434437577db94c4206e2cf57e3a694b5343540b5a44 |
Hashes for css_inline-0.10.0-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ca58538cacd87eeea35d66024bd58b20b5216b2787f03bf8d78c236d3c888d06 |
|
MD5 | ea762efea5a9daa7211f137ae3f9bf86 |
|
BLAKE2b-256 | eff0e6255879c91f837492734b46ceba5f99a7045e542eeb8adbdf0253608dee |
Hashes for css_inline-0.10.0-cp37-abi3-manylinux_2_12_i686.manylinux2010_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 435f4a0e01cec5506004c31843fb01de6d7d2bc32a9a44ddd8055eb826959515 |
|
MD5 | 33c08eb99b68d76a185a862ff5169667 |
|
BLAKE2b-256 | b713ac626e05679aba7fb9bbfa8e766ce411b528547e1a337aba2b59229e4df9 |
Hashes for css_inline-0.10.0-cp37-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b345dfee63f6719cc17e659222cd41bef61691766d5ff483abd509051d398b6c |
|
MD5 | b8a6c09090272fde4ea225576b142308 |
|
BLAKE2b-256 | eae43cc46f666f4d5259463922a609e10dd67a3e29ac5fae8c899f6efc192551 |
Hashes for css_inline-0.10.0-cp37-abi3-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b085acbd7d318f886560d5bf3315d1f44e4a2b91b31a22a98667876bb64d7215 |
|
MD5 | 8f85c376d6579b8d76d67fd528644767 |
|
BLAKE2b-256 | 8a75507a3fb5d8f6402d0c0e58cb8f05f7cf281340ceb10a99ea8ed92c655820 |