docs(python): Clarify explanation and examples for .eq_missing

py-polars/docs/source/reference/series/index.rst

@@ -20,6 +20,7 @@ This page gives an overview of all public Series methods.
    list
    modify_select
    miscellaneous
+   operators
    plot
    string
    struct

py-polars/docs/source/reference/series/operators.rst

@@ -0,0 +1,27 @@
+=========
+Operators
+=========
+
+Comparison
+~~~~~~~~~~
+
+.. currentmodule:: polars
+.. autosummary::
+   :toctree: api/
+
+   Series.eq
+   Series.eq_missing
+   Series.ge
+   Series.gt
+   Series.le
+   Series.lt
+   Series.ne
+   Series.ne_missing
+
+Numeric
+~~~~~~~
+
+.. autosummary::
+   :toctree: api/
+
+   Series.pow

py-polars/polars/expr/expr.py

@@ -5005,9 +5005,12 @@ def eq(self, other: Any) -> Self:
 
     def eq_missing(self, other: Any) -> Self:
         """
-        Method equivalent of equality operator `expr == other` where `None == None`.
+        Equality operator where null is treated as a distinct value.
 
         This differs from default `eq` where null values are propagated.
+        With this method, null is equal to null and is not equal to any other value.
+
+
 
         Parameters
         ----------
@@ -5018,8 +5021,8 @@ def eq_missing(self, other: Any) -> Self:
         --------
         >>> df = pl.DataFrame(
         ...     data={
-        ...         "x": [1.0, 2.0, float("nan"), 4.0, None, None],
-        ...         "y": [2.0, 2.0, float("nan"), 4.0, 5.0, None],
+        ...         "x": [1.0, 2.0, float("nan"), None, None, 5.0],
+        ...         "y": [2.0, 2.0, float("nan"), None, 5.0, None],
         ...     }
         ... )
         >>> df.with_columns(
@@ -5035,9 +5038,9 @@ def eq_missing(self, other: Any) -> Self:
         │ 1.0  ┆ 2.0  ┆ false  ┆ false          │
         │ 2.0  ┆ 2.0  ┆ true   ┆ true           │
         │ NaN  ┆ NaN  ┆ true   ┆ true           │
-        │ 4.0  ┆ 4.0  ┆ true   ┆ true           │
-        │ null ┆ 5.0  ┆ null   ┆ false          │
         │ null ┆ null ┆ null   ┆ true           │
+        │ null ┆ 5.0  ┆ null   ┆ false          │
+        │ 5.0  ┆ null ┆ null   ┆ false          │
         └──────┴──────┴────────┴────────────────┘
         """
         other = parse_into_expression(other, str_as_lit=True)

py-polars/polars/series/series.py

@@ -820,9 +820,11 @@ def eq_missing(self, other: Any) -> Series: ...
 
     def eq_missing(self, other: Any) -> Series | Expr:
         """
-        Method equivalent of equality operator `series == other` where `None == None`.
+        Equality operator where null is treated as a distinct value.
 
-        This differs from the standard `ne` where null values are propagated.
+        This differs from default `eq` where null values are propagated.
+        Equality operator where null is treated as a distinct value.
+        With this method, null is equal to null and is not equal to any other value.
 
         Parameters
         ----------
@@ -836,23 +838,27 @@ def eq_missing(self, other: Any) -> Series | Expr:
 
         Examples
         --------
-        >>> s1 = pl.Series("a", [333, 200, None])
-        >>> s2 = pl.Series("a", [100, 200, None])
+        >>> s1 = pl.Series("a", [333, 200, None, 100, None])
+        >>> s2 = pl.Series("a", [100, 200, None, None, 100])
         >>> s1.eq(s2)
-        shape: (3,)
+        shape: (5,)
         Series: 'a' [bool]
         [
             false
             true
             null
+            null
+            null
         ]
         >>> s1.eq_missing(s2)
-        shape: (3,)
+        shape: (5,)
         Series: 'a' [bool]
         [
             false
             true
             true
+            false
+            false
         ]
         """
         if isinstance(other, pl.Expr):