Skip to content

docs: Add note on return type of columns property #3575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
FBruzzesi wants to merge 4 commits into
base: main
Choose a base branch
from
+32 −2
Open

docs: Add note on return type of columns property #3575

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2d332c9
docs: Add note on return type of columns property
FBruzzesi Apr 25, 2026
f126b58
merge main
FBruzzesi Apr 26, 2026
934d15d
expand column_names.md
FBruzzesi Apr 26, 2026
beb053a
Add Note in Schema as well
FBruzzesi Apr 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/concepts/column_names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
14 changes: 14 additions & 0 deletions narwhals/dataframe.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]`.
Comment on lines +1357 to +1359
Copy link
Copy Markdown
Collaborator

@EdAbati EdAbati Apr 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the phrasing looks good!

I tried to find alternatives.

For the 2nd sentence we can use something like:
This is discouraged but supported, so the return type is not guaranteed to be list[str].

Or have it all one sentence:

Non-string column names (e.g. integers or booleans) are discouraged but supported by pandas-like and Dask backends, so the return type is not guaranteed to be list[str].

But again, I think your version looks good :)


See [concepts - column names](../concepts/column_names.md) for details.

Examples:
>>> import pyarrow as pa
>>> import narwhals as nw
Expand Down Expand Up @@ -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
Expand Down
17 changes: 16 additions & 1 deletion narwhals/schema.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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]:
Expand Down
Loading