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 an id 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 an id 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:

• data (dict) – The submitted form data.

• files (dict, unused) – The submitted files data.

• name (unicode) – The base name for the form fields.

Returns:

A value for the fields. This will be one of ConsentRequirementField.ALLOW, ConsentRequirementField.BLOCK, or None.

Return type:

unicode

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.

Parameters:

• consent_requirements (list of djblets.privacy.consent.base.ConsentRequirement) – The list of consent requirements.

• attrs (dict, optional) – HTML attributes for the widget. This is used only to set an id 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 (list of unicode) – The current values for the fields.

• attrs (dict, optional) – HTML attributes for the widget. This is used only to set a base id 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:

• data (dict) – The submitted form data.

• files (dict, unused) – The submitted files data.

• name (unicode) – The base name for the form fields.

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, or None.

Return type:

list of unicode

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.

Parameters:

value (list) – The list of values (or None) to normalize and return.

Returns:

The resulting list of values. This may be empty.

Return type:

list of unicode

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:

unicode

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:

djblets.privacy.consent.base.ConsentData

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 of djblets.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 of list djblets.privacy.consent.base.Consent) – The list of values to convert.

Returns:

A list of values suitable for use in the field.

Return type:

list of unicode

clean(value)¶

Clean and return values from submitted form data.

Parameters:

value (list of unicode) – A list of values submitted by the client.

Returns:

The list of cleaned consent data values.

Return type:

list of djblets.privacy.consent.base.ConsentData

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 of djblets.privacy.consent.base.ConsentData) – The list of cleaned data.

Returns:

The list of data.

Return type:

list of djblets.privacy.consent.base.ConsentData

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.

Parameters:

• *args (tuple) – Positional arguments passed to the form.

• **kwargs (dict) – Keyword arguments passed to 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:

django.contrib.auth.models.User

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:

unicode

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:

dict

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:

django.contrib.auth.models.User

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:

unicode