Narwhals

https://narwhals-dev.github.io/narwhals
Admin
Narwhals is an extremely lightweight and extensible compatibility layer that enables...
Tokens:185,410
Snippets:1,188
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Narwhals using UV

Source: https://narwhals-dev.github.io/narwhals/installation

Installs the Narwhals library using the UV package manager. Assumes a Python 3.8+ virtual environment is already set up and activated.

```bash
uv pip install narwhals
```

--------------------------------

### Install Narwhals using pip

Source: https://narwhals-dev.github.io/narwhals/installation

Installs the Narwhals library using pip. Assumes a Python 3.8+ virtual environment is already set up and activated.

```bash
python -m pip install narwhals
```

--------------------------------

### Verify Narwhals Installation

Source: https://narwhals-dev.github.io/narwhals/installation

Checks if Narwhals is installed correctly by importing the library and printing its version number in the Python REPL.

```python
import narwhals

print(narwhals.__version__)
```

--------------------------------

### Narwhals Dataframe-Agnostic Function Example

Source: https://narwhals-dev.github.io/narwhals/installation

Demonstrates a dataframe-agnostic function `agnostic_get_columns` that retrieves column names from native pandas, Polars, and PyArrow data structures using Narwhals.

```python
from __future__ import annotations

import pandas as pd
import polars as pl
import pyarrow as pa
import narwhals as nw
from narwhals.typing import IntoFrame


def agnostic_get_columns(df_native: IntoFrame) -> list[str]:
    df = nw.from_native(df_native)
    column_names = df.columns
    return column_names


data = {"a": [1, 2, 3], "b": [4, 5, 6]}
df_pandas = pd.DataFrame(data)
df_polars = pl.DataFrame(data)
table_pa = pa.table(data)

print("pandas output")
print(agnostic_get_columns(df_pandas))

print("Polars output")
print(agnostic_get_columns(df_polars))

print("PyArrow output")
print(agnostic_get_columns(table_pa))
```

--------------------------------

### Get Implementation of Narwhals Series (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/series

Demonstrates how to retrieve the `narwhals.Implementation` enum for a `narwhals.Series`. This is useful for backend-specific logic. The example shows checking if the implementation is pandas-like.

```python
import narwhals as nw
import pandas as pd

s_native = pd.Series([1, 2, 3])
s = nw.from_native(s_native, series_only=True)

print(s.implementation)
print(s.implementation.is_pandas())
print(s.implementation.is_pandas_like())
print(s.implementation.is_polars())

```

--------------------------------

### Example: Collecting Schema with collect_schema in Narwhals

Source: https://narwhals-dev.github.io/narwhals/api-reference/dataframe

This example shows how to create a Narwhals DataFrame from a PyArrow table and then use the collect_schema method to retrieve its schema. The output displays the column names and their associated data types.

```python
>>> import pyarrow as pa
>>> import narwhals as nw
>>> df_native = pa.table({"foo": [1, 2], "bar": [6.0, 7.0]})
>>> nw.from_native(df_native).collect_schema()
Schema({'foo': Int64, 'bar': Float64})
```

--------------------------------

### String Starts With

Source: https://narwhals-dev.github.io/narwhals/api-reference/expr_str

Checks if string values in a column start with a specified prefix.

```APIDOC
## starts_with

### Description
Check if string values start with a substring.

### Method
This is a method on a Narwhals column expression.

### Endpoint
N/A (This is a method, not a REST endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
*   **prefix** (str) - Required - The prefix substring to check for.

### Request Example
```python
import pandas as pd
import narwhals as nw

df_native = pd.DataFrame({"fruits": ["apple", "mango", None]})
df = nw.from_native(df_native)
df.with_columns(has_prefix=nw.col("fruits").str.starts_with("app"))
```

### Response
#### Success Response (200)
Returns a DataFrame with a new boolean column indicating if the string starts with the prefix.

#### Response Example
```json
{
  "example": "┌────────────────────┐\n| Narwhals DataFrame |\n|--------------------|\n|  fruits  has_prefix|\n|0  apple        True|\n|1  mango       False|\n|2    NaN       False|\n└────────────────────┘"
}
```
```

