DEPR: deprecate exposing blocks in core.internals

doc/source/whatsnew/v2.2.0.rst

@@ -169,6 +169,8 @@ Deprecations
 - Deprecated strings ``T``, ``S``, ``L``, ``U``, and ``N`` denoting frequencies in :class:`Minute`, :class:`Second`, :class:`Milli`, :class:`Micro`, :class:`Nano` (:issue:`52536`)
 - Deprecated strings ``T``, ``S``, ``L``, ``U``, and ``N`` denoting units in :class:`Timedelta` (:issue:`52536`)
 - Deprecated the extension test classes ``BaseNoReduceTests``, ``BaseBooleanReduceTests``, and ``BaseNumericReduceTests``, use ``BaseReduceTests`` instead (:issue:`54663`)
+- Deprecated ``core.internals`` members ``Block``, ``ExtensionBlock``, ``DatetimeTZBlock``, and ``make_block``, use public APIs instead (:issue:`??`)
+-
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_220.performance:

pandas/core/internals/__init__.py

@@ -1,4 +1,3 @@
-from pandas.core.internals.api import make_block
 from pandas.core.internals.array_manager import (
     ArrayManager,
     SingleArrayManager,
@@ -7,11 +6,6 @@
     DataManager,
     SingleDataManager,
 )
-from pandas.core.internals.blocks import (  # io.pytables, io.packers
-    Block,
-    DatetimeTZBlock,
-    ExtensionBlock,
-)
 from pandas.core.internals.concat import concatenate_managers
 from pandas.core.internals.managers import (
     BlockManager,
@@ -41,7 +35,14 @@ def __getattr__(name: str):
 
     from pandas.util._exceptions import find_stack_level
 
-    if name in ["NumericBlock", "ObjectBlock"]:
+    if name in [
+        "NumericBlock",
+        "ObjectBlock",
+        "Block",
+        "ExtensionBlock",
+        "DatetimeTZBlock",
+        "make_block",
+    ]:
         warnings.warn(
             f"{name} is deprecated and will be removed in a future version. "
             "Use public APIs instead.",
@@ -52,6 +53,22 @@ def __getattr__(name: str):
             from pandas.core.internals.blocks import NumericBlock
 
             return NumericBlock
+        elif name == "DatetimeTZBlock":
+            from pandas.core.internals.blocks import DatetimeTZBlock
+
+            return DatetimeTZBlock
+        elif name == "ExtensionBlock":
+            from pandas.core.internals.blocks import ExtensionBlock
+
+            return ExtensionBlock
+        elif name == "Block":
+            from pandas.core.internals.blocks import Block
+
+            return Block
+        elif name == "make_block":
+            from pandas.core.internals.api import make_block
+
+            return make_block
         else:
             from pandas.core.internals.blocks import ObjectBlock
 

pandas/core/internals/api.py

@@ -23,9 +23,6 @@
 from pandas.core.arrays import DatetimeArray
 from pandas.core.construction import extract_array
 from pandas.core.internals.blocks import (
-    Block,
-    DatetimeTZBlock,
-    ExtensionBlock,
     check_ndim,
     ensure_block_shape,
     extract_pandas_array,
@@ -36,6 +33,8 @@
 if TYPE_CHECKING:
     from pandas._typing import Dtype
 
+    from pandas.core.internals.blocks import Block
+
 
 def make_block(
     values, placement, klass=None, ndim=None, dtype: Dtype | None = None
@@ -56,6 +55,11 @@ def make_block(
 
     values, dtype = extract_pandas_array(values, dtype, ndim)
 
+    from pandas.core.internals.blocks import (
+        DatetimeTZBlock,
+        ExtensionBlock,
+    )
+
     if klass is ExtensionBlock and isinstance(values.dtype, PeriodDtype):
         # GH-44681 changed PeriodArray to be stored in the 2D
         # NDArrayBackedExtensionBlock instead of ExtensionBlock
@@ -105,3 +109,33 @@ def maybe_infer_ndim(values, placement: BlockPlacement, ndim: int | None) -> int
         else:
             ndim = values.ndim
     return ndim
+
+
+def __getattr__(name: str):
+    import warnings
+
+    from pandas.util._exceptions import find_stack_level
+
+    if name in ["Block", "ExtensionBlock", "DatetimeTZBlock"]:
+        warnings.warn(
+            f"{name} is deprecated and will be removed in a future version. "
+            "Use public APIs instead.",
+            DeprecationWarning,
+            stacklevel=find_stack_level(),
+        )
+        if name == "Block":
+            from pandas.core.internals.blocks import Block
+
+            return Block
+
+        elif name == "DatetimeTZBlock":
+            from pandas.core.internals.blocks import DatetimeTZBlock
+
+            return DatetimeTZBlock
+
+        elif name == "ExtensionBlock":
+            from pandas.core.internals.blocks import ExtensionBlock
+
+            return ExtensionBlock
+
+    raise AttributeError(f"module 'pandas.core.internals' has no attribute '{name}'")

pandas/tests/internals/test_api.py

@@ -3,13 +3,19 @@
 in core.internals
 """
 
+import pytest
+
 import pandas as pd
+import pandas._testing as tm
 from pandas.core import internals
 from pandas.core.internals import api
 
 
 def test_internals_api():
-    assert internals.make_block is api.make_block
+    msg = "make_block is deprecated.* Use public APIs instead"
+    with tm.assert_produces_warning(DeprecationWarning, match=msg):
+        mb = internals.make_block
+    assert mb is api.make_block
 
 
 def test_namespace():
@@ -26,10 +32,6 @@ def test_namespace():
         "ops",
     ]
     expected = [
-        "Block",
-        "DatetimeTZBlock",
-        "ExtensionBlock",
-        "make_block",
         "DataManager",
         "ArrayManager",
         "BlockManager",
@@ -44,6 +46,29 @@ def test_namespace():
     assert set(result) == set(expected + modules)
 
 
+@pytest.mark.parametrize(
+    "name",
+    [
+        "NumericBlock",
+        "ObjectBlock",
+        "Block",
+        "ExtensionBlock",
+        "DatetimeTZBlock",
+        "make_block",
+    ],
+)
+def test_deprecations(name):
+    msg = f"{name} is deprecated.* Use public APIs instead"
+    with tm.assert_produces_warning(DeprecationWarning, match=msg):
+        getattr(internals, name)
+
+    if name not in ["make_block", "NumericBlock", "ObjectBlock"]:
+        # NumericBlock and ObjectBlock are not in the internals.api namespace;
+        #  make_block is not deprecated there.
+        with tm.assert_produces_warning(DeprecationWarning, match=msg):
+            getattr(api, name)
+
+
 def test_make_block_2d_with_dti():
     # GH#41168
     dti = pd.date_range("2012", periods=3, tz="UTC")