From 997b63d6b69828ee6c82b226b7891e877a1507ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aur=C3=A9lien=20Delobelle?= <aurelien.delobelle@gmail.com>
Date: Fri, 1 Sep 2017 13:35:32 +0200
Subject: [PATCH] More docs for kfet.tests.utils

---
 kfet/tests/utils.py | 82 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/kfet/tests/utils.py b/kfet/tests/utils.py
index 4681da67..30eb05ad 100644
--- a/kfet/tests/utils.py
+++ b/kfet/tests/utils.py
@@ -8,6 +8,21 @@ User = get_user_model()
 
 
 def _create_user_and_account(user_attrs, account_attrs, perms=None):
+    """
+    Create a user and its account, and assign permissions to this user.
+
+    Arguments
+        user_attrs (dict): User data (first name, last name, password...).
+        account_attrs (dict): Account data (department, kfet password...).
+        perms (list of str: 'app.perm'): These permissions will be assigned to
+            the created user. No permission are assigned by default.
+
+    If 'password' is not given in 'user_attrs', username is used as password.
+
+    If 'kfet.is_team' is in 'perms' and 'password' is not in 'account_attrs',
+    the account password is 'kfetpwd_<user pwd>'.
+
+    """
     user_pwd = user_attrs.pop('password', user_attrs['username'])
     user = User.objects.create(**user_attrs)
     user.set_password(user_pwd)
@@ -29,6 +44,27 @@ def _create_user_and_account(user_attrs, account_attrs, perms=None):
 
 
 def create_user(username='user', trigramme='000', **kwargs):
+    """
+    Create a user without any permission and its kfet account.
+
+    username and trigramme are accepted as arguments (defaults to 'user' and
+    '000').
+
+    user_attrs, account_attrs and perms can be given as keyword arguments to
+    customize the user and its kfet account.
+
+    # Default values
+
+    User
+        * username: user
+        * password: user
+        * first_name: first
+        * last_name: last
+        * email: mail@user.net
+    Account
+        * trigramme: 000
+
+    """
     user_attrs = kwargs.setdefault('user_attrs', {})
 
     user_attrs.setdefault('username', username)
@@ -43,6 +79,28 @@ def create_user(username='user', trigramme='000', **kwargs):
 
 
 def create_team(username='team', trigramme='100', **kwargs):
+    """
+    Create a user, member of the kfet team, and its kfet account.
+
+    username and trigramme are accepted as arguments (defaults to 'team' and
+    '100').
+
+    user_attrs, account_attrs and perms can be given as keyword arguments to
+    customize the user and its kfet account.
+
+    # Default values
+
+    User
+        * username: team
+        * password: team
+        * first_name: team
+        * last_name: member
+        * email: mail@team.net
+    Account
+        * trigramme: 100
+        * kfet password: kfetpwd_team
+
+    """
     user_attrs = kwargs.setdefault('user_attrs', {})
 
     user_attrs.setdefault('username', username)
@@ -60,6 +118,29 @@ def create_team(username='team', trigramme='100', **kwargs):
 
 
 def create_root(username='root', trigramme='200', **kwargs):
+    """
+    Create a superuser and its kfet account.
+
+    username and trigramme are accepted as arguments (defaults to 'root' and
+    '200').
+
+    user_attrs, account_attrs and perms can be given as keyword arguments to
+    customize the user and its kfet account.
+
+    # Default values
+
+    User
+        * username: root
+        * password: root
+        * first_name: super
+        * last_name: user
+        * email: mail@root.net
+        * is_staff, is_superuser: True
+    Account
+        * trigramme: 200
+        * kfet password: kfetpwd_root
+
+    """
     user_attrs = kwargs.setdefault('user_attrs', {})
 
     user_attrs.setdefault('username', username)
@@ -75,6 +156,7 @@ def create_root(username='root', trigramme='200', **kwargs):
 
 
 def get_perms(*labels):
+    """Return Permission instances from a list of '<app>.<perm_codename>'."""
     perms = {}
     for label in set(labels):
         app_label, codename = label.split('.', 1)