--------------------------------

### Get Elements from Narwhals Series using Indexing (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/series

Illustrates how to use the `__getitem__` method to retrieve elements from a `narwhals.Series` using integer indexing, slicing, or multi-index selectors. Examples show retrieving a single element and a subset of the Series.

```python
import pyarrow as pa
import narwhals as nw

s_native = pa.chunked_array([[1, 2, 3]])
s = nw.from_native(s_native, series_only=True)

# Get single element
print(s[0])

# Get a subset using slicing and convert back to native
subset_native = s[:2].to_native()
print(subset_native)

```

--------------------------------

### Example: Reading Parquet with Implementation Backend (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/typing

Shows how to read a Parquet file using a Narwhals Implementation enum for the backend, such as `nw.Implementation.PYARROW`.

```python
>>> import narwhals as nw
>>> nw.read_parquet("file.parquet", backend=nw.Implementation.PYARROW)
┌──────────────────┐
|Narwhals DataFrame|
|------------------|
|  pyarrow.Table   |
|  a: int64        |
|  b: int64        |
|  ----
|  a: [[1,2]]      |
|  b: [[4,5]]      |
└──────────────────┘

```

--------------------------------

### Example: DataFrame from Dictionary with String Backend (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/typing

Demonstrates creating a Narwhals DataFrame from a dictionary using a string backend name like 'pandas'.

```python
>>> import narwhals as nw
>>> 
>>> data = {"c": [5, 2], "d": [1, 4]}
>>> nw.DataFrame.from_dict(data, backend="pandas")
┌──────────────────┐
|Narwhals DataFrame|
|------------------|
|        c  d      |
|     0  5  1      |
|     1  2  4      |
└──────────────────┘

```

--------------------------------

### show_versions

Source: https://narwhals-dev.github.io/narwhals/api-reference/narwhals

Prints useful debugging information about the installed libraries and their versions.

```APIDOC
## GET /show_versions

### Description
Print useful debugging information.

### Method
GET

### Endpoint
/show_versions

### Parameters
No parameters required.

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **None** - This function does not return a value, it prints to standard output.

#### Response Example
```
System:...
Python:...
Narwhals:...
Pandas:...
Polars:...
...
```
```

--------------------------------

### Generate pretty-printed SQL from Polars-like syntax using narwhals.sql and DuckDB

Source: https://narwhals-dev.github.io/narwhals/generating_sql

This snippet extends the previous example by enabling pretty-printing for the generated SQL query using the `pretty=True` option. This requires the `sqlparse` library to be installed.

```python
print(result.to_sql(pretty=True))
```

--------------------------------

### Example: Series from NumPy with Module Backend (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/typing

Illustrates creating a Narwhals Series from a NumPy array, specifying a Python module like `polars` as the backend.

```python
>>> import numpy as np
>>> import polars as pl
>>> import narwhals as nw
>>> 
>>> arr = np.arange(5, 10)
>>> nw.Series.from_numpy("arr", arr, dtype=nw.Int8, backend=pl)
┌──────────────────┐
| Narwhals Series  |
|------------------|
|shape: (5,)       |
|Series: 'arr' [i8]|
|[                 |
|        5         |
|        6         |
|        7         |
|        8         |
|        9         |
|]                 |
└──────────────────┘

```

--------------------------------

### narwhals.Series.str.pad_start

Source: https://narwhals-dev.github.io/narwhals/api-reference/series_str

Pads the start of each string in the Series with a specified character until it reaches a target length.

```APIDOC
## POST /websites/narwhals-dev_github_io_narwhals/str/pad_start

### Description
Pad the start of the string until it reaches the given length.

### Method
POST

### Endpoint
/websites/narwhals-dev_github_io_narwhals/str/pad_start

### Parameters
#### Query Parameters
- **length** (int) - Required - Pad the string until it reaches this length. Strings with length equal to or greater than this value are returned as-is.
- **fill_char** (str) - Optional - The character to pad the string with. Default: ' '

### Request Body
```json
{
  "data": [
    "cow",
    "monkey",
    "hippopotamus",
    null
  ]
}
```

### Response
#### Success Response (200)
- **data** (array) - Array of padded strings.

#### Response Example
```json
{
  "data": [
    "______cow",
    "__monkey",
    "hippopotamus",
    null
  ]
}
```
```

