Skip to content

narwhals.plugins

For an overview of how to write a plugin, see extensions and plugins.

Runtime discovery of, and dispatch to, Narwhals plugin backends.

A plugin backend registers an entry point in the narwhals.plugins group. Plugins are discovered at runtime, so their names cannot be enumerated in the Literal unions that describe built-in backends.

PluginName bridges that gap: a plugin's entry point name, wrapped as PluginName("my-plugin"), is accepted wherever a backend is expected.

The contract for plugin authors is that the wrapped string must name an installed plugin's entry point in the narwhals.plugins group.

PluginName module-attribute 

PluginName = NewType('PluginName', str)

Name of a plugin's entry point.

  • Wrap an entry point name to pass it wherever a backend is expected, e.g. PluginName("my-plugin").
  • Add it to a signature's IntoBackend parameter to advertise plugin support, e.g. IntoBackend[EagerAllowed | PluginName].

See the narwhals.plugins module for how plugin authors register entry points and the contract a wrapped name must satisfy.

Plugin

Top-level interface a plugin module is expected to implement.

A plugin is a module registered in the narwhals.plugins entry point group:

[project.entry-points.'narwhals.plugins']
narwhals-grizzlies = 'narwhals_grizzlies'

Narwhals discovers installed plugins at runtime and uses this interface to recognise their native objects (NATIVE_PACKAGE, is_native) and to obtain a compliant namespace (__narwhals_namespace__), through which all further dispatch happens.

See extensions and plugins for a complete walk-through.

NATIVE_PACKAGE property 

NATIVE_PACKAGE: LiteralString

Name of the package providing the plugin's native objects, e.g. "grizzlies".

Narwhals only consults the plugin about an object if this package is already imported and the object's class might come from it.

__name__ property 

__name__: str

Name of the plugin module, used in error messages. Every module has one.

__narwhals_namespace__ 

__narwhals_namespace__(
    version: Version,
) -> PluginNamespace[FrameT, FromNativeR_co]

Return a compliant namespace for the given Narwhals API version.

Narwhals wraps native objects with its from_native method, dispatches IO functions to its scan_*/read_* methods, and builds eager constructors from its _dataframe/_series classes (see backend=...).

Important

Narwhals caches the returned namespace per version and shares it across calls, so it must be safe to reuse. The hook itself may still run more than once, e.g. on concurrent first use.

is_native 

is_native(native_object: object) -> bool

Return whether native_object is a native object of the plugin's library.

from_native 

from_native(
    native_object: Any, version: Version
) -> CompliantAny | None

Attempt to convert native_object to a Compliant object, using any available plugin(s).

Parameters:

Name Type Description Default
native_object Any

Raw object from user.

 required
version Version

Narwhals API version.

 required

Returns:

Type Description
CompliantAny | None

If the following conditions are met

  • at least 1 plugin is installed
  • at least 1 installed plugin supports type(native_object)

Then for the first matching plugin, the result of the call below.

This should be an object accepted by a Narwhals Dataframe, Lazyframe, or Series:

plugin: Plugin
plugin.__narwhals_namespace__(version).from_native(native_object)

In all other cases, None is returned instead.