Merge branch 'master' into drf3

.travis.yml

@@ -9,6 +9,13 @@ env:
     - TOX_ENV=py33-django17
     - TOX_ENV=py34-django16
     - TOX_ENV=py34-django17
+    - TOX_ENV=py27-djangopre
+    - TOX_ENV=py34-djangopre
+matrix:
+  fast_finish: true
+  allow_failures:
+    - env: TOX_ENV=py27-djangopre
+    - env: TOX_ENV=py34-djangopre
 install:
   - psql -c 'CREATE DATABASE user_management' -U postgres;
   - pip install tox coveralls
@@ -18,3 +25,12 @@ after_success:
   coveralls
 notifications:
   email: false
+deploy:
+  provider: pypi
+  user: incuna
+  on:
+    condition: $TOX_ENV=py34-django17
+    tags: true
+  password:
+    secure: DBkb54BXJe8FZ9Zp91VWOgDE3UjQ3ZHwPXJxLuSZWoUrluHbyE7ANdD3mbS+M97Ux7kfxRHpl1lSxZUe2ppMdl4Sl4hm5iVvdZkTc1ErmeJTDExMnK9E+4FDFj4UXTtGYQ1atTtE2cR8Dpbf0j3MchjiKBROOytNEUbYQfGnxEU=
+  distributions: "sdist bdist_wheel"

CHANGELOG.md

@@ -1,3 +1,11 @@
+## v8.0.1
+
+* Fix translation for notifications.
+
+## v8.0.0
+
+* Use `incuna-pigeon` for notifications.
+
 ## v7.0.1
 
 * Fix `UserChangeForm` admin form `fields` to only include fields used in `UserAdmin.fieldsets`.
@@ -9,7 +17,7 @@
 ### Notes
 
 * When an object is referencing the user model with a foreign key it is possible
-to define the bahavior with `on_delete`.
+to define the behavior with `on_delete`.
 
 see https://docs.djangoproject.com/en/1.7/ref/models/fields/#django.db.models.ForeignKey.on_delete
 

Makefile

@@ -2,13 +2,13 @@ SHELL := /bin/bash
 
 help:
 	@echo "Usage:"
-	@echo " make release | Release to pypi."
 	@echo " make test    | Run the tests."
-
-release:
-	python setup.py register sdist bdist_wheel upload
+	@echo " make run-doc | Run the docs locally."
 
 test:
 	@coverage run ./user_management/tests/run.py
 	@coverage report --show-missing --fail-under=100
 	@flake8
+
+run-doc:
+	@mkdocs serve

README.md

