API Reference

qrcode.maker

Tools for generating QR codes. This module depends on the Segno library.

qr_code.qrcode.maker.make_embedded_qr_code[source]

Generates a <svg> or <img> tag representing the QR code for the given data. This tag can be embedded into an HTML document.

qr_code.qrcode.maker.make_qr[source]

Creates a QR code that encodes the given data with the given qr_code_options.

Parameters:
  • data (str) – The data to encode
  • qr_code_options – Options to create and serialize the QR code.
  • force_text (bool) – Tells whether we want to force the data to be considered as text string and encoded in byte mode.
Return type:

segno.QRCode
qr_code.qrcode.maker.make_qr_code_image[source]

Creates a bytes object representing a QR code image for the provided data.

Parameters:
  • data (str) – The data to encode
  • qr_code_options – Options to create and serialize the QR code.
  • force_text (bool) – Tells whether we want to force the data to be considered as text string and encoded in byte mode.
Return type:

bytes

qrcode.serve

qr_code.qrcode.serve.get_qr_url_protection_signed_token(qr_code_options: qr_code.qrcode.utils.QRCodeOptions)[source]

Generate a signed token to handle view protection.

qr_code.qrcode.serve.get_qr_url_protection_token(qr_code_options, random_token)[source]

Generate a random token for the QR code image.

The token contains image attributes so that a user cannot use a token provided somewhere on a website to generate bigger QR codes. The random_token part ensures that the signed token is not predictable.

qr_code.qrcode.serve.make_qr_code_url[source]

Build an URL to a view that handle serving QR code image from the given parameters.

Any invalid argument related to the size or the format of the image is silently converted into the default value for that argument.

Parameters:
  • data (str) – Data to encode into a QR code.
  • qr_code_options (QRCodeOptions) – The rendering options for the QR code.
  • force_text (bool) – Tells whether we want to force the data to be considered as text string and encoded in byte mode.
  • cache_enabled (bool) – Allows to skip caching the QR code (when set to False) when caching has been enabled.
  • url_signature_enabled (bool) – Tells whether the random token for protecting the URL against external requests is added to the returned URL. It defaults to True.

qrcode.utils

Utility classes and functions for configuring and setting up the content and the look of a QR code.

class qr_code.qrcode.utils.ContactDetail[source]

Represents the detail of a contact for MeCARD encoding.

Note

This is a legacy class. Please use MeCard instead for new projects.

Fields meaning:
  • first_name
  • last_name
  • first_name_reading: the sound of the first name.
  • last_name_reading: the sound of the last name.
  • tel: the phone number, it can appear multiple times.
  • tel_av: the video-phone number, it can appear multiple times.
  • email: the email address, it can appear multiple times.
  • memo: notes.
  • birthday: the birth date (Python date).
  • address: the fields divided by commas (,) denote PO box, room number, house number, city, prefecture, zip code and country, in order.
  • url: homepage URL.
  • nickname: display name.
  • org: organization or company name (non-standard,but often recognized, ORG field).
__weakref__

list of weak references to the object (if defined)

make_qr_code_data() → str[source]

Make a text for configuring a contact in a phone book. The MeCARD format is used, with an optional, non-standard (but often recognized) ORG field.

See this archive of the format specifications: https://web.archive.org/web/20160304025131/https://www.nttdocomo.co.jp/english/service/developer/make/content/barcode/function/application/addressbook/index.html

Returns:the MeCARD contact description.
class qr_code.qrcode.utils.Coordinates(latitude: float, longitude: float, altitude: Union[int, float, None] = None)[source]

Represents a set of coordinates with an optional altitude.

Fields meaning:
  • latitude: The latitude.
  • latitude: The longitude.
  • latitude: The optional altitude.
__str__() → str[source]

Return str(self).

__weakref__

list of weak references to the object (if defined)

class qr_code.qrcode.utils.Email(to: Union[str, Sequence[str]], cc: Union[str, Sequence[str], None] = None, bcc: Union[str, Sequence[str], None] = None, subject: Optional[str] = None, body: Optional[str] = None)[source]

Represents the data of an e-mail.

Fields meaning:
  • to: The email address (recipient). Multiple values are allowed.
  • cc: The carbon copy recipient. Multiple values are allowed.
  • bcc: The blind carbon copy recipient. Multiple values are allowed.
  • subject: The subject.
  • body: The message body.
__weakref__

list of weak references to the object (if defined)

make_qr_code_data() → str[source]

Creates either a simple “mailto:” URL or complete e-mail message with (blind) carbon copies and a subject and a body.

Return type:str
class qr_code.qrcode.utils.EpcData(name: str, iban: str, amount: Union[int, float, decimal.Decimal], text: Optional[str] = None, reference: Optional[str] = None, bic: Optional[str] = None, purpose: Optional[str] = None)[source]

