diff --git a/README.md b/README.md index 3b5574860..4d813206c 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,12 @@ [![PyPI version](https://badge.fury.io/py/narwhals.svg)](https://badge.fury.io/py/narwhals) -[![Docs](https://img.shields.io/badge/Docs-coolgreen?style=flat&link=https://marcogorelli.github.io/narwhals/)](https://marcogorelli.github.io/narwhals/) -[![Chat with us! - Join Discord](https://img.shields.io/badge/Chat_with_us!-Join_Discord-coolgreen)](https://discord.gg/V3PqtB4VA4) Extremely lightweight and extensible compatibility layer between Polars, pandas, Modin, and cuDF (and more!). +- [Read the documentation](https://marcogorelli.github.io/narwhals/) +- [Chat with us on Discord!](https://discord.gg/V3PqtB4VA4) + Seamlessly support all, without depending on any! - ✅ **Just use** a subset of **the Polars API**, no need to learn anything new @@ -20,6 +21,7 @@ Seamlessly support all, without depending on any! - ✅ Separate **lazy** and eager APIs - ✅ Use **Expressions** - ✅ 100% branch coverage, tested against pandas and Polars nightly builds! +- ✅ Preserve your Index (if present) without it getting in the way! ## Used by diff --git a/docs/extending.md b/docs/extending.md index f6f346c14..9fb516fb2 100644 --- a/docs/extending.md +++ b/docs/extending.md @@ -1,14 +1,22 @@ -# How Narwhals can support your dataframe as well! +# List of supported libraries (and how yours can join this list!) -Currently, Narwhals recognises the following libraries as inputs: +Currently, Narwhals supports the following libraries as inputs: - pandas - Polars - cuDF - Modin -If you want your own library to be recognised too, you can either open a PR (with tests) or -you can make sure that, in addition to the public Narwhals API, you also define: +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. + +## 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` @@ -25,4 +33,8 @@ you can make sure that, in addition to the public Narwhals API, you also define: 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.PandasDataFrame` does! + that's currently what `narwhals._pandas_like.dataframe.PandasDataFrame`, 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 you anything's 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 e6d3d10ca..6bb427787 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,6 +11,7 @@ Seamlessly support both, without depending on either! - ✅ Support both **lazy** and eager execution - ✅ Use **Expressions** - ✅ Tested against pandas and Polars nightly builds! +- ✅ Preserve your Index (if present) without it getting in the way! ## Who's this for? diff --git a/mkdocs.yml b/mkdocs.yml index 1e6b4fd3d..e22fbc9e3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,7 +9,7 @@ nav: - basics/dataframe.md - basics/column.md - basics/complete_example.md - - Extending: extending.md + - extending.md - Roadmap: roadmap.md - Related projects: related.md - API Reference: