fix: change empty to property (#425)

* breaking: make empty a property

* update release notes

* add deprecation wrapper

* add missing types

Author: coroa

doc/release_notes.rst

@@ -3,6 +3,13 @@ Release Notes
 
 Upcoming Version
 ----------------
+**Deprecations**
+
+* Renamed `expression.empty()` to `expression.empty` to align with the use of empty in
+  pandas. A custom wrapper ensures that `expression.empty()` continues to work, but emits
+  a DeprecationWarning.
+
+**Features**
 
 * Added support for arithmetic operations with custom classes.
 * Avoid allocating a floating license for COPT during the initial solver check

linopy/common.py

@@ -1005,3 +1005,34 @@ def __getitem__(
             labels = indexing.expanded_indexer(key, self.object.ndim)
             key = dict(zip(self.object.dims, labels))
         return self.object.sel(key)
+
+
+class EmptyDeprecationWrapper:
+    """
+    Temporary wrapper for a smooth transition from .empty() to .empty
+
+    Use `bool(expr.empty)` to explicitly unwrap.
+
+    See Also
+    --------
+    https://github.com/PyPSA/linopy/pull/425
+    """
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: bool):
+        self.value = value
+
+    def __bool__(self) -> bool:
+        return self.value
+
+    def __repr__(self) -> str:
+        return repr(self.value)
+
+    def __call__(self) -> bool:
+        warn(
+            "Calling `.empty()` is deprecated, use `.empty` property instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.value

linopy/expressions.py

@@ -37,6 +37,7 @@
 
 from linopy import constraints, variables
 from linopy.common import (
+    EmptyDeprecationWrapper,
     LocIndexer,
     as_dataarray,
     assign_multiindex_safe,
@@ -1347,11 +1348,16 @@ def size(self) -> int:
         """
         return self.vars.size
 
-    def empty(self) -> bool:
+    @property
+    def empty(self) -> EmptyDeprecationWrapper:
         """
         Get whether the linear expression is empty.
+
+        .. versionchanged:: 0.5.1
+           Returns a EmptyDeprecationWrapper which behaves like a bool and emits
+           a DeprecationWarning when called.
         """
-        return not self.size
+        return EmptyDeprecationWrapper(not self.size)
 
     def densify_terms(self) -> LinearExpression:
         """

linopy/model.py

@@ -9,10 +9,10 @@
 import logging
 import os
 import re
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from pathlib import Path
 from tempfile import NamedTemporaryFile, gettempdir
-from typing import Any, Callable
+from typing import Any
 
 import numpy as np
 import pandas as pd
@@ -705,7 +705,7 @@ def add_objective(
             The objective function assigned to the model.
         """
         if not overwrite:
-            assert self.objective.expression.empty(), (
+            assert self.objective.expression.empty, (
                 "Objective already defined."
                 " Set `overwrite` to True to force overwriting."
             )

test/test_linear_expression.py

@@ -541,8 +541,11 @@ def test_linear_expression_loc(x: Variable, y: Variable) -> None:
 
 def test_linear_expression_empty(v: Variable) -> None:
     expr = 7 * v
-    assert not expr.empty()
-    assert expr.loc[[]].empty()
+    assert not expr.empty
+    assert expr.loc[[]].empty
+
+    with pytest.warns(DeprecationWarning, match="use `.empty` property instead"):
+        assert expr.loc[[]].empty()
 
 
 def test_linear_expression_isnull(v: Variable) -> None: