narwhals-dev / narwhals

Lightweight and extensible compatibility layer between Polars, pandas, cuDF, Modin, and more!
https://narwhals-dev.github.io/narwhals/
MIT License
221 stars 32 forks source link

Make `DataFrame` and `LazyFrame` docstring examples follow `Expr` and `Series` templates #205

Open MarcoGorelli opened 1 month ago

MarcoGorelli commented 1 month ago

The DataFrame and LazyFrame docstrings were added a while ago, and they follow a different pattern compared with the more modern Expr and Series ones

I much prefer the newer ones - they allow us to really hammer-home the message that Narwhals is meant as an internal tool with which you can make your functions dataframe-agnostic

Can we update the DataFrame and LazyFrame docstrings examples to follow this template too? The template is:

  1. import pandas, Polars, and Narwhals
  2. define data = ..., and make df_pd and df_pl dataframes
  3. define a dataframe-agnostic function which uses the given method
  4. show that you can pass either pandas or Polars to the given method
  5. if there are any differences users need to be aware of, add a "Notes" section (e.g. null handling differences)
mfonekpo commented 1 month ago

I will work on this

FBruzzesi commented 5 days ago

Mentioning here hoping to simplify visibility. The methods that are still not following such template are: