diff --git a/README.md b/README.md index 29623920a..847943486 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,12 @@ Extremely lightweight and extensible compatibility layer between dataframe libraries! - **Full API support**: cuDF, Modin, pandas, Polars, PyArrow +- **Lazy-only support**: Dask - **Interchange-level support**: Ibis, Vaex, anything else which implements the DataFrame Interchange Protocol Seamlessly support all, without depending on any! -- ✅ **Just use** a subset of **the Polars API**, no need to learn anything new +- ✅ **Just use** [a subset of **the Polars API**](https://narwhals-dev.github.io/narwhals/api-reference/), no need to learn anything new - ✅ **Zero dependencies**, Narwhals only uses what the user passes in so your library can stay lightweight - ✅ Separate **lazy** and eager APIs, use **expressions** @@ -117,6 +118,9 @@ Narwhals has been featured in several talks, podcasts, and blog posts: - [Talk Python to me Podcast](https://youtu.be/FSH7BZ0tuE0) Ahoy, Narwhals are bridging the data science APIs +- [Python Bytes Podcast](https://www.youtube.com/live/N7w_ESVW40I?si=y-wN1uCsAuJOKlOT&t=382) + Ahoy, Narwhals are bridging the data science APIs + - [Super Data Science: ML & AI Podcast](https://www.youtube.com/watch?v=TeG4U8R0U8U) Narwhals: For Pandas-to-Polars DataFrame Compatibility diff --git a/docs/css/mkdocstrings.css b/docs/css/mkdocstrings.css deleted file mode 100644 index 0951698ad..000000000 --- a/docs/css/mkdocstrings.css +++ /dev/null @@ -1,9 +0,0 @@ -.md-header__topic { - font-size: 200%; - font-family: Verdana, Geneva, Tahoma, sans-serif; -} - -.md-header__button.md-logo img { - height: 22%; - width: 22%; - } \ No newline at end of file diff --git a/docs/extending.md b/docs/extending.md index f6829ba3f..22d85f701 100644 --- a/docs/extending.md +++ b/docs/extending.md @@ -2,7 +2,7 @@ ## List of supported libraries (and how to add yours!) -Currently, Narwhals supports the following libraries as inputs: +Currently, Narwhals has full API support for the following libraries: | Library | 🔗 Link 🔗 | | ------------- | ------------- | @@ -12,46 +12,13 @@ Currently, Narwhals supports the following libraries as inputs: | Modin | [github.com/modin-project/modin](https://github.com/modin-project/modin) | | PyArrow ⇶ | [arrow.apache.org/docs/python](https://arrow.apache.org/docs/python/index.html) | -If you want your own library to be recognised too, you're welcome open a PR (with tests)! -Alternatively, if you can't do that (for example, if you library is closed-source), see -the next section for what else you can do. - -To check which methods are supported for which backend in depth, please refer to the -[API completeness page](api-completeness/index.md). - -## Extending Narwhals - -We love open source, but we're not "open source absolutists". If you're unable to open -source you library, then this is how you can make your library compatible with Narwhals. - -Make sure that, in addition to the public Narwhals API, you also define: - - - `DataFrame.__narwhals_dataframe__`: return an object which implements public methods - from `Narwhals.DataFrame` - - `DataFrame.__narwhals_namespace__`: return an object which implements public top-level - functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...) - - `DataFrame.__native_namespace__`: return a native namespace object which must have a - `from_dict` method - - `LazyFrame.__narwhals_lazyframe__`: return an object which implements public methods - from `Narwhals.LazyFrame` - - `LazyFrame.__narwhals_namespace__`: return an object which implements public top-level - functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...) - - `LazyFrame.__native_namespace__`: return a native namespace object which must have a - `from_dict` method - - `Series.__narwhals_series__`: return an object which implements public methods - from `Narwhals.Series` - - If your library doesn't distinguish between lazy and eager, then it's OK for your dataframe - object to implement both `__narwhals_dataframe__` and `__narwhals_lazyframe__`. In fact, - that's currently what `narwhals._pandas_like.dataframe.PandasLikeDataFrame` does. So, if you're stuck, - take a look at the source code to see how it's done! - -Note that the "extension" mechanism is still experimental. If anything is not clear, or -doesn't work, please do raise an issue or contact us on Discord (see the link on the README). +It also has lazy-only support for [Dask](https://github.com/dask/dask), and interchange-only support +for [DuckDB](https://github.com/duckdb/duckdb) and [Ibis](https://github.com/ibis-project/ibis). -## Levels +### Levels -Narwhals comes with two levels of support: "full" and "interchange". +Narwhals comes with two levels of support ("full" and "interchange"), and we are working on defining +a "lazy-only" level too. Libraries for which we have full support can benefit from the whole [Narwhals API](https://narwhals-dev.github.io/narwhals/api-reference/). @@ -91,4 +58,38 @@ def func(df: Any) -> Schema: return df.schema ``` is also supported, meaning that, in addition to the libraries mentioned above, you can -also pass Ibis, Vaex, PyArrow, and any other library which implements the protocol. +also pass Ibis, DuckDB, Vaex, and any library which implements the protocol. + +### Extending Narwhals + +If you want your own library to be recognised too, you're welcome open a PR (with tests)!. +Alternatively, if you can't do that (for example, if you library is closed-source), see +the next section for what else you can do. + +We love open source, but we're not "open source absolutists". If you're unable to open +source you library, then this is how you can make your library compatible with Narwhals. + +Make sure that, in addition to the public Narwhals API, you also define: + + - `DataFrame.__narwhals_dataframe__`: return an object which implements public methods + from `Narwhals.DataFrame` + - `DataFrame.__narwhals_namespace__`: return an object which implements public top-level + functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...) + - `DataFrame.__native_namespace__`: return a native namespace object which must have a + `from_dict` method + - `LazyFrame.__narwhals_lazyframe__`: return an object which implements public methods + from `Narwhals.LazyFrame` + - `LazyFrame.__narwhals_namespace__`: return an object which implements public top-level + functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...) + - `LazyFrame.__native_namespace__`: return a native namespace object which must have a + `from_dict` method + - `Series.__narwhals_series__`: return an object which implements public methods + from `Narwhals.Series` + + If your library doesn't distinguish between lazy and eager, then it's OK for your dataframe + object to implement both `__narwhals_dataframe__` and `__narwhals_lazyframe__`. In fact, + that's currently what `narwhals._pandas_like.dataframe.PandasLikeDataFrame` does. So, if you're stuck, + take a look at the source code to see how it's done! + +Note that this "extension" mechanism is still experimental. If anything is not clear, or +doesn't work, please do raise an issue or contact us on Discord (see the link on the README). diff --git a/docs/index.md b/docs/index.md index 1269f70d8..f18d9af85 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,11 +2,15 @@ ![](assets/image.png) -Extremely lightweight compatibility layer between Polars, pandas, and more. +Extremely lightweight and extensible compatibility layer between dataframe libraries! -Seamlessly support both, without depending on either! +- **Full API support**: cuDF, Modin, pandas, Polars, PyArrow +- **Lazy-only support**: Dask +- **Interchange-level support**: Ibis, Vaex, anything else which implements the DataFrame Interchange Protocol -- ✅ **Just use** a subset of **the Polars API**, no need to learn anything new +Seamlessly support all, without depending on any! + +- ✅ **Just use** [a subset of **the Polars API**](https://narwhals-dev.github.io/narwhals/api-reference/), no need to learn anything new - ✅ **Zero dependencies**, Narwhals only uses what the user passes in so your library can stay lightweight - ✅ Separate **lazy** and eager APIs, use **expressions** diff --git a/mkdocs.yml b/mkdocs.yml index ccd4307ae..10c3741ed 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,11 +19,12 @@ nav: - extending.md - how_it_works.md - Roadmap and related projects: roadmap_and_related.md - - API Completeness: - - api-completeness/index.md - - Supported DataFrame methods: api-completeness/dataframe.md - - Supporteda Expr methods: api-completeness/expr.md - - Supported Series methods: api-completeness/series.md + # Commented-out until https://github.com/narwhals-dev/narwhals/issues/1004 is addressed + # - API Completeness: + # - api-completeness/index.md + # - Supported DataFrame methods: api-completeness/dataframe.md + # - Supported Expr methods: api-completeness/expr.md + # - Supported Series methods: api-completeness/series.md - API Reference: - api-reference/narwhals.md - api-reference/dataframe.md