Deprecate conversion utilities (#78957)

* Deprecate utilities

* Deprecate distance and speed

* Add tests

* Adjust pylint

* Simplify temperature deprecation

homeassistant/util/distance.py

@@ -13,6 +13,7 @@ from homeassistant.const import (  # pylint: disable=unused-import # noqa: F401
     LENGTH_YARD,
     UNIT_NOT_RECOGNIZED_TEMPLATE,
 )
+from homeassistant.helpers.frame import report
 
 from .unit_conversion import DistanceConverter
 
@@ -21,4 +22,10 @@ VALID_UNITS = DistanceConverter.VALID_UNITS
 
 def convert(value: float, from_unit: str, to_unit: str) -> float:
     """Convert one unit of measurement to another."""
+    report(
+        "uses distance utility. This is deprecated since 2022.10 and will "
+        "stop working in Home Assistant 2022.4, it should be updated to use "
+        "unit_conversion.DistanceConverter instead",
+        error_if_core=False,
+    )
     return DistanceConverter.convert(value, from_unit, to_unit)

homeassistant/util/pressure.py

@@ -14,6 +14,7 @@ from homeassistant.const import (  # pylint: disable=unused-import # noqa: F401
     PRESSURE_PSI,
     UNIT_NOT_RECOGNIZED_TEMPLATE,
 )
+from homeassistant.helpers.frame import report
 
 from .unit_conversion import PressureConverter
 
@@ -24,5 +25,10 @@ VALID_UNITS = PressureConverter.VALID_UNITS
 
 def convert(value: float, from_unit: str, to_unit: str) -> float:
     """Convert one unit of measurement to another."""
-    # Need to add warning when core migration finished
+    report(
+        "uses pressure utility. This is deprecated since 2022.10 and will "
+        "stop working in Home Assistant 2022.4, it should be updated to use "
+        "unit_conversion.PressureConverter instead",
+        error_if_core=False,
+    )
     return PressureConverter.convert(value, from_unit, to_unit)

homeassistant/util/speed.py

@@ -13,6 +13,7 @@ from homeassistant.const import (  # pylint: disable=unused-import # noqa: F401
     SPEED_MILLIMETERS_PER_DAY,
     UNIT_NOT_RECOGNIZED_TEMPLATE,
 )
+from homeassistant.helpers.frame import report
 
 from .unit_conversion import (  # pylint: disable=unused-import # noqa: F401
     _FOOT_TO_M as FOOT_TO_M,
@@ -31,4 +32,10 @@ VALID_UNITS = SpeedConverter.VALID_UNITS
 
 def convert(value: float, from_unit: str, to_unit: str) -> float:
     """Convert one unit of measurement to another."""
+    report(
+        "uses speed utility. This is deprecated since 2022.10 and will "
+        "stop working in Home Assistant 2022.4, it should be updated to use "
+        "unit_conversion.SpeedConverter instead",
+        error_if_core=False,
+    )
     return SpeedConverter.convert(value, from_unit, to_unit)

homeassistant/util/temperature.py

@@ -6,6 +6,7 @@ from homeassistant.const import (  # pylint: disable=unused-import # noqa: F401
     TEMPERATURE,
     UNIT_NOT_RECOGNIZED_TEMPLATE,
 )
+from homeassistant.helpers.frame import report
 
 from .unit_conversion import TemperatureConverter
 
@@ -14,33 +15,34 @@ VALID_UNITS = TemperatureConverter.VALID_UNITS
 
 def fahrenheit_to_celsius(fahrenheit: float, interval: bool = False) -> float:
     """Convert a temperature in Fahrenheit to Celsius."""
-    # Need to add warning when core migration finished
+    return convert(fahrenheit, TEMP_FAHRENHEIT, TEMP_CELSIUS, interval)
-    return TemperatureConverter.fahrenheit_to_celsius(fahrenheit, interval)
 
 
 def kelvin_to_celsius(kelvin: float, interval: bool = False) -> float:
     """Convert a temperature in Kelvin to Celsius."""
-    # Need to add warning when core migration finished
+    return convert(kelvin, TEMP_KELVIN, TEMP_CELSIUS, interval)
-    return TemperatureConverter.kelvin_to_celsius(kelvin, interval)
 
 
 def celsius_to_fahrenheit(celsius: float, interval: bool = False) -> float:
     """Convert a temperature in Celsius to Fahrenheit."""
-    # Need to add warning when core migration finished
+    return convert(celsius, TEMP_CELSIUS, TEMP_FAHRENHEIT, interval)
-    return TemperatureConverter.celsius_to_fahrenheit(celsius, interval)
 
 
 def celsius_to_kelvin(celsius: float, interval: bool = False) -> float:
     """Convert a temperature in Celsius to Fahrenheit."""
-    # Need to add warning when core migration finished
+    return convert(celsius, TEMP_CELSIUS, TEMP_KELVIN, interval)
-    return TemperatureConverter.celsius_to_kelvin(celsius, interval)
 
 
 def convert(
     temperature: float, from_unit: str, to_unit: str, interval: bool = False
 ) -> float:
     """Convert a temperature from one unit to another."""
-    # Need to add warning when core migration finished
+    report(
+        "uses temperature utility. This is deprecated since 2022.10 and will "
+        "stop working in Home Assistant 2022.4, it should be updated to use "
+        "unit_conversion.TemperatureConverter instead",
+        error_if_core=False,
+    )
     return TemperatureConverter.convert(
         temperature, from_unit, to_unit, interval=interval
     )

homeassistant/util/volume.py

@@ -11,6 +11,7 @@ from homeassistant.const import (  # pylint: disable=unused-import # noqa: F401
     VOLUME_LITERS,
     VOLUME_MILLILITERS,
 )
+from homeassistant.helpers.frame import report
 
 from .unit_conversion import VolumeConverter
 
@@ -21,35 +22,30 @@ VALID_UNITS = VolumeConverter.VALID_UNITS
 
 def liter_to_gallon(liter: float) -> float:
     """Convert a volume measurement in Liter to Gallon."""
-    # Need to add warning when core migration finished
+    return convert(liter, VOLUME_LITERS, VOLUME_GALLONS)
-    return _convert(liter, VOLUME_LITERS, VOLUME_GALLONS)
 
 
 def gallon_to_liter(gallon: float) -> float:
     """Convert a volume measurement in Gallon to Liter."""
-    # Need to add warning when core migration finished
+    return convert(gallon, VOLUME_GALLONS, VOLUME_LITERS)
-    return _convert(gallon, VOLUME_GALLONS, VOLUME_LITERS)
 
 
 def cubic_meter_to_cubic_feet(cubic_meter: float) -> float:
     """Convert a volume measurement in cubic meter to cubic feet."""
-    # Need to add warning when core migration finished
+    return convert(cubic_meter, VOLUME_CUBIC_METERS, VOLUME_CUBIC_FEET)
-    return _convert(cubic_meter, VOLUME_CUBIC_METERS, VOLUME_CUBIC_FEET)
 
 
 def cubic_feet_to_cubic_meter(cubic_feet: float) -> float:
     """Convert a volume measurement in cubic feet to cubic meter."""
-    # Need to add warning when core migration finished
+    return convert(cubic_feet, VOLUME_CUBIC_FEET, VOLUME_CUBIC_METERS)
-    return _convert(cubic_feet, VOLUME_CUBIC_FEET, VOLUME_CUBIC_METERS)
 
 
 def convert(volume: float, from_unit: str, to_unit: str) -> float:
     """Convert a volume from one unit to another."""
-    # Need to add warning when core migration finished
+    report(
+        "uses volume utility. This is deprecated since 2022.10 and will "
+        "stop working in Home Assistant 2022.4, it should be updated to use "
+        "unit_conversion.VolumeConverter instead",
+        error_if_core=False,
+    )
     return VolumeConverter.convert(volume, from_unit, to_unit)
-
-
-def _convert(volume: float, from_unit: str, to_unit: str) -> float:
-    """Convert a volume from one unit to another, bypassing checks."""
-    cubic_meter = volume / UNIT_CONVERSION[from_unit]
-    return cubic_meter * UNIT_CONVERSION[to_unit]

pylint/plugins/hass_imports.py

@@ -286,6 +286,12 @@ _OBSOLETE_IMPORT: dict[str, list[ObsoleteImportMatch]] = {
             constant=re.compile(r"^DISABLED_(\w*)$"),
         ),
     ],
+    "homeassistant.util": [
+        ObsoleteImportMatch(
+            reason="replaced by unit_conversion.***Converter",
+            constant=re.compile(r"^(distance|pressure|speed|temperature|volume)$"),
+        ),
+    ],
 }
 
 

