Separate "writing a plugin" from "registering an expression" in user guide and pyo3-polars examples

[MarcoGorelli]

Separate "writing a plugin" from "registering an expression" in user guide and pyo3-polars examples

[dangotbanned]

Custom namespaces have their downsides:

• they require an extra unused import, which requires an extra # noqa: F401 for linters to not complain about it

• they break static typing

I think these points, particularly the latter, should be documented alongside any mention of custom namespaces. I'm only just discovering this here after searching for why my extension didn't show up in code completion.

[baggiponte]

Then, if people also want to register them with a custom namespace, they are free to do that. It's very easy. The plugins page in the user guide could even point people there and mention it as a possibility. But I think it shouldn't be the primary way that plugins are taught.

This is a good take. We might "standardise" the plugin structure and recommend to add a "registration" method for those who wish to do so, to make it explicit.

import polars as pl
import polars_language

try:
    polars_language.register(namespace="language")
except pl.exceptions.PolarsInvalidNamespaceError as e:
   ...

out = df.with_columns(
   pig_latin = pl.col("names").language.pig_latinnify()  # type: ignore[attr-defined]
)