feat(user): Add custom user and admin #207 (#230)

* Django admin is missing some useful security features, e.g. read-only
  on critical fields.
* A custom user model that extends the existing user model will allow some
  additional flexibility to customise the user.
* Added django project custom user test suite and fixtures.
* Added a custom user how-to.
* Updated django-cookiecutter test suite.
* Updated tutorial-create-django-project.
* Updated README

closes #207
closes #212

README.rst

@@ -38,25 +38,38 @@ delivery using GitHub actions.
    :target: https://python-semantic-release.readthedocs.io/en/latest/
    :alt: Python Sementic Release
 
+Django Project Features
+-----------------------
+
+#. Easy for new users to learn Django with sensible defaults.  Also, `local`
+   and `test` environments default to using `SQLite`_, Django's bundled
+   database.
+#. More advanced users can change the test environment database with an
+   environment variable to match the production environment.
+#. `Django-allauth`_ provides authentication.
+#. A `CustomUser` model, complete with tests and custom user types. See
+   `How-to Custom User`_ for customisation options before your initial migration.
+#. Improved  Admin panel security requires an authorised user to be logged in.
+   The Admin panel now has the protections provided by django-allauth.
+
+.. _Django-allauth: https://django-allauth.readthedocs.io/en/latest/installation.html
+.. _SQLite: https://www.sqlite.org/index.html
+.. _How-to Custom User: <https://django-cookiecutter.readthedocs.io/en/latest/how-tos/how-to-custom-user.html>
+
+
 Django Project Creation Options
 -------------------------------
 
+Customise your project with the following options when creating your
+django-cookiecutter.
+
 Django Settings
 ~~~~~~~~~~~~~~~
 
 #. Quickly configure common `Django settings`_ as you setup your project.
 
 .. _Django settings: https://docs.djangoproject.com/en/3.2/ref/settings/
 
-
-Django Options
-~~~~~~~~~~~~~~
-
-#. Choose to use `Django-allauth`_ for authentication.
-
-.. _Django-allauth: https://django-allauth.readthedocs.io/en/latest/installation.html
-
-
 Docker
 ~~~~~~
 
@@ -68,10 +81,10 @@ Docker
 Documentation
 ~~~~~~~~~~~~~
 
-#. Choose to add documentation using Sphinx with:
+#. Add documentation using Sphinx with:
 
    #. `Furo`_, a clean modern theme,  with dark and light mode options.
-   #. A `Copy Button`_ to assist your users copy.
+   #. A `Copy Button`_ to assist your users copy text or code snippets.
    #. `Inline Tabs`_ to group similar items.
    #. Use markdown or restructured text.
 #. Deploy to `Read the Docs`_.
@@ -118,7 +131,7 @@ Contributions are very welcome and appreciated!
 
 You can contribute in many ways.
 
-See `How-To Contribute <https://django-cookiecutter.readthedocs.io/en/
+See `How-to Contribute <https://django-cookiecutter.readthedocs.io/en/
 latest/how-tos/how-to-contribute.html>`_ to help you get started.
 
 Please take a moment to read our `Code of Conduct

cookiecutter.json

@@ -18,10 +18,6 @@
     "False"
   ],
   "SITE_ID": "1",
