DEPR: deprecate exposing blocks in core.internals

doc/source/whatsnew/v2.2.0.rst

@@ -232,9 +232,10 @@ For example:
     pd.date_range('2020-01-01', periods=3, freq='ME')
 
 Other Deprecations
-^^^^^^^^^^^^^^^^^^
 - Changed :meth:`Timedelta.resolution_string` to return ``h``, ``min``, ``s``, ``ms``, ``us``, and ``ns`` instead of ``H``, ``T``, ``S``, ``L``, ``U``, and ``N``, for compatibility with respective deprecations in frequency aliases (:issue:`52536`)
+^^^^^^^^^^^^^^^^^^
 - Deprecated :meth:`Index.format`, use ``index.astype(str)`` or ``index.map(formatter)`` instead (:issue:`55413`)
+- Deprecated ``core.internals`` members ``Block``, ``ExtensionBlock``, and ``DatetimeTZBlock``, use public APIs instead (:issue:`55139`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_clipboard`. (:issue:`54229`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_csv` except ``path_or_buf``. (:issue:`54229`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_dict`. (:issue:`54229`)

pandas/core/internals/__init__.py

@@ -1,4 +1,4 @@
-from pandas.core.internals.api import make_block
+from pandas.core.internals.api import make_block  # 2023-09-18 pyarrow uses this
 from pandas.core.internals.array_manager import (
     ArrayManager,
     SingleArrayManager,
@@ -7,11 +7,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,
@@ -20,9 +15,9 @@
 )
 
 __all__ = [
-    "Block",
-    "DatetimeTZBlock",
-    "ExtensionBlock",
+    "Block",  # pylint: disable=undefined-all-variable
+    "DatetimeTZBlock",  # pylint: disable=undefined-all-variable
+    "ExtensionBlock",  # pylint: disable=undefined-all-variable
     "make_block",
     "DataManager",
     "ArrayManager",
@@ -37,11 +32,18 @@
 
 
 def __getattr__(name: str):
+    # GH#55139
     import warnings
 
     from pandas.util._exceptions import find_stack_level
 
-    if name in ["NumericBlock", "ObjectBlock"]:
+    if name in [
+        "NumericBlock",
+        "ObjectBlock",
+        "Block",
+        "ExtensionBlock",
+        "DatetimeTZBlock",
+    ]:
         warnings.warn(
             f"{name} is deprecated and will be removed in a future version. "
             "Use public APIs instead.",
@@ -52,6 +54,18 @@ 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
         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,34 @@ def maybe_infer_ndim(values, placement: BlockPlacement, ndim: int | None) -> int
         else:
             ndim = values.ndim
     return ndim
+
+
+def __getattr__(name: str):
+    # GH#55139
+    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,7 +3,10 @@
 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
 
@@ -26,9 +29,6 @@ def test_namespace():
         "ops",
     ]
     expected = [
-        "Block",
-        "DatetimeTZBlock",
-        "ExtensionBlock",
         "make_block",
         "DataManager",
         "ArrayManager",
@@ -44,6 +44,28 @@ def test_namespace():
     assert set(result) == set(expected + modules)
 
 
+@pytest.mark.parametrize(
+    "name",
+    [
+        "NumericBlock",
+        "ObjectBlock",
+        "Block",
+        "ExtensionBlock",
+        "DatetimeTZBlock",
+    ],
+)
+def test_deprecations(name):
+    # GH#55139
+    msg = f"{name} is deprecated.* Use public APIs instead"
+    with tm.assert_produces_warning(DeprecationWarning, match=msg):
+        getattr(internals, name)
+
+    if name not in ["NumericBlock", "ObjectBlock"]:
+        # NumericBlock and ObjectBlock are not in the internals.api namespace
+        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")