feat: Make register_plugin a standalone function and include shared lib discovery

py-polars/docs/source/reference/index.rst

@@ -22,3 +22,4 @@ methods. All classes and functions exposed in ``polars.*`` namespace are public.
    testing
    sql
    metadata
+   plugins

py-polars/docs/source/reference/plugins.rst

@@ -0,0 +1,15 @@
+=======
+Plugins
+=======
+.. currentmodule:: polars
+
+Plugins allow for extending Polars' functionality. See the
+`user guide <https://docs.pola.rs/user-guide/expressions/plugins/>`_ for more information
+and resources.
+
+Available plugin utility functions are:
+
+.. automodule:: polars.plugins
+    :members:
+    :autosummary:
+    :autosummary-no-titles:

py-polars/polars/__init__.py

@@ -17,7 +17,7 @@
 
     __register_startup_deps()
 
-from polars import api
+from polars import api, exceptions, plugins, selectors
 from polars._utils.polars_version import get_polars_version as _get_polars_version
 
 # TODO: remove need for importing wrap utils at top level
@@ -225,6 +225,7 @@
 __all__ = [
     "api",
     "exceptions",
+    "plugins",
     # exceptions/errors
     "ArrowError",
     "ColumnNotFoundError",

py-polars/polars/plugins.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from polars._utils.unstable import unstable
+
+__all__ = ["get_shared_lib_location"]
+
+
+@unstable()
+def get_shared_lib_location(package_init_path: str) -> str:
+    """
+    Get location of Shared Object file.
+
+    See the `user guide <https://docs.pola.rs/user-guide/expressions/plugins/>`_
+    for more information about plugins.
+
+    .. warning::
+        This functionality is considered **unstable**. It may be changed
+        at any point without it being considered a breaking change.
+
+    Parameters
+    ----------
+    package_init_path
+        The ``__init__.py`` file of the plugin package.
+
+    Returns
+    -------
+    str
+        The location of the Shared Object file.
+    """
+    directory = Path(package_init_path).parent
+    return str(next(path for path in directory.iterdir() if _is_shared_lib(path)))
+
+
+def _is_shared_lib(file: Path) -> bool:
+    return file.name.endswith((".so", ".dll", ".pyd"))

py-polars/polars/utils/udfs.py

@@ -3,10 +3,17 @@
 import os
 from typing import Any
 
+from polars._utils.deprecation import issue_deprecation_warning
+
 __all__ = ["_get_shared_lib_location"]
 
 
 def _get_shared_lib_location(main_file: Any) -> str:
+    issue_deprecation_warning(
+        "polars.utils will be made private in a future release. Please use "
+        "`from polars.plugins import get_shared_lib_location` instead.",
+        version="0.20.14",
+    )
     directory = os.path.dirname(main_file)  # noqa: PTH120
     return os.path.join(  # noqa: PTH118
         directory, next(filter(_is_shared_lib, os.listdir(directory)))