diff --git a/docs/concepts/column_names.md b/docs/concepts/column_names.md index 0aee9d5ab9..c13846aa25 100644 --- a/docs/concepts/column_names.md +++ b/docs/concepts/column_names.md @@ -1,6 +1,7 @@ # Column names -Polars and PyArrow only allow for string column names. What about pandas? +The majority of backends, as Polars, PyArrow, duckdb and PySpark for example, +only allow for string column names. What about pandas-like and Dask backends? ```python exec="yes" source="above" result="python" session="col_names" import pandas as pd diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py index bd602efd52..703f97248e 100644 --- a/narwhals/dataframe.py +++ b/narwhals/dataframe.py @@ -1353,6 +1353,13 @@ def collect_schema(self) -> Schema: def columns(self) -> list[str]: """Get column names. + Note: + The pandas-like and dask backends allow non-string column names + (e.g. integers or booleans). While discouraged, this is supported, + so the return type is not guaranteed to be `list[str]`. + + See [concepts - column names](../concepts/column_names.md) for details. + Examples: >>> import pyarrow as pa >>> import narwhals as nw @@ -2638,6 +2645,13 @@ def collect_schema(self) -> Schema: def columns(self) -> list[str]: r"""Get column names. + Note: + The pandas-like and dask backends allow non-string column names + (e.g. integers or booleans). While discouraged, this is supported, + so the return type is not guaranteed to be `list[str]`. + + See [concepts - column names](../concepts/column_names.md) for details. + Examples: >>> import duckdb >>> import narwhals as nw diff --git a/narwhals/schema.py b/narwhals/schema.py index b459be68fa..4af3b57298 100644 --- a/narwhals/schema.py +++ b/narwhals/schema.py @@ -45,6 +45,13 @@ class Schema(OrderedDict[str, "DType"]): """Ordered mapping of column names to their data type. + Note: + The pandas-like and dask backends allow non-string column names + (e.g. integers or booleans). While discouraged, this is supported, + so we cannot guarantee that the keys are strictly strings. + + See [concepts - column names](../concepts/column_names.md) for details. + Arguments: schema: The schema definition given by column names and their associated *instantiated* Narwhals data type. Accepts a mapping or an iterable of tuples. @@ -81,7 +88,15 @@ def __init__( super().__init__(schema) def names(self) -> list[str]: - """Get the column names of the schema.""" + """Get the column names of the schema. + + Note: + The pandas-like and dask backends allow non-string column names + (e.g. integers or booleans). While discouraged, this is supported, + so the return type is not guaranteed to be `list[str]`. + + See [concepts - column names](../concepts/column_names.md) for details. + """ return list(self.keys()) def dtypes(self) -> list[DType]: