Add low-level create_dataframe_from_blocks helper function

pandas/api/internals.py

@@ -0,0 +1,50 @@
+from pandas import DataFrame
+from pandas.core.internals.api import _make_block
+from pandas.core.internals.managers import BlockManager as _BlockManager
+
+
+def create_dataframe_from_blocks(blocks, index, columns):
+    """
+    Low-level function to create a DataFrame from arrays as they are
+    representing the block structure of the resulting DataFrame.
+
+    Attention: this is an advanced, low-level function that should only be
+    used if you know that the below-mentioned assumptions are guaranteed.
+    If passing data that do not follow those assumptions, subsequent
+    subsequent operations on the resulting DataFrame might lead to strange
+    errors.
+
+    Assumptions:
+
+    - The block arrays are either a 2D numpy array or a pandas ExtensionArray
+    - In case of a numpy array, it is assumed to already be in the expected
+      shape for Blocks (2D, (cols, rows), i.e. transposed compared to the
+      DataFrame columns).
+    - All arrays are taken as is (no type inference) and expected to have the
+      correct size.
+    - The placement arrays have the correct length (equalling the number of
+      columns that its equivalent block array represents), and all placement
+      arrays together form a complete set of 0 to n_columns - 1.
+
+    Parameters
+    ----------
+    blocks : list of tuples of (block_array, block_placement)
+        This should be a list of tuples existing of (block_array, block_placement),
+        where:
+
+        - block_array is a 2D numpy array or a 1D ExtensionArray, following the
+          requirements listed above.
+        - block_placement is a 1D integer numpy array
+    index : Index
+        The Index object for the `index` of the resulting DataFrame.
+    columns : Index
+        The Index object for the `columns` of the resulting DataFrame.
+
+    Returns
+    -------
+    DataFrame
+    """
+    blocks = [_make_block(*block) for block in blocks]
+    axes = [columns, index]
+    mgr = _BlockManager(blocks, axes)
+    return DataFrame._from_mgr(mgr, mgr.axes)

pandas/core/internals/api.py

@@ -18,10 +18,14 @@
 from pandas.core.dtypes.common import pandas_dtype
 from pandas.core.dtypes.dtypes import (
     DatetimeTZDtype,
+    ExtensionDtype,
     PeriodDtype,
 )
 
-from pandas.core.arrays import DatetimeArray
+from pandas.core.arrays import (
+    DatetimeArray,
+    ExtensionArray,
+)
 from pandas.core.construction import extract_array
 from pandas.core.internals.blocks import (
     check_ndim,
@@ -37,6 +41,33 @@
     from pandas.core.internals.blocks import Block
 
 
+def _make_block(values: ExtensionArray | np.ndarray, placement: np.ndarray) -> Block:
+    """
+    This is an analogue to blocks.new_block(_2d) that ensures:
+    1) correct dimension for EAs that support 2D (`ensure_block_shape`), and
+    2) correct EA class for datetime64/timedelta64 (`maybe_coerce_values`).
+
+    The input `values` is assumed to be either numpy array or ExtensionArray:
+    - In case of a numpy array, it is assumed to already be in the expected
+      shape for Blocks (2D, (cols, rows)).
+    - In case of an ExtensionArray the input can be 1D, also for EAs that are
+      internally stored as 2D.
+
+    For the rest no preprocessing or validation is done, except for those dtypes
+    that are internally stored as EAs but have an exact numpy equivalent (and at
+    the moment use that numpy dtype), i.e. datetime64/timedelta64.
+    """
+    dtype = values.dtype
+    klass = get_block_type(dtype)
+    placement = BlockPlacement(placement)
+
+    if isinstance(dtype, ExtensionDtype) and dtype._supports_2d:
+        values = ensure_block_shape(values, ndim=2)
+
+    values = maybe_coerce_values(values)
+    return klass(values, ndim=2, placement=placement)
+
+
 def make_block(
     values, placement, klass=None, ndim=None, dtype: Dtype | None = None
 ) -> Block:

scripts/validate_unwanted_patterns.py

@@ -54,6 +54,7 @@
     # TODO(4.0): GH#55043 - remove upon removal of CoW option
     "_get_option",
     "_fill_limit_area_1d",
+    "_make_block",
 }