tests/util/test_distance.py

@@ -19,6 +19,12 @@ INVALID_SYMBOL = "bob"
 VALID_SYMBOL = LENGTH_KILOMETERS
 
 
+def test_raise_deprecation_warning(caplog: pytest.LogCaptureFixture) -> None:
+    """Ensure that a warning is raised on use of convert."""
+    assert distance_util.convert(2, LENGTH_METERS, LENGTH_METERS) == 2
+    assert "use unit_conversion.DistanceConverter instead" in caplog.text
+
+
 def test_convert_same_unit():
     """Test conversion from any unit to same unit."""
     assert distance_util.convert(5, LENGTH_KILOMETERS, LENGTH_KILOMETERS) == 5

tests/util/test_pressure.py

@@ -18,6 +18,12 @@ INVALID_SYMBOL = "bob"
 VALID_SYMBOL = PRESSURE_PA
 
 
+def test_raise_deprecation_warning(caplog: pytest.LogCaptureFixture) -> None:
+    """Ensure that a warning is raised on use of convert."""
+    assert pressure_util.convert(2, PRESSURE_PA, PRESSURE_PA) == 2
+    assert "use unit_conversion.PressureConverter instead" in caplog.text
+
+
 def test_convert_same_unit():
     """Test conversion from any unit to same unit."""
     assert pressure_util.convert(2, PRESSURE_PA, PRESSURE_PA) == 2

