django-pfx 1.4.dev28__tar.gz → 1.4.dev36__tar.gz

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/.gitlab-ci.yml

@@ -23,20 +23,29 @@ stages:
   - build
   - package
 
+quality check:
+  variables:
+    DJANGO_VERSION: 'django==4.2.*'  # LTS
+  script:
+    - apt-get update
+    - apt-get install -y gettext
+    - flake8 .
+    - isort . -c
+    - ./make_messages
+    - git diff --exit-code  # exit if messages changed
+    - python manage.py makemigrations --check --dry-run --setting='pfx.settings.dev'
+
 test:
   variables:
     POSTGRES_DB: ci
     POSTGRES_USER: postgres
     POSTGRES_PASSWORD: postgres
-    TEST_SETTINGS_MODULE: 'tests.settings.ci'
+    DJANGO_SETTINGS_MODULE: 'tests.settings.ci'
   script:
     - apt-get update
     - apt-get install -y gettext
-    - flake8 .
-    - isort . -c
-    - django-admin compilemessages --ignore venv
-    - export DJANGO_SETTINGS_MODULE=$TEST_SETTINGS_MODULE
-    - coverage run --source='.' runtest.py
+    - python manage.py compilemessages -i venv
+    - coverage run --source='.' manage.py test
     - coverage report
     - coverage xml
     - coverage html
@@ -86,6 +95,10 @@ pages:
     - master
 
 package:
+  stage: package
+  needs:
+    - job: quality check
+    - job: test
   rules:
     - if: $CI_COMMIT_TAG =~ /^\d+\.\d+$/
       when: on_success
@@ -97,6 +110,6 @@ package:
     - git fetch --prune --unshallow
     - pip install --upgrade twine
     - pip install -r requirements.txt
