# Flask-Compress
[](https://github.com/colour-science/flask-compress/actions/workflows/ci.yaml)
[](https://pypi.python.org/pypi/Flask-Compress)
[](https://pypi.python.org/pypi/Flask-Compress)
Flask-Compress allows you to easily compress your [Flask](http://flask.pocoo.org/) application's responses with gzip, deflate, brotli or zstd. It originally started as a fork of [Flask-gzip](https://github.com/closeio/Flask-gzip). Supported Python versions are 3.9 and newer.
The preferred solution is to have a server (like [Nginx](http://wiki.nginx.org/Main)) automatically compress the static files for you. If you don't have that option Flask-Compress will solve the problem for you.
## How it works
Flask-Compress both adds the various headers required for a compressed response and compresses the response data.
This makes serving compressed static files extremely easy.
Internally, every time a request is made the extension will check if it matches one of the compressible MIME types
and whether the client and the server use some common compression algorithm, and will automatically attach the
appropriate headers.
To determine the compression algorithm, the `Accept-Encoding` request header is inspected, respecting the
quality factor as described in [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding).
If no requested compression algorithm is supported by the server, we don't compress the response. If, on the other
hand, multiple suitable algorithms are found and are requested with the same quality factor, we choose the first one
defined in the `COMPRESS_ALGORITHM` option (see below).
## Installation
If you use pip then installation is simply:
```shell
$ pip install flask-compress
```
or, if you want the latest github version:
```shell
$ pip install git+git://github.com/colour-science/flask-compress.git
```
## Using Flask-Compress
### Globally
Flask-Compress is incredibly simple to use. In order to start compressing your Flask application's assets, the first thing to do is let Flask-Compress know about your [`flask.Flask`](http://flask.pocoo.org/docs/latest/api/#flask.Flask) application object.
```python
from flask import Flask
from flask_compress import Compress
app = Flask(__name__)
Compress(app)
```
In many cases, however, one cannot expect a Flask instance to be ready at import time, and a common pattern is to return a Flask instance from within a function only after other configuration details have been taken care of. In these cases, Flask-Compress provides a simple function, `flask_compress.Compress.init_app`, which takes your application as an argument.
```python
from flask import Flask
from flask_compress import Compress
compress = Compress()
def start_app():
app = Flask(__name__)
compress.init_app(app)
return app
```
In terms of automatically compressing your assets, passing your [`flask.Flask`](http://flask.pocoo.org/docs/latest/api/#flask.Flask) object to the `flask_compress.Compress` object is all that needs to be done.
### Per-view compression
Compression is possible per view using the `@compress.compressed()` decorator. Make sure to disable global compression first.
```python
from flask import Flask
from flask_compress import Compress
app = Flask(__name__)
app.config["COMPRESS_REGISTER"] = False # disable default compression of all eligible requests
compress = Compress()
compress.init_app(app)
# Compress this view specifically
@app.route("/test")
@compress.compressed()
def view():
pass
```
### Cache example
Flask-Compress can be integrated with caching mechanisms to serve compressed responses directly from the cache. This can significantly reduce server load and response times.
Here is an example of how to configure Flask-Compress with caching using Flask-Caching.
The example demonstrates how to create a simple cache instance with a 1-hour timeout, and use it to cache compressed responses for incoming requests.
```python
from flask import Flask
from flask_compress import Compress
from flask_cache import Cache
# Initializing flask app
app = Flask(__name__)
cache = Cache(config={
'CACHE_TYPE': 'SimpleCache',
'CACHE_DEFAULT_TIMEOUT': 60*60 # 1 hour cache timeout
})
cache.init_app(app)
# Define a function to return cache key for incoming requests
def get_cache_key(request):
return request.url
# Initialize Flask-Compress
compress = Compress()
compress.init_app(app)
# Set up cache for compressed responses
compress.cache = cache
compress.cache_key = get_cache_key
```
## Options
Within your Flask application's settings you can provide the following settings to control the behavior of Flask-Compress. None of the settings are required.
| Option | Description | Default |
| ------ | ----------- | ------- |
| `COMPRESS_MIMETYPES` | Set the list of mimetypes to compress here. | `[`<br>`'text/html',`<br>`'text/css',`<br>`'text/plain',`<br>`'text/xml',`<br>`'text/x-component',`<br>`'text/javascript',`<br>`'application/x-javascript',`<br>`'application/javascript',`<br>`'application/json',`<br>`'application/manifest+json',`<br>`'application/vnd.api+json',`<br>`'application/xml',`<br>`'application/xhtml+xml',`<br>`'application/rss+xml',`<br>`'application/atom+xml',`<br>`'application/vnd.ms-fontobject',`<br>`'application/x-font-ttf',`<br>`'application/x-font-opentype',`<br>`'application/x-font-truetype',`<br>`'image/svg+xml',`<br>`'image/x-icon',`<br>`'image/vnd.microsoft.icon',`<br>`'font/ttf',`<br>`'font/eot',`<br>`'font/otf',`<br>`'font/opentype',`<br>`]` |
| `COMPRESS_LEVEL` | Specifies the gzip compression level. | `6` |
| `COMPRESS_BR_LEVEL` | Specifies the Brotli compression level. Ranges from 0 to 11. | `4` |
| `COMPRESS_BR_MODE` | For Brotli, the compression mode. The options are 0, 1, or 2. These correspond to "generic", "text" (for UTF-8 input), and "font" (for WOFF 2.0). | `0` |
| `COMPRESS_BR_WINDOW` | For Brotli, this specifies the base-2 logarithm of the sliding window size. Ranges from 10 to 24. | `22` |
| `COMPRESS_BR_BLOCK` | For Brotli, this provides the base-2 logarithm of the maximum input block size. If zero is provided, value will be determined based on the quality. Ranges from 16 to 24. | `0` |
| `COMPRESS_ZSTD_LEVEL` | Specifies the ZStandard compression level. Ranges from 1 to 22. Levels >= 20, labeled ultra, should be used with caution, as they require more memory. 0 means use the default level. -131072 to -1, negative levels extend the range of speed vs ratio preferences. The lower the level, the faster the speed, but at the cost of compression ratio. | `3` |
| `COMPRESS_DEFLATE_LEVEL` | Specifies the deflate compression level. | `-1` |
| `COMPRESS_MIN_SIZE` | Specifies the minimum file size threshold for compressing files. | `500` |
| `COMPRESS_CACHE_KEY` | Specifies the cache key method for lookup/storage of response data. | `None` |
| `COMPRESS_CACHE_BACKEND` | Specified the backend for storing the cached response data. | `None` |
| `COMPRESS_REGISTER` | Specifies if compression should be automatically registered. | `True` |
| `COMPRESS_ALGORITHM` | Supported compression algorithms. | `['zstd', 'br', 'gzip', 'deflate']` |
| `COMPRESS_STREAMS` | Compress content streams. | `True` |
Raw data
{
"_id": null,
"home_page": "https://github.com/colour-science/flask-compress",
"name": "Flask-Compress",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Thomas Mansencal",
"author_email": "thomas.mansencal@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cc/1f/260db5a4517d59bfde7b4a0d71052df68fb84983bda9231100e3b80f5989/flask_compress-1.17.tar.gz",
"platform": "any",
"description": "# Flask-Compress\n\n[](https://github.com/colour-science/flask-compress/actions/workflows/ci.yaml)\n[](https://pypi.python.org/pypi/Flask-Compress)\n[](https://pypi.python.org/pypi/Flask-Compress)\n\nFlask-Compress allows you to easily compress your [Flask](http://flask.pocoo.org/) application's responses with gzip, deflate, brotli or zstd. It originally started as a fork of [Flask-gzip](https://github.com/closeio/Flask-gzip). Supported Python versions are 3.9 and newer.\n\nThe preferred solution is to have a server (like [Nginx](http://wiki.nginx.org/Main)) automatically compress the static files for you. If you don't have that option Flask-Compress will solve the problem for you.\n\n\n## How it works\n\nFlask-Compress both adds the various headers required for a compressed response and compresses the response data.\nThis makes serving compressed static files extremely easy.\n\nInternally, every time a request is made the extension will check if it matches one of the compressible MIME types\nand whether the client and the server use some common compression algorithm, and will automatically attach the\nappropriate headers.\n\nTo determine the compression algorithm, the `Accept-Encoding` request header is inspected, respecting the\nquality factor as described in [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding).\nIf no requested compression algorithm is supported by the server, we don't compress the response. If, on the other\nhand, multiple suitable algorithms are found and are requested with the same quality factor, we choose the first one\ndefined in the `COMPRESS_ALGORITHM` option (see below).\n\n\n## Installation\n\nIf you use pip then installation is simply:\n\n```shell\n$ pip install flask-compress\n```\n\nor, if you want the latest github version:\n\n```shell\n$ pip install git+git://github.com/colour-science/flask-compress.git\n```\n\n## Using Flask-Compress\n\n### Globally\n\nFlask-Compress is incredibly simple to use. In order to start compressing your Flask application's assets, the first thing to do is let Flask-Compress know about your [`flask.Flask`](http://flask.pocoo.org/docs/latest/api/#flask.Flask) application object.\n\n```python\nfrom flask import Flask\nfrom flask_compress import Compress\n\napp = Flask(__name__)\nCompress(app)\n```\n\nIn many cases, however, one cannot expect a Flask instance to be ready at import time, and a common pattern is to return a Flask instance from within a function only after other configuration details have been taken care of. In these cases, Flask-Compress provides a simple function, `flask_compress.Compress.init_app`, which takes your application as an argument.\n\n```python\nfrom flask import Flask\nfrom flask_compress import Compress\n\ncompress = Compress()\n\ndef start_app():\n app = Flask(__name__)\n compress.init_app(app)\n return app\n```\n\nIn terms of automatically compressing your assets, passing your [`flask.Flask`](http://flask.pocoo.org/docs/latest/api/#flask.Flask) object to the `flask_compress.Compress` object is all that needs to be done.\n\n### Per-view compression\n\nCompression is possible per view using the `@compress.compressed()` decorator. Make sure to disable global compression first.\n\n```python\nfrom flask import Flask\nfrom flask_compress import Compress\n\napp = Flask(__name__)\napp.config[\"COMPRESS_REGISTER\"] = False # disable default compression of all eligible requests\ncompress = Compress()\ncompress.init_app(app)\n\n# Compress this view specifically\n@app.route(\"/test\")\n@compress.compressed()\ndef view():\n pass\n```\n\n### Cache example\n\nFlask-Compress can be integrated with caching mechanisms to serve compressed responses directly from the cache. This can significantly reduce server load and response times.\nHere is an example of how to configure Flask-Compress with caching using Flask-Caching.\nThe example demonstrates how to create a simple cache instance with a 1-hour timeout, and use it to cache compressed responses for incoming requests.\n\n```python\nfrom flask import Flask\nfrom flask_compress import Compress\nfrom flask_cache import Cache\n\n# Initializing flask app\napp = Flask(__name__)\n\ncache = Cache(config={\n 'CACHE_TYPE': 'SimpleCache',\n 'CACHE_DEFAULT_TIMEOUT': 60*60 # 1 hour cache timeout\n})\ncache.init_app(app)\n\n# Define a function to return cache key for incoming requests\ndef get_cache_key(request):\n return request.url\n\n# Initialize Flask-Compress\ncompress = Compress()\ncompress.init_app(app)\n\n# Set up cache for compressed responses\ncompress.cache = cache\ncompress.cache_key = get_cache_key\n```\n\n## Options\n\nWithin your Flask application's settings you can provide the following settings to control the behavior of Flask-Compress. None of the settings are required.\n\n| Option | Description | Default |\n| ------ | ----------- | ------- |\n| `COMPRESS_MIMETYPES` | Set the list of mimetypes to compress here. | `[`<br>`'text/html',`<br>`'text/css',`<br>`'text/plain',`<br>`'text/xml',`<br>`'text/x-component',`<br>`'text/javascript',`<br>`'application/x-javascript',`<br>`'application/javascript',`<br>`'application/json',`<br>`'application/manifest+json',`<br>`'application/vnd.api+json',`<br>`'application/xml',`<br>`'application/xhtml+xml',`<br>`'application/rss+xml',`<br>`'application/atom+xml',`<br>`'application/vnd.ms-fontobject',`<br>`'application/x-font-ttf',`<br>`'application/x-font-opentype',`<br>`'application/x-font-truetype',`<br>`'image/svg+xml',`<br>`'image/x-icon',`<br>`'image/vnd.microsoft.icon',`<br>`'font/ttf',`<br>`'font/eot',`<br>`'font/otf',`<br>`'font/opentype',`<br>`]` |\n| `COMPRESS_LEVEL` | Specifies the gzip compression level. | `6` |\n| `COMPRESS_BR_LEVEL` | Specifies the Brotli compression level. Ranges from 0 to 11. | `4` |\n| `COMPRESS_BR_MODE` | For Brotli, the compression mode. The options are 0, 1, or 2. These correspond to \"generic\", \"text\" (for UTF-8 input), and \"font\" (for WOFF 2.0). | `0` |\n| `COMPRESS_BR_WINDOW` | For Brotli, this specifies the base-2 logarithm of the sliding window size. Ranges from 10 to 24. | `22` |\n| `COMPRESS_BR_BLOCK` | For Brotli, this provides the base-2 logarithm of the maximum input block size. If zero is provided, value will be determined based on the quality. Ranges from 16 to 24. | `0` |\n| `COMPRESS_ZSTD_LEVEL` | Specifies the ZStandard compression level. Ranges from 1 to 22. Levels >= 20, labeled ultra, should be used with caution, as they require more memory. 0 means use the default level. -131072 to -1, negative levels extend the range of speed vs ratio preferences. The lower the level, the faster the speed, but at the cost of compression ratio. | `3` |\n| `COMPRESS_DEFLATE_LEVEL` | Specifies the deflate compression level. | `-1` |\n| `COMPRESS_MIN_SIZE` | Specifies the minimum file size threshold for compressing files. | `500` |\n| `COMPRESS_CACHE_KEY` | Specifies the cache key method for lookup/storage of response data. | `None` |\n| `COMPRESS_CACHE_BACKEND` | Specified the backend for storing the cached response data. | `None` |\n| `COMPRESS_REGISTER` | Specifies if compression should be automatically registered. | `True` |\n| `COMPRESS_ALGORITHM` | Supported compression algorithms. | `['zstd', 'br', 'gzip', 'deflate']` |\n| `COMPRESS_STREAMS` | Compress content streams. | `True` |\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Compress responses in your Flask app with gzip, deflate, brotli or zstandard.",
"version": "1.17",
"project_urls": {
"Homepage": "https://github.com/colour-science/flask-compress"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f754ff08f947d07c0a8a5d8f1c8e57b142c97748ca912b259db6467ab35983cd",
"md5": "08930c6d303da951038a88bf7490b7b0",
"sha256": "415131f197c41109f08e8fdfc3a6628d83d81680fb5ecd0b3a97410e02397b20"
},
"downloads": -1,
"filename": "Flask_Compress-1.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "08930c6d303da951038a88bf7490b7b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8723,
"upload_time": "2024-10-14T08:13:31",
"upload_time_iso_8601": "2024-10-14T08:13:31.726954Z",
"url": "https://files.pythonhosted.org/packages/f7/54/ff08f947d07c0a8a5d8f1c8e57b142c97748ca912b259db6467ab35983cd/Flask_Compress-1.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc1f260db5a4517d59bfde7b4a0d71052df68fb84983bda9231100e3b80f5989",
"md5": "e0044a29f9e3f20b0ad0c6331467f867",
"sha256": "1ebb112b129ea7c9e7d6ee6d5cc0d64f226cbc50c4daddf1a58b9bd02253fbd8"
},
"downloads": -1,
"filename": "flask_compress-1.17.tar.gz",
"has_sig": false,
"md5_digest": "e0044a29f9e3f20b0ad0c6331467f867",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 15733,
"upload_time": "2024-10-14T08:13:33",
"upload_time_iso_8601": "2024-10-14T08:13:33.196503Z",
"url": "https://files.pythonhosted.org/packages/cc/1f/260db5a4517d59bfde7b4a0d71052df68fb84983bda9231100e3b80f5989/flask_compress-1.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-14 08:13:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "colour-science",
"github_project": "flask-compress",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "flask-compress"
}
JSON