Data for representing an European Payments Council Quick Response Code (EPC QR Code) version 002.

You must always use the error correction level “M” and utilizes max. version 13 to fulfill the constraints of the

EPC QR Code standard.

Note

Either the text or reference must be provided but not both

Note

Neither the IBAN, BIC, nor remittance reference number or any other information is validated (aside from checks regarding the allowed string lengths).

Fields meaning:
  • name: Name of the recipient.
  • iban: International Bank Account Number (IBAN)
  • amount: The amount to transfer. The currency is always Euro, no other currencies are supported.
  • text: Remittance Information (unstructured)
  • reference: Remittance Information (structured)
  • bic: Bank Identifier Code (BIC). Optional, only required for non-EEA countries.
  • purpose: SEPA purpose code.
__weakref__

list of weak references to the object (if defined)

make_qr_code_data() → str[source]

Validates the input and creates the data for an European Payments Council Quick Response Code (EPC QR Code) version 002.

This is a wrapper for segno.helpers._make_epc_qr_data() with no choice for encoding.

Return type:str
class qr_code.qrcode.utils.EventClass[source]

An enumeration.

class qr_code.qrcode.utils.EventStatus[source]

An enumeration.

class qr_code.qrcode.utils.EventTransparency[source]

An enumeration.

class qr_code.qrcode.utils.MeCard(name: str, reading: Optional[str] = None, email: Union[str, Sequence[str], None] = None, phone: Union[str, Sequence[str], None] = None, videophone: Union[str, Sequence[str], None] = None, memo: Optional[str] = None, nickname: Optional[str] = None, birthday: Union[str, datetime.date, None] = None, url: Union[str, Sequence[str], None] = None, pobox: Optional[str] = None, roomno: Optional[str] = None, houseno: Optional[str] = None, city: Optional[str] = None, prefecture: Optional[str] = None, zipcode: Union[int, str, None] = None, country: Optional[str] = None, org: Optional[str] = None)[source]

Represents the detail of a contact for MeCARD encoding.

Fields meaning:
  • name: Name. If it contains a comma, the first part is treated as lastname and the second part is treated as forename.
  • reading: Designates a text string to be set as the kana name in the phonebook
  • email: E-mail address. Multiple values are allowed.
  • phone: Phone number. Multiple values are allowed.
  • videophone: Phone number for video calls. Multiple values are allowed.
  • memo: A notice for the contact.
  • nickname: Nickname.
  • birthday: Birthday. If a string is provided, it should encode the date as YYYYMMDD value.
  • url: Homepage. Multiple values are allowed.
  • pobox: P.O. box (address information).
  • roomno: Room number (address information).
  • houseno: House number (address information).
  • city: City (address information).
  • prefecture: Prefecture (address information).
  • zipcode: Zip code (address information).
  • country: Country (address information).
  • org: organization or company name (ORG field, non-standard,but often recognized by readers).
__weakref__

list of weak references to the object (if defined)

make_qr_code_data() → str[source]

Creates a string encoding the contact information as MeCARD.

Return type:str
class qr_code.qrcode.utils.QRCodeOptions[source]

Represents the options used to create and draw a QR code.