-  "use_django_allauth": [
-    "y",
-    "n"
-  ],
   "deploy_with_docker": [
     "n",
     "y",

docs/source/how-tos/how-to-custom-user.rst

@@ -0,0 +1,80 @@
+.. include:: /extras.rst.txt
+.. highlight:: rst
+.. index:: cust-user-how-to ; Index
+
+.. _cust-user-how-to:
+===========
+Custom User
+===========
+
+By default, a Custom User employs django-allauth.
+
+The Custom User comes with custom user types.
+
+The CustomUser types have Admin panel filters and are sortable in the
+Users view.
+
+All Django Admin security and features remain intact.
+
+
+Options Before Initial Migration
+--------------------------------
+
+CustomUser types can be left as is, or if you wish to change the user types
+to meet your needs, change the values in Users/models.py
+
+
+.. code-block:: python
+    :caption: Customise these user types.
+
+    class CustomUser(AbstractUser):
+
+        class CustomUserType(models.TextChoices):
+            """Custom user type choices"""
+
+            # Change these to suit your needs before initial migration.
+            FREE = "FREE", _("Free")
+            LEVEL_1 = "LEVEL 1", _("Level 1")
+            LEVEL_2 = "LEVEL 2", _("Level 2")
+            STAFF = "STAFF", _("Staff")
+            SUPERUSER = "SUPERUSER", _("Superuser")
+
+
+Accessing Admin Panel
+---------------------
+
+Additional security with your Custom User comes by default.
+
+You can only access your new Django project Admin after a successful login.
+
+Placing the Admin panel behind the django-allauth login gives Admin all the
+protections of django-allauth.
+
+If this behaviour does not suit your workflow, you can disable this feature by
+commenting out the line `admin.site.login`.
+
+.. code-block:: python
+    :caption: Users/admin.py
+
+    # Require login before Admin panel is available.  Removes the opportunity for
+    # a brute force attack on Admin Login. Provided by django-allauth.
+    # https://django-allauth.readthedocs.io/en/latest/advanced.html
+    # Comment the following line to disable django-allauth protection
+    admin.site.login = login_required(admin.site.login)
+
+
+Adding a New User
+-----------------
+
+When creating a new user with the django-allauth Sign-up form, the Custom User
+model is used.
+
+.. note::
+
+    **Adding a new user via the Admin panel**
+
+    The email should be entered under the Accounts menu when creating a new
+    user in the Admin panel.
+
+    Entering the email in this manner will ensure the email will be available to
+    django-allauth.  A search button will help locate the correct user.

docs/source/how-tos/index-how-to.rst

@@ -15,5 +15,6 @@ See below for a list of How-To for Django Cookiecutter.
    :titlesonly:
 
    how-to-quickstart
+   how-to-custom-user
    how-to-docker-linux-cheatsheet
    how-to-contribute

docs/source/tutorials/new-django-project-options.txt

@@ -17,10 +17,6 @@ Select USE_I18N:
 2 - False
 Choose from 1, 2 [1]:
 SITE_ID [1]:
-Select use_django_allauth:
-1 - y
-2 - n
-Choose from 1, 2 [1]:
 Select deploy_with_docker:
 1 - n
 2 - y

docs/source/tutorials/tutorial-create-django-project.rst

@@ -4,9 +4,9 @@
 
 .. _cookie-create-pkg:
 ============================
-Create a Django Cookiecutter
-============================
+Create a Django Cookiecutterrk
 
+============================
 
 |
 
@@ -59,14 +59,14 @@ Select the tab for your preferred Operating System.
     Python version in your Operating System.
 
     If you prefer another python version installed on your computer, you can
-    replace `python3` with `python3.n`, where n is the version number.
+    replace `python3.8` with `python3.n`, where n is the version number.
 
 .. tab:: Linux
 
     .. code-block:: bash
         :caption: **bash/zsh**
 
-        python3 -m venv my_venv
+        python3.8 -m venv my_venv
 
     You will have a folder structure similar to this.
 
@@ -82,7 +82,7 @@ Select the tab for your preferred Operating System.
     .. code-block:: bash
         :caption: **bash/zsh**
 
-        python3 -m venv my_venv
+        python3.8 -m venv my_venv
 
     You will have a folder structure similar to this.
 
@@ -98,14 +98,14 @@ Select the tab for your preferred Operating System.
     .. code-block:: bash
         :caption: **cmd/PowerShell**
 
-        python3 -m venv my_venv
+        python3.8 -m venv my_venv
 
     Otherwise use
 
     .. code-block:: bash
         :caption: **cmd/PowerShell**
 
-        c:\>c:\Python36\python -m venv c:\path\to\projects\my_env
+        c:\>c:\Python38\python -m venv c:\path\to\projects\my_env
 
     You will have a folder structure similar to this.
 
@@ -317,10 +317,6 @@ An Example Django Project
       2 - False
       Choose from 1, 2 [1]:
       SITE_ID [1]:
-      Select use_django_allauth:
-      1 - y
-      2 - n
-      Choose from 1, 2 [1]:
       Select deploy_with_docker:
       1 - n
       2 - y
@@ -451,6 +447,15 @@ will look something similar to this.
     │   │   ├── asgi.py
     │   │   ├── urls.py
     │   │   └── wsgi.py
+    │   ├── users
+    │   │   ├── __init__.py
+    │   │   ├── admin.py
+    │   │   ├── apps.py
+    │   │   ├── forms.py
+    │   │   ├── migrations
+    │   │   │   └── __init__.py
+    │   │   ├── models.py
+    │   │   └── views.py
     │   ├── pytest.ini
     │   ├── requirements_dev.txt
     │   └── templates
@@ -582,6 +587,21 @@ You will see something similar to this in your CLI.
 
 .. include:: tutorial-segment-create-env-variable.rst
 
+Before Initial Migration
+------------------------
+
+.. important::
+
+    You may wish to make some changes to the Custom User model
+    before making your initial migration.
+
+For example, you can change the default user types to suit your application.
+
+See `How-to Custom User`_ for customisation options before your initial migration.
+
+.. _How-to Custom User: <https://django-cookiecutter.readthedocs.io/en/latest/how-tos/how-to-custom-user.html>
+
+
 Final Project Setup
 -------------------
 
@@ -675,6 +695,86 @@ You will see something similar to this in your CLI.
    Bypass password validation and create user anyway? [y/N]: y
    Superuser created successfully.
 
+
+Run the Tests
+-------------
+
+Your project comes complete with a test suite for the custom user.
+
+Tox, the test runner is configured to test locally with Python
+3.8, 3.9 and 3.10.
+
+See the following commands for options.
+
+.. code-block:: bash
+    :caption: Test against all python versions.
+
+    tox
+
+.. code-block:: bash
+    :caption: Test against a single python version.
+
+    tox -e py38
+
+    or
+
+    tox -e py39
+
+    or
+
+    tox -e py3.10
+
+You will see something similar to this in your CLI.
+
+.. code-block:: bash
+
+    platform linux -- Python 3.8.10, pytest-6.2.5, py-1.11.0, pluggy-1.0.0 -- /projects/my-new-django/.tox/py38/bin/python
+    cachedir: .tox/py38/.pytest_cache
+    django: settings: config.settings.test (from ini)
+    rootdir: /projects/my-new-django, configfile: pytest.ini
+    plugins: reverse-1.3.0, forked-1.4.0, xdist-2.5.0, django-4.5.2
+    [gw0] linux Python 3.8.10 cwd: /projects/my-new-django
+    [gw1] linux Python 3.8.10 cwd: /projects/my-new-django
+    [gw0] Python 3.8.10 (default, Nov 26 2021, 20:14:08)  -- [GCC 9.3.0]
+    [gw1] Python 3.8.10 (default, Nov 26 2021, 20:14:08)  -- [GCC 9.3.0]
+    gw0 [6] / gw1 [6]
+    scheduling tests via LoadScopeScheduling
+
+    tests/test_custom_user.py::test_create_superuser_errors_raised_ok
+    [gw0] [ 16%] PASSED tests/test_custom_user.py::test_create_superuser_errors_raised_ok
+    tests/test_custom_user.py::test_create_superuser_ok
+    [gw0] [ 33%] PASSED tests/test_custom_user.py::test_create_superuser_ok
+    tests/test_custom_user.py::test_create_user_errors_raised_ok
+    [gw0] [ 50%] PASSED tests/test_custom_user.py::test_create_user_errors_raised_ok
+    tests/test_custom_user.py::test_create_user_is_superuser_ok
+    [gw0] [ 66%] PASSED tests/test_custom_user.py::test_create_user_is_superuser_ok
+    tests/test_custom_user.py::test_create_user_is_staff_ok
+    [gw0] [ 83%] PASSED tests/test_custom_user.py::test_create_user_is_staff_ok
+    tests/test_custom_user.py::test_create_user_ok
+    [gw0] [100%] PASSED tests/test_custom_user.py::test_create_user_ok
+
+    ================================= PASSES ==================================
+    _________________ test_create_superuser_errors_raised_ok___________________
+    [gw0] linux -- Python 3.8.10 projects/my-new-django/.tox/py38/bin/python
+    -------------------------- Captured stderr setup --------------------------
+    Creating test database for alias 'default'...
+    ------------------------ Captured stderr teardown -------------------------
+    Destroying test database for alias 'default'...
+    ============================ 6 passed in 1.19s ============================
+    _________________________________ summary _________________________________
+      py38: commands succeeded
+      congratulations :)
+
+
+Run Your Project
+----------------
+
+Django comes with a development server. This server provides all the features
+needed to view your Django project locally; however, it is not suitable for a
+production environment.
+
+To view your project in the browser, type the following command.
+
 .. code-block:: bash
 
     python3 manage.py runserver  # In your browser 127.0.0.1/admin

hooks/post_gen_project.py

@@ -53,8 +53,6 @@
         compose {% endif %}',
     '{% if cookiecutter.deploy_with_docker == "n" %} \
         docker-entrypoint.sh {% endif %}',
-    '{% if cookiecutter.use_django_allauth == "n" %} \
-        templates/account {% endif %}',
 ]
 
 # Helper functions