--------------------------------

### Series.head

Source: https://narwhals-dev.github.io/narwhals/api-reference/series

Gets the first n rows of the Series.

```APIDOC
## Series.head

### Description
Get the first `n` rows.

### Method
`head`

### Endpoint
`Series.head`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **n** (int) - Optional - Number of rows to return. Default: `10`

### Request Example
```python
import pandas as pd
import narwhals as nw

s_native = pd.Series(list(range(10)))
nw.from_native(s_native, series_only=True).head(3)
```

### Response
#### Success Response (200)
- **Self** (Self) - A new Series containing the first n rows.

#### Response Example
```json
{
  "example": "0    0\n1    1\n2    2\ndtype: int64"
}
```
```

--------------------------------

### Example: Extracting a Column with __getitem__ in Narwhals

Source: https://narwhals-dev.github.io/narwhals/api-reference/dataframe

This example demonstrates how to extract a single column named 'a' from a Narwhals DataFrame and convert it back to a pandas DataFrame for inspection. It highlights the usage of the __getitem__ method for column selection.

```python
>>> import pandas as pd
>>> import narwhals as nw
>>> df_native = pd.DataFrame({"a": [1, 2]})
>>> df = nw.from_native(df_native)
>>> df["a"].to_native()
0    1
1    2
Name: a, dtype: int64
```

--------------------------------

### Boolean DType Example

Source: https://narwhals-dev.github.io/narwhals/api-reference/dtypes

Shows the Narwhals Boolean DType for boolean values. It demonstrates obtaining this dtype from a native PyArrow chunked array.

```python
import pyarrow as pa
import narwhals as nw

s_native = pa.chunked_array([[True, False, False, True]])
dtype = nw.from_native(s_native, series_only=True).dtype
print(dtype)
```

--------------------------------

### Example: DataFrame from Dictionary with Explicit Schema (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/typing

Shows creating a Narwhals DataFrame from a dictionary with an explicitly defined schema using Narwhals DType objects for each column.

```python
>>> import narwhals as nw
>>> import pyarrow as pa
>>> data = {"a": [1, 2, 3], "b": [None, "hi", "howdy"], "c": [2.1, 2.0, None]}
>>> nw.DataFrame.from_dict(
...     data,
...     schema={"a": nw.UInt8(), "b": nw.String(), "c": nw.Float32()},
...     backend="pyarrow",
... )
┌────────────────────────┐
|   Narwhals DataFrame   |
|------------------------|
|pyarrow.Table           |
|a: uint8                |
|b: string               |
|c: float                |
|----                    |
|a: [[1,2,3]]            |
|b: [[null,"hi","howdy"]]| 
|c: [[2.1,2,null]]       |
└────────────────────────┘

```

--------------------------------

### Binary DType Example

Source: https://narwhals-dev.github.io/narwhals/api-reference/dtypes

Demonstrates the Narwhals Binary DType for handling binary data. It shows how to obtain this dtype from native Polars Series, PyArrow chunked arrays, and DuckDB relations.

```python
import polars as pl
import narwhals as nw
import pyarrow as pa
import duckdb

data = [b"test1", b"test2"]

# From Polars Series
ser_pl = pl.Series(data, dtype=pl.Binary)
print(nw.from_native(ser_pl, series_only=True).dtype)

# From PyArrow chunked array
ser_pa = pa.chunked_array([pa.array(data, type=pa.binary())])
print(nw.from_native(ser_pa, series_only=True).dtype)

# From DuckDB relation
rel = duckdb.sql("SELECT * FROM (VALUES (BLOB 'test1'), (BLOB 'test2')) AS df(t)")
print(nw.from_native(rel).collect_schema()["t"])
```

--------------------------------

### Example: Casting Columns with Narwhals DTypes (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/typing