__init__[source]
Parameters:
  • size – The size of the QR code as an integer or a string. Default is ‘m’.
  • border (int) – The size of the border (blank space around the code).
  • version (int, str or None) – The version of the QR code gives the size of the matrix. Default is None which mean automatic in order to avoid data overflow.
  • version – QR Code version. If the value is None (default), the minimal version which fits for the input data will be used. Valid values: “M1”, “M2”, “M3”, “M4” (for Micro QR codes) or an integer between 1 and 40 (for QR codes). The version parameter is case insensitive.
  • image_format (str) – The graphics format used to render the QR code. It can be either ‘svg’ or ‘png’. Default is ‘svg’.
  • error_correction (str) – How much error correction that might be required to read the code. It can be either ‘L’, ‘M’, ‘Q’, or ‘H’. Default is ‘M’.
  • boost_error (bool) – Tells whether the QR code encoding engine 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.
  • micro (bool) – Indicates if a Micro QR Code should be created. Default: False
  • encoding (str or None) – Indicates the encoding in mode “byte”. By default encoding is UTF-8. When set to None, the implementation 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 :paramref:`eci`). The encoding parameter is case-insensitive.
  • eci (bool) – 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.
  • dark_color – Color of the dark modules (default: black). The color can be provided as (R, G, B) tuple, as hexadecimal format (#RGB, #RRGGBB RRGGBBAA), or web color name (i.e. red). If alpha transparency is supported (i.e. PNG and SVG), hexadecimal values like #RRGGBBAA are accepted.
  • light_color – Color of the light modules (default: white). See color for valid values. If light is set to None the light modules will be transparent.
  • finder_dark_color – Color of the dark finder modules (default: same as dark_color)
  • finder_light_color – Color of the light finder modules (default: same as light_color)
  • data_dark_color – Color of the dark data modules (default: same as dark_color)
  • data_light_color – Color of the light data modules (default: same as light_color)
  • version_dark_color – Color of the dark version modules (default: same as dark_color)
  • version_light_color – Color of the light version modules (default: same as light_color)
  • format_dark_color – Color of the dark format modules (default: same as dark_color)
  • format_light_color – Color of the light format modules (default: same as light_color)
  • alignment_dark_color – Color of the dark alignment modules (default: same as dark_color)
  • alignment_light_color – Color of the light alignment modules (default: same as light_color)
  • timing_dark_color – Color of the dark timing pattern modules (default: same as dark_color)
  • timing_light_color – Color of the light timing pattern modules (default: same as light_color)
  • separator_color – Color of the separator (default: same as light_color)
  • dark_module_color – Color of the dark module (default: same as dark_color)
  • quiet_zone_color – Color of the quiet zone modules (default: same as light_color)
Type:

str or int
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 0.1 mm for SVG format.

The border parameter controls how many modules thick the border should be (blank space around the code). The default is 4, which is the minimum according to the specs.

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. For Micro QR codes, valid values are “M1”, “M2”, “M3”, “M4”.

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 follow:

  • 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.

Raises:TypeError in case an unknown argument is given.
__weakref__

list of weak references to the object (if defined)

color_mapping()[source]

Internal method which returns the color mapping.

Only non-default values are returned.

Return type:dict
kw_make()[source]

Internal method which returns a dict of parameters to create a QR code.

Return type:dict
kw_save()[source]

Internal method which returns a dict of parameters to save a QR code.

Return type:dict
class qr_code.qrcode.utils.VCard(name: str, displayname: Optional[str] = None, email: Union[str, Sequence[str], None] = None, phone: Union[str, Sequence[str], None] = None, fax: Union[str, Sequence[str], None] = None, videophone: Union[str, Sequence[str], None] = None, memo: Optional[str] = None, nickname: Optional[str] = None, birthday: Union[str, datetime.date, None] = None, url: Union[str, Sequence[str], None] = None, pobox: Optional[str] = None, street: Optional[str] = None, city: Optional[str] = None, region: Optional[str] = None, zipcode: Union[int, str, None] = None, country: Optional[str] = None, org: Optional[str] = None, lat: Optional[float] = None, lng: Optional[float] = None, source: Optional[str] = None, rev: Union[str, datetime.date, None] = None, title: Union[str, Sequence[str], None] = None, photo_uri: Union[str, Sequence[str], None] = None, cellphone: Union[str, Sequence[str], None] = None, homephone: Union[str, Sequence[str], None] = None, workphone: Union[str, Sequence[str], None] = None)[source]

Represents the detail of a contact for vCard encoding.

Creates a QR code which encodes a vCard version 3.0.

Only a subset of available vCard 3.0 properties <https://tools.ietf.org/html/rfc2426> is supported.

Fields meaning: name: The name. If it contains a semicolon, , the first part

is treated as lastname and the second part is treated as forename.

displayname: Common name. email: E-mail address. Multiple values are allowed. phone: Phone number. Multiple values are allowed. fax: Fax number. Multiple values are allowed. videophone: Phone number for video calls. Multiple values are allowed. memo: A notice for the contact. nickname: Nickname. birthday: Birthday. If a string is provided, it should encode the

date as YYYY-MM-DD value.

url: Homepage. Multiple values are allowed. pobox: P.O. box (address information). street: Street address. city: City (address information). region: Region (address information). zipcode: Zip code (address information). country: Country (address information). org: Company / organization name. lat: Latitude. lng: Longitude. source: URL where to obtain the vCard. rev: Revision of the vCard / last modification date. title: Job Title. Multiple values are allowed. photo_uri: Photo URI. Multiple values are allowed. cellphone: Cell phone number. Multiple values are allowed. homephone: Home phone number. Multiple values are allowed. workphone: Work phone number. Multiple values are allowed.

__weakref__

list of weak references to the object (if defined)

make_qr_code_data() → str[source]

Creates a string encoding the contact information as vCard 3.0.

Only a subset of available vCard 3.0 properties <https://tools.ietf.org/html/rfc2426> is supported.

Return type:str
class qr_code.qrcode.utils.VEvent(uid: str, summary: str, start: datetime.datetime, end: datetime.datetime, dtstamp: Optional[datetime.datetime] = None, description: Optional[str] = None, organizer: Optional[str] = None, status: Optional[qr_code.qrcode.utils.EventStatus] = None, location: Optional[str] = None, geo: Optional[Tuple[float, float]] = None, event_class: Optional[qr_code.qrcode.utils.EventClass] = None, categories: Optional[List[str]] = None, transparency: Optional[qr_code.qrcode.utils.EventTransparency] = None, url: Optional[str] = None)[source]

Data for representing VEVENT for iCalendar (.ics) event.

Only a subset of https://icalendar.org/iCalendar-RFC-5545/3-6-1-event-component.html is supported.

Fields meaning:
  • uid: Event identifier
  • summary: This property defines a short summary or subject for the calendar event.
  • start: Start of event
  • end: End of event
  • dtstamp: The property indicates the date/time that the instance of the iCalendar object was created. Defaults to current time in UTC.
  • description: This property provides a more complete description of the calendar component, than that provided by the “SUMMARY” property.
  • organizer: E-mail of organizer
  • status: Status of event
  • location: Location of event
  • geo: This property specifies information related to the global position of event. The property value specifies latitude and longitude, in that order. Whole degrees of latitude shall be represented by a two-digit decimal number ranging from -90 through 90. The longitude represents the location east or west of the prime meridian as a positive or negative real number, respectively (a decimal number ranging from -180 through 180).
  • event_class: Either PUBLIC, PRIVATE or CONFIDENTIAL (see utils.EventClass).
  • categories: This property defines the categories for calendar event.
  • transparency: Tell whether the event can have its Time Transparency set to “TRANSPARENT” in order to prevent blocking of the event in searches for busy time.
  • url: This property defines a Uniform Resource Locator (URL) associated with the iCalendar object.
__weakref__

list of weak references to the object (if defined)

make_qr_code_data() → str[source]

Creates a string encoding the event information.

Only a subset of https://icalendar.org/iCalendar-RFC-5545/3-6-1-event-component.html is supported.

class qr_code.qrcode.utils.WifiConfig(ssid: str = '', authentication: int = 0, password: str = '', hidden: bool = False)[source]

Represents a WIFI configuration.

Fields meaning:
  • ssid: the name of the SSID
  • authentication: the authentication type for the SSID; can be AUTHENTICATION.wep or AUTHENTICATION.wpa, or AUTHENTICATION.nopass for no password. Or, omit for no password.
  • password: the password, ignored if “authentication” is ‘nopass’ (in which case it may be omitted).
  • hidden: tells whether the SSID is hidden or not; can be True or False.
__init__(ssid: str = '', authentication: int = 0, password: str = '', hidden: bool = False) → None[source]

Initialize self. See help(type(self)) for accurate signature.

__weakref__

list of weak references to the object (if defined)

make_qr_code_data() → str[source]

Make a text for configuring a Wi-Fi connexion. The syntax is inspired by the MeCARD format used for contacts.

Returns:the WIFI configuration text that can be translated to a QR code.
Return type:str

qrcode.views

qr_code.views.cache_qr_code()[source]

Decorator that caches the requested page if a settings named ‘QR_CODE_CACHE_ALIAS’ exists and is not empty or None.

qr_code.views.check_image_access_permission(request, qr_code_options) → None[source]

Handle image access protection (we do not allow external requests for anyone).

qr_code.views.serve_qr_code_image(request) → django.http.response.HttpResponse[source]

Serve an image that represents the requested QR code.

IMPORTANT NOTE: Each boolean option mentioned below (value True/False) must be passed as <option name>=1 for True, respectively <option name>=0 for False.

You may pass any argument available for qr_code.qrcode.utils.QRCodeOptions.__init__() to adjust the appearance of the returned QR code. The arguments must be passed as query string arguments in the URL. Additionally, the following arguments are available:

  • cache_enabled: boolean – Tells the generator to work around the caching mechanism if it is empty (default: True/undefined).
  • token: str – 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.

templatetags.qr_code

Tags for Django template system that help generating QR codes.

qr_code.templatetags.qr_code.qr_for_geolocation(**kwargs) → str[source]

Accepts a ‘coordinates’ keyword argument or a triplet ‘latitude’, ‘longitude’, and ‘altitude’.

qr_code.templatetags.qr_code.qr_for_google_maps(**kwargs) → str[source]

Accepts a ‘coordinates’ keyword argument or a pair ‘latitude’ and ‘longitude’.

qr_code.templatetags.qr_code.qr_url_for_geolocation(**kwargs) → str[source]

Accepts a ‘coordinates’ keyword argument or a triplet ‘latitude’, ‘longitude’, and ‘altitude’.

qr_code.templatetags.qr_code.qr_url_for_google_maps(**kwargs) → str[source]

Accepts a ‘coordinates’ keyword argument or a pair ‘latitude’ and ‘longitude’.

tests