refactor(python): Rename utils module to _utils to explicitly mark it as private

.github/scripts/test_bytecode_parser.py

@@ -18,7 +18,7 @@
 from typing import Any, Callable
 
 import pytest
-from polars.utils.udfs import BytecodeParser
+from polars._utils.udfs import BytecodeParser
 from tests.unit.operations.map.test_inefficient_map_warning import (
     MY_DICT,
     NOOP_TEST_CASES,
@@ -44,7 +44,7 @@ def test_bytecode_parser_expression_in_ipython(
     col: str, func: Callable[[Any], Any], expected: str
 ) -> None:
     script = (
-        "from polars.utils.udfs import BytecodeParser; "
+        "from polars._utils.udfs import BytecodeParser; "
         "import datetime as dt; "
         "from datetime import datetime; "
         "import numpy as np; "
@@ -73,7 +73,7 @@ def test_bytecode_parser_expression_noop(func: str) -> None:
 )
 def test_bytecode_parser_expression_noop_in_ipython(func: str) -> None:
     script = (
-        "from polars.utils.udfs import BytecodeParser; "
+        "from polars._utils.udfs import BytecodeParser; "
         f"MY_DICT = {MY_DICT};"
         f'parser = BytecodeParser({func}, map_target="expr");'
         f'print(not parser.can_attempt_rewrite() or not parser.to_expression("x"));'

crates/polars-lazy/src/physical_plan/executors/python_scan.rs

@@ -21,7 +21,7 @@ impl Executor for PythonScanExec {
         let n_rows = self.options.n_rows.take();
         Python::with_gil(|py| {
             let pl = PyModule::import(py, "polars").unwrap();
-            let utils = pl.getattr("utils").unwrap();
+            let utils = pl.getattr("_utils").unwrap();
             let callable = utils.getattr("_execute_from_rust").unwrap();
 
             let python_scan_function = self.options.scan_fn.take().unwrap().0;

py-polars/polars/__init__.py

@@ -18,6 +18,10 @@
     __register_startup_deps()
 
 from polars import api
+from polars._utils.polars_version import get_polars_version as _get_polars_version
+
+# TODO: remove need for importing wrap utils at top level
+from polars._utils.wrap import wrap_df, wrap_s  # noqa: F401
 from polars.config import Config
 from polars.convert import (
     from_arrow,
@@ -214,10 +218,6 @@
     using_string_cache,
 )
 from polars.type_aliases import PolarsDataType
-from polars.utils._polars_version import get_polars_version as _get_polars_version
-
-# TODO: remove need for importing wrap utils at top level
-from polars.utils._wrap import wrap_df, wrap_s  # noqa: F401
 
 __version__: str = _get_polars_version()
 del _get_polars_version

py-polars/polars/_utils/__init__.py

@@ -0,0 +1,36 @@
+"""
+Utility functions.
+
+Functions that are part of the public API are re-exported here.
+"""
+from polars._utils.convert import (
+    date_to_int,
+    datetime_to_int,
+    time_to_int,
+    timedelta_to_int,
+    to_py_date,
+    to_py_datetime,
+    to_py_decimal,
+    to_py_time,
+    to_py_timedelta,
+)
+from polars._utils.scan import _execute_from_rust
+from polars._utils.various import NoDefault, _polars_warn, is_column, no_default
+
+__all__ = [
+    "NoDefault",
+    "is_column",
+    "no_default",
+    # Required for Rust bindings
+    "date_to_int",
+    "datetime_to_int",
+    "time_to_int",
+    "timedelta_to_int",
+    "_execute_from_rust",
+    "_polars_warn",
+    "to_py_date",
+    "to_py_datetime",
+    "to_py_decimal",
+    "to_py_time",
+    "to_py_timedelta",
+]

py-polars/polars/utils/_async.py → py-polars/polars/_utils/async_.py

@@ -2,8 +2,8 @@
 
 from typing import TYPE_CHECKING, Any, Awaitable, Generator, Generic, TypeVar
 
+from polars._utils.wrap import wrap_df
 from polars.dependencies import _GEVENT_AVAILABLE
-from polars.utils._wrap import wrap_df
 
 if TYPE_CHECKING:
     from asyncio.futures import Future

py-polars/polars/utils/_construction.py → py-polars/polars/_utils/construction.py

@@ -23,6 +23,14 @@
 
 import polars._reexport as pl
 from polars import functions as F
+from polars._utils.various import (
+    _is_generator,
+    arrlen,
+    find_stacklevel,
+    parse_version,
+    range_to_series,
+)
+from polars._utils.wrap import wrap_df, wrap_s
 from polars.datatypes import (
     INTEGER_DTYPES,
     N_INFER_DEFAULT,
@@ -70,14 +78,6 @@
     TimeZoneAwareConstructorWarning,
 )
 from polars.meta import get_index_type, thread_pool_size
-from polars.utils._wrap import wrap_df, wrap_s
-from polars.utils.various import (
-    _is_generator,
-    arrlen,
-    find_stacklevel,
-    parse_version,
-    range_to_series,
-)
 
 with contextlib.suppress(ImportError):  # Module not available when building docs
     from polars.polars import PyDataFrame, PySeries

py-polars/polars/utils/deprecation.py → py-polars/polars/_utils/deprecation.py

@@ -5,7 +5,7 @@
 from functools import wraps
 from typing import TYPE_CHECKING, Callable, Sequence, TypeVar
 
-from polars.utils.various import find_stacklevel
+from polars._utils.various import find_stacklevel
 
 if TYPE_CHECKING:
     import sys

py-polars/polars/utils/_parse_expr_input.py → py-polars/polars/_utils/parse_expr_input.py

@@ -5,8 +5,8 @@
 
 import polars._reexport as pl
 from polars import functions as F
+from polars._utils.deprecation import issue_deprecation_warning
 from polars.exceptions import ComputeError
-from polars.utils.deprecation import issue_deprecation_warning
 
 with contextlib.suppress(ImportError):  # Module not available when building docs
     import polars.polars as plr