Demonstrates casting columns in a Narwhals DataFrame to different data types using Narwhals DType objects, such as `nw.Int32` and `nw.String`.

```python
>>> import polars as pl
>>> import narwhals as nw
>>> df_native = pl.DataFrame({"a": [1, 2, 3], "b": [4.0, 5.0, 6.0]})
>>> df = nw.from_native(df_native)
>>> df.select(
...     nw.col("a").cast(nw.Int32),
...     nw.col("b").cast(nw.String()).str.split(".").cast(nw.List(nw.Int8)),
... )
┌──────────────────┐
|Narwhals DataFrame|
|------------------|
|shape: (3, 2)     |
|┌─────┬──────────┐|
|│ a   ┆ b        │|
|│ --- ┆ ---      │|
|│ i32 ┆ list[i8] │|
|╞═════╪══════════╡|
|│ 1   ┆ [4, 0]   │|
|│ 2   ┆ [5, 0]   │|
|│ 3   ┆ [6, 0]   │|
|└─────┴──────────┘|
└──────────────────┘

```

--------------------------------

### Implementation Instantiation Methods

Source: https://narwhals-dev.github.io/narwhals/api-reference/utils

Methods for creating an Implementation object from various inputs.

```APIDOC
## Implementation Instantiation Methods

### from_backend
```python
from_backend(
    backend: IntoBackend[Backend] | UnknownBackendName,
) -> Implementation
```

Instantiate from native namespace module, string, or Implementation.

**Parameters:**

| Name    | Type                                    | Description                                       |
|---------|-----------------------------------------|---------------------------------------------------|
| `backend` | `IntoBackend[Backend] | UnknownBackendName` | Backend to instantiate Implementation from. | _required_  

### from_native_namespace
```python
from_native_namespace(
    native_namespace: ModuleType,
) -> Implementation
```

Instantiate Implementation object from a native namespace module.

**Parameters:**

| Name               | Type       | Description                      |
|--------------------|------------|----------------------------------|
| `native_namespace` | `ModuleType` | Native namespace. | _required_  

### from_string
```python
from_string(backend_name: str) -> Implementation
```

Instantiate Implementation object from a native namespace module.

**Parameters:**

| Name         | Type | Description                     |
|--------------|------|---------------------------------|
| `backend_name` | `str`  | Name of backend, expressed as string. | _required_  
```

--------------------------------

### Get Name of Narwhals Series (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/series

Shows how to get the name of a `narwhals.Series` using the `.name` property. The example uses a Series created from a polars Series.

```python
import polars as pl
import narwhals as nw

s_native = pl.Series("foo", [1, 2, 3])
s = nw.from_native(s_native, series_only=True)

print(s.name)

```

--------------------------------

### Implementation Instantiation Methods

Source: https://narwhals-dev.github.io/narwhals/api-reference/implementation

Methods for creating Narwhals Implementation objects from various inputs.

```APIDOC
## Class Methods: Implementation Instantiation

These class methods allow you to create `Implementation` objects.

### `from_backend`

- **Description**: Instantiate from native namespace module, string, or Implementation.
- **Method**: `classmethod`
- **Parameters**:
  - **`backend`** (`IntoBackend[Backend] | UnknownBackendName`) - Required - Backend to instantiate Implementation from.
- **Returns**: `Implementation`

### `from_native_namespace`

- **Description**: Instantiate Implementation object from a native namespace module.
- **Method**: `classmethod`
- **Parameters**:
  - **`native_namespace`** (`ModuleType`) - Required - Native namespace.
- **Returns**: `Implementation`

### `from_string`

- **Description**: Instantiate Implementation object from a native namespace module.
- **Method**: `classmethod`
- **Parameters**:
  - **`backend_name`** (`str`) - Required - Name of backend, expressed as string.
- **Returns**: `Implementation`
```

--------------------------------

### Instantiate Narwhals Implementation from String (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/implementation

Provides a way to create a Narwhals Implementation object by simply providing the backend name as a string. This is a convenient method for quick instantiation.

```python
from_string(backend_name: str) -> Implementation
```

--------------------------------

