From 61393dcc36247f340d4d5ad1363bc5964c5a4438 Mon Sep 17 00:00:00 2001 From: James Bennett Date: Sun, 18 Jun 2023 01:12:21 -0700 Subject: [PATCH] More documentation cleanup. --- docs/activation-workflow.rst | 44 +++++++++---------- docs/custom-user.rst | 12 +++--- docs/faq.rst | 27 ++++-------- docs/forms.rst | 16 +++---- docs/one-step-workflow.rst | 12 +++--- docs/quickstart.rst | 82 ++++++++++++++++++------------------ docs/settings.rst | 6 +-- docs/signals.rst | 12 +++--- docs/upgrade.rst | 72 +++++++++++++++---------------- docs/validators.rst | 6 +-- docs/views.rst | 16 +++---- 11 files changed, 148 insertions(+), 157 deletions(-) diff --git a/docs/activation-workflow.rst b/docs/activation-workflow.rst index 2eb32b6..93e78fd 100644 --- a/docs/activation-workflow.rst +++ b/docs/activation-workflow.rst @@ -5,7 +5,7 @@ The two-step activation workflow ================================ The two-step activation workflow, found in -`django_registration.backends.activation`, implements a two-step registration +``django_registration.backends.activation``, implements a two-step registration process: a user signs up, an inactive account is created, and an email is sent containing an activation link which must be clicked to make the account active. @@ -15,8 +15,8 @@ Behavior and configuration A default URLconf is provided, which you can :func:`~django.urls.include` in your URL configuration; that URLconf is -`django_registration.backends.activation.urls`. For example, to place user -registration under the URL prefix `/accounts/`, you could place the following +``django_registration.backends.activation.urls``. For example, to place user +registration under the URL prefix ``/accounts/``, you could place the following in your root URLconf: .. code-block:: python @@ -30,7 +30,7 @@ in your root URLconf: # More URL patterns ... ] -That also sets up the views from `django.contrib.auth` (login, logout, password +That also sets up the views from ``django.contrib.auth`` (login, logout, password reset, etc.). This workflow makes use of up to three settings (click for details on each): @@ -45,7 +45,7 @@ This workflow makes use of up to three settings (click for details on each): By default, this workflow uses :class:`~django_registration.forms.RegistrationForm` as its form class for user registration; this can be overridden by passing the keyword argument -`form_class` to the registration view. +``form_class`` to the registration view. Views @@ -75,7 +75,7 @@ specified below), and their context variables, see :ref:`the quick start guide Creates and returns an inactive user account, and calls :meth:`send_activation_email()` to send the email with the activation - key. The argument `form` is a valid registration form instance passed + key. The argument ``form`` is a valid registration form instance passed from :meth:`~django_registration.views.RegistrationView.register()`. :param django_registration.forms.RegistrationForm form: The registration form. @@ -108,13 +108,13 @@ specified below), and their context variables, see :ref:`the quick start guide .. attribute:: email_body_template A string specifying the template to use for the body of the activation - email. Default is `"django_registration/activation_email_body.txt"`. + email. Default is ``"django_registration/activation_email_body.txt"``. .. attribute:: email_subject_template A string specifying the template to use for the subject of the activation email. Default is - `"django_registration/activation_email_subject.txt"`. Note that, to avoid + ``"django_registration/activation_email_subject.txt"``. Note that, to avoid `header-injection vulnerabilities `_, the result of rendering this template will be forced into a single line of text, @@ -127,19 +127,19 @@ specified below), and their context variables, see :ref:`the quick start guide Errors in activating the user account will raise :exc:`~django_registration.exceptions.ActivationError`, with one of the - following values for the exception's `code`: + following values for the exception's ``code``: - `"already_activated"` + ``"already_activated"`` Indicates the account has already been activated. - `"bad_username"` + ``"bad_username"`` Indicates the username decoded from the activation key is invalid (does not correspond to any user account). - `"expired"` + ``"expired"`` Indicates the account/activation key has expired. - `"invalid_key"` + ``"invalid_key"`` Generic indicator that the activation key was invalid. Important customization points unique to this class are: @@ -153,7 +153,7 @@ specified below), and their context variables, see :ref:`the quick start guide :attr:`~django.contrib.auth.models.User.is_active` field to avoid re-activating already-active accounts, and raises :exc:`~django_registration.exceptions.ActivationError` with code - `already_activated` to indicate this case. + ``already_activated`` to indicate this case. :param str username: The username of the new user account. :rtype: django.contrib.auth.models.AbstractUser @@ -164,7 +164,7 @@ specified below), and their context variables, see :ref:`the quick start guide Given the activation key, verifies that it carries a valid signature and a timestamp no older than the number of days specified in the setting - `ACCOUNT_ACTIVATION_DAYS`, and returns the username from the activation + ``ACCOUNT_ACTIVATION_DAYS``, and returns the username from the activation key. Raises :exc:`~django_registration.exceptions.ActivationError`, as described above, if the activation key has an invalid signature or if the timestamp is too old. @@ -183,21 +183,21 @@ specified below), and their context variables, see :ref:`the quick start guide URL) is produced by :func:`django.core.signing.dumps()`, which base64-encodes its output. Thus, the only characters this pattern needs to match are those from `the URL-safe base64 alphabet - `_, plus the colon ("`:`") + `_, plus the colon ("``:``") which is used as a separator. The default URL pattern for the activation view in - `django_registration.backends.activation.urls` handles this for you. + ``django_registration.backends.activation.urls`` handles this for you. How it works ------------ When a user signs up, the activation workflow creates a new user instance to -represent the account, and sets the `is_active` field to :data:`False`. It then +represent the account, and sets the ``is_active`` field to :data:`False`. It then sends an email to the address provided during signup, containing a link to activate the account. When the user clicks the link, the activation view sets -`is_active` to :data:`True`, after which the user can log in. +``is_active`` to :data:`True`, after which the user can log in. The activation key is the username of the new account, signed using `Django's cryptographic signing tools @@ -219,8 +219,8 @@ of the form:: encoded_username:timestamp:signature -where `encoded_username` is the username of the new account, `timestamp` is the -timestamp of the time the user registered, and `signature` is an HMAC of the +where ``encoded_username`` is the username of the new account, ``timestamp`` is the +timestamp of the time the user registered, and ``signature`` is an HMAC of the username and timestamp. The username and HMAC will be URL-safe base64 encoded; the timestamp will be base62 encoded. @@ -233,7 +233,7 @@ additionally, it permits the specification of a salt value which can be used to The activation workflow will use the value (a string) of the setting :data:`~django.conf.settings.REGISTRATION_SALT` as the salt, defaulting to the -string `"registration"` if that setting is not specified. This value does *not* +string ``"registration"`` if that setting is not specified. This value does *not* need to be kept secret (only :data:`~django.conf.settings.SECRET_KEY` does); it serves only to ensure that other parts of a site which also produce signed values from user input could not be used as a way to generate activation keys diff --git a/docs/custom-user.rst b/docs/custom-user.rst index 9c63245..93f77d2 100644 --- a/docs/custom-user.rst +++ b/docs/custom-user.rst @@ -77,7 +77,7 @@ automatically handled for you. If your custom user model defines additional fields beyond the minimum requirements, you'll either need to ensure that all of those fields are -optional (i.e., can be `NULL` in your database, or provide a suitable default +optional (i.e., can be ``NULL`` in your database, or provide a suitable default value defined in the model), or specify the correct list of fields to display in your :class:`~django_registration.forms.RegistrationForm` subclass. @@ -92,7 +92,7 @@ requirements on your user model: :attr:`~django.contrib.auth.models.CustomUser.USERNAME_FIELD` to indicate the field used as the username. -* It must define a textual field named `password` for storing the user's +* It must define a textual field named ``password`` for storing the user's password. Also note that the base :class:`~django_registration.forms.RegistrationForm` @@ -109,7 +109,7 @@ automatically handled for you. If your custom user model defines additional fields beyond the minimum requirements, you'll either need to ensure that all of those fields are -optional (i.e., can be `NULL` in your database, or provide a suitable default +optional (i.e., can be ``NULL`` in your database, or provide a suitable default value defined in the model), or specify the correct list of fields to display in your :class:`~django_registration.forms.RegistrationForm` subclass. @@ -119,7 +119,7 @@ creating it, you also must either use Django's backend `_, or use an authentication backend which accepts a combination of -`USERNAME_FIELD` and `password` as sufficient credentials to authenticate a +``USERNAME_FIELD`` and ``password`` as sufficient credentials to authenticate a user. @@ -148,7 +148,7 @@ django-registration, you will be able to subclass :class:`~django_registration.forms.RegistrationForm`, set it to use your custom user model as the model, and then configure the views in django-registration to use your form subclass. For example, you might do the following (in a -`forms.py` module somewhere in your codebase -- do **not** directly edit +``forms.py`` module somewhere in your codebase -- do **not** directly edit django-registration's code): .. code-block:: python @@ -203,7 +203,7 @@ One is to subclass the built-in form and view classes of django-registration and make the necessary adjustments to achieve compatibility with your user model. For example, if you want to use the two-step activation workflow, but your user model uses a completely different way of marking accounts -active/inactive (compared to the the assumed `is_active` field), you might +active/inactive (compared to the the assumed ``is_active`` field), you might write subclasses of that workflow's :class:`~django_registration.backends.activation.views.RegistrationView` and :class:`~django_registration.backends.activation.views.ActivationView` which diff --git a/docs/faq.rst b/docs/faq.rst index ab60df5..0a54403 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -31,7 +31,7 @@ By using `django-allauth `_. No single application can or should provide a universal API for every authentication system ever developed; django-registration sticks to making it easy to implement typical signup workflows using Django's default model-based -authentication system, while apps like `django-allauth` handle integration with +authentication system, while apps like ``django-allauth`` handle integration with third-party authentication services far more effectively. What license is django-registration under? @@ -41,7 +41,7 @@ django-registration is offered under a three-clause BSD-style license; this is `an OSI-approved open-source license `_, and allows you a large degree of freedom in modifying and redistributing the code. For the full terms, -see the file `LICENSE` which came with your copy of django-registration; if you +see the file ``LICENSE`` which came with your copy of django-registration; if you did not receive a copy of this file, you can view it online at . @@ -107,7 +107,7 @@ django-registration's tests are run using `nox `_, but typical installation of django-registration (via ``pip install django-registration``) will not install the tests. -To run the tests, download the source (`.tar.gz`) distribution of +To run the tests, download the source (``.tar.gz``) distribution of django-registration |release| from `its page on the Python Package Index `_, unpack it (``tar zxvf django-registration-|version|.tar.gz`` on most Unix-like operating systems), @@ -204,7 +204,7 @@ I don't want to write my own URLconf because I don't want to write patterns for ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You're in luck, then; Django provides a URLconf for this, at -`django.contrib.auth.urls`. +``django.contrib.auth.urls``. I don't like the names you've given to the URL patterns! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -228,8 +228,8 @@ If you haven't modified the behavior of the :meth:`~django_registration.views.RegistrationView.registration_allowed` method in :class:`~django_registration.views.RegistrationView`, you can use the setting :data:`~django.conf.settings.REGISTRATION_OPEN` to control this; when -the setting is `True`, or isn't supplied, user registration will be -permitted. When the setting is `False`, user registration will not be +the setting is :data:`True`, or isn't supplied, user registration will be +permitted. When the setting is :data:`False`, user registration will not be permitted. How do I log a user in immediately after registration or activation? @@ -242,24 +242,15 @@ How do I manually activate a user? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In :ref:`the two-step activation workflow `, toggle the -`is_active` field of the user in the admin. +``is_active`` field of the user in the admin. How do I delete expired unactivated accounts? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Perform a query for those accounts, and call the `delete()` method of the -resulting `QuerySet`. Since django-registration doesn't know in advance what +Perform a query for those accounts, and call the ``delete()`` method of the +resulting ``QuerySet``. Since django-registration doesn't know in advance what your definition of "expired" will be, it leaves this step to you. -How do I allow Unicode in usernames? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use Python 3. Django's username validation allows any word character plus some -additional characters, but the definition of "word character" depends on the -Python version in use. On Python 2, only ASCII will be permitted; on Python 3, -usernames containing word characters matched by a regex with the -:data:`re.UNICODE` flag will be accepted. - How do I tell why an account's activation failed? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/forms.rst b/docs/forms.rst index b875cda..0410fe2 100644 --- a/docs/forms.rst +++ b/docs/forms.rst @@ -17,16 +17,16 @@ situations. :class:`~django.contrib.auth.forms.UserCreationForm`, and has the following fields, all of which are required: - `username` + ``username`` The username to use for the new account. - `email` + ``email`` The email address to use for the new account. - `password1` + ``password1`` The password to use for the new account. - `password2` + ``password2`` The password to use for the new account, repeated to catch typos. .. note:: **Validation of usernames** @@ -34,7 +34,7 @@ situations. Django supplies a default regex-based validator for usernames in its base :class:`~django.contrib.auth.models.AbstractBaseUser` implementation, allowing any word character along with the following set of additional - characters: `.`, `@`, `+`, and `-`. + characters: ``.``, ``@``, ``+``, and ``-``. Because it's a subclass of Django's :class:`~django.contrib.auth.forms.UserCreationForm`, @@ -52,7 +52,7 @@ situations. The HTML5 validator uses `the HTML5 email-validation rule `_ - (as implemented on HTML's `input type="email"`), which is more + (as implemented on HTML's ``input type="email"``), which is more restrictive than the email RFCs. The purpose of this validator is twofold: to match the behavior of HTML5, and to simplify django-registration's other validators. The full RFC grammar for email @@ -82,7 +82,7 @@ situations. This form will normalize the username value to form NFKC, matching Django's default approach to Unicode normalization. it will then case fold - the value, and use a case-insensitive (`iexact`) lookup to determine if a + the value, and use a case-insensitive (``iexact``) lookup to determine if a user with the same username already exists; the results of this query may depend on the quality of your database's Unicode implementation, and on configuration details. The results may also be surprising to developers @@ -95,7 +95,7 @@ situations. A subclass of :class:`RegistrationForm` which adds one additional, required field: - `tos` + ``tos`` A checkbox indicating agreement to the site's terms of service/user agreement. diff --git a/docs/one-step-workflow.rst b/docs/one-step-workflow.rst index 8a0639e..8063fba 100644 --- a/docs/one-step-workflow.rst +++ b/docs/one-step-workflow.rst @@ -6,7 +6,7 @@ The one-step workflow As an alternative to :ref:`the two-step (registration and activation) workflow `, django-registration bundles a one-step registration -workflow in `django_registration.backends.one_step`. This workflow consists of +workflow in ``django_registration.backends.one_step``. This workflow consists of as few steps as possible: 1. A user signs up by filling out a registration form. @@ -21,7 +21,7 @@ Configuration ------------- To use this workflow, include the URLconf -`django_registration.backends.one_step.urls` somewhere in your site's own URL +``django_registration.backends.one_step.urls`` somewhere in your site's own URL configuration. For example: .. code-block:: python @@ -39,7 +39,7 @@ To control whether registration of new accounts is allowed, you can specify the setting :data:`~django.conf.settings.REGISTRATION_OPEN`. Upon successful registration, the user will be redirected to the site's home -page -- the URL `/`. This can be changed by subclassing +page -- the URL ``/``. This can be changed by subclassing :class:`django_registration.backends.one_step.views.RegistrationView` and overriding the method :meth:`~django_registration.views.RegistrationView.get_success_url` or setting @@ -66,7 +66,7 @@ do this in a URLconf. For example: The default form class used for account registration will be :class:`django_registration.forms.RegistrationForm`, although this can be overridden by supplying a custom URL pattern for the registration view and -passing the keyword argument `form_class`, or by subclassing +passing the keyword argument ``form_class``, or by subclassing :class:`django_registration.backends.one_step.views.RegistrationView` and either overriding :attr:`~django_registration.views.RegistrationView.form_class` or implementing @@ -79,8 +79,8 @@ Templates The one-step workflow uses two templates: -* `django_registration/registration_form.html`. -* `django_registration/registration_closed.html` +* ``django_registration/registration_form.html``. +* ``django_registration/registration_closed.html`` See :ref:`the quick start guide ` for details of these templates. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 6b85fe9..ef089b0 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -29,10 +29,10 @@ setting. .. important:: **Django's authentication system must be installed** Before proceeding with either of the recommended built-in workflows, you'll - need to ensure `django.contrib.auth` has been installed (by adding it to - :data:`~django.conf.settings.INSTALLED_APPS` and running `manage.py migrate` - to install needed database tables). Also, if you're making use of `a custom - user model + need to ensure ``django.contrib.auth`` has been installed (by adding it to + :data:`~django.conf.settings.INSTALLED_APPS` and running ``manage.py + migrate`` to install needed database tables). Also, if you're making use of + `a custom user model `_, you'll probably want to pause and read :ref:`the custom user compatibility guide ` before using django-registration. @@ -75,9 +75,9 @@ Setting up URLs Each bundled registration workflow in django-registration includes a Django URLconf which sets up URL patterns for :ref:`the views in django-registration `. The URLconf for the two-step activation workflow can be found at -`django_registration.backends.activation.urls`. For example, to place the -registration URLs under the prefix `/accounts/`, you could add the following to -your project's root URLconf: +``django_registration.backends.activation.urls``. For example, to place the +registration URLs under the prefix ``/accounts/``, you could add the following +to your project's root URLconf: .. code-block:: python @@ -90,26 +90,26 @@ your project's root URLconf: # More URL patterns ... ] -Users would then be able to register by visiting the URL `/accounts/register/`, -log in (once activated) at `/accounts/login/`, etc. +Users would then be able to register by visiting the URL +``/accounts/register/``, log in (once activated) at ``/accounts/login/``, etc. The sample URL configuration above also sets up the built-in auth views included in Django (login, logout, password reset, etc.) via the -`django.contrib.auth.urls` URLconf. +``django.contrib.auth.urls`` URLconf. The following URL names are defined by -`django_registration.backends.activation.urls`: +``django_registration.backends.activation.urls``: -* `django_registration_register` is the account-registration view. +* ``django_registration_register`` is the account-registration view. -* `django_registration_complete` is the post-registration success message. +* ``django_registration_complete`` is the post-registration success message. -* `django_registration_activate` is the account-activation view. +* ``django_registration_activate`` is the account-activation view. -* `django_registration_activation_complete` is the post-activation success +* ``django_registration_activation_complete`` is the post-activation success message. -* `django_registration_disallowed` is a message indicating registration is not +* ``django_registration_disallowed`` is a message indicating registration is not currently permitted. @@ -120,7 +120,7 @@ Required templates You will also need to create several templates required by django-registration, and possibly additional templates required by views in -`django.contrib.auth`. The templates required by django-registration are as +``django.contrib.auth``. The templates required by django-registration are as follows; note that, with the exception of the templates used for account activation emails, all of these are rendered using a :class:`~django.template.RequestContext` and so will also receive any @@ -136,7 +136,7 @@ additional variables provided by `context processors Used to show the form users will fill out to register. By default, has the following context: -`form` +``form`` The registration form. This will likely be a subclass of :class:`~django_registration.forms.RegistrationForm`; consult `Django's forms documentation @@ -164,7 +164,7 @@ context variables of its own. Used if account activation fails. Has the following context: -`activation_error` +``activation_error`` A :class:`dict` containing the information supplied to the :exc:`~django_registration.exceptions.ActivationError` which occurred during activation. See the documentation for that exception for a @@ -189,31 +189,31 @@ line of an email must be a single line of text, any output from this template will be forcibly condensed to a single line before being used. This template has the following context: -`activation_key` +``activation_key`` The activation key for the new account, as a string. -`expiration_days` +``expiration_days`` The number of days remaining during which the account may be activated, as an integer. -`request` +``request`` The :class:`~django.http.HttpRequest` object representing the request in which the user registered. -`scheme` +``scheme`` The protocol scheme used during registration, as a string; will be either - `'http'` or `'https'`. + ``'http'`` or ``'https'``. -`site` +``site`` An object representing the site on which the user registered; depending on - whether `django.contrib.sites` is installed, this may be an instance of + whether ``django.contrib.sites`` is installed, this may be an instance of either :class:`django.contrib.sites.models.Site` (if the sites application is installed) or :class:`django.contrib.sites.requests.RequestSite` (if not). Consult `the documentation for the Django sites framework `_ for details regarding these objects' interfaces. -`user` +``user`` The newly-created user object. @@ -224,22 +224,22 @@ Used to generate the body of the activation email. Should display a link the user can click to activate the account. This template has the following context: -`activation_key` +``activation_key`` The activation key for the new account, as a string. -`expiration_days` +``expiration_days`` The number of days remaining during which the account may be activated, as an integer. -`request` +``request`` The :class:`~django.http.HttpRequest` object representing the request in which the user registered. -`scheme` +``scheme`` The protocol scheme used during registration, as a string; will be either `'http'` or `'https'`. -`site` +``site`` An object representing the site on which the user registered; depending on whether `django.contrib.sites` is installed, this may be an instance of either :class:`django.contrib.sites.models.Site` (if the sites application @@ -248,16 +248,16 @@ context: `_ for details regarding these objects. -`user` +``user`` The newly-created user object. Note that the templates used to generate the account activation email use the -extension `.txt`, not `.html`. Due to widespread antipathy toward and +extension ``.txt``, not ``.html``. Due to widespread antipathy toward and interoperability problems with HTML email, django-registration produces plain-text email, and so these templates should output plain text rather than HTML. -To make use of the views from `django.contrib.auth` (which are set up for you +To make use of the views from ``django.contrib.auth`` (which are set up for you by the example URL configuration above), you will also need to create the templates required by those views. Consult `the documentation for Django's authentication system `_ @@ -287,16 +287,16 @@ your URL structure: # More URL patterns ... ] -Users could then register accounts by visiting the URL `/accounts/register/`. +Users could then register accounts by visiting the URL ``/accounts/register/``. The following URL names are defined by -`django_registration.backends.one_step.urls`: +``django_registration.backends.one_step.urls``: -* `django_registration_register` is the account-registration view. +* ``django_registration_register`` is the account-registration view. -* `django_registration_complete` is the post-registration success message. +* ``django_registration_complete`` is the post-registration success message. -* `django_registration_disallowed` is a message indicating registration is not +* ``django_registration_disallowed`` is a message indicating registration is not currently permitted. This URLconf will also configure the appropriate URLs for the rest of the @@ -311,7 +311,7 @@ Finally, you will need to create following templates: See :ref:`the documentation above ` for details of these templates. -To make use of the views from `django.contrib.auth` (which are set up for you +To make use of the views from ``django.contrib.auth`` (which are set up for you by the example URL configuration above), you will also need to create the templates required by those views. Consult `the documentation for Django's authentication system `_ diff --git a/docs/settings.rst b/docs/settings.rst index a3c5b7e..aaa8775 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -26,9 +26,9 @@ workflows of django-registration make use of several custom settings. A :class:`bool` indicating whether registration of new accounts is currently permitted. - A default of `True` is assumed when this setting is not supplied, so + A default of :data:`True` is assumed when this setting is not supplied, so specifying it is optional unless you want to temporarily close registration - (in which case, set it to `False`). + (in which case, set it to :data:`False`). Used by: @@ -48,7 +48,7 @@ workflows of django-registration make use of several custom settings. A :class:`str` used as an additional "salt" in the process of generating signed activation keys. - This setting is optional, and a default of `"registration"` will be used if + This setting is optional, and a default of ``"registration"`` will be used if not specified. The value of this setting does not need to be kept secret; see :ref:`the note about this salt value and security ` for details. diff --git a/docs/signals.rst b/docs/signals.rst index c008434..73e8890 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -27,14 +27,14 @@ and connecting functions which will listen for signals. Sent when a user account is activated (not applicable to all workflows). Provides the following arguments: - `sender` + ``sender`` The :class:`~django_registration.views.ActivationView` subclass used to activate the user. - `user` + ``user`` A user-model instance representing the activated account. - `request` + ``request`` The :class:`~django.http.HttpRequest` in which the account was activated. @@ -49,14 +49,14 @@ and connecting functions which will listen for signals. Sent when a new user account is registered. Provides the following arguments: - `sender` + ``sender`` The :class:`~django_registration.views.RegistrationView` subclass used to register the account. - `user` + ``user`` A user-model instance representing the new account. - `request` + ``request`` The :class:`~django.http.HttpRequest` in which the new account was registered. diff --git a/docs/upgrade.rst b/docs/upgrade.rst index a7fc52c..25d648c 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -118,13 +118,13 @@ Module renaming ~~~~~~~~~~~~~~~ Prior to 3.x, django-registration installed a Python module named -`registration`. To avoid silent incompatibilities, and to conform to more +``registration``. To avoid silent incompatibilities, and to conform to more recent best practices, django-registration 3.x now installs a module named -`django_registration`. Attempts to import from the `registration` module will +``django_registration``. Attempts to import from the ``registration`` module will immediately fail with :exc:`ImportError`. Many installations will be able to adapt by replacing references to -`registration` with references to `django_registration`. +``registration`` with references to ``django_registration``. Removal of model-based workflow @@ -141,16 +141,16 @@ Renaming of two-step activation workflow ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :ref:`The two-step activation workflow ` was previously -found at `registration.backends.hmac`; it has been renamed and is now found at -`registration.backends.activation`. +found at ``registration.backends.hmac``; it has been renamed and is now found at +``registration.backends.activation``. Renaming of one-step workflow ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :ref:`The one-step workflow ` was previously found at -`registration.backends.simple`; it has been renamed and is now found at -`registration.backends.one_step`. +``registration.backends.simple``; it has been renamed and is now found at +``registration.backends.one_step``. Removal of auth URLs @@ -163,7 +163,7 @@ Django's auth views to be class-based, as it required detecting the set of auth views and choosing a set of URL patterns at runtime. As a result, auth views are no longer automatically configured for you; if you -want them, :func:`~django.urls.include` the URLconf `django.contrib.auth.urls` +want them, :func:`~django.urls.include` the URLconf ``django.contrib.auth.urls`` at a location of your choosing. @@ -171,15 +171,15 @@ Distinguishing activation failure conditions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Prior to 3.x, failures to activate a user account (in workflows which use -activation) all simply returned `None` in place of the activated account. This -meant it was not possible to determine, from inspecting the result, what -exactly caused the failure. +activation) all simply returned :data:`None` in place of the activated +account. This meant it was not possible to determine, from inspecting the +result, what exactly caused the failure. In django-registration 3.x, activation failures raise an exception -- :exc:`~django_registration.exceptions.ActivationError` -- with a message and -code (such as `"expired"`), to indicate the cause of failure. This exception is +code (such as ``"expired"``), to indicate the cause of failure. This exception is caught by :class:`~django_registration.views.ActivationView` and turned into -the template context variable `activation_error`. +the template context variable ``activation_error``. Changes to custom user support @@ -195,7 +195,7 @@ models should now provide, in addition to methods. See :ref:`the custom user documentation ` for details. -Changes to `success_url` +Changes to ``success_url`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ Both the registration and activation views mimic Django's own generic views in @@ -217,12 +217,12 @@ arguments. Also, earlier versions of django-registration allowed :attr:`~django_registration.views.RegistrationView.success_url` and :meth:`~django_registration.views.RegistrationView.get_success_url` to provide -either a string URL, or a tuple of `(viewname, args, kwargs)` to pass to +either a string URL, or a tuple of ``(viewname, args, kwargs)`` to pass to Django's :func:`~django.urls.reverse` helper, in order to work around issues caused by calling :func:`~django.urls.reverse` at the level of a class attribute. -In django-registration 3.x, the `user` argument to +In django-registration 3.x, the ``user`` argument to :meth:`~django_registration.views.RegistrationView.get_success_url` is now optional, meaning :class:`~django.views.generic.edit.FormMixin`'s default behavior is now compatible with any @@ -230,8 +230,8 @@ behavior is now compatible with any implementation that doesn't require the user object; as a result, implementations which don't rely on the user object should either switch to specifying :attr:`~django_registration.views.RegistrationView.success_url` as -an attribute, or change their own signature to `get_success_url(self, -user=None)`. +an attribute, or change their own signature to ``get_success_url(self, +user=None)``. Also, the ability to supply the 3-tuple of arguments for :func:`~django.urls.reverse` has been removed; both @@ -239,14 +239,14 @@ Also, the ability to supply the 3-tuple of arguments for :meth:`~django_registration.views.RegistrationView.get_success_url` now *must* be/return either a string, or a lazy object that resolves to a string. To avoid class-level calls to :func:`~django.urls.reverse`, use -`django.urls.reverse_lazy()` instead. +``django.urls.reverse_lazy()`` instead. Removed "no free email" form ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Earlier versions of django-registration included a form class, -`RegistrationFormNoFreeEmail`, which attempted to forbid user signups using +``RegistrationFormNoFreeEmail``, which attempted to forbid user signups using common free/throwaway email providers. Since this is a pointless task (the number of possible domains of such providers is ever-growing), this form class has been removed. @@ -255,32 +255,32 @@ has been removed. Template names ~~~~~~~~~~~~~~ -Since django-registration's Python module has been renamed from `registration` -to `django_registration`, its default template folder has also been renamed, -from `registration` to `django_registration`. Additionally, the following +Since django-registration's Python module has been renamed from ``registration`` +to ``django_registration``, its default template folder has also been renamed, +from ``registration`` to ``django_registration``. Additionally, the following templates have undergone name changes: * The default template name for the body of the activation email in the two-step activation workflow is now - `django_registration/activation_email_body.txt` (previously, it was - `registration/activation_email.txt`) + ``django_registration/activation_email_body.txt`` (previously, it was + ``registration/activation_email.txt``) * The default template name for :class:`~django_registration.views.ActivationView` and its subclasses is now - `django_registration/activation_failed.html` (previously, it was - `registration/activate.html`). + ``django_registration/activation_failed.html`` (previously, it was + ``registration/activate.html``). Renaming of URL patterns ~~~~~~~~~~~~~~~~~~~~~~~~ Prior to 3.x, django-registration's included URLconf modules provided URL -pattern names beginning with `"registration"`. For example: -`"registration_register"`. In 3.x, these are all renamed to begin with -`"django_registration"`. For example: `"django_registration_register"`. +pattern names beginning with ``"registration"``. For example: +``"registration_register"``. In 3.x, these are all renamed to begin with +``"django_registration"``. For example: ``"django_registration_register"``. -Removal of `cleanupregistration` management command -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Removal of ``cleanupregistration`` management command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The "cleanupregistration" management command, and the RegistrationProfile.objects.delete_expired_users() and @@ -292,10 +292,10 @@ own methods for this. Other changes ~~~~~~~~~~~~~ -The URLconf `registration.urls` has been removed; it was an alias for the +The URLconf ``registration.urls`` has been removed; it was an alias for the URLconf of the model-based workflow, which has also been removed. -The compatibility alias `registration.backends.default`, which also pointed to +The compatibility alias ``registration.backends.default``, which also pointed to the model-based workflow, has been removed. @@ -315,9 +315,9 @@ usernames. If you need to allow users to register with usernames forbidden by this validator, see its documentation for notes on how to customize or disable it. -In 2.2, the behavior of the `RegistrationProfile.expired()` method was +In 2.2, the behavior of the ``RegistrationProfile.expired()`` method was clarified to accommodate user expectations; it does *not* return (and thus, -`RegistrationProfile.delete_expired_users()` does not delete) profiles of users +``RegistrationProfile.delete_expired_users()`` does not delete) profiles of users who had successfully activated. In django-registration 2.3, the new validators diff --git a/docs/validators.rst b/docs/validators.rst index 84142e4..8b59d43 100644 --- a/docs/validators.rst +++ b/docs/validators.rst @@ -70,16 +70,16 @@ By default, django-registration treats some usernames as reserved. subclasses. This validator is attached to the list of validators for the username field, so to remove it (not recommended), subclass :class:`~django_registration.forms.RegistrationForm` and override - `__init__()` to change the set of validators on the username field. + ``__init__()`` to change the set of validators on the username field. If you want to supply your own custom list of reserved names, you can subclass :class:`~django_registration.forms.RegistrationForm` and set the - attribute `reserved_names` to the list of values you want to disallow. + attribute ``reserved_names`` to the list of values you want to disallow. The default list of reserved names, if you don't specify one, is :data:`~django_registration.validators.DEFAULT_RESERVED_NAMES`. The validator will also reject any value beginning with the string - `".well-known"` (see `RFC 5785 `_). + ``".well-known"`` (see `RFC 5785 `_). :param list reserved_names: A list of reserved names to forbid. :raises django.core.exceptions.ValidationError: if the provided diff --git a/docs/views.rst b/docs/views.rst index fdb51c1..62a84bd 100644 --- a/docs/views.rst +++ b/docs/views.rst @@ -31,7 +31,7 @@ your own custom registration workflows. .. method:: register(form) - Implement your registration logic here. `form` will be the + Implement your registration logic here. ``form`` will be the (already-validated) form filled out by the user during the registration process (i.e., a valid instance of :class:`~django_registration.forms.RegistrationForm` or a subclass of @@ -54,7 +54,7 @@ your own custom registration workflows. :func:`~django.urls.reverse` helper, or the lazy object produced by Django's :func:`~django.urls.reverse_lazy` helper. Default value is the result of calling :func:`~django.urls.reverse_lazy` with the URL name - `'registration_disallowed'`. + ``'registration_disallowed'``. .. attribute:: form_class @@ -69,13 +69,13 @@ your own custom registration workflows. string, the string resulting from calling Django's :func:`~django.urls.reverse` helper, or the lazy object produced by Django's :func:`~django.urls.reverse_lazy` helper. Can be overridden on a - per-request basis (see below). Default value is `None`; subclasses must - override and provide this. + per-request basis (see below). Default value is :data:`None`; subclasses + must override and provide this. .. attribute:: template_name The template to use for user registration. Should be a string. Default - value is `'django_registration/registration_form.html'`. + value is ``'django_registration/registration_form.html'``. .. method:: get_form_class() @@ -134,13 +134,13 @@ your own custom registration workflows. string, the string resulting from calling Django's :func:`~django.urls.reverse` helper, or the lazy object produced by Django's :func:`~django.urls.reverse_lazy` helper. Can be overridden on a - per-request basis (see below). Default value is `None`; subclasses must - override and provide this. + per-request basis (see below). Default value is :data:`None`; subclasses + must override and provide this. .. attribute:: template_name The template to use after failed user activation. Should be a - string. Default value is `'django_registration/activation_failed.html'`. + string. Default value is ``'django_registration/activation_failed.html'``. .. method:: get_success_url(user)