introduce KwantDeprecationWarning

doc/source/reference/kwant.rst

@@ -3,9 +3,18 @@
 
 .. module:: kwant
 
-The top-level Kwant package serves as a container for sub-packages and does not
-have any functions of its own.  For convenience, short names are provided for a
-few widely used objects from the sub-packages:
+For convenience, short names are provided for a few widely used objects from
+the sub-packages.
+Otherwise, this package has only very limited functionality of its own.
+
+Generic functionality
+---------------------
+The version of Kwant is available under the name ``__version__``.
+
+.. autosummary::
+   :toctree: generated/
+
+   KwantDeprecationWarning
 
 .. currentmodule:: kwant.builder
 
@@ -43,7 +52,3 @@ From `kwant.solvers.default`
    ldos
    smatrix
    wave_function
-
-Version information
--------------------
-The version of Kwant is available under the name ``__version__``.

kwant/__init__.py

@@ -6,6 +6,8 @@
 # the AUTHORS file at the top-level directory of this distribution and at
 # http://kwant-project.org/authors.
 
+__all__ = []
+
 import numpy                    # Needed by C. Gohlke's Windows package.
 
 try:
@@ -16,12 +18,14 @@ except ImportError:
     and relaunch your Python intepreter from there."""
     raise ImportError(msg)
 
-__all__ = ['system', 'version', 'builder', 'lattice', 'solvers',
-           'digest', 'rmt']
-for module in __all__:
-    exec 'from . import {0}'.format(module)
+from ._common import KwantDeprecationWarning
+__all__.append('KwantDeprecationWarning')
 
-from .version import version as __version__
+from ._common import version as __version__
+
+for module in ['system', 'builder', 'lattice', 'solvers', 'digest', 'rmt']:
+    exec 'from . import {0}'.format(module)
+    __all__.append(module)
 
 # Make selected functionality available directly in the root namespace.
 available = [('builder', ['Builder', 'HoppingKind']),

kwant/version.py → kwant/_common.py

-# Copyright 2011-2013 Kwant authors.
+# Copyright 2011-2014 Kwant authors.
 #
 # This file is part of Kwant.  It is subject to the license terms in the
 # LICENSE file found in the top-level directory of this distribution and at
@@ -9,7 +9,7 @@
 import subprocess
 import os
 
-__all__ = ['version']
+__all__ = ['version', 'KwantDeprecationWarning']
 
 distr_root = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 
@@ -63,3 +63,14 @@ if version is None:
         from _static_version import version
     except:
         version = "unknown"
+
+
+class KwantDeprecationWarning(Warning):
+    """Class of warnings about a deprecated feature of Kwant.
+
+    DeprecatedWarning has been made invisible by default in Python 2.7 in order
+    to not confuse non-developer users with warnings that are not relevant to
+    them.  In the case of Kwant, by far most users are developers, so we feel
+    that a KwantDeprecationWarning that is visible by default is useful.
+    """
+    pass

setup.py

@@ -202,7 +202,7 @@ The existing MANIFEST file seems to have been generated by distutils (it begins
 with a comment).  It may well be incomplete."""
 
 
-# This is an exact copy of the function from kwant/version.py.  We can't import
+# This is an exact copy of the function from kwant/_common.py.  We can't import
 # it here (because Kwant is not yet built when this scipt is run), so we just
 # include a copy.
 def get_version_from_git():