### Get Maximum Value with Narwhals

Source: https://narwhals-dev.github.io/narwhals/api-reference/expr

Returns the maximum value(s) from specified column(s). This example uses Pandas DataFrames.

```python
import pandas as pd
import narwhals as nw
df_native = pd.DataFrame({"a": [10, 20], "b": [50, 100]})
df = nw.from_native(df_native)
df.select(nw.max("a", "b"))
```

--------------------------------

### Get Shape of Narwhals Series (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/series

Demonstrates how to retrieve the shape of a `narwhals.Series` using the `.shape` property. The example uses a Series created from a pandas Series.

```python
import pandas as pd
import narwhals as nw

s_native = pd.Series([1, 2, 3])
s = nw.from_native(s_native, series_only=True)

print(s.shape)

```

--------------------------------

### Broadcasting in Narwhals (SQL Backend Example)

Source: https://narwhals-dev.github.io/narwhals/how_it_works

Illustrates broadcasting in Narwhals, specifically how SQL-like libraries require explicit window functions for operations like column mean subtraction. This ensures correct behavior across different backends.

```sql
-- Example for SQL-like backend
-- Assuming a table with column 'a'
SELECT
    a - SUM(a) OVER () AS result
FROM
    your_table;
```

--------------------------------

### Instantiate Narwhals Implementation from Backend (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/implementation

Demonstrates how to instantiate a Narwhals Implementation object from a given backend. This class method accepts various input types, including native namespace modules, strings, or existing Implementation objects.

```python
from_backend(
    backend: IntoBackend[Backend] | UnknownBackendName,
) -> Implementation
```

--------------------------------

### Get Data Type of Narwhals Series (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/series

Illustrates how to access the data type (`dtype`) of a `narwhals.Series`. The example shows retrieving the dtype from a Series created from a pandas Series.

```python
import pandas as pd
import narwhals as nw

s_native = pd.Series([1, 2, 3])
s = nw.from_native(s_native, series_only=True)

print(s.dtype)

```

--------------------------------

### Instantiate Implementation from Backend (Python)

Source: https://narwhals-dev.github.io/narwhals/api-reference/utils

Provides class methods to instantiate an Implementation object. `from_backend` takes a backend type or name, `from_native_namespace` uses a module, and `from_string` uses a backend name string. These methods are crucial for creating Narwhals DataFrame objects from various sources.

```python
from_backend(
    backend: IntoBackend[Backend] | UnknownBackendName,
) -> Implementation
```

```python
from_native_namespace(
    native_namespace: ModuleType,
) -> Implementation
```

```python
from_string(backend_name: str) -> Implementation
```

--------------------------------

### Object DType Example

Source: https://narwhals-dev.github.io/narwhals/api-reference/dtypes

Illustrates the Narwhals Object DType, used for wrapping arbitrary Python objects. It shows how to get this dtype from a native Pandas Series containing custom objects.

```python
import pandas as pd
import narwhals as nw

class Foo: ...
s_native = pd.Series([Foo(), Foo()])
dtype = nw.from_native(s_native, series_only=True).dtype
print(dtype)
```

--------------------------------

### Select Every Nth Row (Narwhals)

Source: https://narwhals-dev.github.io/narwhals/api-reference/dataframe

Extracts every nth row from a Narwhals DataFrame, starting from a specified offset. This is useful for sampling or selecting data at regular intervals. The example demonstrates its use with a PyArrow backend.

```python
import pyarrow as pa
import narwhals as nw
df_native = pa.table({"foo": [1, None, 2, 3]})
nw.from_native(df_native).gather_every(2)
```

--------------------------------

### Series Methods Overview

Source: https://narwhals-dev.github.io/narwhals/api-completeness/series

This section provides an overview of the available methods for the Series object, categorized by their functionality and backend support.

