from __future__ import annotations
|
|
from typing import (
|
TYPE_CHECKING,
|
Literal,
|
overload,
|
)
|
import warnings
|
|
import numpy as np
|
|
from pandas._libs import (
|
lib,
|
missing as libmissing,
|
)
|
from pandas.util._exceptions import find_stack_level
|
|
from pandas.core.dtypes.cast import maybe_box_native
|
from pandas.core.dtypes.dtypes import (
|
BaseMaskedDtype,
|
ExtensionDtype,
|
)
|
|
from pandas.core import common as com
|
|
if TYPE_CHECKING:
|
from pandas._typing import MutableMappingT
|
|
from pandas import DataFrame
|
|
|
@overload
|
def to_dict(
|
df: DataFrame,
|
orient: Literal["dict", "list", "series", "split", "tight", "index"] = ...,
|
*,
|
into: type[MutableMappingT] | MutableMappingT,
|
index: bool = ...,
|
) -> MutableMappingT:
|
...
|
|
|
@overload
|
def to_dict(
|
df: DataFrame,
|
orient: Literal["records"],
|
*,
|
into: type[MutableMappingT] | MutableMappingT,
|
index: bool = ...,
|
) -> list[MutableMappingT]:
|
...
|
|
|
@overload
|
def to_dict(
|
df: DataFrame,
|
orient: Literal["dict", "list", "series", "split", "tight", "index"] = ...,
|
*,
|
into: type[dict] = ...,
|
index: bool = ...,
|
) -> dict:
|
...
|
|
|
@overload
|
def to_dict(
|
df: DataFrame,
|
orient: Literal["records"],
|
*,
|
into: type[dict] = ...,
|
index: bool = ...,
|
) -> list[dict]:
|
...
|
|
|
# error: Incompatible default for argument "into" (default has type "type[dict
|
# [Any, Any]]", argument has type "type[MutableMappingT] | MutableMappingT")
|
def to_dict(
|
df: DataFrame,
|
orient: Literal[
|
"dict", "list", "series", "split", "tight", "records", "index"
|
] = "dict",
|
*,
|
into: type[MutableMappingT] | MutableMappingT = dict, # type: ignore[assignment]
|
index: bool = True,
|
) -> MutableMappingT | list[MutableMappingT]:
|
"""
|
Convert the DataFrame to a dictionary.
|
|
The type of the key-value pairs can be customized with the parameters
|
(see below).
|
|
Parameters
|
----------
|
orient : str {'dict', 'list', 'series', 'split', 'tight', 'records', 'index'}
|
Determines the type of the values of the dictionary.
|
|
- 'dict' (default) : dict like {column -> {index -> value}}
|
- 'list' : dict like {column -> [values]}
|
- 'series' : dict like {column -> Series(values)}
|
- 'split' : dict like
|
{'index' -> [index], 'columns' -> [columns], 'data' -> [values]}
|
- 'tight' : dict like
|
{'index' -> [index], 'columns' -> [columns], 'data' -> [values],
|
'index_names' -> [index.names], 'column_names' -> [column.names]}
|
- 'records' : list like
|
[{column -> value}, ... , {column -> value}]
|
- 'index' : dict like {index -> {column -> value}}
|
|
.. versionadded:: 1.4.0
|
'tight' as an allowed value for the ``orient`` argument
|
|
into : class, default dict
|
The collections.abc.MutableMapping subclass used for all Mappings
|
in the return value. Can be the actual class or an empty
|
instance of the mapping type you want. If you want a
|
collections.defaultdict, you must pass it initialized.
|
|
index : bool, default True
|
Whether to include the index item (and index_names item if `orient`
|
is 'tight') in the returned dictionary. Can only be ``False``
|
when `orient` is 'split' or 'tight'.
|
|
.. versionadded:: 2.0.0
|
|
Returns
|
-------
|
dict, list or collections.abc.Mapping
|
Return a collections.abc.MutableMapping object representing the
|
DataFrame. The resulting transformation depends on the `orient` parameter.
|
"""
|
if not df.columns.is_unique:
|
warnings.warn(
|
"DataFrame columns are not unique, some columns will be omitted.",
|
UserWarning,
|
stacklevel=find_stack_level(),
|
)
|
# GH16122
|
into_c = com.standardize_mapping(into)
|
|
# error: Incompatible types in assignment (expression has type "str",
|
# variable has type "Literal['dict', 'list', 'series', 'split', 'tight',
|
# 'records', 'index']")
|
orient = orient.lower() # type: ignore[assignment]
|
|
if not index and orient not in ["split", "tight"]:
|
raise ValueError(
|
"'index=False' is only valid when 'orient' is 'split' or 'tight'"
|
)
|
|
if orient == "series":
|
# GH46470 Return quickly if orient series to avoid creating dtype objects
|
return into_c((k, v) for k, v in df.items())
|
|
box_native_indices = [
|
i
|
for i, col_dtype in enumerate(df.dtypes.values)
|
if col_dtype == np.dtype(object) or isinstance(col_dtype, ExtensionDtype)
|
]
|
box_na_values = [
|
lib.no_default if not isinstance(col_dtype, BaseMaskedDtype) else libmissing.NA
|
for i, col_dtype in enumerate(df.dtypes.values)
|
]
|
are_all_object_dtype_cols = len(box_native_indices) == len(df.dtypes)
|
|
if orient == "dict":
|
return into_c((k, v.to_dict(into=into)) for k, v in df.items())
|
|
elif orient == "list":
|
object_dtype_indices_as_set: set[int] = set(box_native_indices)
|
return into_c(
|
(
|
k,
|
list(map(maybe_box_native, v.to_numpy(na_value=box_na_values[i])))
|
if i in object_dtype_indices_as_set
|
else list(map(maybe_box_native, v.to_numpy())),
|
)
|
for i, (k, v) in enumerate(df.items())
|
)
|
|
elif orient == "split":
|
data = df._create_data_for_split_and_tight_to_dict(
|
are_all_object_dtype_cols, box_native_indices
|
)
|
|
return into_c(
|
((("index", df.index.tolist()),) if index else ())
|
+ (
|
("columns", df.columns.tolist()),
|
("data", data),
|
)
|
)
|
|
elif orient == "tight":
|
data = df._create_data_for_split_and_tight_to_dict(
|
are_all_object_dtype_cols, box_native_indices
|
)
|
|
return into_c(
|
((("index", df.index.tolist()),) if index else ())
|
+ (
|
("columns", df.columns.tolist()),
|
(
|
"data",
|
[
|
list(map(maybe_box_native, t))
|
for t in df.itertuples(index=False, name=None)
|
],
|
),
|
)
|
+ ((("index_names", list(df.index.names)),) if index else ())
|
+ (("column_names", list(df.columns.names)),)
|
)
|
|
elif orient == "records":
|
columns = df.columns.tolist()
|
if are_all_object_dtype_cols:
|
rows = (
|
dict(zip(columns, row)) for row in df.itertuples(index=False, name=None)
|
)
|
return [
|
into_c((k, maybe_box_native(v)) for k, v in row.items()) for row in rows
|
]
|
else:
|
data = [
|
into_c(zip(columns, t)) for t in df.itertuples(index=False, name=None)
|
]
|
if box_native_indices:
|
object_dtype_indices_as_set = set(box_native_indices)
|
object_dtype_cols = {
|
col
|
for i, col in enumerate(df.columns)
|
if i in object_dtype_indices_as_set
|
}
|
for row in data:
|
for col in object_dtype_cols:
|
row[col] = maybe_box_native(row[col])
|
return data
|
|
elif orient == "index":
|
if not df.index.is_unique:
|
raise ValueError("DataFrame index must be unique for orient='index'.")
|
columns = df.columns.tolist()
|
if are_all_object_dtype_cols:
|
return into_c(
|
(t[0], dict(zip(df.columns, map(maybe_box_native, t[1:]))))
|
for t in df.itertuples(name=None)
|
)
|
elif box_native_indices:
|
object_dtype_indices_as_set = set(box_native_indices)
|
is_object_dtype_by_index = [
|
i in object_dtype_indices_as_set for i in range(len(df.columns))
|
]
|
return into_c(
|
(
|
t[0],
|
{
|
columns[i]: maybe_box_native(v)
|
if is_object_dtype_by_index[i]
|
else v
|
for i, v in enumerate(t[1:])
|
},
|
)
|
for t in df.itertuples(name=None)
|
)
|
else:
|
return into_c(
|
(t[0], dict(zip(df.columns, t[1:]))) for t in df.itertuples(name=None)
|
)
|
|
else:
|
raise ValueError(f"orient '{orient}' not understood")
|
