pax_global_header 0000666 0000000 0000000 00000000064 14513162264 0014516 g ustar 00root root 0000000 0000000 52 comment=1b04faa722ae73055f2eb62afcf66b22b52ee060
django-qr-code-3.1.1a/ 0000775 0000000 0000000 00000000000 14513162264 0014453 5 ustar 00root root 0000000 0000000 django-qr-code-3.1.1a/.editorconfig 0000664 0000000 0000000 00000000174 14513162264 0017132 0 ustar 00root root 0000000 0000000 root = true
[*]
indent_style = space
indent_size = 4
insert_final_newline = true
charset = utf-8
[*.html]
indent_size = 2
django-qr-code-3.1.1a/.gitignore 0000664 0000000 0000000 00000002571 14513162264 0016450 0 ustar 00root root 0000000 0000000 # Generated data and logs during tests.
tests_result/
tests_result.back/
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
.hypothesis/
.pytest_cache/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# pyenv
.python-version
# celery beat schedule file
celerybeat-schedule
# SageMath parsed files
*.sage.py
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
django-qr-code-3.1.1a/.travis.yml 0000664 0000000 0000000 00000000607 14513162264 0016567 0 ustar 00root root 0000000 0000000 dist: focal
language: python
python:
- "3.8"
- "3.9"
- "3.10"
env:
- DJANGO_VERSION=3.2
- DJANGO_VERSION=4.0
# command to install dependencies
install:
- pip install django~=$DJANGO_VERSION
- pip install -r requirements.txt
- pip install python-coveralls coverage
# command to run tests
script:
- coverage run --source='qr_code' manage.py test
after_success:
- coveralls
django-qr-code-3.1.1a/CHANGELOG.md 0000664 0000000 0000000 00000020546 14513162264 0016273 0 ustar 00root root 0000000 0000000 # Change Log
## 3.1.1 (2022-07-28)
* Fix regression in demo site due to improper runtime type validation on `QRCodeOptions`.
* Minor improvements to documentation.
* Modernize code syntax for Python >= 3.7.
## 3.1.0 (2022-06-26)
* Add support for more properties for vCard: cellphone (TEL;TYPE=CELL), homephone (TEL;TYPE=HOME), workphone (TEL;TYPE=WORK)
* Add support for simple iCalendar event (VEVENT). (#38)
* Add support for Django 4.0.
* BREAKING CHANGES:
* Introduce type validation at runtime with pydantic. Existing code might need some type-related fixes.
* Drop support for Django 2.2.
## 3.0.0 (2021-11-27)
* Add support for European Payments Council Quick Response Code (EPC QR Code) version 002.
* Add support for vCard v3 QR code.
* Revamp support for MeCARD QR code to provide a cleaner API (old API remains available for compatibility).
* Introduce `qr_from_data` and `qr_url_from_data` to allow optimized encoding of alphanumeric, numeric, and byte data (adopt appropriate encoding mode depending on data content).
* Introduce support for `boost_error` flag.
* Introduce support for `encoding` parameter.
* Several breaking changes in API and generated QR codes:
* `text` parameters renamed to `data`;
* class methods `make_qr_text` renamed to `make_qr_data`;
* uses UTF-8 encoding by default for application and text QR codes (you must set the new `encoding` option or use the new `qr_from_data` and `qr_url_from_data` template tags to emulate old behavior);
* encoded geolocations always contain a decimal separator.
* Improve API documentation.
* Add support for Python 3.10
* Drop support for Python 3.6.
* Drop support for Django 3.1.
## 2.3.0 (2021-11-07)
* Add support for `ECI mode` to control bytes encoding.
* Fix handling of `micro` QR code option when using URLs to serve image via `{% qr_url_from_text %}`.
* Fix handling of `cache_enabled` option when using URLs to serve image via `{% qr_url_from_text %}`.
* Fix handling of `url_signature_enabled` option when using URLs to serve image via `{% qr_url_from_text %}`.
## 2.2.0 (2021-06-03)
* Change encoding from URL-safe Base64 to standard Base64 for `text` query argument (used for serving QR code images).
* Fix #31 by passing the border parameter for segno.QRCode.save.
* Ensure compatibility with Django 3.2.
* Drop support for Django 3.0.
## 2.1.0 (2021-01-23)
* Change encoding from URL-safe Base64 to standard Base64 for `text` query argument (used for serving QR code images).
* Introduce setting `SERVE_QR_CODE_IMAGE_PATH` to configure the path under which QR Code images are served.
* Reorganize and improve documentation.
* Fix #23
* Introduce usage of type hints.
## 2.0.1 (2020-11-24)
* Update the install_requires after the move from qrcode to Segno.
## 2.0.0 (2020-11-22)
* Remove dependency to Pillow / qrcode
* Switch to [Segno](https://pypi.org/project/segno/) for generating QR Codes
* Add support for QR Codes with multiple colors
* Add support for Micro QR Codes
* Stable SVG format for QR code between 32-bit and 64-bit architecture (#19)
* Use hyphens in URLs (#16)
* Add support for Python 3.9
## 1.3.1 (2020-09-07)
* Fix local testing script.
* Fix date of release 1.3.0 in readme.
* Code cleanup.
## 1.3.0 (2020-09-05)
* Drop support for Django 2.1.
* Ensure compatibility with Django 3.1.
## 1.2.0 (2020-04-26)
* Ensure compatibility with Django 3.0.
* Upgrade Pillow requirement to 7.1.
* Drop support for Python 3.5.
* Drop support for Django <2.2.
* More modern build environment and configuration for ReadTheDocs.
## 1.1.0 (2019-11-16)
* Ensure compatibility with Django 2.1.
* Ensure compatibility with Django 2.2.
* Upgrade qr_code library from 5.3 to 6.1 (several fixes).
* Drop support for Python 3.4.
* Fixed error when generating qr code from lazy text. (#1)
* Add support for customizing usage of URL signature token via template tags (allows to generate URLs for serving QR code images that do not include a signature token). (#4)
* The caching of QR codes images could allow to bypass checking the user when external access is active.
* Upgrade Pillow requirement to 6.2.0 (CVE-2019-16865).
* Adopt a dedicated logger, and move message "Pillow is not installed. No support available for PNG format." from info to debug. (#6)
## 1.0.0 (2018-03-23)
* BREAKING CHANGES:
* QR code options have been factorized and now use the `QRCodeOptions` class.
* The context for rendering a QR code encoding a Wi-Fi configuration uses the dedicated `WifiConfig` class.
* The context for rendering a QR code encoding a contact detail uses the dedicated `ContactDetail` class.
* `qr_for_contact` and `qr_url_for_contact` keyword arg has been renamed from `contact_dict` to `contact_detail`.
* `qr_for_wifi` and `qr_url_for_wifi` keyword arg has been renamed from `wifi_dict` to `wifi_config`.
* Reorganize code and split qr_code.py into several modules.
The changes mentioned above might break the compatibility with code using qr_code.py's API directly, but template tags are not impacted, except for `qr_for_contact`, `qr_url_for_contact`, `qr_for_wifi`, and `qr_url_for_wifi` if they were using a keyword argument.
* Other changes:
* Added support for `error_correction` parameter when generating a QR code.
* Added support for `coordinates` keyword argument to `qr_for_geolocation`, `qr_for_google_maps`, `qr_url_for_geolocation`, and `qr_url_for_google_maps`.
* Additions to documentation.
* Added ability to use a `QRCodeOptions` instance with `options` keyword argument in all tags.
* Bug fixes:
* Fixed non-closed tag when generating embedded PNG image.
* Escape colon char (':') if it appears within a contact detail or a wifi configuration.
* Add a second terminal semi-colon at the end of the text representing a wifi configuration, as recommended in some sources.
## 0.4.1 (2018-03-10)
* Fixed unescaped chars when generating QR code for a contact.
* Simplify handling of default values for QR code options.
* Add documentation about what a QR code can encode.
## 0.4.0 (2018-03-09)
* Added support for multiple new tags:
* `qr_for_email` and `qr_url_for_email`
* `qr_for_tel` and `qr_url_for_tel`
* `qr_for_sms` and `qr_url_for_sms`
* `qr_for_geolocation` and `qr_url_for_geolocation`
* `qr_for_google_maps` and `qr_url_for_google_maps`
* `qr_for_youtube` and `qr_url_for_youtube`
* `qr_for_google_play` and `qr_url_for_google_play`
* `qr_for_contact` and `qr_url_for_contact`
* `qr_for_wifi` and `qr_url_for_wifi`
* Reformat documentation on the demo site for better readability.
* Drop support for Django <1.11.
## 0.3.3 (2017-08-16)
* Added `app_name` namespace to `qr_code.urls` (better compatibility with `include()` function provided with Django >= 1.9).
* Update documentation regarding the inclusion of `qr_code.urls` for distinct versions of Django.
* Minor improvements to the documentation.
## 0.3.2 (2017-08-13)
* Allows optional installation of Pillow (PNG format unavailable, fallback to SVG).
* Fixed caching of images (not working due protection against external queries).
* Fixed conditional view processing (HTTP 304) for rendered QR codes (not working due protection against external queries).
## 0.3.1 (2017-08-12)
* Added a mention about Pillow library requirement in documentation.
* Minor improvements to the documentation and the demo application.
## 0.3.0 (2017-08-12)
* Added new tag qr_url_from_text:
* Separate image from the page displaying the image
* Handle caching of images
* Conditional view processing (HTTP 304) for rendered QR codes
* Protection against external requests
* Settings to configure URLs accesses as a service for generating QR code images
* Add documentation for new features
* Add tests for new features
* Add examples to demo site
* More robust testing of make_embedded_qr_code's arguments.
* Improved documentation.
* Demo site is compatible with Django 1.8.
* Added support for Docker Compose for running the demo application and running the tests.
## 0.2.1 (2017-08-05)
* Added support for Django 1.8.
* Fixed version specifiers for Django requirement so that it wont force the installation of Django 1.11.
* Added badges for PyPi, Read the Docs and Travis CI to readme file.
* Several additions to the documentation.
## 0.2.0 (2017-08-04)
* Add support for PNG image format via an `img` tag.
* Add documentation for users and developers.
* Improve examples in demo app.
## 0.1.1 (2017-08-02)
First public release.
django-qr-code-3.1.1a/Dockerfile 0000664 0000000 0000000 00000002106 14513162264 0016444 0 ustar 00root root 0000000 0000000 ARG PYTHON_VERSION
FROM python:${PYTHON_VERSION}
LABEL vendor="dProg - Philippe Docourt" maintainer="Philippe Docourt" description="Demo Site for Django QR code"
ENV PYTHONUNBUFFERED 1
# Avoid possible occurrences of UnicodeEncodeError when running on x86 architecture.
ENV PYTHONIOENCODING utf-8
# Set env variables used in this Dockerfile (add a unique prefix, such as )
# Directory in container for project source files.
ARG APP_BASE_DIR=/usr/src/app
# Declare a proper Django settings file.
ENV DJANGO_SETTINGS_MODULE=demo_site.settings
# Make app dir.
RUN mkdir -p "$APP_BASE_DIR"
WORKDIR "$APP_BASE_DIR"
# Install requirements (separate step for caching intermediate image).
COPY requirements.txt "$APP_BASE_DIR/"
RUN pip install --upgrade pip
RUN pip install -r requirements.txt
COPY requirements-web-deployment.txt "$APP_BASE_DIR/"
RUN pip install -r requirements-web-deployment.txt
# Copy entrypoint script into the image.
COPY ./docker-entrypoint.sh /
# Invoke app's entrypoint via dumb-init so that sub-processes are handled properly.
CMD ["/docker-entrypoint.sh"]
django-qr-code-3.1.1a/LICENSE 0000664 0000000 0000000 00000002771 14513162264 0015467 0 ustar 00root root 0000000 0000000 BSD 3-Clause License
Copyright (c) 2017-2021, dProg - Philippe Docourt
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
django-qr-code-3.1.1a/MANIFEST.in 0000664 0000000 0000000 00000000067 14513162264 0016214 0 ustar 00root root 0000000 0000000 include README.md
include LICENSE
include CHANGELOG.md
django-qr-code-3.1.1a/README.md 0000664 0000000 0000000 00000071113 14513162264 0015735 0 ustar 00root root 0000000 0000000 # Django QR Code
[](https://badge.fury.io/py/django-qr-code)
[](https://pypi.python.org/pypi/django-qr-code)
[](http://django-qr-code.readthedocs.io/en/latest/)
[](https://app.travis-ci.com/github/dprog-philippe-docourt/django-qr-code)
[](https://codeclimate.com/github/dprog-philippe-docourt/django-qr-code/maintainability)
[](https://coveralls.io/github/dprog-philippe-docourt/django-qr-code?branch=master)
This is an application that provides tools for displaying QR codes on your [Django](https://www.djangoproject.com/) site.
This application depends on the [Segno QR Code generator](https://pypi.org/project/segno/) library.
This app makes no usage of the Django models and therefore do not use any database.
Only Python >= 3.7 is supported.
## Installation
### Binary Package from PyPi
In order to use this app in a Django project, the simplest way is to install it from [PyPi](https://pypi.python.org/pypi/django-qr-code):
```bash
pip install django-qr-code
```
### From the Source Code
In order to modify or test this app you may want to install it from the source code.
Clone the [GitHub repository](https://github.com/dprog-philippe-docourt/django-qr-code) and then run:
```bash
pip install -r requirements.txt -r requirements-dev.txt
python manage.py collectstatic --no-input
```
## Usage
Start by adding `qr_code` to your `INSTALLED_APPS` setting like this:
```python
INSTALLED_APPS = (
# ...,
'qr_code',
)
```
You need to load the tags provided by this app in your template with:
```djangotemplate
{% load qr_code %}
```
The source code on [GitHub](https://github.com/dprog-philippe-docourt/django-qr-code) contains a simple demo app. Please check out the [templates folder](https://github.com/dprog-philippe-docourt/django-qr-code/tree/master/qr_code_demo/templates/qr_code_demo) for an example of template, and the [setting](https://github.com/dprog-philippe-docourt/django-qr-code/tree/master/demo_site/settings.py) and [urls](https://github.com/dprog-philippe-docourt/django-qr-code/tree/master/demo_site/urls.py) files for an example of configuration and integration.
### Generating Inline QR Code in your HTML (qr_from_text)
The tag **`qr_from_text`** generates an embedded `svg` or `img` tag within the HTML code produced by your template.
The following renders a tiny "hello world" QR code with a `svg` tag:
```djangotemplate
{% qr_from_text "Hello World!" size="T" %}
```
Here is a medium "hello world" QR code with an `img` tag:
```djangotemplate
{% qr_from_text "Hello World!" size="m" image_format="png" error_correction="L" %}
```
### QR Code Rendering Options
The `size` parameter gives the size of each module of the QR code matrix. It can be either a positive integer or one of the following letters:
* t or T: tiny (value: 6)
* s or S: small (value: 12)
* m or M: medium (value: 18)
* l or L: large (value: 30)
* h or H: huge (value: 48)
For PNG image format the size unit is in pixels, while the unit is 1 mm for SVG format.
Here is a "hello world" QR code using the version 12:
```djangotemplate
{% qr_from_text "Hello World!" size=8 version=12 %}
```
The `version` parameter is an integer from 1 to 40 that controls the size of the QR code matrix. Set to None to determine this automatically. The smallest, version 1, is a 21 x 21 matrix. The biggest, version 40, is 177 x 177 matrix. The size grows by 4 modules/side.
Here is a "hello world" QR code using a border of 6 modules:
```djangotemplate
{% qr_from_text "Hello World!" size=10 border=6 %}
```
The `border` parameter controls how many modules thick the border should be (the default is 4, which is the minimum according to the specs).
There are 4 error correction levels used for QR codes, with each one adding different amounts of "backup" data
depending on how much damage the QR code is expected to suffer in its intended environment, and hence how much
error correction may be required. The correction level can be configured with the `error_correction` parameter as follows:
* l or L: error correction level L – up to 7% damage
* m or M: error correction level M – up to 15% damage
* q or Q: error correction level Q – up to 25% damage
* h or H: error correction level H – up to 30% damage
You may enforce the creation of a Micro QR Code with `micro=True`. The `micro` option defaults to `False`.
The `encoding` option controls the text encoding used in mode "byte" (used for any general text content). By default `encoding` is ``UTF-8``. When set to ``None``, the implementation (based on Segno) tries to use the standard conform ISO/IEC 8859-1 encoding and if it does not fit, it will use UTF-8. Note that no ECI mode indicator is inserted by default (see `eci` option). The `encoding` parameter is case-insensitive.
The `boost_error` indicates whether the QR code encoding engine (Segno) tries to increase the error correction level if it does not affect the version. Error correction level is not increased when it impacts the version of the code.
The `eci` option indicates if binary data which does not use the default encoding (ISO/IEC 8859-1) should enforce the ECI mode. Since a lot of QR code readers do not support the ECI mode, this feature is disabled by default and the data is encoded in the provided encoding using the usual “byte” mode. Set eci to `True` if an ECI header should be inserted into the QR Code. Note that the implementation may not know the ECI designator for the provided encoding and may raise an exception if the ECI designator cannot be found. The ECI mode is not supported by Micro QR Codes.
Alternatively, you may use the `options` keyword argument with an instance of `QRCodeOptions` as value instead of listing every requested options. Here is an example of view:
```python
from django.shortcuts import render
from qr_code.qrcode.utils import QRCodeOptions
def my_view(request):
# Build context for rendering QR codes.
context = dict(
my_options=QRCodeOptions(size='t', border=6, error_correction='L'),
)
# Render the view.
return render(request, 'my_app/my_view.html', context=context)
```
and an example of template for the view above:
```djangotemplate
{% qr_from_text "Hello World!" options=my_options %}
```
### Generating URLs to QR Code Images (qr_url_from_text)
The **`qr_url_from_text`** tag generates an url to an image representing the QR code. It comes with the same options as `qr_from_text` to customize the image format (SVG or PNG), the size, the border, and the matrix size. It also has an additional option **`cache_enabled`** to disable caching of served image.
Here is a medium "hello world" QR code that uses an URL to serve the image in SVG format:
```djangotemplate
```
Here is a "hello world" QR code in version 10 that uses an URL to serve the image in PNG format:
```djangotemplate
```
The image targeted by the generated URL is served by a view provided in `qr_code.urls`. Therefore, you need to include the URLs provided by `qr_code.urls` in your app in order to make this tag work. This can be achieved with something like this:
```python
from django.conf.urls import include
from django.urls import path
urlpatterns = [
path('qr_code/', include('qr_code.urls', namespace="qr_code")),
]
```
The QR code images are served via a URL named **`qr_code:serve_qr_code_image`**. You can customize the path under which the images are served (i.e. the path bound to the URL named `qr_code:serve_qr_code_image`) with the optional setting **`SERVE_QR_CODE_IMAGE_PATH`** which defaults to `images/serve-qr-code-image/`. Note that the trailing slash is mandatory and that defining this setting to an empty string leads to using the default value. The example below will serve any QR code image from `/qr-code-image/`:
```python
# In urls.py
from django.conf.urls import include
from django.urls import path
urlpatterns = [
path('', include('qr_code.urls', namespace='qr_code')),
]
# In your settings
SERVE_QR_CODE_IMAGE_PATH = 'qr-code-image/'
```
### Generating Image Object Representing a QR Code
If you do not want to use Django tags for rendering QR code in a template, you can simply use the API in your code. For instance, `qr_code.qrcode.maker.make_qr_code_image` will return bytes representing an image according to the image_format passed in the `qr_code_options` parameter.
### Special encoding modes with qr_from_data and qr_url_from_data
The tags **`qr_from_data`** and **`qr_url_from_data`** produce results similar to those of `qr_from_text` and `qr_url_from_text`, but they avoid converting everything to text (UTF-8 encoded by default, or any supported charset depending on `encoding` option).
The ISO/IEC 18004 standard defines four modes in order to encode the data as efficiently as possible.
#### Numeric mode
The numeric mode is the most efficient way to encode digits. This mode does not cover negative numbers because it does not support the minus sign (or plus sign).
The numeric mode is supported by QR Codes and Micro QR Codes. The encoding engine detects (Segno) the numeric mode if the data is provided as string (e.g. '54') or integer (e.g. 54) to `qr_from_data` or `qr_url_from_data`.
#### Alphanumeric mode
The alphanumeric mode extends the numeric mode by various characters. Namely, about the upper case letters ABCDEFGHIJKLMNOPQRSTUVWXYZ, a space character " " and other letters $%*+-./:.
#### Kanji mode
Kanji can be encoded compactly and efficiently and requires significantly less space than encoding the characters in UTF-8.
#### Byte mode
The byte mode covers all data which cannot be represented by the other modes. When the `encoding` option is set to `None`, the encoding engine (Segno) detects, according to ISO/IEC 18004, to encode the data with ISO 8859-1. In case the data cannot be represented by ISO 8859-1, UTF-8 is used as fallback.
NOTE: When using `qr_from_text` or `qr_url_from_text`, the byte mode with UTF-8 encoding is forced by default . You may use the `encoding` option to change this behavior. It appears to be one of the most portable way of encoding text for proper decoding among the readers.
#### Examples
The following renders a tiny numeric QR code containing the value `2021` with a `svg` tag:
```djangotemplate
{% qr_from_data 2021 size="T" %}
```
Here is a micro QR code with an `img` tag containing the value `2021`:
```djangotemplate
{% qr_from_data 2021 micro=True image_format="png" %}
```
### Caching Served Images
A large QR code (version 40) requires 0.2 second to be generated on a powerful machine (in 2018), and probably more than half a second on a really cheap hosting.
The image served by the *qr_code* app can be cached to improve performances and reduce CPU usage required to generate the QR codes. In order to activate caching, you simply need to declare a cache alias with the setting **`QR_CODE_CACHE_ALIAS`** to indicate in which cache to store the generated QR codes.
For instance, you may declare an additional cache for your QR codes like this in your Django settings:
```python
CACHES = {
'default': {
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
},
'qr-code': {
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
'LOCATION': 'qr-code-cache',
'TIMEOUT': 3600
}
}
QR_CODE_CACHE_ALIAS = 'qr-code'
```
The `QR_CODE_CACHE_ALIAS = 'qr-code'` tells the *qr_code* app to use that cache for storing the generated QR codes. All QR codes will be cached with the specified *TIMEOUT* when a non-empty value is set to `QR_CODE_CACHE_ALIAS`.
If you want to activate the cache for QR codes, but skip the caching for some specific codes, you can use the keyword argument `cache_enabled=False` when using `qr_url_from_text`.
Here is a "hello world" QR code in version 20 with an error correction level Q (25% of redundant data) that uses a URL to serve the image in SVG format, and disable caching for served image:
```djangotemplate
```
### Protecting Access to QR Code Images
The default settings protect the URLs that serve QR code images against external requests, and thus against possibly easy (D)DoS attacks.
Here are the available settings to manage the protection for served images:
```python
from qr_code.qrcode import constants
QR_CODE_URL_PROTECTION = {
constants.TOKEN_LENGTH: 30, # Optional random token length for URL protection. Defaults to 20.
constants.SIGNING_KEY: 'my-secret-signing-key', # Optional signing key for URL token. Uses SECRET_KEY if not defined.
constants.SIGNING_SALT: 'my-signing-salt', # Optional signing salt for URL token.
constants.ALLOWS_EXTERNAL_REQUESTS_FOR_REGISTERED_USER: True # Tells whether a registered user can request the QR code URLs from outside a site that uses this app. It can be a boolean value used for any user or a callable that takes a user as parameter. Defaults to False (nobody can access the URL without the signature token).
}
```
#### Signing Request URLs
By default, the application only serves QR code images for authenticated URLs (requests generated from your application and addressed to your application). The authentication uses a HMAC to sign the request query arguments. The authentication code is passed as a query argument named **`token`** which is automatically generated by `qr_url_from_text` or `qr_url_from_data`. Whenever the signature is invalid, the application returns a *HTTP 403 Permission denied* response when processing the request for serving a QR code image.
This mechanism ensures that, by default, nobody can send external requests to your application to obtain custom QR codes for free. This is especially useful if you display QR code URLs on public pages (no user authentication).
The `token` query argument is not mandatory and, when a request reaches the `qr_code:serve_qr_code_image` URL without that token, the protection mechanism falls back to the user authentication mechanism (see chapter below).
It is possible to explicitly remove the signature token that protects a specific URL with the parameter **`url_signature_enabled=False`**. Here is a "hello world" QR code that uses a URL to serve the image in SVG format without the `token` query argument :
```djangotemplate
```
The `token` parameter will not be part of the query string of the generated URL, making possible to build a simpler, predictable URL. However, this will trigger the user authentication mechanism (see chapter below).
#### Handling User Authentication when Serving QR Code Images
If you are interested in providing the QR code images as a service, there is a setting named **`ALLOWS_EXTERNAL_REQUESTS_FOR_REGISTERED_USER`** to grant access to some controlled users. This setting tells who can bypass the url signature token (see chapter above). It can be a boolean value used for any authenticated user, or a callable that takes a user as only parameter.
Setting the `ALLOWS_EXTERNAL_REQUESTS_FOR_REGISTERED_USER` option to `True` tells the application to serve QR code images to authenticated users only. Hence, to grant access to any authenticated user to generated images, you can use this in your settings:
```python
from qr_code.qrcode import constants
QR_CODE_URL_PROTECTION = {
constants.ALLOWS_EXTERNAL_REQUESTS_FOR_REGISTERED_USER: True
}
```
Setting the option `ALLOWS_EXTERNAL_REQUESTS_FOR_REGISTERED_USER` to a callable that always returns `True` (even for anonymous users) will allow anyone to access QR code image generation from outside your Django app. The following settings will grant access to anonymous users to generated images:
```python
from qr_code.qrcode import constants
QR_CODE_URL_PROTECTION = {
constants.ALLOWS_EXTERNAL_REQUESTS_FOR_REGISTERED_USER: lambda u: True
}
```
Please note that, if your service is available on the Internet, allowing anyone to generate any kind of QR code via your Django application - as shown above - might generate a very heavy load on your server.
### QR Codes for Apps
Aside from generating a QR code from a given text, you can also generate codes for specific application purposes, that a reader can interpret as an action to take: open a mail client to send an e-mail to a given address, add a contact to your phone book, connect to a Wi-Fi, start a SMS, etc. See [this documentation](https://github.com/zxing/zxing/wiki/Barcode-Contents) about what a QR code can encode.
Django QR Code proposes several utility tags to ease the generation of such codes, without having to build the appropriate text representation for each action you need. This remove the hassle of reading the specifications and handling all the required escaping for reserved chars.
Please note that some commands are common patterns, rather than formal specifications. Therefore, there is no guarantee that all QR code readers will handle them properly.
The following tags targeting apps are available:
* `qr_for_email` and `qr_url_for_email`
* `qr_for_tel` and `qr_url_for_tel`
* `qr_for_sms` and `qr_url_for_sms`
* `qr_for_geolocation` and `qr_url_for_geolocation`
* `qr_for_google_maps` and `qr_url_for_google_maps`
* `qr_for_youtube` and `qr_url_for_youtube`
* `qr_for_google_play` and `qr_url_for_google_play`
* `qr_for_mecard` and `qr_url_for_mecard`
* `qr_for_vcard` and `qr_url_for_vcard`
* `qr_for_wifi` and `qr_url_for_wifi`
* `qr_for_epc` and `qr_url_for_epc`
* `qr_for_event` and `qr_url_for_event`
* `qr_for_contact` and `qr_url_for_contact` (legacy, do not use in new projects)
You could write a view like this:
```python
import datetime
from datetime import date
from django.shortcuts import render
from qr_code.qrcode.utils import MeCard, VCard, EpcData, VEvent, EventClass, EventTransparency, EventStatus, WifiConfig, Coordinates, QRCodeOptions
def application_qr_code_demo(request):
# Use a MeCard instance to encapsulate the detail of the contact.
mecard_contact = MeCard(
name='Doe, John',
phone='+41769998877',
email='j.doe@company.com',
url='http://www.company.com',
birthday=date(year=1985, month=10, day=2),
memo='Development Manager',
org='Company Ltd'
)
# Use a VCard instance to encapsulate the detail of the contact.
vcard_contact = VCard(
name='Doe; John',
phone='+41769998877',
email='j.doe@company.com',
url='http://www.company.com',
birthday=date(year=1985, month=10, day=2),
street='Cras des Fourches 987',
city='Delémont',
zipcode=2800,
region='Jura',
country='Switzerland',
memo='Development Manager',
org='Company Ltd'
)
# Use a WifiConfig instance to encapsulate the configuration of the connexion.
wifi_config = WifiConfig(
ssid='my-wifi',
authentication=WifiConfig.AUTHENTICATION.WPA,
password='wifi-password'
)
# Use a EpcData instance to encapsulate the data of the European Payments Council Quick Response Code.
epc_data = EpcData(
name='Wikimedia Foerdergesellschaft',
iban='DE33100205000001194700',
amount=50.0,
text='To Wikipedia'
)
# Build coordinates instances.
google_maps_coordinates = Coordinates(latitude=586000.32, longitude=250954.19)
geolocation_coordinates = Coordinates(latitude=586000.32, longitude=250954.19, altitude=500)
# Build event data (VEVENT properties)
# NB for start and end of event:
# - Naive date and time is rendered as floating time.
# - Aware date and time is rendered as UTC converted time.
event = VEvent(
uid="some-event-id",
summary="Vacations",
start=datetime.datetime(2022, 8, 6, hour=8, minute=30),
end=datetime.datetime(2022, 8, 17, hour=12),
location="New-York, Statue de la Liberté",
geo=(40.69216097988203, -74.04460073403436),
categories=["PERSO", "holidays"],
status=EventStatus.CONFIRMED,
event_class=EventClass.PRIVATE,
transparency=EventTransparency.OPAQUE,
organizer="foo@bar.com",
url="https://bar.com",
description="""Fake description. Meeting to provide technical review for "Phoenix" design. Happy Face Conference Room.
Phoenix design team MUST attend this meeting.
RSVP to team leader."""
)
# Build context for rendering QR codes.
context = dict(
mecard_contact=mecard_contact,
vcard_contact=vcard_contact,
wifi_config=wifi_config,
epc_data=epc_data,
event=event,
video_id='J9go2nj6b3M',
google_maps_coordinates=google_maps_coordinates,
geolocation_coordinates=geolocation_coordinates,
options_example=QRCodeOptions(size='t', border=6, error_correction='L'),
)
# Render the index page.
return render(request, 'my_app/application_qr_code_demo.html', context=context)
```
Then, in your template, you can render the appropriate QR codes for the given context:
```djangotemplate
Add contact '{{ mecard_contact.name }}' to phone book