```APIDOC
## Series Methods

This documentation lists the methods available for the `Series` object, indicating support for different backends: Arrow, pandas-like, and Polars.

### Available Methods

- **abs**: Computes the absolute value.
- **alias**: Sets or gets the alias of the Series.
- **all**: Checks if all elements are true.
- **any**: Checks if any element is true.
- **any_value**: Returns any value from the Series.
- **arg_max**: Returns the index of the maximum value.
- **arg_min**: Returns the index of the minimum value.
- **arg_true**: Returns the index of the first true value.
- **cast**: Casts the Series to a different data type.
- **cat**: Accesses categorical data methods.
- **ceil**: Rounds elements up to the nearest integer.
- **clip**: Clips values to a specified range.
- **cos**: Computes the cosine of elements.
- **count**: Counts non-null elements.
- **cum_count**: Computes the cumulative count.
- **cum_max**: Computes the cumulative maximum.
- **cum_min**: Computes the cumulative minimum.
- **cum_prod**: Computes the cumulative product.
- **cum_sum**: Computes the cumulative sum.
- **diff**: Computes the difference between consecutive elements.
- **drop_nulls**: Drops null values.
- **dt**: Accesses datetime properties.
- **dtype**: Returns the data type of the Series.
- **ewm_mean**: Computes the exponentially weighted mean.
- **exp**: Computes the exponential of elements.
- **fill_nan**: Fills NaN values.
- **fill_null**: Fills null values.
- **filter**: Filters elements based on a condition.
- **first**: Returns the first element.
- **floor**: Rounds elements down to the nearest integer.
- **from_iterable**: Creates a Series from an iterable.
- **from_numpy**: Creates a Series from a NumPy array.
- **gather_every**: Gathers elements at specified intervals.
- **head**: Returns the first n elements.
- **hist**: Computes a histogram.
- **is_between**: Checks if elements are within a range.
- **is_close**: Checks if elements are close to each other.
- **is_duplicated**: Checks for duplicated elements.
- **is_empty**: Checks if the Series is empty.
- **is_finite**: Checks if elements are finite.
- **is_first_distinct**: Checks if elements are the first distinct occurrence.
- **is_in**: Checks if elements are present in a given set.
- **is_last_distinct**: Checks if elements are the last distinct occurrence.
- **is_nan**: Checks for NaN values.
- **is_null**: Checks for null values.
- **is_sorted**: Checks if the Series is sorted.
- **is_unique**: Checks for unique elements.
- **item**: Returns the single element of a Series with one element.
- **kurtosis**: Computes the kurtosis.
- **last**: Returns the last element.
- **len**: Returns the length of the Series.
- **list**: Converts the Series to a list.
- **log**: Computes the natural logarithm of elements.
- **max**: Computes the maximum value.
- **mean**: Computes the mean of elements.
- **median**: Computes the median of elements.
- **min**: Computes the minimum value.
- **mode**: Computes the mode of elements.
- **n_unique**: Computes the number of unique elements.
- **name**: Sets or gets the name of the Series.
- **null_count**: Counts the number of null elements.
- **pipe**: Applies a function to the Series.
- **quantile**: Computes the quantile.
- **rank**: Computes the rank of elements.
- **rename**: Renames the Series.
- **replace_strict**: Replaces elements strictly.
- **rolling_mean**: Computes the rolling mean.
- **rolling_std**: Computes the rolling standard deviation.
- **rolling_sum**: Computes the rolling sum.
- **rolling_var**: Computes the rolling variance.
- **round**: Rounds elements to a specified number of decimal places.
- **sample**: Samples elements from the Series.
- **scatter**: Creates a scatter plot.
- **shape**: Returns the shape of the Series.
- **shift**: Shifts elements by a specified number of positions.
- **sin**: Computes the sine of elements.
- **skew**: Computes the skewness.
- **sort**: Sorts the Series.
- **sqrt**: Computes the square root of elements.
- **std**: Computes the standard deviation.
- **str**: Accesses string manipulation methods.
- **struct**: Accesses struct properties.
- **sum**: Computes the sum of elements.
- **tail**: Returns the last n elements.
- **to_arrow**: Converts the Series to an Arrow Array.
- **to_dummies**: Converts categorical variables into dummy/indicator variables.
- **to_frame**: Converts the Series to a DataFrame.
- **to_list**: Converts the Series to a Python list.
- **to_native**: Converts the Series to its native representation.
- **to_numpy**: Converts the Series to a NumPy array.
- **to_pandas**: Converts the Series to a Pandas Series.
- **to_polars**: Converts the Series to a Polars Series.
- **unique**: Returns unique elements.
- **value_counts**: Counts the occurrences of unique values.
- **var**: Computes the variance.
- **zip_with**: Zips the Series with another Series or list.
```

