Allow user to be tracked by explicit ID (#511)

* Allow user to be tracked by explicit ID

* Added initial tests to show failing functionality when user in different db

* rebase

* Initial set of tests

* Format

* Finished first round of testing

* Added documentation

* Fixed typo

* Updated model name

* format

Author: Ross Mechanic

CHANGES.rst

@@ -3,28 +3,29 @@ Changes
 
 Unreleased
 ----------
-- Add support for `using` chained manager method and save/delete keyword argument (gh-507)
-- Added management command `clean_duplicate_history` to remove duplicate history entries (gh-483)
+- Add support for ``using`` chained manager method and save/delete keyword argument (gh-507)
+- Added management command ``clean_duplicate_history`` to remove duplicate history entries (gh-483)
 - Updated most_recent to work with excluded_fields (gh-477)
-- Fixed bug that prevented self-referential foreign key from using `'self'` (gh-513)
+- Fixed bug that prevented self-referential foreign key from using ``'self'`` (gh-513)
+- Added ability to track custom user with explicit custom ``history_user_id_field`` (gh-511)
 
 2.6.0 (2018-12-12)
 ------------------
-- Add `app` parameter to the constructor of `HistoricalRecords` (gh-486)
-- Add `custom_model_name` parameter to the constructor of `HistoricalRecords` (gh-451)
+- Add ``app`` parameter to the constructor of ``HistoricalRecords`` (gh-486)
+- Add ``custom_model_name`` parameter to the constructor of ``HistoricalRecords`` (gh-451)
 - Fix header on history pages when custom site_header is used (gh-448)
-- Modify `pre_create_historircal_record` to pass `history_instance` for ease of customization (gh-421)
-- Raise warning if HistoricalRecords(inherit=False) is in an abstract model (gh-341)
+- Modify ``pre_create_historical_record`` to pass ``history_instance`` for ease of customization (gh-421)
+- Raise warning if ``HistoricalRecords(inherit=False)`` is in an abstract model (gh-341)
 - Ensure custom arguments for fields are included in historical models' fields (gh-431)
 - Add german translations (gh-484)
-- Add `extra_context` parameter to history_form_view (gh-467)
-- Fixed bug that prevented `next_record` and `prev_record` to work with custom manager names (gh-501)
+- Add ``extra_context`` parameter to history_form_view (gh-467)
+- Fixed bug that prevented ``next_record`` and ``prev_record`` to work with custom manager names (gh-501)
 
 2.5.1 (2018-10-19)
 ------------------
-- Add `'+'` as the `history_type` for each instance in `bulk_history_create` (gh-449)
-- Add support for  `history_change_reason` for each instance in `bulk_history_create` (gh-449)
-- Add `history_change_reason` in the history list view under the  `Change reason` display name (gh-458)
+- Add ``'+'`` as the ``history_type`` for each instance in ``bulk_history_create`` (gh-449)
+- Add support for  ``history_change_reason`` for each instance in ``bulk_history_create`` (gh-449)
+- Add ``history_change_reason`` in the history list view under the  ``Change reason`` display name (gh-458)
 - Fix bug that caused failures when using a custom user model (gh-459)
 
 2.5.0 (2018-10-18)
@@ -35,12 +36,12 @@ Unreleased
 2.4.0 (2018-09-20)
 ------------------
 - Add pre and post create_historical_record signals (gh-426)
-- Remove support for `django_mongodb_engine` when converting AutoFields (gh-432)
+- Remove support for ``django_mongodb_engine`` when converting AutoFields (gh-432)
 - Add support for Django 2.1 (gh-418)
 
 2.3.0 (2018-07-19)
 ------------------
-- Add ability to diff HistoricalRecords (gh-244)
+- Add ability to diff ``HistoricalRecords`` (gh-244)
 
 2.2.0 (2018-07-02)
 ------------------
@@ -54,22 +55,22 @@ Unreleased
 
 2.1.0 (2018-06-04)
 ------------------
-- Add ability to specify custom history_reason field (gh-379)
-- Add ability to specify custom history_id field (gh-368)
-- Add HistoricalRecord instance properties `prev_record` and `next_record` (gh-365)
+- Add ability to specify custom ``history_reason`` field (gh-379)
+- Add ability to specify custom ``history_id`` field (gh-368)
+- Add HistoricalRecord instance properties ``prev_record`` and ``next_record`` (gh-365)
 - Can set admin methods as attributes on object history change list template (gh-390)
 - Fixed compatibility of >= 2.0 versions with old-style middleware (gh-369)
 
 2.0 (2018-04-05)
 ----------------
 - Added Django 2.0 support (gh-330)
 - Dropped support for Django<=1.10 (gh-356)
-- Fix bug where history_view ignored user permissions (gh-361)
-- Fixed HistoryRequestMiddleware which hadn't been working for Django>1.9 (gh-364)
+- Fix bug where ``history_view`` ignored user permissions (gh-361)
+- Fixed ``HistoryRequestMiddleware`` which hadn't been working for Django>1.9 (gh-364)
 
 1.9.1 (2018-03-30)
 ------------------
-- Use get_queryset rather than model.objects in history_view. (gh-303)
+- Use ``get_queryset`` rather ``than model.objects`` in ``history_view``. (gh-303)
 - Change ugettext calls in models.py to ugettext_lazy
 - Resolve issue where model references itself (gh-278)
 - Fix issue with tracking an inherited model (abstract class) (gh-269)
@@ -78,13 +79,13 @@ Unreleased
 
 1.9.0 (2017-06-11)
 ------------------
-- Add --batchsize option to the populate_history management command. (gh-231)
+- Add ``--batchsize`` option to the ``populate_history`` management command. (gh-231)
 - Add ability to show specific attributes in admin history list view. (gh-256)
 - Add Brazilian Portuguese translation file. (gh-279)
 - Fix locale file packaging issue. (gh-280)
 - Add ability to specify reason for history change. (gh-275)
 - Test against Django 1.11 and Python 3.6. (gh-276)
-- Add `excluded_fields` option to exclude fields from history. (gh-274)
+- Add ``excluded_fields`` option to exclude fields from history. (gh-274)
 
 1.8.2 (2017-01-19)
 ------------------
@@ -97,18 +98,18 @@ Unreleased
 
 1.8.0 (2016-02-02)
 ------------------
-- History tracking can be inherited by passing `inherit=True`. (gh-63)
+- History tracking can be inherited by passing ``inherit=True``. (gh-63)
 
 1.7.0 (2015-12-02)
 ------------------
 - Add ability to list history in admin when the object instance is deleted. (gh-72)
-- Add ability to change history through the admin. (Enabled with the `SIMPLE_HISTORY_EDIT` setting.)
+- Add ability to change history through the admin. (Enabled with the ``SIMPLE_HISTORY_EDIT`` setting.)
 - Add Django 1.9 support.
 - Support for custom tables names. (gh-196)
 
 1.6.3 (2015-07-30)
 ------------------
-- Respect `to_field` and `db_column` parameters (gh-182)
+- Respect ``to_field`` and ``db_column`` parameters (gh-182)
 
 1.6.2 (2015-07-04)
 ------------------
@@ -125,7 +126,7 @@ Unreleased
 ------------------
 - Add support for Django 1.8+
 - Deprecated use of ``CustomForeignKeyField`` (to be removed)
-- Remove default reverse accessor to `auth.User` for historical models (gh-121)
+- Remove default reverse accessor to ``auth.User`` for historical models (gh-121)
 
 1.5.4 (2015-01-03)
 ------------------

docs/multiple_dbs.rst

@@ -1,5 +1,9 @@
 Multiple databases
 ==================
+
+Interacting with Multiple Databases
+-----------------------------------
+
 `django-simple-history` follows the Django conventions for interacting with multiple databases.
 
 .. code-block:: python
@@ -26,3 +30,12 @@ When interacting with manager methods, use ``db_manager()``:
     >>> poll.history.db_manager('other').as_of(datetime(2010, 10, 25, 18, 4, 0))
 
 See the Django documentation for more information on how to interact with multiple databases.
+
+Tracking User in a Separate Database
+------------------------------------
+
+When using ``django-simple-history`` in app with multiple database, you may run into
+an issue where you want to track the history on a table that lives in a separate
+database to your user model. Since Django does not support cross-database relations,
+you will have to manually track the ``history_user`` using an explicit ID. The full
+documentation on this feature is in :ref:`Manually Track User Model`.

docs/user_tracking.rst

@@ -4,7 +4,7 @@ User Tracking
 
 Recording Which User Changed a Model
 ------------------------------------
-There are three documented ways to attach users to a tracked change:
+There are four documented ways to attach users to a tracked change:
 
 1. Use the ``HistoryRequestMiddleware``. The middleware sets the
 User instance that made the request as the ``history_user`` on the history
@@ -15,7 +15,15 @@ table.
 attach the user to the tracked change by overriding the `save_model` method.
 
 3. Assign a user to the ``_history_user`` attribute of the object as described
-below:
+in the `_history_user section`_.
+
+4. Track the user using an explicit ``history_user_id``, which is described in
+`Manually Track User Model`_. This method is particularly useful when using multiple
+databases (where your user model lives in a separate database to your historical model),
+or when using a user that doesn't live within the Django app (i.e. a user model retrieved
+from an API).
+
+.. _`_history_user section`:
 
 Using ``_history_user`` to Record Which User Changed a Model
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -75,8 +83,65 @@ This is very helpful when using ``register``:
     register(Poll, get_user=get_poll_user)
 
 
