diff --git a/CHANGES.rst b/CHANGES.rst index 8ab472289a4b..d0b83c4185dd 100644 --- a/CHANGES.rst +++ b/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`` diff --git a/astropy/units/cgs.py b/astropy/units/cgs.py index 8e1122ff7bb8..4e3d592fcedc 100644 --- a/astropy/units/cgs.py +++ b/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') diff --git a/astropy/units/deprecated.py b/astropy/units/deprecated.py new file mode 100644 index 000000000000..bc72ac9cda90 --- /dev/null +++ b/astropy/units/deprecated.py @@ -0,0 +1,62 @@ +# -*- 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 will disable + all of the "default" `astropy.units` units, since there + are some namespace clashes between the two. + + This may be used with the ``with`` statement to enable deprecated + units only temporarily. + """ + # Local import to avoid cyclical import + from .core import set_enabled_units + # Local import to avoid polluting namespace + import inspect + return set_enabled_units(inspect.getmodule(enable)) diff --git a/astropy/units/tests/test_deprecated.py b/astropy/units/tests/test_deprecated.py new file mode 100644 index 000000000000..4dbeaf642c8b --- /dev/null +++ b/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 diff --git a/docs/units/index.rst b/docs/units/index.rst index 829ffcff4442..3021adb88a62 100644 --- a/docs/units/index.rst +++ b/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 - + `astropy.units` also handles :ref:`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 ===============