Commits

Mikhail Korobov committed 279d9cf

Show deprecation warnings for old import paths. Docstrings are updated for new recommended import paths.

Comments (0)

Files changed (12)

admin_tools/dashboard/dashboards.py

     can declare css stylesheets and/or javascript files to include when
     rendering the dashboard, for example::
 
-        from admin_tools.dashboard.models import *
+        from admin_tools.dashboard import Dashboard
 
         class MyDashboard(Dashboard):
             class Media:
 
         from django.core.urlresolvers import reverse
         from django.utils.translation import ugettext_lazy as _
-        from admin_tools.dashboard.models import *
+        from admin_tools.dashboard import modules, Dashboard
 
         class MyDashboard(Dashboard):
             def __init__(self, **kwargs):
                 self.columns = 3
 
                 # append an app list module for "Applications"
-                self.children.append(AppListDashboardModule(
+                self.children.append(modules.AppListDashboardModule(
                     title=_('Applications'),
                     exclude_list=('django.contrib',),
                 ))
 
                 # append an app list module for "Administration"
-                self.children.append(AppListDashboardModule(
+                self.children.append(modules.AppListDashboardModule(
                     title=_('Administration'),
                     include_list=('django.contrib',),
                 ))
 
                 # append a recent actions module
-                self.children.append(RecentActionsDashboardModule(
+                self.children.append(modules.RecentActionsDashboardModule(
                     title=_('Recent Actions'),
                     limit=5
                 ))
 
         from django.core.urlresolvers import reverse
         from django.utils.translation import ugettext_lazy as _
-        from admin_tools.dashboard.models import *
+        from admin_tools.dashboard import modules, AppIndexDashboard
 
         class MyAppIndexDashboard(AppIndexDashboard):
             def __init__(self, **kwargs):
 
                 # append a model list module that lists all models
                 # for the app
-                self.children.append(ModelListDashboardModule(
+                self.children.append(modules.ModelListDashboardModule(
                     title=self.app_title,
                     include_list=self.models,
                 ))
 
                 # append a recent actions module for the current app
-                self.children.append(RecentActionsDashboardModule(
+                self.children.append(modules.RecentActionsDashboardModule(
                     title=_('Recent Actions'),
                     include_list=self.models,
                     limit=5

admin_tools/dashboard/models.py

 """
 This module contains the base classes for the dashboard and dashboard modules.
 """
-
 from django.db import models
-from admin_tools.dashboard.modules import *
-from admin_tools.dashboard.dashboards import *
 
 class DashboardPreferences(models.Model):
     """
         ordering = ('user',)
 
 
+# warnings for deprecated imports
+from admin_tools.deprecate_utils import import_path_is_changed
+from admin_tools import dashboard
+from admin_tools.dashboard import modules
+
+class Dashboard(
+          import_path_is_changed(
+              'admin_tools.dashboard.models.Dashboard',
+              'admin_tools.dashboard.Dashboard'
+          ),
+          dashboard.Dashboard
+      ): pass
+
+class DefaultIndexDashboard(
+          import_path_is_changed(
+              'admin_tools.dashboard.models.DefaultIndexDashboard',
+              'admin_tools.dashboard.DefaultIndexDashboard',
+          ),
+          dashboard.DefaultIndexDashboard
+      ):pass
+
+class DefaultAppIndexDashboard(
+          import_path_is_changed(
+              'admin_tools.dashboard.models.DefaultAppIndexDashboard',
+              'admin_tools.dashboard.DefaultAppIndexDashboard'
+          ),
+          dashboard.DefaultAppIndexDashboard
+      ):pass
+
+class AppIndexDashboard(
+          import_path_is_changed(
+              'admin_tools.dashboard.models.AppIndexDashboard',
+              'admin_tools.dashboard.AppIndexDashboard'
+          ),
+          dashboard.AppIndexDashboard
+      ):pass
+
+
+class DashboardModule(
+          import_path_is_changed(
+              'admin_tools.dashboard.models.DashboardModule',
+              'admin_tools.dashboard.modules.DashboardModule',
+          ),
+          modules.DashboardModule
+      ):pass
+
+class AppListDashboardModule(
+          import_path_is_changed(
+              'admin_tools.dashboard.models.AppListDashboardModule',
+              'admin_tools.dashboard.modules.AppListDashboardModule',
+          ),
+          modules.AppListDashboardModule
+      ): pass
+
+class ModelListDashboardModule(
+          import_path_is_changed(
+              'admin_tools.dashboard.models.ModelListDashboardModule',
+              'admin_tools.dashboard.modules.ModelListDashboardModule',
+          ),
+          modules.ModelListDashboardModule
+      ): pass
+
+class LinkListDashboardModule(
+          import_path_is_changed(
+              'admin_tools.dashboard.models.LinkListDashboardModule',
+              'admin_tools.dashboard.modules.LinkListDashboardModule',
+          ),
+          modules.LinkListDashboardModule
+      ): pass
+
+class FeedDashboardModule(
+          import_path_is_changed(
+              'admin_tools.dashboard.models.FeedDashboardModule',
+              'admin_tools.dashboard.modules.FeedDashboardModule',
+          ),
+          modules.FeedDashboardModule
+      ): pass

admin_tools/dashboard/modules.py

 
     Here's a small example of building a link list module::
 
-        from admin_tools.dashboard.models import *
+        from admin_tools.dashboard import modules, Dashboard
 
         class MyDashboard(Dashboard):
             def __init__(self, **kwargs):
                 Dashboard.__init__(self, **kwargs)
 
-                self.children.append(LinkListDashboardModule(
+                self.children.append(modules.LinkListDashboardModule(
                     layout='inline',
                     children=(
                         {
 
     Here's a small example of building an app list module::
 
-        from admin_tools.dashboard.models import *
+        from admin_tools.dashboard import modules, Dashboard
 
         class MyDashboard(Dashboard):
             def __init__(self, **kwargs):
                 Dashboard.__init__(self, **kwargs)
 
                 # will only list the django.contrib apps
-                self.children.append(AppListDashboardModule(
+                self.children.append(modules.AppListDashboardModule(
                     title='Administration',
                     include_list=('django.contrib',)
                 ))
                 # will list all apps except the django.contrib ones
-                self.children.append(AppListDashboardModule(
+                self.children.append(modules.AppListDashboardModule(
                     title='Applications',
                     exclude_list=('django.contrib',)
                 ))
 
     Here's a small example of building a model list module::
 
-        from admin_tools.dashboard.models import *
+        from admin_tools.dashboard import modules, Dashboard
 
         class MyDashboard(Dashboard):
             def __init__(self, **kwargs):
                 Dashboard.__init__(self, **kwargs)
 
                 # will only list the django.contrib.auth models
-                self.children.append(ModelListDashboardModule(
+                self.children.append(modules.ModelListDashboardModule(
                     title='Authentication',
                     include_list=('django.contrib.auth',)
                 ))
 
     Here's a small example of building a recent actions module::
 
-        from admin_tools.dashboard.models import *
+        from admin_tools.dashboard import modules, Dashboard
 
         class MyDashboard(Dashboard):
             def __init__(self, **kwargs):
                 Dashboard.__init__(self, **kwargs)
 
                 # will only list the django.contrib apps
-                self.children.append(RecentActionsDashboardModule(
+                self.children.append(modules.RecentActionsDashboardModule(
                     title='Django CMS recent actions',
                     include_list=('cms.page', 'cms.cmsplugin',)
                 ))
 
     Here's a small example of building a recent actions module::
 
-        from admin_tools.dashboard.models import *
+        from admin_tools.dashboard import modules, Dashboard
 
         class MyDashboard(Dashboard):
             def __init__(self, **kwargs):
                 Dashboard.__init__(self, **kwargs)
 
                 # will only list the django.contrib apps
-                self.children.append(FeedDashboardModule(
+                self.children.append(modules.FeedDashboardModule(
                     title=_('Latest Django News'),
                     feed_url='http://www.djangoproject.com/rss/weblog/',
                     limit=5

admin_tools/dashboard/utils.py

     dashboard_cls = getattr(
         settings,
         'ADMIN_TOOLS_INDEX_DASHBOARD',
-        'admin_tools.dashboard.models.DefaultIndexDashboard'
+        'admin_tools.dashboard.DefaultIndexDashboard'
     )
     try:
         mod, inst = dashboard_cls.rsplit('.', 1)
     dashboard_cls = getattr(
         settings,
         'ADMIN_TOOLS_APP_INDEX_DASHBOARD',
-        'admin_tools.dashboard.models.DefaultAppIndexDashboard'
+        'admin_tools.dashboard.DefaultAppIndexDashboard'
     )
     try:
         mod, inst = dashboard_cls.rsplit('.', 1)

admin_tools/deprecate_utils.py

+"""
+This module contains some utils for easy deprecation warnings.
+"""
+import warnings
+
+def import_path_is_changed(old_name, new_name):
+    class ImportDeprecationMixin(object):
+        def __new__(cls, *args, **kwargs):
+            klass = super(ImportDeprecationMixin, cls).__new__(cls)
+            msg = '%s: %s is deprecated. Please use %s instead.' % (klass, old_name, new_name)
+            warnings.warn(msg, DeprecationWarning)
+            return klass
+    return ImportDeprecationMixin
+
+

admin_tools/menu/items.py

         let's build a "history" menu item, that will list the last ten visited
         pages::
 
-            from admin_tools.menu.models import *
+            from admin_tools.menu.items import MenuItem
 
             class HistoryMenuItem(MenuItem):
                 def init_with_context(self, context):
 
     Here's a small example of building an app list menu item::
 
-        from admin_tools.menu.models import *
+        from admin_tools.menu import items, Menu
 
         class MyMenu(Menu):
             def __init__(self, **kwargs):
                 super(MyMenu, self).__init__(**kwargs)
-                self.children.append(AppListMenuItem(
+                self.children.append(items.AppListMenuItem(
                     title='Applications',
                     exclude_list=('django.contrib',)
                 )
 
     Here's a small example of adding a bookmark menu item::
 
-        from admin_tools.menu.models import *
+        from admin_tools.menu import items, Menu
 
         class MyMenu(Menu):
             def __init__(self, **kwargs):
                 super(MyMenu, self).__init__(**kwargs)
-                self.children.append(BookmarkMenuItem(title='My bookmarks'))
+                self.children.append(items.BookmarkMenuItem(title='My bookmarks'))
 
     """
 

admin_tools/menu/models.py

 """
 from django.db import models
 
-# for backward-compatibility
-from admin_tools.menu.menus import *
-from admin_tools.menu.items import *
-
 class Bookmark(models.Model):
     """
     This model represents a user created bookmark.
         db_table = 'admin_tools_menu_bookmark'
         ordering = ('id',)
 
+# for backward-compatibility
+from admin_tools import menu
+from admin_tools.menu import items
+from admin_tools.deprecate_utils import import_path_is_changed
+
+class Menu(
+          import_path_is_changed(
+              'admin_tools.menu.models',
+              'admin_tools.menu.Menu'
+          ),
+          menu.Menu
+      ): pass
+
+class DefaultMenu(
+          import_path_is_changed(
+              'admin_tools.menu.models.DefaultMenu',
+              'admin_tools.menu.DefaultMenu'
+          ),
+          menu.DefaultMenu
+      ): pass
+
+class MenuItem(
+          import_path_is_changed(
+              'admin_tools.menu.models.MenuItem',
+              'admin_tools.menu.items.MenuItem'
+          ),
+          items.MenuItem
+      ): pass
+
+class AppListMenuItem(
+          import_path_is_changed(
+              'admin_tools.menu.models.BookmarkMenuItem',
+              'admin_tools.menu.items.AppListMenuItem'
+          ),
+          items.AppListMenuItem
+      ): pass
+
+class BookmarkMenuItem(
+          import_path_is_changed(
+              'admin_tools.menu.models.BookmarkMenuItem',
+              'admin_tools.menu.items.BookmarkMenuItem'
+          ),
+          items.BookmarkMenuItem
+      ): pass

admin_tools/menu/utils.py

     menu_cls = getattr(
         settings,
         'ADMIN_TOOLS_MENU',
-        'admin_tools.menu.models.DefaultMenu'
+        'admin_tools.menu.DefaultMenu'
     )
     try:
         mod, inst = menu_cls.rsplit('.', 1)

admin_tools/tests.py

+import warnings
+from unittest import TestCase
+
+class DeprecationTest(TestCase):
+
+    def assertDeprecated(self, cls, *args, **kwargs):
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            obj = cls(*args, **kwargs)
+
+            assert len(w) == 1
+            assert issubclass(w[-1].category, DeprecationWarning)
+            assert "deprecated" in str(w[-1].message)
+
+    def assertNotDeprecated(self, cls, *args, **kwargs):
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            obj = cls(*args, **kwargs)
+            assert len(w) == 0
+
+
+    def test_dashboard(self):
+        from admin_tools.dashboard import models
+
+        self.assertDeprecated(models.Dashboard)
+        self.assertDeprecated(models.DefaultIndexDashboard)
+        self.assertDeprecated(models.DefaultAppIndexDashboard, '', [])
+        self.assertDeprecated(models.AppIndexDashboard, '', [])
+
+        self.assertDeprecated(models.DashboardModule)
+        self.assertDeprecated(models.AppListDashboardModule)
+        self.assertDeprecated(models.ModelListDashboardModule)
+        self.assertDeprecated(models.LinkListDashboardModule)
+        self.assertDeprecated(models.FeedDashboardModule)
+
+    def test_dashboard_new(self):
+        from admin_tools import dashboard
+
+        self.assertNotDeprecated(dashboard.Dashboard)
+        self.assertNotDeprecated(dashboard.DefaultIndexDashboard)
+        self.assertNotDeprecated(dashboard.DefaultAppIndexDashboard, '', [])
+        self.assertNotDeprecated(dashboard.AppIndexDashboard, '', [])
+
+        from admin_tools.dashboard import modules
+        self.assertNotDeprecated(modules.DashboardModule)
+        self.assertNotDeprecated(modules.AppListDashboardModule)
+        self.assertNotDeprecated(modules.ModelListDashboardModule)
+        self.assertNotDeprecated(modules.LinkListDashboardModule)
+        self.assertNotDeprecated(modules.FeedDashboardModule)
+
+
+    def test_menu(self):
+        from admin_tools.menu import models
+        self.assertDeprecated(models.Menu)
+        self.assertDeprecated(models.DefaultMenu)
+        self.assertDeprecated(models.MenuItem)
+        self.assertDeprecated(models.AppListMenuItem)
+        self.assertDeprecated(models.BookmarkMenuItem)
+
+    def test_menu_new(self):
+        from admin_tools import menu
+        self.assertNotDeprecated(menu.Menu)
+        self.assertNotDeprecated(menu.DefaultMenu)
+
+        from admin_tools.menu import items
+        self.assertNotDeprecated(items.MenuItem)
+        self.assertNotDeprecated(items.AppListMenuItem)
+        self.assertNotDeprecated(items.BookmarkMenuItem)

test_proj/dashboard.py

+from django.utils.translation import ugettext_lazy as _
+from django.core.urlresolvers import reverse
+from admin_tools.dashboard import Dashboard, AppIndexDashboard
+from admin_tools.dashboard import modules
+
+
+# to activate your index dashboard add the following to your settings.py:
+#
+# ADMIN_TOOLS_INDEX_DASHBOARD = 'test_proj.dashboard.CustomIndexDashboard'
+
+class CustomIndexDashboard(Dashboard):
+    """
+    Custom index dashboard for test_proj.
+    """
+    def __init__(self, **kwargs):
+        Dashboard.__init__(self, **kwargs)
+
+        # append a link list module for "quick links"
+        self.children.append(modules.LinkListDashboardModule(
+            title=_('Quick links'),
+            layout='inline',
+            draggable=False,
+            deletable=False,
+            collapsible=False,
+            children=[
+                {
+                    'title': _('Return to site'),
+                    'url': '/',
+                },
+                {
+                    'title': _('Change password'),
+                    'url': reverse('admin:password_change'),
+                },
+                {
+                    'title': _('Log out'),
+                    'url': reverse('admin:logout')
+                },
+            ]
+        ))
+
+        # append an app list module for "Applications"
+        self.children.append(modules.AppListDashboardModule(
+            title=_('Applications'),
+            exclude_list=('django.contrib',),
+        ))
+
+        # append an app list module for "Administration"
+        self.children.append(modules.AppListDashboardModule(
+            title=_('Administration'),
+            include_list=('django.contrib',),
+        ))
+
+        # append a recent actions module
+        self.children.append(modules.RecentActionsDashboardModule(
+            title=_('Recent Actions'),
+            limit=5
+        ))
+
+        # append another link list module for "support".
+        self.children.append(modules.LinkListDashboardModule(
+            title=_('Support'),
+            children=[
+                {
+                    'title': _('Django documentation'),
+                    'url': 'http://docs.djangoproject.com/',
+                    'external': True,
+                },
+                {
+                    'title': _('Django "django-users" mailing list'),
+                    'url': 'http://groups.google.com/group/django-users',
+                    'external': True,
+                },
+                {
+                    'title': _('Django irc channel'),
+                    'url': 'irc://irc.freenode.net/django',
+                    'external': True,
+                },
+            ]
+        ))
+
+    def init_with_context(self, context):
+        """
+        Use this method if you need to access the request context.
+        """
+        pass
+
+
+# to activate your app index dashboard add the following to your settings.py:
+#
+# ADMIN_TOOLS_APP_INDEX_DASHBOARD = 'test_proj.dashboard.CustomAppIndexDashboard'
+
+class CustomAppIndexDashboard(AppIndexDashboard):
+    """
+    Custom app index dashboard for test_proj.
+    """
+    def __init__(self, *args, **kwargs):
+        AppIndexDashboard.__init__(self, *args, **kwargs)
+
+        # we disable title because its redundant with the model list module
+        self.title = ''
+
+        # append a model list module
+        self.children.append(modules.ModelListDashboardModule(
+            title=self.app_title,
+            include_list=self.models,
+        ))
+
+        # append a recent actions module
+        self.children.append(modules.RecentActionsDashboardModule(
+            title=_('Recent Actions'),
+            include_list=self.get_app_content_types(),
+        ))
+
+    def init_with_context(self, context):
+        """
+        Use this method if you need to access the request context.
+        """
+        pass

test_proj/settings.py

 
 FIXTURE_DIRS = ['fixtures']
 
+ADMIN_TOOLS_INDEX_DASHBOARD = 'test_proj.dashboard.CustomIndexDashboard'
 
 INSTALLED_APPS = [
     'admin_tools',

test_proj/test_app/tests.py

         self.assertContains(res, 'Foos')
         self.assertContains(res, 'Bars')
         self.assertContains(res, 'Users', 1) # only item from menu
+