From 35cbce7bd150692da848ca5767537c55ce372de3 Mon Sep 17 00:00:00 2001 From: Kevin Etienne Date: Thu, 19 Mar 2015 16:57:22 +0000 Subject: [PATCH 1/6] Add docstrings for API views. Help reading the code and will be displayed in the browsable api from rest-framework. --- user_management/api/views.py | 63 +++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/user_management/api/views.py b/user_management/api/views.py index 9c8bf3d..23708bd 100644 --- a/user_management/api/views.py +++ b/user_management/api/views.py @@ -15,6 +15,15 @@ class GetAuthToken(ObtainAuthToken): + """ + Authentication by token. + + Define `POST` (create) method to authenticate a user from its `email` and + `password` and return a `token` if successful. + The `token` would be valid for a value defined in `settings.AUTH_TOKEN_MAX_AGE`. + + `DELETE` method remove the current `token` from the database. + """ model = models.AuthToken throttle_classes = [ throttling.UsernameLoginRateThrottle, @@ -59,6 +68,11 @@ def delete(self, request, *args, **kwargs): class UserRegister(generics.CreateAPIView): + """ + User registration. + + Register a user and send an email to validate the new account. + """ serializer_class = serializers.RegistrationSerializer permission_classes = [permissions.IsNotAuthenticated] @@ -95,6 +109,12 @@ def is_valid(self, serializer): class PasswordResetEmail(generics.GenericAPIView): + """ + Password reset request. + + Accept an `email` and send an email to reset a password if the user is found. + If the user is not found no error is raised. + """ permission_classes = [permissions.IsNotAuthenticated] template_name = 'user_management/password_reset_email.html' serializer_class = serializers.PasswordResetEmailSerializer @@ -122,6 +142,11 @@ def post(self, request, *args, **kwargs): class OneTimeUseAPIMixin(object): + """ + Check `uid` and `token`. + + Set user as a class attribute or raise an `InvalidExpiredToken`. + """ def initial(self, request, *args, **kwargs): uidb64 = kwargs['uidb64'] uid = urlsafe_base64_decode(force_text(uidb64)) @@ -143,6 +168,12 @@ def initial(self, request, *args, **kwargs): class PasswordReset(OneTimeUseAPIMixin, generics.UpdateAPIView): + """ + Password reset verification and update. + + `GET` and `UPDATE` view to check an user with the given `uid` and `token` + and allow to send a new password. + """ permission_classes = [permissions.IsNotAuthenticated] model = User serializer_class = serializers.PasswordResetSerializer @@ -152,6 +183,12 @@ def get_object(self): class PasswordChange(generics.UpdateAPIView): + """ + Password update. + + Give ability to `PUT` (update) a password when authenticated by submitting current + password. + """ model = User permission_classes = (IsAuthenticated,) serializer_class = serializers.PasswordChangeSerializer @@ -161,6 +198,11 @@ def get_object(self): class VerifyAccountView(OneTimeUseAPIMixin, views.APIView): + """ + Verify account. + + Verify a newly created account by checking the `uid` and `token` in a `POST` request. + """ permission_classes = [AllowAny] ok_message = _('Your account has been verified.') @@ -179,6 +221,11 @@ def post(self, request, *args, **kwargs): class ProfileDetail(generics.RetrieveUpdateDestroyAPIView): + """ + User profile. + + `GET`, `UPDATE` and `DELETE` current logged-in user. + """ model = User permission_classes = (IsAuthenticated,) serializer_class = serializers.ProfileSerializer @@ -188,19 +235,33 @@ def get_object(self): class UserList(generics.ListCreateAPIView): + """ + User list and create view. + + Allow to `GET` a list users and to `POST` new user for admin user only. + """ model = User permission_classes = (IsAuthenticated, permissions.IsAdminOrReadOnly) serializer_class = serializers.UserSerializerCreate class UserDetail(generics.RetrieveUpdateDestroyAPIView): + """ + User detail view. + + `GET`, `UPDATE` or `DESTROY` a specific user. + """ model = User permission_classes = (IsAuthenticated, permissions.IsAdminOrReadOnly) serializer_class = serializers.UserSerializer class ResendConfirmationEmail(generics.GenericAPIView): - """Resend a confirmation email.""" + """Resend a confirmation email. + + `POST` request to resend a confirmation email for existing user. Useful when + the token has expired. + """ permission_classes = [permissions.IsNotAuthenticated] serializer_class = serializers.ResendConfirmationEmailSerializer throttle_classes = [throttling.ResendConfirmationEmailRateThrottle] From 234bdb7cd96c7fbb266af94b9549a89cf78d8ca6 Mon Sep 17 00:00:00 2001 From: Kevin Etienne Date: Thu, 19 Mar 2015 17:11:48 +0000 Subject: [PATCH 2/6] Update docstrings --- user_management/api/views.py | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/user_management/api/views.py b/user_management/api/views.py index 23708bd..3f02f35 100644 --- a/user_management/api/views.py +++ b/user_management/api/views.py @@ -169,10 +169,15 @@ def initial(self, request, *args, **kwargs): class PasswordReset(OneTimeUseAPIMixin, generics.UpdateAPIView): """ - Password reset verification and update. + Password reset update view. - `GET` and `UPDATE` view to check an user with the given `uid` and `token` - and allow to send a new password. + This view is generally called when a user has followed an email link to + reset a password. + + This view will check first if the `uid` and `token` are valid. + + `PasswordReset` is called with an `UPDATE` containing the new password + (`new_password` and `new_password2`). """ permission_classes = [permissions.IsNotAuthenticated] model = User @@ -184,7 +189,7 @@ def get_object(self): class PasswordChange(generics.UpdateAPIView): """ - Password update. + Password update view. Give ability to `PUT` (update) a password when authenticated by submitting current password. @@ -199,7 +204,7 @@ def get_object(self): class VerifyAccountView(OneTimeUseAPIMixin, views.APIView): """ - Verify account. + Verify account view. Verify a newly created account by checking the `uid` and `token` in a `POST` request. """ @@ -222,7 +227,7 @@ def post(self, request, *args, **kwargs): class ProfileDetail(generics.RetrieveUpdateDestroyAPIView): """ - User profile. + User profile detail view. `GET`, `UPDATE` and `DELETE` current logged-in user. """ From fc7f96f1c83471617dc5c9d3f93e0e9c0fcd97a7 Mon Sep 17 00:00:00 2001 From: Kevin Etienne Date: Tue, 24 Mar 2015 11:15:02 +0000 Subject: [PATCH 3/6] Update docstrings --- user_management/api/views.py | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/user_management/api/views.py b/user_management/api/views.py index 3f02f35..4d99aac 100644 --- a/user_management/api/views.py +++ b/user_management/api/views.py @@ -16,13 +16,14 @@ class GetAuthToken(ObtainAuthToken): """ - Authentication by token. + Obtain an authentication token. - Define `POST` (create) method to authenticate a user from its `email` and + Define a `POST` (create) method to authenticate a user from useing their `email` and `password` and return a `token` if successful. - The `token` would be valid for a value defined in `settings.AUTH_TOKEN_MAX_AGE`. + The `token` remains valid until `settings.AUTH_TOKEN_MAX_AGE` time has passed. - `DELETE` method remove the current `token` from the database. + + `DELETE` method removes the current `token` from the database. """ model = models.AuthToken throttle_classes = [ @@ -69,7 +70,7 @@ def delete(self, request, *args, **kwargs): class UserRegister(generics.CreateAPIView): """ - User registration. + Register a new `User`. Register a user and send an email to validate the new account. """ @@ -110,9 +111,9 @@ def is_valid(self, serializer): class PasswordResetEmail(generics.GenericAPIView): """ - Password reset request. + Send a password reset email to a user on request. - Accept an `email` and send an email to reset a password if the user is found. + A user can request a password request email by providing their email address. If the user is not found no error is raised. """ permission_classes = [permissions.IsNotAuthenticated] @@ -143,7 +144,8 @@ def post(self, request, *args, **kwargs): class OneTimeUseAPIMixin(object): """ - Check `uid` and `token`. + Use a `uid` and a `token` to allow one-time access to a view. + Set user as a class attribute or raise an `InvalidExpiredToken`. """ @@ -169,7 +171,7 @@ def initial(self, request, *args, **kwargs): class PasswordReset(OneTimeUseAPIMixin, generics.UpdateAPIView): """ - Password reset update view. + Reset a user's password. This view is generally called when a user has followed an email link to reset a password. @@ -189,7 +191,7 @@ def get_object(self): class PasswordChange(generics.UpdateAPIView): """ - Password update view. + Change a user's password. Give ability to `PUT` (update) a password when authenticated by submitting current password. @@ -204,7 +206,7 @@ def get_object(self): class VerifyAccountView(OneTimeUseAPIMixin, views.APIView): """ - Verify account view. + Verify a new user's email address. Verify a newly created account by checking the `uid` and `token` in a `POST` request. """ @@ -227,7 +229,7 @@ def post(self, request, *args, **kwargs): class ProfileDetail(generics.RetrieveUpdateDestroyAPIView): """ - User profile detail view. + Allow a user to view and edit their profile information. `GET`, `UPDATE` and `DELETE` current logged-in user. """ @@ -241,7 +243,7 @@ def get_object(self): class UserList(generics.ListCreateAPIView): """ - User list and create view. + Return information about all users and allow creation of new users. Allow to `GET` a list users and to `POST` new user for admin user only. """ @@ -252,9 +254,9 @@ class UserList(generics.ListCreateAPIView): class UserDetail(generics.RetrieveUpdateDestroyAPIView): """ - User detail view. + Display information about a user. - `GET`, `UPDATE` or `DESTROY` a specific user. + Allow admin users to update or delete user information. """ model = User permission_classes = (IsAuthenticated, permissions.IsAdminOrReadOnly) From a47aa5b96fbbaff17531b2dd9515bd59a05e971a Mon Sep 17 00:00:00 2001 From: Kevin Etienne Date: Tue, 24 Mar 2015 11:20:19 +0000 Subject: [PATCH 4/6] Add detail about `email_verification_required` in `UserRegister` --- user_management/api/views.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/user_management/api/views.py b/user_management/api/views.py index 4d99aac..6bd2811 100644 --- a/user_management/api/views.py +++ b/user_management/api/views.py @@ -72,7 +72,8 @@ class UserRegister(generics.CreateAPIView): """ Register a new `User`. - Register a user and send an email to validate the new account. + An email to validate the new account is sent if `email_verification_required` + is set to `True`. """ serializer_class = serializers.RegistrationSerializer permission_classes = [permissions.IsNotAuthenticated] From a09fea48bf5be8bcdd148d929a3a228cb41132a7 Mon Sep 17 00:00:00 2001 From: Kevin Etienne Date: Tue, 24 Mar 2015 11:53:10 +0000 Subject: [PATCH 5/6] Remove extra blank lines [ci skip] --- user_management/api/views.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/user_management/api/views.py b/user_management/api/views.py index 6bd2811..e72cf7f 100644 --- a/user_management/api/views.py +++ b/user_management/api/views.py @@ -22,7 +22,6 @@ class GetAuthToken(ObtainAuthToken): `password` and return a `token` if successful. The `token` remains valid until `settings.AUTH_TOKEN_MAX_AGE` time has passed. - `DELETE` method removes the current `token` from the database. """ model = models.AuthToken @@ -147,7 +146,6 @@ class OneTimeUseAPIMixin(object): """ Use a `uid` and a `token` to allow one-time access to a view. - Set user as a class attribute or raise an `InvalidExpiredToken`. """ def initial(self, request, *args, **kwargs): From 00b3d09845f4e7ea98bb46f05ca989332a9c4d1d Mon Sep 17 00:00:00 2001 From: Kevin Etienne Date: Tue, 24 Mar 2015 12:09:46 +0000 Subject: [PATCH 6/6] Start multilines comment with a new line [ci skip] --- user_management/api/views.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/user_management/api/views.py b/user_management/api/views.py index e72cf7f..281c422 100644 --- a/user_management/api/views.py +++ b/user_management/api/views.py @@ -263,7 +263,8 @@ class UserDetail(generics.RetrieveUpdateDestroyAPIView): class ResendConfirmationEmail(generics.GenericAPIView): - """Resend a confirmation email. + """ + Resend a confirmation email. `POST` request to resend a confirmation email for existing user. Useful when the token has expired.