@@ -1,199 +1,24 @@
 # django-user-management
 [![Build Status](https://travis-ci.org/incuna/django-user-management.png?branch=merge-version)](https://travis-ci.org/incuna/django-user-management) [![Coverage Status](https://coveralls.io/repos/incuna/django-user-management/badge.png?branch=master)](https://coveralls.io/r/incuna/django-user-management?branch=master) [![Requirements Status](https://requires.io/github/incuna/django-user-management/requirements.svg?branch=master)](https://requires.io/github/incuna/django-user-management/requirements/?branch=master)
 
-User management model mixins and api views.
-
-## Custom user model mixins
-
-###  ActiveUserMixin
-`user_management.models.mixins.ActiveUserMixin` provides a base custom user
-mixin with a `name`, `email`, `date_joined`, `is_staff`, and `is_active`.
-
-###  VerifyEmailMixin
-`user_management.models.mixins.VerifyEmailMixin` extends ActiveUserMixin to
-provide functionality to verify the email. It includes an additional
-`email_verification_required` field.  
-By default users will be created with `is_active = False`, a verification email
-will be sent including a link to verify the email and activate the account. 
-
-###  AvatarMixin
-`user_management.models.mixins.AvatarMixin` adds an avatar field. The 
-serializers require `django-imagekit`.
-
-#### Avatar views
-`user_management.api.avatar.views.ProfileAvatar` provides an endpoint to retrieve 
-and update the logged in user's avatar.
-
-`user_management.api.avatar.views.UserAvatar` provides an endpoint to retrieve 
-and update other user's avatar. Only admin user can update other user's data.
-
-Both avatar views provides an endpoint to retrieve a thumbnail of the
-authenticated user's avatar.
-
-    Thumbnail options can be specified as get parameters. Options are:
-        width: Specify the width (in pixels) to resize / crop to.
-        height: Specify the height (in pixels) to resize / crop to.
-        crop: Whether to crop or not [1,0]
-        anchor: Where to anchor the crop [t,r,b,l]
-        upscale: Whether to upscale or not [1,0]
-
-    If no options are specified the users avatar is returned.
-
-    To crop avatar to 100x100 anchored to the top right:
-        avatar?width=100&height=100&crop=1&anchor=tr
-
-
-## Installation
-Install the package
-
-    pip install django-user-management
-
-Install with avatar functionality
-
-    pip install django-user-management[avatar]
-
-Install with filtering sensitive data out of Sentry
-
-    pip install django-user-management[utils]
-
-
-Create a custom user model
-
-    from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin
-    from user_management.models.mixins import ActiveUserMixin
-
-
-    class User(ActiveUserMixin, PermissionsMixin, AbstractBaseUser):
-        pass
-
-If you want to use the `VerifyEmailMixin` then substitute it for `ActiveUserMixin`
-
-
-Make sure your custom user model in added to `INSTALLED_APPS` and set 
-`AUTH_USER_MODEL` to your custom user model.
-
-
-## Dependencies
-
-    djangorestframework
-    incuna_mail
-
-The optional `AvatarMixin` functionality depends on `django-imagekit`.
-
-
-### To use the api views
-Add to your `INSTALLED_APPS` in `settings.py`
-
-    INSTALLED_APPS = (
-        ...
-        'user_management.api',
-        ...
-    )
-
-Set your `DEFAULT_AUTHENTICATION_CLASSES`, for example:
-
-    REST_FRAMEWORK = {
-        'DEFAULT_AUTHENTICATION_CLASSES': {
-            'rest_framework.authentication.TokenAuthentication',
-            'rest_framework.authentication.SessionAuthentication',
-        },
-    }
-
-Add the urls to your `ROOT_URLCONF`
-
-    urlpatterns = patterns(''
-        ...
-        url('', include('user_management.api.urls', namespace='user_management_api')),
-        ...
-    )
-
-If you are using the `VerifyEmailMixin` then also include
-`user_management.api.urls.verify_email`
-
-    urlpatterns = patterns(''
-        ...
-        url('', include('user_management.api.urls.verify_email')),
-        ...
-    )
-
-If you are using the `AvatarMixin` then also include
-`user_management.api.avatar.urls.avatar`
-
-    urlpatterns = patterns(''
-        ...
-        url('', include('user_management.api.avatar.urls.avatar')),
-        ...
-    )
-
-
-If you need more fine-grained control you can replace `user_management.api.urls`
-with a selection from
-
-    urlpatterns = patterns(''
-        ...
-        url('', include('user_management.api.urls.auth')),
-        url('', include('user_management.api.urls.password_reset')),
-        url('', include('user_management.api.urls.profile')),
-        url('', include('user_management.api.urls.register')),
-        ...
-    )
-
-
-### Throttling protection
-The `/auth/` and `/auth/password_reset/` URLs are protected against throttling
-using the built-in [DRF throttle module](http://www.django-rest-framework.org/api-guide/throttling).
-
-The default throttle rates are:
-
-    'logins': '10/hour'
-    'passwords': '3/hour'
-
-You can customise the throttling rates by setting `REST_FRAMEWORK['DEFAULT_THROTTLE_RATES']`
-in your `settings.py`:
-
-    REST_FRAMEWORK = {
-        'DEFAULT_THROTTLE_RATES': {
-            'logins': '100/day',
-            'passwords': 100/day',
-        },
-    }
-
-
-### Filtering sensitive data
-
-Custom Sentry logging class is available to disallow sensitive data being logged
-by Sentry client.
-
-Activate it in the `settings.py` by adding:
-
-    SENTRY_CLIENT = 'user_management.utils.sentry.SensitiveDjangoClient'
-
-
-### Expiry of Auth tokens
-
-By default DRF does not offer expiration for authorization tokens nor any form
-of validation for the expired tokens.
-
-`django-user-management` comes in help here and this functionality can be
-easily activated.
-
-Override the authentication class for DRF in `settings.py`:
-
-    REST_FRAMEWORK = {
-        ...
-        'DEFAULT_AUTHENTICATION_CLASSES': 'user_management.api.authentication.TokenAuthentication',
-        ...
-    }
-
-Remember to run the management command (eg via cronjob) to clear expired tokens:
-
-    python manage.py remove_expired_tokens
-
-##### Tokens expiry times
-
-You can set custom expiry time for the auth tokens.
-
-Add below constants in the `settings.py`:
-
-    AUTH_TOKEN_MAX_AGE = <seconds_value> (default: 200 days)
-    AUTH_TOKEN_MAX_INACTIVITY = <seconds_value> (default: 12 hours)
+User management model mixins and API views/serializers based on [`Django`](https://github.com/django/django)
+and [`djangorestframework`](https://github.com/tomchristie/django-rest-framework).
+
+All documentation is in the [docs](docs/) directory.
+
+- [Installation](docs/installation.md)
+- [Mixins](docs/mixins.md)
+- [Views](docs/views.md)
+- [Avatar](docs/avatar.md)
+
+`user_management` model mixins give flexibility to create your own `User` model.
+By default all mixins are optional. Our mixins allow to create, identify users
+(from their emails instead of their username) as well as sending password reset
+and account validation emails.
+
+`user_management` API views and serializers can be grouped into five sections:
+* `auth`: authenticate and destroy a user session
+* `password_reset`: send and confirm a request to reset a password
+* `profile`: retrieve/update/delete the current user profile
+* `register`: create an account and send an email to validate it
+* `users`: give a list and a detail (retrieve, update, destroy) views about users

docs/avatar.md

@@ -0,0 +1,43 @@
+# Avatar
+
+## Mixin
+
+`user_management.models.mixins.AvatarMixin` adds an avatar field. The
+serializers for this field require `django-imagekit` to be installed.
+
+## Installation
+
+To install `django-user-management` with avatar functionality:
+
+    pip install django-user-management[avatar]
+
+Add the urls to your `ROOT_URLCONF`:
+
+    urlpatterns = [
+        ...
+        url(r'', include('user_management.api.avatar.urls.avatar')),
+        ...
+    ]
+
+## View
+
+`user_management.api.avatar.views.ProfileAvatar` provides an endpoint to retrieve
+and update the logged-in user's avatar.
+
+`user_management.api.avatar.views.UserAvatar` provides an endpoint to retrieve
+and update another user's avatar. Only an admin user can update other users' data.
+
+Both avatar views provides an endpoint to retrieve a thumbnail of the
+authenticated user's avatar.
+
+Thumbnail options can be specified as GET arguments. Options are:
+    width: Specify the width (in pixels) to resize/crop to.
+    height: Specify the height (in pixels) to resize/crop to.
+    crop: Whether to crop or not (allowed values: 0 or 1)
+    anchor: Where to anchor the crop, top/bottom/left/right (allowed values: t, b, l, r)
+    upscale: Whether to upscale or not (allowed values: 0 or 1)
+
+If no options are specified, the user's avatar is returned.
+
+For example, to return an avatar cropped to 100x100 anchored to the top right:
+    avatar?width=100&height=100&crop=1&anchor=tr

docs/index.md

@@ -0,0 +1,9 @@
+# Welcome to django-user-management documentation
+
+Documentation generated with [mkdocs.org](http://mkdocs.org).
+
+
+`django-user-management` contains user management model mixins and API views. The mixins
+provide common user-related functionality such as custom avatars and email verification
+during the registration process. The API views provide endpoints to support this
+functionality.

docs/installation.md

@@ -0,0 +1,38 @@
+# Installation
+
+## Dependencies
+
+    djangorestframework
+    incuna_mail
+
+## Install with pip
+
+Install the package:
+
+    pip install django-user-management
+
+Install with avatar functionality:
+
+    pip install django-user-management[avatar]
+
+Install with filtering sensitive data out of Sentry:
+
+    pip install django-user-management[utils]
+
+
+## User model
+
+To create a custom user model using the `django-user-management` functionality, declare
+your user class like this:
+
+    from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin
+    from user_management.models.mixins import ActiveUserMixin
+
+
+    class User(ActiveUserMixin, PermissionsMixin, AbstractBaseUser):
+        pass
+
+If you want to use the `VerifyEmailMixin`, substitute it for `ActiveUserMixin`.
+
+Make sure the app containing your custom user model is added to `settings.INSTALLED_APPS`,
+and set `settings.AUTH_USER_MODEL` to be the path to your custom user model.