.. This file is part of the pelican_precompress plugin.
.. Copyright 2019-2023 Kurt McKee <contactme@kurtmckee.org>
.. Released under the MIT license.
pelican_precompress
*******************
*Pre-compress your Pelican site using gzip, zopfli, and brotli!*
----
Are you using `Pelican`_, the static site generator? If so, great!
Are you pre-compressing your static files to have the fastest site possible?
If not, install **pelican_precompress** today!
It's the plugin that makes your visitors happy and saves you money!
Installation
============
There are three steps required to start using static compression:
#. Install the plugin and any supporting Python packages you want.
#. Configure Pelican to use the pelican_precompress plugin.
#. Configure your web server to use static, pre-compressed files.
1. Install the Python modules
-----------------------------
At minimum, you'll need to install the pelican_precompress plugin.
It will automatically generate gzip files because gzip is built into the
Python standard library.
However, if you want highly-optimized gzip files you'll need the zopfli module.
And if you want to have the very best compression currently available, you'll
need to install the brotli module (which will require extra work in step 3).
.. code-block:: shell-session
$ pip install pelican_precompress
$ pip install zopfli # This produces smaller gzip'd files. Use it!
$ pip install brotli # This requires extra work in step 3.
Further reading: `zopfli`_, `brotli`_
2. Configure Pelican
--------------------
If you're using Pelican 4.5 or higher then you might not need to configure anything.
pelican_precompress supports Pelican's namespace plugin architecture
and will be automatically detected and loaded when Pelican runs.
However, if you're maintaining a list of plugins for Pelican to use (even in Pelican 4.5)
then you'll need to add it to the list of active plugins.
Feel free to copy and paste the code below into your Pelican configuration file.
Just uncomment and edit the configuration lines to your liking...or leave
them alone because the defaults are awesome!
.. code-block:: python3
# Pelican 4.5 introduced automatic plugin discovery and loading.
# You only need to add pelican_precompress to your PLUGINS list
# if your configuration file already has a PLUGINS list!
#
# PLUGINS = ['pelican.plugins.precompress']
# These options can be customized as desired.
#
# PRECOMPRESS_GZIP = True or False
# PRECOMPRESS_ZOPFLI = True or False
# PRECOMPRESS_BROTLI = True or False
# PRECOMPRESS_OVERWRITE = False
# PRECOMPRESS_MIN_SIZE = 20
# PRECOMPRESS_TEXT_EXTENSIONS = {
# '.atom',
# '.css',
# '.html',
# '.but-the-default-extensions-are-pretty-comprehensive',
# }
Further reading: `Pelican plugins`_
3. Configure nginx
------------------
nginx supports gzip compression right out of the box.
To enable it, add something like this to your nginx configuration file:
.. code-block:: nginx
http {
gzip_static on;
gzip_vary on;
}
At the time of writing, nginx doesn't natively support brotli compression.
To get it, you'll need to compile the static brotli module as an nginx
dynamic module, or recompile nginx from scratch. When it's done you'll
add something like this to your nginx configuration file:
.. code-block:: nginx
load_module /usr/lib/nginx/modules/ngx_http_brotli_static_module.so;
http {
brotli_static on;
}
Further reading: `gzip_static`_, `gzip_vary`_, `nginx brotli module`_
Configuration
=============
There are a small number of configuration options available.
You set them in your Pelican configuration file.
* ``PRECOMPRESS_GZIP`` (bool, default is True)
This is always ``True`` unless you set this to ``False``.
For example, you might turn this off during development.
* ``PRECOMPRESS_ZOPFLI`` (bool, default is True if zopfli is installed)
If the zopfli module is installed this will default to ``True``.
You might set this to ``False`` during development.
Note that if you try to enable zopfli compression but the module
isn't installed then nothing will happen.
* ``PRECOMPRESS_BROTLI`` (bool, default is True if brotli is installed)
If the brotli module is installed this will default to ``True``.
You might set this to ``False`` during development.
Like ``PRECOMPRESS_ZOPFLI``, if you set this to ``True`` when the
brotli module isn't installed then nothing will happen.
* ``PRECOMPRESS_OVERWRITE`` (bool, default is False)
When pelican_precompress encounters an existing compressed file
it will refuse to overwrite it. If you want the plugin to overwrite
files you can set this to ``True``.
* ``PRECOMPRESS_TEXT_EXTENSIONS`` (Set[str])
This setting controls which file extensions will be pre-compressed.
If you modify this setting in the Pelican configuration file it will
completely replace the default extensions!
* ``PRECOMPRESS_MIN_SIZE`` (int, default is 20)
Small files tend to result in a larger file size when compressed, and any
improvement is likely to be marginal. The default setting is chosen to
avoid speculatively compressing files that are likely to result in a
larger file size after compression.
To try compressing every file regardless of size, set this to ``0``.
Development
===========
If you'd like to develop and/or test the code yourself,
clone the git repository and run these commands to set
up a Python virtual environment, install dependencies,
and run the test suite:
.. code-block:: shell
python -m venv .venv
# Activate the virtual environment (Linux)
source .venv/bin/activate
# Activate the virtual environment (Windows)
& .venv/Scripts/Activate.ps1
python -m pip install poetry pre-commit tox
pre-commit install
poetry install
# Run the test suite
tox
The test suite uses tox to setup multiple environments with varying
dependencies using multiple Python interpreters; pytest allows the
test suite to have parametrized tests; pyfakefs creates a fake
filesystem that the tests safely create and erase files in;
and coverage keeps track of which lines of code have been run.
**pelican_precompress** has 100% test coverage, but there may still be bugs.
Please report any issues that you encounter.
Further reading: `poetry`_, `tox`_, `venv`_, `pytest`_, `pyfakefs`_, `coverage`_
.. Links
.. =====
.. _Pelican: https://getpelican.com/
.. _Pelican plugins: https://docs.getpelican.com/en/latest/plugins.html
.. _zopfli: https://pypi.org/project/zopfli/
.. _brotli: https://pypi.org/project/Brotli/
.. _gzip_static: https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html#gzip_static
.. _gzip_vary: https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_vary
.. _nginx brotli module: https://github.com/google/ngx_brotli
.. _poetry: https://python-poetry.org/
.. _tox: https://tox.wiki/en/latest/
.. _pytest: https://docs.pytest.org/en/latest/
.. _pyfakefs: https://pytest-pyfakefs.readthedocs.io/en/latest/
.. _venv: https://docs.python.org/3/library/venv.html
.. _coverage: https://coverage.readthedocs.io/en/latest/
Raw data
{
"_id": null,
"home_page": "https://github.com/kurtmckee/pelican_precompress/",
"name": "pelican-precompress",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "pelican,plugin,gzip,brotli,zopfli",
"author": "Kurt McKee",
"author_email": "contactme@kurtmckee.org",
"download_url": "https://files.pythonhosted.org/packages/1f/73/d07f67126d8e92a009e1aaff22fb44022387ab73f87d4267936fc27ff61f/pelican_precompress-2.2.0.tar.gz",
"platform": null,
"description": ".. This file is part of the pelican_precompress plugin.\n.. Copyright 2019-2023 Kurt McKee <contactme@kurtmckee.org>\n.. Released under the MIT license.\n\npelican_precompress\n*******************\n\n*Pre-compress your Pelican site using gzip, zopfli, and brotli!*\n\n----\n\nAre you using `Pelican`_, the static site generator? If so, great!\nAre you pre-compressing your static files to have the fastest site possible?\nIf not, install **pelican_precompress** today!\nIt's the plugin that makes your visitors happy and saves you money!\n\n\nInstallation\n============\n\nThere are three steps required to start using static compression:\n\n#. Install the plugin and any supporting Python packages you want.\n#. Configure Pelican to use the pelican_precompress plugin.\n#. Configure your web server to use static, pre-compressed files.\n\n\n1. Install the Python modules\n-----------------------------\n\nAt minimum, you'll need to install the pelican_precompress plugin.\nIt will automatically generate gzip files because gzip is built into the\nPython standard library.\n\nHowever, if you want highly-optimized gzip files you'll need the zopfli module.\nAnd if you want to have the very best compression currently available, you'll\nneed to install the brotli module (which will require extra work in step 3).\n\n.. code-block:: shell-session\n\n $ pip install pelican_precompress\n $ pip install zopfli # This produces smaller gzip'd files. Use it!\n $ pip install brotli # This requires extra work in step 3.\n\nFurther reading: `zopfli`_, `brotli`_\n\n\n2. Configure Pelican\n--------------------\n\nIf you're using Pelican 4.5 or higher then you might not need to configure anything.\npelican_precompress supports Pelican's namespace plugin architecture\nand will be automatically detected and loaded when Pelican runs.\n\nHowever, if you're maintaining a list of plugins for Pelican to use (even in Pelican 4.5)\nthen you'll need to add it to the list of active plugins.\n\nFeel free to copy and paste the code below into your Pelican configuration file.\nJust uncomment and edit the configuration lines to your liking...or leave\nthem alone because the defaults are awesome!\n\n.. code-block:: python3\n\n # Pelican 4.5 introduced automatic plugin discovery and loading.\n # You only need to add pelican_precompress to your PLUGINS list\n # if your configuration file already has a PLUGINS list!\n #\n # PLUGINS = ['pelican.plugins.precompress']\n\n # These options can be customized as desired.\n #\n # PRECOMPRESS_GZIP = True or False\n # PRECOMPRESS_ZOPFLI = True or False\n # PRECOMPRESS_BROTLI = True or False\n # PRECOMPRESS_OVERWRITE = False\n # PRECOMPRESS_MIN_SIZE = 20\n # PRECOMPRESS_TEXT_EXTENSIONS = {\n # '.atom',\n # '.css',\n # '.html',\n # '.but-the-default-extensions-are-pretty-comprehensive',\n # }\n\nFurther reading: `Pelican plugins`_\n\n\n3. Configure nginx\n------------------\n\nnginx supports gzip compression right out of the box.\nTo enable it, add something like this to your nginx configuration file:\n\n.. code-block:: nginx\n\n http {\n gzip_static on;\n gzip_vary on;\n }\n\nAt the time of writing, nginx doesn't natively support brotli compression.\nTo get it, you'll need to compile the static brotli module as an nginx\ndynamic module, or recompile nginx from scratch. When it's done you'll\nadd something like this to your nginx configuration file:\n\n.. code-block:: nginx\n\n load_module /usr/lib/nginx/modules/ngx_http_brotli_static_module.so;\n\n http {\n brotli_static on;\n }\n\nFurther reading: `gzip_static`_, `gzip_vary`_, `nginx brotli module`_\n\n\nConfiguration\n=============\n\nThere are a small number of configuration options available.\nYou set them in your Pelican configuration file.\n\n* ``PRECOMPRESS_GZIP`` (bool, default is True)\n\n This is always ``True`` unless you set this to ``False``.\n For example, you might turn this off during development.\n\n* ``PRECOMPRESS_ZOPFLI`` (bool, default is True if zopfli is installed)\n\n If the zopfli module is installed this will default to ``True``.\n You might set this to ``False`` during development.\n Note that if you try to enable zopfli compression but the module\n isn't installed then nothing will happen.\n\n* ``PRECOMPRESS_BROTLI`` (bool, default is True if brotli is installed)\n\n If the brotli module is installed this will default to ``True``.\n You might set this to ``False`` during development.\n Like ``PRECOMPRESS_ZOPFLI``, if you set this to ``True`` when the\n brotli module isn't installed then nothing will happen.\n\n* ``PRECOMPRESS_OVERWRITE`` (bool, default is False)\n\n When pelican_precompress encounters an existing compressed file\n it will refuse to overwrite it. If you want the plugin to overwrite\n files you can set this to ``True``.\n\n* ``PRECOMPRESS_TEXT_EXTENSIONS`` (Set[str])\n\n This setting controls which file extensions will be pre-compressed.\n\n If you modify this setting in the Pelican configuration file it will\n completely replace the default extensions!\n\n* ``PRECOMPRESS_MIN_SIZE`` (int, default is 20)\n\n Small files tend to result in a larger file size when compressed, and any\n improvement is likely to be marginal. The default setting is chosen to\n avoid speculatively compressing files that are likely to result in a\n larger file size after compression.\n\n To try compressing every file regardless of size, set this to ``0``.\n\n\nDevelopment\n===========\n\nIf you'd like to develop and/or test the code yourself,\nclone the git repository and run these commands to set\nup a Python virtual environment, install dependencies,\nand run the test suite:\n\n.. code-block:: shell\n\n python -m venv .venv\n\n # Activate the virtual environment (Linux)\n source .venv/bin/activate\n\n # Activate the virtual environment (Windows)\n & .venv/Scripts/Activate.ps1\n\n python -m pip install poetry pre-commit tox\n pre-commit install\n poetry install\n\n # Run the test suite\n tox\n\nThe test suite uses tox to setup multiple environments with varying\ndependencies using multiple Python interpreters; pytest allows the\ntest suite to have parametrized tests; pyfakefs creates a fake\nfilesystem that the tests safely create and erase files in;\nand coverage keeps track of which lines of code have been run.\n\n**pelican_precompress** has 100% test coverage, but there may still be bugs.\nPlease report any issues that you encounter.\n\nFurther reading: `poetry`_, `tox`_, `venv`_, `pytest`_, `pyfakefs`_, `coverage`_\n\n\n.. Links\n.. =====\n\n.. _Pelican: https://getpelican.com/\n.. _Pelican plugins: https://docs.getpelican.com/en/latest/plugins.html\n.. _zopfli: https://pypi.org/project/zopfli/\n.. _brotli: https://pypi.org/project/Brotli/\n.. _gzip_static: https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html#gzip_static\n.. _gzip_vary: https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip_vary\n.. _nginx brotli module: https://github.com/google/ngx_brotli\n.. _poetry: https://python-poetry.org/\n.. _tox: https://tox.wiki/en/latest/\n.. _pytest: https://docs.pytest.org/en/latest/\n.. _pyfakefs: https://pytest-pyfakefs.readthedocs.io/en/latest/\n.. _venv: https://docs.python.org/3/library/venv.html\n.. _coverage: https://coverage.readthedocs.io/en/latest/\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pre-compress your Pelican site using gzip, zopfli, and brotli!",
"version": "2.2.0",
"project_urls": {
"Homepage": "https://github.com/kurtmckee/pelican_precompress/",
"Repository": "https://github.com/kurtmckee/pelican_precompress/"
},
"split_keywords": [
"pelican",
"plugin",
"gzip",
"brotli",
"zopfli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "daa3cf5d8ead1c6459e9e1d65e332de4ab2912d893ccd9244820e3aaeaa2b1db",
"md5": "8b8efd5cb0a06c5f38f8c62134d60c1e",
"sha256": "2599b9975b94637fe7d8f6a18c62f7ed0a7798d8ef85828d98214b5a57942f35"
},
"downloads": -1,
"filename": "pelican_precompress-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b8efd5cb0a06c5f38f8c62134d60c1e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7413,
"upload_time": "2023-05-23T01:33:42",
"upload_time_iso_8601": "2023-05-23T01:33:42.421934Z",
"url": "https://files.pythonhosted.org/packages/da/a3/cf5d8ead1c6459e9e1d65e332de4ab2912d893ccd9244820e3aaeaa2b1db/pelican_precompress-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1f73d07f67126d8e92a009e1aaff22fb44022387ab73f87d4267936fc27ff61f",
"md5": "9c59982073b8b7ac5a833eb0fad741f5",
"sha256": "5ee89e72c38c284455a7d4d4068b8f7aff33469d93a4221127434158596a7d19"
},
"downloads": -1,
"filename": "pelican_precompress-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "9c59982073b8b7ac5a833eb0fad741f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6838,
"upload_time": "2023-05-23T01:33:44",
"upload_time_iso_8601": "2023-05-23T01:33:44.323565Z",
"url": "https://files.pythonhosted.org/packages/1f/73/d07f67126d8e92a009e1aaff22fb44022387ab73f87d4267936fc27ff61f/pelican_precompress-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-23 01:33:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kurtmckee",
"github_project": "pelican_precompress",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "pelican-precompress"
}
JSON
