README.md
1# Flask-Compress
2
3[](https://github.com/colour-science/flask-compress/actions/workflows/ci.yaml)
4[](https://pypi.python.org/pypi/Flask-Compress)
5[](https://pypi.python.org/pypi/Flask-Compress)
6
7Flask-Compress allows you to easily compress your [Flask](http://flask.pocoo.org/) application's responses with gzip, deflate or brotli. It originally started as a fork of [Flask-gzip](https://github.com/closeio/Flask-gzip).
8
9The 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.
10
11
12## How it works
13
14Flask-Compress both adds the various headers required for a compressed response and compresses the response data.
15This makes serving compressed static files extremely easy.
16
17Internally, every time a request is made the extension will check if it matches one of the compressible MIME types
18and whether the client and the server use some common compression algorithm, and will automatically attach the
19appropriate headers.
20
21To determine the compression algorithm, the `Accept-Encoding` request header is inspected, respecting the
22quality factor as described in [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding).
23If no requested compression algorithm is supported by the server, we don't compress the response. If, on the other
24hand, multiple suitable algorithms are found and are requested with the same quality factor, we choose the first one
25defined in the `COMPRESS_ALGORITHM` option (see below).
26
27
28## Installation
29
30If you use pip then installation is simply:
31
32```shell
33$ pip install --user flask-compress
34```
35
36or, if you want the latest github version:
37
38```shell
39$ pip install --user git+git://github.com/colour-science/flask-compress.git
40```
41
42You can also install Flask-Compress via Easy Install:
43
44```shell
45$ easy_install flask-compress
46```
47
48
49## Using Flask-Compress
50
51### Globally
52
53Flask-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.
54
55```python
56from flask import Flask
57from flask_compress import Compress
58
59app = Flask(__name__)
60Compress(app)
61```
62
63In 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.
64
65```python
66from flask import Flask
67from flask_compress import Compress
68
69compress = Compress()
70
71def start_app():
72 app = Flask(__name__)
73 compress.init_app(app)
74 return app
75```
76
77In 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.
78
79### Per-view compression
80
81Compression is possible per view using the `@compress.compressed()` decorator. Make sure to disable global compression first.
82
83```python
84from flask import Flask
85from flask_compress import Compress
86
87app = Flask(__name__)
88app.config["COMPRESS_REGISTER"] = False # disable default compression of all eligible requests
89compress = Compress()
90compress.init_app(app)
91
92# Compress this view specifically
93@app.route("/test")
94@compress.compressed()
95def view():
96 pass
97```
98
99## Options
100
101Within your Flask application's settings you can provide the following settings to control the behavior of Flask-Compress. None of the settings are required.
102
103| Option | Description | Default |
104| ------ | ----------- | ------- |
105| `COMPRESS_MIMETYPES` | Set the list of mimetypes to compress here. | `[`<br>`'text/html',`<br>`'text/css',`<br>`'text/xml',`<br>`'application/json',`<br>`'application/javascript'`<br>`]` |
106| `COMPRESS_LEVEL` | Specifies the gzip compression level. | `6` |
107| `COMPRESS_BR_LEVEL` | Specifies the Brotli compression level. Ranges from 0 to 11. | `4` |
108| `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` |
109| `COMPRESS_BR_WINDOW` | For Brotli, this specifies the base-2 logarithm of the sliding window size. Ranges from 10 to 24. | `22` |
110| `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` |
111| `COMPRESS_DEFLATE_LEVEL` | Specifies the deflate compression level. | `-1` |
112| `COMPRESS_MIN_SIZE` | Specifies the minimum file size threshold for compressing files. | `500` |
113| `COMPRESS_CACHE_KEY` | Specifies the cache key method for lookup/storage of response data. | `None` |
114| `COMPRESS_CACHE_BACKEND` | Specified the backend for storing the cached response data. | `None` |
115| `COMPRESS_REGISTER` | Specifies if compression should be automatically registered. | `True` |
116| `COMPRESS_ALGORITHM` | Supported compression algorithms. | `['br', 'gzip', 'deflate']` |
117
){kind=link}
){kind=link}
){kind=link}