docs(python): Include warning in docstrings that accessing `LazyFrame…

…` properties may be expensive (#16618)

py-polars/polars/dataframe/frame.py

@@ -628,7 +628,11 @@ def shape(self) -> tuple[int, int]:
     @property
     def height(self) -> int:
         """
-        Get the height of the DataFrame.
+        Get the number of rows.
+
+        Returns
+        -------
+        int
 
         Examples
         --------
@@ -641,13 +645,22 @@ def height(self) -> int:
     @property
     def width(self) -> int:
         """
-        Get the width of the DataFrame.
+        Get the number of columns.
+
+        Returns
+        -------
+        int
 
         Examples
         --------
-        >>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5]})
+        >>> df = pl.DataFrame(
+        ...     {
+        ...         "foo": [1, 2, 3],
+        ...         "bar": [4, 5, 6],
+        ...     }
+        ... )
         >>> df.width
-        1
+        2
         """
         return self._df.width()
 
@@ -656,6 +669,11 @@ def columns(self) -> list[str]:
         """
         Get or set column names.
 
+        Returns
+        -------
+        list of str
+            A list containing the name of each column in order.
+
         Examples
         --------
         >>> df = pl.DataFrame(
@@ -701,13 +719,18 @@ def columns(self, names: Sequence[str]) -> None:
     @property
     def dtypes(self) -> list[DataType]:
         """
-        Get the datatypes of the columns of this DataFrame.
+        Get the column data types.
 
-        The datatypes can also be found in column headers when printing the DataFrame.
+        The data types can also be found in column headers when printing the DataFrame.
+
+        Returns
+        -------
+        list of DataType
+            A list containing the data type of each column in order.
 
         See Also
         --------
-        schema : Returns a {colname:dtype} mapping.
+        schema
 
         Examples
         --------
@@ -749,7 +772,12 @@ def flags(self) -> dict[str, dict[str, bool]]:
     @property
     def schema(self) -> OrderedDict[str, DataType]:
         """
-        Get a dict[column name, DataType].
+        Get a mapping of column names to their data type.
+
+        Returns
+        -------
+        OrderedDict
+            An ordered mapping of column names to their data type.
 
         Examples
         --------

py-polars/polars/lazyframe/frame.py

@@ -392,7 +392,18 @@ def deserialize(cls, source: str | Path | IOBase) -> Self:
     @property
     def columns(self) -> list[str]:
         """
-        Get column names.
+        Get the column names.
+
+        Returns
+        -------
+        list of str
+            A list containing the name of each column in order.
+
+        Warnings
+        --------
+        Determining the column names of a LazyFrame requires resolving its schema.
+        Resolving the schema of a LazyFrame can be an expensive operation.
+        Avoid accessing this property repeatedly if possible.
 
         Examples
         --------
@@ -411,11 +422,22 @@ def columns(self) -> list[str]:
     @property
     def dtypes(self) -> list[DataType]:
         """
-        Get dtypes of columns in LazyFrame.
+        Get the column data types.
+
+        Returns
+        -------
+        list of DataType
+            A list containing the data type of each column in order.
+
+        Warnings
+        --------
+        Determining the data types of a LazyFrame requires resolving its schema.
+        Resolving the schema of a LazyFrame can be an expensive operation.
+        Avoid accessing this property repeatedly if possible.
 
         See Also
         --------
-        schema : Returns a {colname:dtype} mapping.
+        schema
 
         Examples
         --------
@@ -434,7 +456,17 @@ def dtypes(self) -> list[DataType]:
     @property
     def schema(self) -> OrderedDict[str, DataType]:
         """
-        Get a dict[column name, DataType].
+        Get a mapping of column names to their data type.
+
+        Returns
+        -------
+        OrderedDict
+            An ordered mapping of column names to their data type.
+
+        Warnings
+        --------
+        Resolving the schema of a LazyFrame can be an expensive operation.
+        Avoid accessing this property repeatedly if possible.
 
         Examples
         --------
@@ -453,7 +485,17 @@ def schema(self) -> OrderedDict[str, DataType]:
     @property
     def width(self) -> int:
         """
-        Get the width of the LazyFrame.
+        Get the number of columns.
+
+        Returns
+        -------
+        int
+
+        Warnings
+        --------
+        Determining the width of a LazyFrame requires resolving its schema.
+        Resolving the schema of a LazyFrame can be an expensive operation.
+        Avoid accessing this property repeatedly if possible.
 
         Examples
         --------