+.. _`Manually Track User Model`:
+
+
+Manually Track User Model
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Although ``django-simple-history`` tracks the ``history_user`` (the user who changed the
+model) using a django foreign key, there are instances where we might want to track this
+user but cannot use a Django foreign key.
+
+**Note:** If you want to track a custom user model that is still accessible through a
+Django foreign key, refer to `Change User Model`_.
+
+The two most common cases where this feature will be helpful are:
+
+1. You are working on a Django app with multiple databases, and your history table
+   is in a separate database from the user table.
+
+2. The user model that you want to use for ``history_user`` does not live within the
+   Django app, but is only accessible elsewhere (i.e. through an API call).
+
+There are three parameters to ``HistoricalRecords`` or ``register`` that facilitate
+the ability to manually track a ``history_user``.
+
+
+:history_user_id_field: An instance of field (i.e. ``IntegerField(null=True)`` or
+    ``UUIDField(default=uuid.uuid4, null=True)`` that will uniquely identify your user
+    object. This is generally the field type of the primary key on your user object.
+
+:history_user_getter: *optional*. A callable that takes the historical instance of the
+    model and returns the ``history_user`` object. The default getter is shown below:
+
+.. code-block:: python
+
+    def _history_user_getter(historical_instance):
+        if historical_instance.history_user_id is None:
+            return None
+        User = get_user_model()
+        try:
+            return User.objects.get(pk=historical_instance.history_user_id)
+        except User.DoesNotExist:
+            return None
+
+
+:history_user_setter: *optional*. A callable that takes the historical instance and
+    the user instance, and sets ``history_user_id`` on the historical instance. The
+    default setter is shown below:
+
+.. code-block:: python
+
+    def _history_user_setter(historical_instance, user):
+        if user is not None:
+            historical_instance.history_user_id = user.pk
+
+
+.. _`Change User Model`:
+
 Change User Model
-------------------------------------
+-----------------
 
 If you need to use a different user model then ``settings.AUTH_USER_MODEL``,
 pass in the required model to ``user_model``.  Doing this requires ``_history_user``

simple_history/admin.py

@@ -48,9 +48,10 @@ def history_view(self, request, object_id, extra_context=None):
         pk_name = opts.pk.attname
         history = getattr(model, model._meta.simple_history_manager_attribute)
         object_id = unquote(object_id)
-        action_list = history.filter(**{pk_name: object_id}).select_related(
-            "history_user"
-        )
+        action_list = history.filter(**{pk_name: object_id})
+        if not isinstance(history.model.history_user, property):
+            # Only select_related when history_user is a ForeignKey (not a property)
+            action_list = action_list.select_related("history_user")
         history_list_display = getattr(self, "history_list_display", [])
         # If no history was found, see whether this object even exists.
         try: