Add some cleanup and more docs

Author: agjohnson

readthedocs/core/utils/extend.py

@@ -6,7 +6,16 @@
 from django.utils.module_loading import import_by_path
 
 
-def get_override_class(proxy_class, default_class):
+def get_override_class(proxy_class, default_class=None):
+    """Determine which class to use in an override class
+
+    The `proxy_class` is the main class that is used, and `default_class` is the
+    default class that this proxy class will instantiate.  If `default_class` is
+    not defined, this will be inferred from the `proxy_class`, as is defined in
+    :py:cls:`SettingsOverrideObject`.
+    """
+    if default_class is None:
+        default_class = getattr(proxy_class, '_default_class')
     class_id = '.'.join([
         inspect.getmodule(proxy_class).__name__,
         proxy_class.__name__
@@ -33,22 +42,23 @@ class SettingsOverrideObject(object):
     """Base class for creating class that can be overridden
 
     This is used for extension points in the code, where we want to extend a
-    class without monkey patching it. This abstract class allows for lazy
-    inheritance, creating a class from the specified class or from a setting,
-    but only once the class is called.
+    class without monkey patching it. This class will proxy classmethod calls
+    and instantiation to an underlying class, determined by used of
+    :py:cvar:`_default_class` or an override class from settings.
 
-    Default to an instance of the class defined by :py:cvar:`_default_class`.
+    The default target class is defined by :py:cvar:`_default_class`.
 
-    Next, look for an override setting class path in
-    ``settings.CLASS_OVERRIDES``, which should be a dictionary of class paths.
-    The setting should be a dictionary keyed by the object path name::
+    To override this class, an override setting class path can be added to
+    ``settings.CLASS_OVERRIDES``. This settings should be a dictionary keyed by
+    source class paths, with values to the override classes::
 
         CLASS_OVERRIDES = {
             'readthedocs.core.resolver.Resolver': 'something.resolver.Resolver',
         }
 
     Lastly, if ``settings.CLASS_OVERRIDES`` is missing, or the key is not found,
-    attempt to pull the key :py:cvar:`_override_setting` from ``settings``.
+    attempt to pull the key :py:cvar:`_override_setting` from ``settings``. This
+    matches the pattern we've been using previously.
     """
 
     __metaclass__ = SettingsOverrideMeta
@@ -59,7 +69,7 @@ class without monkey patching it. This abstract class allows for lazy
     def __new__(cls, *args, **kwargs):
         """Set up wrapped object
 
-        Create an instance of the underlying proxy class and return instead of
+        Create an instance of the underlying target class and return instead of
         this class.
         """
         return get_override_class(cls, cls._default_class)(*args, **kwargs)

readthedocs/privacy/backend.py

@@ -1,5 +1,3 @@
-import logging
-
 from django.db import models
 
 from guardian.shortcuts import get_objects_for_user
@@ -14,7 +12,6 @@
                                            get_override_class)
 from readthedocs.projects import constants
 
-log = logging.getLogger(__name__)
 
 class ProjectManager(models.Manager):
 
@@ -87,6 +84,9 @@ class VersionManager(models.Manager):
 
     @classmethod
     def from_queryset(cls, queryset_class, class_name=None):
+        # This is overridden because :py:meth:`models.Manager.from_queryset`
+        # uses `inspect` to retrieve the class methods, and the proxy class has
+        # no direct members.
         queryset_class = get_override_class(
             VersionQuerySet,
             VersionQuerySet._default_class