如何用DataFrame.loc[]获取单行数据，非单行时抛出异常

假设我们有如下DataFrame：

import pandas as pd
df = pd.DataFrame([["house", "red"], ["car", "blue"]], columns=["item", "colour"])

需求：使用DataFrame.loc筛选数据时，获取单行数据并以pd.Series返回；若筛选结果不是恰好一行（0行或多行），则抛出异常，实现类似SQLAlchemy中Query.one()的功能。

现有代码片段：

match = df.loc[df["colour"] == "red"]
# 已知结果DataFrame恰好有一行
# TODO：如何让match返回单行pd.Series

解决方案 #

基础实现方式 #

先执行筛选，手动校验行数后转换为Series：

mask = df["colour"] == "red"
match_df = df.loc[mask]

# 校验行数，非1行则抛异常
if len(match_df) != 1:
    raise ValueError(f"预期恰好1行数据，实际获取到{len(match_df)}行")

# 将单行DataFrame转为Series
match_series = match_df.iloc[0]

封装复用函数（惯用方式） #

将逻辑封装成可复用函数，方便多次调用：

def get_one_row(df, filter_mask):
    result_df = df.loc[filter_mask]
    row_count = len(result_df)
    if row_count != 1:
        raise ValueError(f"预期1行数据，实际找到{row_count}行")
    return result_df.iloc[0]

# 使用示例
match_series = get_one_row(df, df["colour"] == "red")

关键说明 #

• 用len(result_df)检查筛选结果的行数，确保符合"恰好一行"的要求，不符合时抛出明确的异常信息
• 通过iloc[0]将单行DataFrame转换为pd.Series，这是Pandas中提取单行并转为Series的标准操作

内容的提问来源于stack exchange，提问作者Mikko Ohtamaa