--------------------------------

### Define Narwhals Plugin Entrypoint in pyproject.toml

Source: https://narwhals-dev.github.io/narwhals/extending

This snippet shows how to define a plugin entrypoint for Narwhals in a pyproject.toml file. The entrypoint allows Narwhals to discover and load the plugin for a specific library. The section name 'narwhals.plugins' is standard, and the key 'narwhals-<library name>' should be replaced with the actual library name.

```toml
[project.entry-points.'narwhals.plugins']
narwhals-<library name> = 'narwhals_<library name>'

```

--------------------------------

### Get Unique Values using Narwhals

Source: https://narwhals-dev.github.io/narwhals/api-reference/expr

Returns the unique values from specified columns in a Narwhals DataFrame. This function is useful for identifying distinct entries within a dataset. The example demonstrates its use in conjunction with `.sum()` to count unique occurrences.

```python
import pandas as pd
import narwhals as nw
df_native = pd.DataFrame({"a": [1, 1, 3, 5, 5], "b": [2, 4, 4, 6, 6]})
df = nw.from_native(df_native)
df.select(nw.col("a", "b").unique().sum())
```

--------------------------------

### Implementation Conversion

Source: https://narwhals-dev.github.io/narwhals/api-reference/utils

Methods to access the native backend implementation or parse version strings.

```APIDOC
## to_native_namespace

### Description
Return the native namespace module corresponding to the current Implementation.

### Method
GET

### Endpoint
/implementation/to_native_namespace

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **native_namespace** (ModuleType) - The native namespace module (e.g., pyspark.sql, polars).

#### Response Example
```json
{
  "native_namespace": "pyspark.sql"
}
```

## parse_version

### Description
Simple version parser; split into a tuple of ints for comparison.

### Method
POST

### Endpoint
/utils/parse_version

### Parameters
#### Query Parameters
None

#### Request Body
- **version** (str | ModuleType | _SupportsVersion) - Required - Version string, or object with one, to parse.

### Request Example
```json
{
  "version": "1.2.3"
}
```

### Response
#### Success Response (200)
- **parsed_version** (tuple[int, ...]) - The version parsed into a tuple of integers.

#### Response Example
```json
{
  "parsed_version": [1, 2, 3]
}
```
```

--------------------------------

### Implement Narwhals Plugin Initialization

Source: https://narwhals-dev.github.io/narwhals/extending

This code demonstrates the essential components required in a plugin's __init__.py file for Narwhals integration. It includes the `is_native` function to identify the library's dataframes, the `__narwhals_namespace__` function to provide a compliant namespace, and the `NATIVE_PACKAGE` constant to specify the library name.

```python
from narwhals.plugins import Plugin

NATIVE_PACKAGE = "<library name>"

def is_native(obj) -> bool:
    # Implementation to check if obj is a dataframe of the library
    ...

def __narwhals_namespace__(narwhals_version: str) -> Plugin:
    # Implementation to return a compliant namespace
    ...

```

--------------------------------

### Example: Conditional Column Creation with Narwhals

Source: https://narwhals-dev.github.io/narwhals/api-reference/narwhals

Demonstrates how to use the `when` function to create a new column based on a condition. This example uses pandas as the underlying DataFrame implementation and applies a conditional logic to create the 'a_when' column.

```python
>>> import pandas as pd
>>> import narwhals as nw
>>> 
>>> data = {"a": [1, 2, 3], "b": [5, 10, 15]}
>>> df_native = pd.DataFrame(data)
>>> nw.from_native(df_native).with_columns(
...     nw.when(nw.col("a") < 3).then(5).otherwise(6).alias("a_when")
... )

```
Tokens:
Raw