-    - (cd pfx/pfxcore/ && django-admin compilemessages)
+    - ./manage.py compilemessages -i venv -i tests
     - python3 -m build
     - TWINE_PASSWORD=${PYPI_DEPLOY_TOKEN} TWINE_USERNAME=__token__ python3 -m twine upload dist/*

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev28
+Version: 1.4.dev36
 Summary: Django PFX is a toolkit designed to streamline the development of RESTful APIs using the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/django_pfx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev28
+Version: 1.4.dev36
 Summary: Django PFX is a toolkit designed to streamline the development of RESTful APIs using the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/django_pfx.egg-info/SOURCES.txt

@@ -4,10 +4,10 @@
 LICENSE
 MANIFEST.in
 README.md
-django-admin-test
+make_messages
+manage.py
 pyproject.toml
 requirements.txt
-runtest.py
 serve-doc
 setup.cfg
 setup.py
@@ -60,6 +60,8 @@ pfx/pfxcore/middleware/__init__.py
 pfx/pfxcore/middleware/authentication.py
 pfx/pfxcore/middleware/locale.py
 pfx/pfxcore/middleware/profiling.py
+pfx/pfxcore/migrations/0001_initial.py
+pfx/pfxcore/migrations/__init__.py
 pfx/pfxcore/models/__init__.py
 pfx/pfxcore/models/abstract_pfx_base_user.py
 pfx/pfxcore/models/cache_mixins.py
@@ -67,6 +69,7 @@ pfx/pfxcore/models/login_ban.py
 pfx/pfxcore/models/not_null_fields.py
 pfx/pfxcore/models/otp_user_mixin.py
 pfx/pfxcore/models/pfx_models.py
+pfx/pfxcore/models/pfx_user.py
 pfx/pfxcore/models/user_filtered_queryset_mixin.py
 pfx/pfxcore/serializers/__init__.py
 pfx/pfxcore/serializers/json.py
@@ -102,6 +105,8 @@ pfx/pfxcore/views/parameters/subset_offset.py
 pfx/pfxcore/views/parameters/subset_page.py
 pfx/pfxcore/views/parameters/subset_page_size.py
 pfx/pfxcore/views/parameters/subset_page_subset.py
+pfx/settings/__init__.py
+pfx/settings/dev.py
 tests/__init__.py
 tests/models.py
 tests/urls.py

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/django_pfx.egg-info/top_level.txt

@@ -1,3 +1,4 @@
 dist
 doc
+htmlcov
 pfx

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/doc/source/api.views.rst

@@ -32,6 +32,18 @@ API Reference
     :undoc-members:
     :show-inheritance:
 
+.. autoclass:: pfx.pfxcore.models.AbstractPFXBaseUser
+    :members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.models.OtpUserMixin
+    :members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.models.PFXUser
+    :members:
+    :show-inheritance:
+
 ``pfx.pfxcore.views``
 *********************
 
@@ -43,12 +55,17 @@ Base services
     :undoc-members:
     :show-inheritance:
 
+.. autoclass:: pfx.pfxcore.views.SignupView
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 .. autoclass:: pfx.pfxcore.views.ForgottenPasswordView
     :members:
     :undoc-members:
     :show-inheritance:
 
-.. autoclass:: pfx.pfxcore.views.SignupView
+.. autoclass:: pfx.pfxcore.views.OtpEmailView
     :members:
     :undoc-members:
     :show-inheritance:

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/doc/source/authentication.md

@@ -1,20 +1,21 @@
 # Authentication
 
 Django PFX offers services and middlewares for managing user authentication in your API.
-These services replicate some of the functionalities provided by the `django.contrib.auth`
+These services replicate some of the functionalities provided by the {mod}`django.contrib.auth`
 package but in the form of RESTful services.
 They utilize the same user model and authentication backend features,
 including password validation and hashing.
 
 ## User Model
 
-You have the option to use the standard `django.contrib.auth.models.User`,
+You have the option to use the standard Django User with {class}`pfx.pfxcore.models.PFXUser`
+(which is a {class}`django.contrib.auth.models.User` with PFX required mixins),
 but you may prefer to use your own model. To do this, create your own user class.
 
 ```python
-from django.contrib.auth.models import AbstractUser
+from pfx.pfxcore.models import AbstractPFXBaseUser
 
-class MyUser(AbstractUser):
+class MyUser(AbstractPFXBaseUser):
     pass
 ```
 
@@ -28,8 +29,8 @@ AUTH_USER_MODEL = "myapp.MyUser"
 
 There are two authentication modes available: cookie and bearer token. You can activate either or both by enabling the following middlewares:
 
-* `'pfx.pfxcore.middleware.AuthenticationMiddleware'` (bearer token)
-* `'pfx.pfxcore.middleware.CookieAuthenticationMiddleware'` (cookie)
+* {class}`pfx.pfxcore.middleware.AuthenticationMiddleware` (bearer token)
+* {class}`pfx.pfxcore.middleware.CookieAuthenticationMiddleware` (cookie)
 
 ### Token Validity
 
@@ -40,7 +41,7 @@ You can customize token validity by configuring these parameters:
 
 ### Cookie Settings
 
-To use the `CookieAuthenticationMiddleware`, you need to configure the following settings:
+To use the {class}`pfx.pfxcore.middleware.CookieAuthenticationMiddleware`, you need to configure the following settings:
 
 * `PFX_COOKIE_DOMAIN`: The cookie domain
 * `PFX_COOKIE_SECURE`: `Secure` attribute of the cookie (`True`/`False`)
@@ -48,28 +49,55 @@ To use the `CookieAuthenticationMiddleware`, you need to configure the following
 
 See the [MDN Website](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) for more details.
 
+### Temporary bans
+
+Users will be temporarily banned after several unsuccessful login attempts.
+
+In the event of a temporary ban, login services will respond with the HTTP code `429` and
+the `Retry-After` header.
+
+#### Settings
+
+* `PFX_LOGIN_BAN_FAILED_NUMBER`: The number of failed login attempts before banning. To deactivate the ban completely, set `0` (optional, default `5`).
+* `PFX_LOGIN_BAN_SECONDS_START`: The number of seconds for the first ban (optional, default `60`).
+* `PFX_LOGIN_BAN_SECONDS_STEP`: The number of seconds to be added to the previous ban for consecutive bans (optional, default `60`).
+
 ### Multifactor Authentication
 Multifactor authentication can be enabled in django-pfx Authentication API.
 
 PFX currently provides MFA with One Time Password (OTP), compatible with FreeOTP,
 Google Authenticator and other OTP app.
 
-To enable this feature, install django-pfx with otp
+To enable this feature, install django-pfx with otp.
 
 ```bash
 pip install django-pfx[otp]
 ```
 
-Then the user class must use the ```OtpUserMixin```
+Then the user class must use the {class}`pfx.pfxcore.models.OtpUserMixin`.
 
 ```python
-from django.contrib.auth.models import AbstractUser
-from pfx.pfxcore.models import OtpUserMixin
+from pfx.pfxcore.models import PFXUser, OtpUserMixin
 
-class MyUser(OtpUserMixin, AbstractUser):
+class MyUser(OtpUserMixin, PFXUser):
     pass
 ```
 
+or
+
+```python
+from pfx.pfxcore.models import AbstractPFXBaseUser, OtpUserMixin
+
+class MyUser(OtpUserMixin, AbstractPFXBaseUser):
+    pass
+```
+
+#### Settings
+
+* `PFX_TOKEN_OTP_VALIDITY`: Validity for OTP tokens (corresponds to the maximum time to enter
+  an OTP code after logging in with a password) (optional, default `{'minutes': 15}`)
+* `PFX_HOTP_CODE_VALIDITY`: Validity of HOTP codes in minutes (used to send code by email) (optional, default `15`).
+
 The user can then enable or disable the OTP auth using the [services documented below](#enable-mfa-otp).
 
 ## Services
@@ -263,7 +291,7 @@ like so: `https://example.com/reset-password?token={token}&uidb64={uidb64}`.
 Your reset page should then call the "set password" service with these two parameters.
 
 You can override this class if you need to customize the email templates.
-Refer to the [API doc](api.views.rst#pfx.pfxcore.views.ForgottenPasswordView) for more details.
+Refer to {class}`pfx.pfxcore.views.ForgottenPasswordView` for more details.
 
 **Request :** `POST` `/auth/forgotten-password`
 
@@ -288,7 +316,7 @@ like so: `https://example.com/reset-password?token={token}&uidb64={uidb64}`.
 Your reset page should then call the "set password" service with these two parameters.
 
 You can override this class if you need to customize the user or email templates.
-Refer to the [API doc](api.views.rst#pfx.pfxcore.views.SignupView) for more details.
+Refer to {class}`pfx.pfxcore.views.SignupView` for more details.
 
 **Request :** `POST` `/auth/signup`
 

django-pfx-1.4.dev36/make_messages

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+(cd pfx/pfxcore && django-admin makemessages -a)
+(cd tests/tests && django-admin makemessages -a)

django-pfx-1.4.dev36/manage.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+"""Django's command-line utility for administrative tasks."""
+import logging
+import os
+import sys
+
+from django.db.migrations import writer
+
+if len(sys.argv) > 1 and sys.argv[1] == 'test':
+    logging.disable(logging.WARNING)
+
+
+writer.MIGRATION_HEADER_TEMPLATE = """\
+# Generated by Django %(version)s on %(timestamp)s
+# flake8: noqa
+
+"""
+
+def main():
+    """Run administrative tasks."""
+    cmd = len(sys.argv) > 1 and sys.argv[1]
+    os.environ.setdefault(
+        "DJANGO_SETTINGS_MODULE",
+        cmd == 'test' and "tests.settings.dev" or "pfx.settings.dev")
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError as exc:
+        raise ImportError(
+            "Couldn't import Django. Are you sure it's installed and "
+            "available on your PYTHONPATH environment variable? Did you "
+            "forget to activate a virtual environment?"
+        ) from exc
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == '__main__':
+    main()

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/pfx/pfxcore/locale/fr/LC_MESSAGES/django.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-04-08 13:51+0200\n"
+"POT-Creation-Date: 2024-04-11 11:40+0200\n"
 "PO-Revision-Date: 2021-06-22 23:31+0200\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -18,7 +18,7 @@ msgstr ""
 "Plural-Forms: nplurals=2; plural=(n > 1);\n"
 "X-Generator: Poedit 2.3\n"
 
-#: decorator/rest.py:43
+#: decorator/rest.py:41
 msgid "An internal server error occured."
 msgstr "Une erreur interne du serveur est survenue."
 
@@ -59,39 +59,39 @@ msgstr ""
 "Format non valide, il peut s’agir d’un nombre en heures, « 1:05 », « :05 », "
 "« 1h 5m », « 1.5h » ou « 30m »."
 
-#: models/login_ban.py:45
+#: models/login_ban.py:43
 msgid "Username"
 msgstr "Nom d’utilisateur"
 
-#: models/login_ban.py:46
+#: models/login_ban.py:44
 msgid "Failed counter"
 msgstr "Compteur d’échec"
 
-#: models/login_ban.py:47
+#: models/login_ban.py:45
 msgid "Last failed"
 msgstr "Dernier échec"
 
-#: models/login_ban.py:52
+#: models/login_ban.py:50
 msgid "Login ban"
 msgstr "Login banni"
 
-#: models/login_ban.py:53
+#: models/login_ban.py:51
 msgid "Login bans"
 msgstr "Login bannis"
 
-#: models/otp_user_mixin.py:10
+#: models/otp_user_mixin.py:15
 msgid "OTP secret token"
 msgstr "Jeton secret OTP"
 
-#: models/otp_user_mixin.py:13
+#: models/otp_user_mixin.py:19
 msgid "Temporary OTP secret token"
 msgstr "Jeton secret OTP temporaire"
 
-#: models/otp_user_mixin.py:14
+#: models/otp_user_mixin.py:21
 msgid "HOTP count"
 msgstr "Compte HOTP"
 
-#: models/otp_user_mixin.py:15
+#: models/otp_user_mixin.py:23
 msgid "HOTP expiry"
 msgstr "Expiration HOTP"
 
@@ -100,22 +100,22 @@ msgstr "Expiration HOTP"
 msgid "%(model_name)s with this %(field_labels)s already exists."
 msgstr "%(model_name)s avec ce/cette %(field_labels)s éxiste déjà."
 
-#: shortcuts.py:52
+#: shortcuts.py:50
 #, python-brace-format
 msgid "{key} must be an integer number."
 msgstr "{key} doit être un nombre entier."
 
-#: shortcuts.py:68
+#: shortcuts.py:66
 #, python-brace-format
 msgid "{key} must be a number."
 msgstr "{key} doit être un nombre."
 
-#: shortcuts.py:84
+#: shortcuts.py:82
 #, python-brace-format
 msgid "{key} must be a date."
 msgstr "{key} doit être une date."
 
-#: shortcuts.py:105
+#: shortcuts.py:103
 #, python-brace-format
 msgid "{key} must be “true”, “false”, “1”, “0” or empty."
 msgstr "{key} doit être « true », « false », « 1 », « 0 » ou vide"
@@ -152,6 +152,7 @@ msgid "The %(site_name)s team"
 msgstr "L'équipe de %(site_name)s"
 
 #: templates/registration/otp_code_subject.txt:2
+#, python-format
 msgid "New authentication code for %(site_name)s"
 msgstr "Nouveau code d’authentication pour %(site_name)s"
 
@@ -191,7 +192,7 @@ msgstr "Bienvenue sur %(site_name)s."
 msgid "Welcome on %(site_name)s"
 msgstr "Bienvenue sur %(site_name)s"
 
-#: views/authentication_views.py:82
+#: views/authentication_views.py:81
 #, python-brace-format
 msgid ""
 "Your connection is temporarily disabled after several unsuccessful attempts, "
@@ -200,43 +201,43 @@ msgstr ""
 "Votre connexion est temporairement désactivée après plusieurs tentatives "
 "infructueuses, veuillez réessayer dans {seconds} secondes."
 
-#: views/authentication_views.py:244 views/authentication_views.py:407
+#: views/authentication_views.py:243 views/authentication_views.py:404
 msgid "password updated successfully"
 msgstr "le mot de passe a été mis à jour avec succès"
 
-#: views/authentication_views.py:249
+#: views/authentication_views.py:248
 msgid "Incorrect password"
 msgstr "Mot de passe incorrect"
 
-#: views/authentication_views.py:252 views/authentication_views.py:416
+#: views/authentication_views.py:251 views/authentication_views.py:413
 msgid "Empty password is not allowed"
 msgstr "Un mot de passe vide n’est pas autorisé"
 
-#: views/authentication_views.py:341
+#: views/authentication_views.py:338
 msgid "User and token are valid"
 msgstr "L'utilisateur et le token sont valides"
 
-#: views/authentication_views.py:343
+#: views/authentication_views.py:340
 msgid "User or token is invalid"
 msgstr "L'utilisateur ou le token est invalide"
 
-#: views/authentication_views.py:449
+#: views/authentication_views.py:446
 msgid "OTP is already activated"
 msgstr "L'OTP est déjà activé"
 
-#: views/authentication_views.py:487
+#: views/authentication_views.py:484
 msgid "OTP is activated"
 msgstr "L'OTP est activé"
 
-#: views/authentication_views.py:488 views/authentication_views.py:522
+#: views/authentication_views.py:485 views/authentication_views.py:519
 msgid "Invalid OTP code"
 msgstr "Code OTP invalide"
 
-#: views/authentication_views.py:521
+#: views/authentication_views.py:518
 msgid "OTP is disabled"
 msgstr "L'OTP est désactivé"
 
-#: views/authentication_views.py:777
+#: views/authentication_views.py:778
 msgid ""
 "If the email address you entered is correct, you will receive an email from "
 "us with instructions to reset your password."
@@ -245,7 +246,7 @@ msgstr ""
 "un courrier électronique de notre part contenant des instructions pour "
 "réinitialiser votre mot de passe."
 
-#: views/authentication_views.py:845
+#: views/authentication_views.py:852
 msgid "A new authentication code has been sent by email."
 msgstr "Un nouveau code d'authentification a été envoyé par e-mail."
 

django-pfx-1.4.dev36/pfx/pfxcore/migrations/0001_initial.py

@@ -0,0 +1,59 @@
+# Generated by Django 4.2.11 on 2024-04-11 04:19
+# flake8: noqa
+
+import django.contrib.auth.models
+import django.contrib.auth.validators
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('auth', '0012_alter_user_first_name_max_length'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='LoginBan',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('username', models.CharField(max_length=150, unique=True, verbose_name='Username')),
+                ('failed_counter', models.IntegerField(verbose_name='Failed counter')),
+                ('last_failed', models.DateTimeField(auto_now=True, verbose_name='Last failed')),
+            ],
+            options={
+                'verbose_name': 'Login ban',
+                'verbose_name_plural': 'Login bans',
+            },
+        ),
+        migrations.CreateModel(
+            name='PFXUser',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('password', models.CharField(max_length=128, verbose_name='password')),
+                ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
+                ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+                ('username', models.CharField(error_messages={'unique': 'A user with that username already exists.'}, help_text='Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.', max_length=150, unique=True, validators=[django.contrib.auth.validators.UnicodeUsernameValidator()], verbose_name='username')),
+                ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')),
+                ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')),
+                ('email', models.EmailField(blank=True, max_length=254, verbose_name='email address')),
+                ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff status')),
+                ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')),
+                ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')),
+                ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
+                ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
+            ],
+            options={
+                'verbose_name': 'user',
+                'verbose_name_plural': 'users',
+                'abstract': False,
+                'swappable': 'AUTH_USER_MODEL',
+            },
+            managers=[
+                ('objects', django.contrib.auth.models.UserManager()),
+            ],
+        ),
+    ]

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/pfx/pfxcore/models/__init__.py

@@ -13,4 +13,5 @@ from .pfx_models import (
     PFXModelMixin,
     UniqueConstraint,
 )
+from .pfx_user import PFXUser
 from .user_filtered_queryset_mixin import UserFilteredQuerySetMixin

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/pfx/pfxcore/models/abstract_pfx_base_user.py

@@ -2,6 +2,8 @@ from django.contrib.auth.models import AbstractBaseUser
 
 
 class AbstractPFXBaseUser(AbstractBaseUser):
+    """The base abstract user for PFX."""
+
     class Meta:
         abstract = True
 
@@ -10,6 +12,7 @@ class AbstractPFXBaseUser(AbstractBaseUser):
         Return a user secret to sign JWT token.
 
         If not empty, the JWT token validity depends on all values
-        user to build the return string.
+        user to build the return string. So, each time the returned value
+        changes, the previously issued tokens will no longer be valid.
         """
         return self.password

{django-pfx-1.4.dev28 → django-pfx-1.4.dev36}/pfx/pfxcore/models/otp_user_mixin.py

@@ -8,23 +8,42 @@ from pfx.pfxcore.settings import settings
 
 
 class OtpUserMixin(models.Model):
+    """A mixin to enable OTP MFA on a user class."""
+
+    #: OTP secret token.
     otp_secret_token = models.CharField(
         _("OTP secret token"), max_length=32, null=True,
         blank=True, unique=True)
+    #: Temporary OTP secret token (needs confirmation).
     otp_secret_token_tmp = models.CharField(
         _("Temporary OTP secret token"), max_length=32, null=True, blank=True)
+    #: HOTP count.
     hotp_count = models.IntegerField(_("HOTP count"), default=0)
+    #: HOTP expiry.
     hotp_expiry = models.DateTimeField(_("HOTP expiry"), default=timezone.now)
 
     class Meta:
         abstract = True
 
     def enable_otp(self):
+        """Activate OTP for this user.
+
+        Generates a new temporary OTP secret token. To complete activation,
+        call `confirm_otp` with a valid code.
+        """
         import pyotp
         self.otp_secret_token_tmp = pyotp.random_base32()
         self.save(update_fields=['otp_secret_token_tmp'])
 
     def confirm_otp(self, otp_code):
+        """Confirm OTP activation for this user.
+
+        Set the OTP secret token from the temporary one if the provided
+        code is valid.
+
+        :param otp_code: A valid OTP code for the temporary OTP secret key.
+        :returns: `True` if success, `False` otherwise.
+        """
         if self.is_otp_valid(otp_code, tmp=True):
             self.otp_secret_token = self.otp_secret_token_tmp
             self.otp_secret_token_tmp = None
@@ -34,10 +53,16 @@ class OtpUserMixin(models.Model):
         return False
 
     def disable_otp(self):
+        """Disable OTP for this user.
+
+        Remove the OTP secret token.
+        """
         self.otp_secret_token = None
         self.save(update_fields=['otp_secret_token'])
 
     def get_otp_setup_uri(self, tmp=False):
+        """Return the setup URL for OTP activation.
+        """
         import pyotp
         return pyotp.totp.TOTP(
             tmp and self.otp_secret_token_tmp or
@@ -45,6 +70,13 @@ class OtpUserMixin(models.Model):
                 name=self.email, issuer_name=settings.PFX_SITE_NAME)
 
     def is_otp_valid(self, otp_code, tmp=False):
+        """Verify an OTP code.
+
+        :param otp_code: A valid OTP code for the OTP secret key.
+        :param tmp: If `True`, verify the code with the temporary
+            OTP secret key.
+        :returns: `True` if the code is valid, `False` otherwise.
+        """
         import pyotp
         totp = pyotp.parse_uri(self.get_otp_setup_uri(tmp=tmp))
         valid = totp.verify(otp_code)
@@ -56,10 +88,17 @@ class OtpUserMixin(models.Model):
         return valid
 
     def get_user_jwt_signature_key(self):
+        """Return a user secret to sign JWT token.
+
+        If the user inherit :class:`pfx.pfxcore.models.AbstractPFXBaseUser`,
+        add the OTP secret token to the user signature."""
         return super().get_user_jwt_signature_key() + (
             self.otp_secret_token or "")
 
     def get_hotp_code(self):
+        """Return a new valid HOTP code.
+
+        Increment the HOTP counter and reset the expiry."""
         import pyotp
         if not self.otp_secret_token:
             raise Exception("OTP disabled")