tests/util/test_speed.py

@@ -18,6 +18,12 @@ INVALID_SYMBOL = "bob"
 VALID_SYMBOL = SPEED_KILOMETERS_PER_HOUR
 
 
+def test_raise_deprecation_warning(caplog: pytest.LogCaptureFixture) -> None:
+    """Ensure that a warning is raised on use of convert."""
+    assert speed_util.convert(2, SPEED_INCHES_PER_DAY, SPEED_INCHES_PER_DAY) == 2
+    assert "use unit_conversion.SpeedConverter instead" in caplog.text
+
+
 def test_convert_same_unit():
     """Test conversion from any unit to same unit."""
     assert speed_util.convert(2, SPEED_INCHES_PER_DAY, SPEED_INCHES_PER_DAY) == 2

tests/util/test_temperature.py

@@ -9,6 +9,12 @@ INVALID_SYMBOL = "bob"
 VALID_SYMBOL = TEMP_CELSIUS
 
 
+def test_raise_deprecation_warning(caplog: pytest.LogCaptureFixture) -> None:
+    """Ensure that a warning is raised on use of convert."""
+    assert temperature_util.convert(2, TEMP_CELSIUS, TEMP_CELSIUS) == 2
+    assert "use unit_conversion.TemperatureConverter instead" in caplog.text
+
+
 @pytest.mark.parametrize(
     "function_name, value, expected",
     [

tests/util/test_volume.py

@@ -17,6 +17,12 @@ INVALID_SYMBOL = "bob"
 VALID_SYMBOL = VOLUME_LITERS
 
 
+def test_raise_deprecation_warning(caplog: pytest.LogCaptureFixture) -> None:
+    """Ensure that a warning is raised on use of convert."""
+    assert volume_util.convert(2, VOLUME_LITERS, VOLUME_LITERS) == 2
+    assert "use unit_conversion.VolumeConverter instead" in caplog.text
+
+
 @pytest.mark.parametrize(
     "function_name, value, expected",
     [