Skip to main content
`Ctrl`+`K`

# Source code for astropy.units.imperial

    # Licensed under a 3-clause BSD style license - see LICENSE.rst

    """Colloquially used Imperial units.

    These units are available in the `astropy.units.imperial` namespace, but not in the
    top-level `astropy.units` namespace, e.g.::

        >>> import astropy.units as u
        >>> mph = u.imperial.mile / u.hour
        >>> mph
        Unit("mi / h")

    To include them in `~astropy.units.UnitBase.compose` and the results of
    `~astropy.units.UnitBase.find_equivalent_units`, do::

        >>> import astropy.units as u
        >>> u.imperial.enable()  # doctest: +SKIP
    """
    # avoid ruff complaints about undefined names defined by def_unit
    # ruff: noqa: F821

    __all__: list[str] = ["enable"]  #  Units are added at the end

    from . import si
    from .core import _UnitContext, add_enabled_units, def_unit
    from .docgen import generate_dunder_all, generate_unit_summary

    _ns = globals()

    ###########################################################################
    # LENGTH

    def_unit(["inch"], 2.54 * si.cm, namespace=_ns, doc="International inch")
    def_unit(["ft", "foot"], 12 * inch, namespace=_ns, doc="International foot")
    def_unit(["yd", "yard"], 3 * ft, namespace=_ns, doc="International yard")
    def_unit(["mi", "mile"], 5280 * ft, namespace=_ns, doc="International mile")
    def_unit(["mil", "thou"], 0.001 * inch, namespace=_ns, doc="Thousandth of an inch")
    def_unit(["nmi", "nauticalmile", "NM"], 1852 * si.m, namespace=_ns, doc="Nautical mile")
    def_unit(["fur", "furlong"], 660 * ft, namespace=_ns, doc="Furlong")

    ###########################################################################
    # AREAS

    def_unit(["ac", "acre"], 43560 * ft**2, namespace=_ns, doc="International acre")

    ###########################################################################
    # VOLUMES

    def_unit(["gallon"], si.liter / 0.264172052, namespace=_ns, doc="U.S. liquid gallon")
    def_unit(["quart"], gallon / 4, namespace=_ns, doc="U.S. liquid quart")
    def_unit(["pint"], quart / 2, namespace=_ns, doc="U.S. liquid pint")
    def_unit(["cup"], pint / 2, namespace=_ns, doc="U.S. customary cup")
    def_unit(
        ["foz", "fluid_oz", "fluid_ounce"], cup / 8, namespace=_ns, doc="U.S. fluid ounce"
    )
    def_unit(
        ["tbsp", "tablespoon"], foz / 2, namespace=_ns, doc="U.S. customary tablespoon"
    )
    def_unit(["tsp", "teaspoon"], tbsp / 3, namespace=_ns, doc="U.S. customary teaspoon")

    ###########################################################################
    # MASS

    def_unit(
        ["oz", "ounce"],
        28.349523125 * si.g,
        namespace=_ns,
        doc="International avoirdupois ounce: mass",
    )
    def_unit(
        ["lb", "lbm", "pound"],
        16 * oz,
        namespace=_ns,
        doc="International avoirdupois pound: mass",
    )
    def_unit(
        ["st", "stone"], 14 * lb, namespace=_ns, doc="International avoirdupois stone: mass"
    )
    def_unit(["ton"], 2000 * lb, namespace=_ns, doc="International avoirdupois ton: mass")
    def_unit(["slug"], 32.174049 * lb, namespace=_ns, doc="slug: mass")

    ###########################################################################
    # SPEED

    def_unit(
        ["kn", "kt", "knot", "NMPH"],
        nmi / si.h,
        namespace=_ns,
        doc="nautical unit of speed: 1 nmi per hour",
    )

    ###########################################################################
    # FORCE

    def_unit("lbf", slug * ft * si.s**-2, namespace=_ns, doc="Pound: force")
    def_unit(["kip", "kilopound"], 1000 * lbf, namespace=_ns, doc="Kilopound: force")

    ##########################################################################
    # ENERGY

    def_unit(["BTU", "btu"], 1.05505585 * si.kJ, namespace=_ns, doc="British thermal unit")
    def_unit(
        ["cal", "calorie"],
        4.184 * si.J,
        namespace=_ns,
        doc="Thermochemical calorie: pre-SI metric unit of energy",
    )
    def_unit(
        ["kcal", "Cal", "Calorie", "kilocal", "kilocalorie"],
        1000 * cal,
        namespace=_ns,
        doc="Calorie: colloquial definition of Calorie",
    )

    ##########################################################################
    # PRESSURE

    def_unit("psi", lbf * inch**-2, namespace=_ns, doc="Pound per square inch: pressure")

    ###########################################################################
    # POWER

    # Imperial units
    def_unit(
        ["hp", "horsepower"],
        si.W / 0.00134102209,
        namespace=_ns,
        doc="Electrical horsepower",
    )

    ###########################################################################
    # TEMPERATURE

    def_unit(
        ["deg_F", "Fahrenheit"],
        namespace=_ns,
        doc="Degrees Fahrenheit",
        format={"latex": r"{}^{\circ}F", "unicode": "°F"},
    )
    def_unit(
        ["deg_R", "Rankine"],
        5 / 9 * si.K,
        namespace=_ns,
        doc="Rankine scale: absolute scale of thermodynamic temperature",
        format={"latex": r"{}^{\circ}R", "unicode": "°R"},
    )

    ###########################################################################
    # ALL & DOCSTRING

    __all__ += generate_dunder_all(globals())  # noqa: PLE0605

    if __doc__ is not None:
        # This generates a docstring for this module that describes all of the
        # standard units defined here.
        __doc__ += generate_unit_summary(globals())

    def enable() -> _UnitContext:
        """
        Enable Imperial 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 Imperial
        units only temporarily.
        """
        return add_enabled_units(globals())