Deprecate emu unit

CHANGES.rst

@@ -124,6 +124,9 @@ API Changes
 
 - ``astropy.units``
 
+  - Moved ``units.cgs.emu`` to ``units.deprecated.emu`` due to ambiguous
+    definition of "emu". [#4918, #5906]
+
 - ``astropy.utils``
 
 - ``astropy.visualization``

astropy/units/cgs.py

@@ -97,7 +97,7 @@
 def_unit(['statA', 'statampere'], Fr * s ** -1, namespace=_ns,
          doc='statampere: CGS (ESU) unit of current')
 
-def_unit(['Bi', 'Biot', 'abA', 'abampere', 'emu'],
+def_unit(['Bi', 'Biot', 'abA', 'abampere'],
          g ** Fraction(1, 2) * cm ** Fraction(1, 2) * s ** -1, namespace=_ns,
          doc='Biot: CGS (EMU) unit of current')
 

astropy/units/deprecated.py

@@ -0,0 +1,61 @@
+# -*- coding: utf-8 -*-
+# Licensed under a 3-clause BSD style license - see LICENSE.rst
+"""
+This package defines deprecated units.
+
+These units are not available in the top-level `astropy.units`
+namespace. To use these units, you must import the `astropy.units.deprecated`
+module::
+
+    >>> from astropy.units import deprecated
+    >>> q = 10. * deprecated.emu  # doctest: +SKIP
+
+To include them in `~astropy.units.UnitBase.compose` and the results of
+`~astropy.units.UnitBase.find_equivalent_units`, do::
+
+    >>> from astropy.units import deprecated
+    >>> deprecated.enable()  # doctest: +SKIP
+
+"""
+from __future__ import (absolute_import, division, print_function,
+                        unicode_literals)
+
+_ns = globals()
+
+
+def _initialize_module():
+    # Local imports to avoid polluting top-level namespace
+    from . import cgs
+    from .core import def_unit
+
+    def_unit(['emu'], cgs.Bi, namespace=_ns,
+             doc='Biot: CGS (EMU) unit of current')
+
+
+_initialize_module()
+
+
+###########################################################################
+# DOCSTRING
+
+# This generates a docstring for this module that describes all of the
+# standard units defined here.
+from .utils import generate_unit_summary as _generate_unit_summary  # noqa
+if __doc__ is not None:
+    __doc__ += _generate_unit_summary(globals())
+
+
+def enable():
+    """
+    Enable deprecated units so they appear in results of
+    `~astropy.units.UnitBase.find_equivalent_units` and
+    `~astropy.units.UnitBase.compose`.
+
+    This may be used with the ``with`` statement to enable deprecated
+    units only temporarily.
+    """
+    # Local import to avoid cyclical import
+    from .core import add_enabled_units
+    # Local import to avoid polluting namespace
+    import inspect
+    return add_enabled_units(inspect.getmodule(enable))

astropy/units/tests/test_deprecated.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+# Licensed under a 3-clause BSD style license - see LICENSE.rst
+
+# TEST_UNICODE_LITERALS
+
+"""Regression tests for deprecated units."""
+from __future__ import (absolute_import, unicode_literals, division,
+                        print_function)
+
+from .. import deprecated
+from ... import units as u
+from ...tests.helper import pytest  # TODO: Stop using bundled pytest
+
+
+def test_emu():
+    with pytest.raises(AttributeError):
+        u.emu
+
+    assert u.Bi.to(deprecated.emu, 1) == 1
+
+    with deprecated.enable():
+        assert u.Bi.compose()[0] == deprecated.emu
+
+    assert u.Bi.compose()[0] == u.Bi

docs/units/index.rst

@@ -106,7 +106,7 @@ parentheses to create a corresponding logarithmic quantity::
     >>> from astropy import constants as c
     >>> u.Dex((c.G * u.M_sun / u.R_sun**2).cgs)  # doctest: +FLOAT_CMP
     <Dex 4.43842814841305 dex(cm / s2)>
-    
+
 `astropy.units` also handles :ref:`equivalencies <unit_equivalencies>`, such as
 that between wavelength and frequency. To use that feature, equivalence objects
 are passed to the :meth:`~astropy.units.quantity.Quantity.to` conversion
@@ -207,6 +207,8 @@ Reference/API
 
 .. automodapi:: astropy.units.function
 
+.. automodapi:: astropy.units.deprecated
+
 Acknowledgments
 ===============