函数封装数据处理逻辑时，大多数情况下会在函数内部创建或转换 Pandas DataFrame，然后通过 return 语句把结果交给调用方。调用方拿到这个返回的 DataFrame 对象后，可以继续做筛选、聚合、可视化或写入文件。这里的关键不是函数内部如何创建数据，而是 Python 的 return 机制如何把一个局部作用域中的对象引用传递出来。理解这一点能帮助你避免返回 None、误改外部变量等常见问题。
一、return 是对象引用跨作用域传递的通道
Python 函数内部会新建独立的局部命名空间。函数内的变量名比如 df 默认只在这个命名空间中有效，函数执行结束后，局部命名空间会被销毁。但对象本身并不一定被销毁，只要还有引用指向它。return 语句的作用就是把这个对象引用传递到调用方的作用域中。如果函数内创建了一个 DataFrame 并将其 return，外部的变量就可以绑定到同一个对象，从而继续访问其中的数据。
例如，下面的函数根据一份字典构造 DataFrame，并返回。调用时用 df_result 接收返回值。
import pandas as pd
def create_sales_data():
data = {
"product": ["手机", "平板", "耳机"],
"amount": [1200, 800, 300],
"region": ["华东", "华南", "华北"]
}
df = pd.DataFrame(data)
return df
df_result = create_sales_data()
print(df_result)
在这个例子中，函数内部的 df 变量在函数结束后会消失，但 DataFrame 对象本身由 df_result 继续引用。外部访问 df_result 时看到的是与函数内相同的三行数据。既然返回的是引用而不是副本，如果在外部对 df_result 进行原地修改，比如添加新列，那么底层对象会随之改变。这一点在数据量较大时非常有利，因为它避免了不必要的拷贝开销。
二、接收返回值的几种常用写法
最常见的做法是直接用一个变量接收函数的返回值。接收后变量就是普通的 DataFrame，可以无缝使用 Pandas 提供的所有方法和属性。比如马上查看前几行、检查维度、或者继续筛选数据。这种写法简单直接，适合大多数数据清洗和转换场景。
如果函数返回多个 DataFrame，可以让函数返回元组或列表，调用方通过解包同时接收。比如一个函数同时返回训练集和测试集，或者将原始数据按区域拆分。解包后每个变量都指向对应的 DataFrame。
import pandas as pd
def split_by_region(df):
east = df[df["region"] == "华东"].copy()
north = df[df["region"] == "华北"].copy()
return east, north
df_east, df_north = split_by_region(df_result)
print(df_east.head())
print(df_north.head())
另一种常见写法是在函数返回之后直接链式调用。因为函数调用的结果就是一个 DataFrame 对象，可以直接在其后接上方法。例如 create_sales_data().query("amount > 500")。这种写法适合一次性处理，不需要保留中间变量。不过如果需要多次使用同一个 DataFrame，还是建议先赋值给变量，否则重复调用函数会重复创建数据，既浪费计算又可能导致结果不一致。
三、忘记 return 与原地修改的两类典型问题
第一个典型问题是函数内创建了 DataFrame 却没有 return。此时函数仍然可以运行，但调用方拿到的值是 None。很多人误以为只要函数内部用了变量名 df，外部就能自动看到它。实际上函数内部的 df 只是局部变量，不会影响外部命名空间。比如下面这个写法就会得到 None。
import pandas as pd
def build_df_wrong():
df = pd.DataFrame({"value": [1, 2, 3]})
# 没有 return df
result = build_df_wrong()
print(result is None) # True
第二个典型问题与原地修改有关。Pandas 的一些操作支持 inplace=True 参数，比如 drop、rename 等。这类操作如果设置了 inplace=True，会在原对象上修改并返回 None。假设函数接收外部传入的 DataFrame，并在内部使用 inplace=True 修改了数据，那么外部传入的 DataFrame 会被改变，但函数返回值仍然是 None。这会让调用方同时遇到两个意外：外部数据被修改了，但返回值无法再用于链式调用。
import pandas as pd
def clean_inplace(df):
df.drop(columns=["tmp"], inplace=True)
return None
data = pd.DataFrame({"value": [10, 20], "tmp": [1, 2]})
clean_inplace(data)
print(data.columns.tolist()) # ['value']
print(clean_inplace(data)) # None
为了避免混淆，建议函数要么返回一个新的 DataFrame，要么原地修改并明确返回 None。最好不要既修改传入对象又返回一个表面看起来像新对象的结果。若函数需要保留原始数据，应在内部使用 .copy() 后再修改，然后 return 修改后的副本。这样调用侧的数据流会更加清晰。
四、把返回 DataFrame 封装成可组合的数据管道
当数据处理步骤变多时，可以把每个步骤写成独立的函数，每个函数都接收 DataFrame 并返回 DataFrame。这样外部访问每个阶段的结果都非常直观。典型的清理流程可以拆成读取数据、清洗字段、构造特征三个函数，主流程依次调用并将返回值传给下一个环节。由于每一步的返回值都是 DataFrame，外部变量可以随时检查中间结果是否合理。
下面的代码演示了一个小型管道，函数之间只通过返回值和参数传递数据，没有依赖任何全局变量。
import pandas as pd
def load_raw():
return pd.DataFrame({
"order_id": [1, 2, 3],
"price": [99.0, 150.5, 80.0],
"qty": [2, 1, 4]
})
def add_total(df):
df = df.copy()
df["total"] = df["price"] * df["qty"]
return df
def filter_big_orders(df, threshold):
return df[df["total"] >= threshold].copy()
raw = load_raw()
with_total = add_total(raw)
big_orders = filter_big_orders(with_total, 200)
print(big_orders)
这种函数式风格让每个函数的返回值都成为下一个函数的输入，外部访问 DataFrame 自然不存在障碍。加上类型注解可以进一步提高可读性和 IDE 支持，例如将返回值标注为 pd.DataFrame。团队协作时，清晰的函数签名能帮助其他人快速判断数据在管道中的流动方向。最终你会发现，函数外部访问 DataFrame 并不复杂，核心就是显式 return、调用侧接收、按需控制副作用。
Pandas DataFrame函数返回值变量作用域修改时间：2026-08-23 04:29:22