djblets.privacy.consent.forms¶
Forms, fields, and widgets for gathering and displaying consent.
- class ConsentRequirementWidget(consent_requirement=None, attrs=None)¶
Bases:
Widget
A widget for displaying and gathering consent information.
This presents the consent requirement in an easy-to-digest form, and makes it easy for users to choose to allow or block the thing requiring consent.
This is meant to be used with
ConsentRequirementField
.- __init__(consent_requirement=None, attrs=None)¶
Initialize the widget.
- Parameters:
consent_requirement (
djblets.privacy.consent.base.ConsentRequirement
, optional) – The consent requirement information. If not provided, this must be directly set on the instance before rendering the widget.attrs (
dict
, optional) – HTML attributes for the widget. This is used only to set anid
attribute for the field.
- render(name, value, attrs=None, renderer=None)¶
Render the widget.
- Parameters:
name (
unicode
) – The base name used for the<input>
elements. Specific names will be composed from this.value (
unicode
) – The current value for the field.attrs (
dict
, optional) – HTML attributes for the widget. This is used only to set anid
attribute for the field.renderer (
django.forms.renderers.BaseRenderer
, optional) – The form renderer.
- Returns:
The rendered HTML for the widget.
- Return type:
django.utils.safestring.SafeText
- value_from_datadict(data, files, name)¶
Return the field value from the submitted form data.
- Parameters:
- Returns:
A value for the fields. This will be one of
ConsentRequirementField.ALLOW
,ConsentRequirementField.BLOCK
, orNone
.- Return type:
- __annotations__ = {}¶
- class MultiConsentRequirementsWidget(consent_requirements, attrs=None)¶
Bases:
MultiWidget
A widget for displaying and gathering multiple consent information.
This adds a
ConsentRequirementWidget
for each consent requirement provided to the widget.This is meant to be used with
MultiConsentRequirementsField
.- __init__(consent_requirements, attrs=None)¶
Initialize the widget.
- render(name, value, attrs=None, renderer=None)¶
Render the widget.
- Parameters:
name (
unicode
) – The base name used for the<input>
elements. Specific names will be composed from this.value (
list
ofunicode
) – The current values for the fields.attrs (
dict
, optional) – HTML attributes for the widget. This is used only to set a baseid
attribute for the fields.renderer (
django.forms.renderers.BaseRenderer
, optional) – The form renderer.
- Returns:
The rendered HTML for the widget.
- Return type:
django.utils.safestring.SafeText
- value_from_datadict(data, files, name)¶
Return the field values from the submitted form data.
- Parameters:
- Returns:
A list of values for all the fields, in the order of the list of consent requirements provided to the widget. Each item will be one of
ConsentRequirementField.ALLOW
,ConsentRequirementField.BLOCK
, orNone
.- Return type:
- decompress(value)¶
Decompress a list of values for the widget.
This is required by the parent class, and is responsible for taking the provided data and returning a list of values that can be used for the sub-widgets.
- __annotations__ = {}¶
- class ConsentRequirementField(consent_requirement, user=None, consent_source=None, extra_consent_data=None, **kwargs)¶
Bases:
ChoiceField
A form field for displaying and gathering consent information.
This presents the consent requirement in an easy-to-digest form, and makes it easy for users to choose to allow or block the thing requiring consent.
The cleaned result from this field is a
ConsentData
instance, which can be recorded directly in the tracker.- ALLOW = 'allow'¶
- BLOCK = 'block'¶
- CHOICES = (('allow', 'Allow'), ('block', 'Block'))¶
- widget¶
alias of
ConsentRequirementWidget
- default_error_messages = {'required': 'You must choose Allow or Block to continue.'}¶
- __init__(consent_requirement, user=None, consent_source=None, extra_consent_data=None, **kwargs)¶
Initialize the field.
- Parameters:
consent_requirement (
djblets.privacy.consent.base.ConsentRequirement
) – The consent requirement information.user (
django.contrib.auth.models.User
, optional) – The user viewing the form. If provided, the default value for the field will be based on the choice already made by the user, if any.consent_source (
unicode
, optional) – The source to record in the consent audit trail for the consent choice saved in this field.extra_consent_data (
dict
, optional) – Extra information to record in the consent audit trail for the consent choice saved in this field.**kwargs (
dict
) – Additional keyword arguments to pass to the parent class.
- set_initial_from_user(user)¶
Set the initial state of the field based on a user’s prior consent.
This is called automatically if passing a user to the constructor. Otherwise, it should be called manually when setting up a form.
- Parameters:
user (
django.contrib.auth.models.User
) – The user viewing the form.
- prepare_value(value)¶
Prepare a value for use in the field.
This will convert a
Consent
value to a value suitable for use in the field.- Parameters:
value (
djblets.privacy.consent.base.Consent
) – The value to convert.- Returns:
A valid value for use in the field.
- Return type:
- clean(value)¶
Clean and return a value from submitted form data.
- Parameters:
value (
unicode
) – A value submitted by the client.- Returns:
The cleaned consent data value, or
None
if a suitable value was not provided.- Return type:
- __annotations__ = {}¶
- class MultiConsentRequirementsField(consent_requirements=None, user=None, consent_source=None, extra_consent_data=None, *args, **kwargs)¶
Bases:
MultiValueField
A form field for displaying and gathering mulltiple consent information.
This provides a
ConsentRequirementField
for each consent requirement provided to the field (or all registered ones if an explicit list was not provided). It’s handy for forms that offer all consent choices to the user.The cleaned result from this field is a list of
ConsentData
instances, which can be recorded directly in the tracker.- default_error_messages = {'required': 'You must choose Allow or Block for all options to continue.'}¶
- widget¶
alias of
MultiConsentRequirementsWidget
- __init__(consent_requirements=None, user=None, consent_source=None, extra_consent_data=None, *args, **kwargs)¶
Initialize the field.
- Parameters:
consent_requirements (
list
ofdjblets.privacy.consent.base.ConsentRequirement
, optional) – The list of consent requirements to display. If not provided, all registered consent requirements will be used.user (
django.contrib.auth.models.User
, optional) – The user viewing the form. If provided, the default options for each field will be based on the choices already made by the user.consent_source (
unicode
, optional) – The source to record in the consent audit trail for anything saved in this field.extra_consent_data (
dict
, optional) – Extra information to record in the consent audit trail for anything saved in this field.*args (
tuple
) – Additional positional arguments to pass to the parent class.**kwargs (
dict
) – Additional keyword arguments to pass to the parent class.
- set_initial_from_user(user)¶
Set the initial state of the field based on a user’s prior consent.
This is called automatically if passing a user to the constructor. Otherwise, it should be called manually when setting up a form.
- Parameters:
user (
django.contrib.auth.models.User
) – The user viewing the form.
- prepare_value(value)¶
Prepare a value for use in the field.
This will convert a list of
Consent
values given in the order of the field’s list of requirements to values suitable for use in the field.- Parameters:
value (
list
oflist
djblets.privacy.consent.base.Consent
) – The list of values to convert.- Returns:
A list of values suitable for use in the field.
- Return type:
- clean(value)¶
Clean and return values from submitted form data.
- compress(data_list)¶
Compress cleaned values for the field.
This is required by the parent class, and is responsible for taking a list of cleaned values and returning something that can be validated and returned. This implementation returns the data as-is.
- Parameters:
data_list (
list
ofdjblets.privacy.consent.base.ConsentData
) – The list of cleaned data.- Returns:
The list of data.
- Return type:
- __annotations__ = {}¶
- class ConsentFormMixin(*args, **kwargs)¶
Bases:
object
A mixin for forms that present registered consent requirements.
This can be mixed into a form to provide consent field initialization and saving.
- consent_field_name = 'consent'¶
The name of the consent field.
- __init__(*args, **kwargs)¶
Initialize the form.
- get_consent_user()¶
Return the user deciding on consent.
This must be implemented by subclasses.
- Returns:
The user deciding on consent.
- Return type:
- get_consent_source()¶
Return a source to record in the consent audit trail.
This must be implemented by subclasses.
- Returns:
The source to record for each consent entry.
- Return type:
- get_extra_consent_data()¶
Return extra data to record in the consent audit trail.
By default, this just returns an empty dictionary.
- Returns:
Extra data to record for each consent entry.
- Return type:
- save_consent(user)¶
Save the consent information recorded in the form.
- Parameters:
user (
django.contrib.auth.models.User
) – The user who made the consent decisions.
- class ConsentConfigPageFormMixin(*args, **kwargs)¶
Bases:
ConsentFormMixin
A mixin for config forms that present registered consent requirements.
This can be mixed into a config form to provide consent field initialization and saving. It would be used instead of
ConsentFormMixin
.- form_id = 'privacy_consent'¶
- form_title = 'Privacy Consent'¶
- save()¶
Save the form.
This will save the consent information from the field.
- get_consent_user()¶
Return the user deciding on consent.
- Returns:
The user deciding on consent.
- Return type:
- get_consent_source()¶
Return a source to record in the consent audit trail.
By default, this returns the absolute URL for the page.
- Returns:
The source to record for each consent entry.
- Return type:
- __annotations__ = {}¶