Python __repr__ 与 __str__ 深度解析：5 个真实项目案例与最佳实践

在 Python 开发中，对象的字符串表示形式是调试、日志记录和用户交互的核心部分。 __repr__ 和 __str__ 这两个魔术方法虽然功能相似，但设计目的和使用场景截然不同。本文将深入探讨它们的差异，并通过 5 个真实项目案例展示如何高效实现这两个方法。

1. 核心概念解析： __repr__ 与 __str__ 的本质区别

1.1 设计哲学对比

• __repr__ ：面向开发者，目标是提供 无歧义的 对象描述，理想情况下应该能直接用于重建对象
• __str__ ：面向终端用户，提供 可读性强的 信息展示

class User:
    def __init__(self, name, user_id):
        self.name = name
        self.user_id = user_id
        
    def __repr__(self):
        return f"User(name={self.name!r}, user_id={self.user_id!r})"
    
    def __str__(self):
        return f"User: {self.name} (ID: {self.user_id})"

1.2 调用场景对照表

提示：当 __str__ 未定义时，Python 会回退到使用 __repr__

2. 实战案例：Web 开发中的最佳实践

2.1 Django 模型表示

在 Django 项目中，良好的字符串表示能极大提升开发效率：

from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    stock = models.PositiveIntegerField()

    def __str__(self):
        return f"{self.name} - ${self.price}"
    
    def __repr__(self):
        return (
            f"<Product id={self.id} name={self.name!r} "
            f"price={float(self.price)} stock={self.stock}>"
        )

典型输出对比 ：

• str(product) → "iPhone 13 - $999.99"
• repr(product) → " "

2.2 Pydantic 模型调试

Pydantic 的数据验证模型中， __repr__ 应该包含所有关键字段：

from pydantic import BaseModel

class APIResponse(BaseModel):
    status: int
    data: dict
    timestamp: float

    def __repr__(self):
        return (
            f"APIResponse(status={self.status}, "
            f"data_keys={list(self.data.keys())}, "
            f"timestamp={self.timestamp})"
        )
    
    def __str__(self):
        return f"API Status: {self.status} | Data Keys: {len(self.data)}"

3. 数据分析场景的应用

3.1 Pandas DataFrame 包装类

class AnalyzedData:
    def __init__(self, raw_data, stats):
        self.raw_data = raw_data  # pd.DataFrame
        self.stats = stats        # dict
        
    def __repr__(self):
        return (
            f"AnalyzedData(shape={self.raw_data.shape}, "
            f"stats_keys={list(self.stats.keys())})"
        )
    
    def __str__(self):
        return (
            f"Data Analysis Report\n"
            f"-------------------\n"
            f"Records: {len(self.raw_data)}\n"
            f"Features: {len(self.raw_data.columns)}\n"
            f"Statistics: {', '.join(self.stats.keys())}"
        )

3.2 实验配置对象

class ExperimentConfig:
    def __init__(self, params):
        self.params = params
        
    def __repr__(self):
        return f"ExperimentConfig({self.params!r})"
    
    def __str__(self):
        return "Experiment Configuration:\n" + "\n".join(
            f"  {k}: {v}" for k, v in self.params.items()
        )

4. API 设计中的实用技巧

4.1 错误响应对象

class APIError:
    def __init__(self, code, message, details=None):
        self.code = code
        self.message = message
        self.details = details or {}
        
    def __repr__(self):
        return (
            f"APIError(code={self.code!r}, "
            f"message={self.message!r}, "
            f"details_keys={list(self.details.keys())})"
        )
    
    def __str__(self):
        return f"[Error {self.code}] {self.message}"

4.2 分页结果表示

class PaginatedResult:
    def __init__(self, items, total, page, per_page):
        self.items = items
        self.total = total
        self.page = page
        self.per_page = per_page
        
    def __repr__(self):
        return (
            f"PaginatedResult(items_type={type(self.items).__name__}, "
            f"total={self.total}, page={self.page}, "
            f"per_page={self.per_page})"
        )
    
    def __str__(self):
        return (
            f"Page {self.page} of {self.total_pages} "
            f"({len(self.items)} items shown)"
        )
    
    @property
    def total_pages(self):
        return (self.total + self.per_page - 1) // self.per_page

5. 最佳实践清单

1. __repr__ 实现原则 ：

   • 包含足够信息重建对象
   • 对字符串属性使用 !r 自动添加引号
   • 对于复杂对象，显示关键元数据而非全部内容

2. __str__ 设计指南 ：

   • 保持简洁易懂
   • 避免技术细节
   • 考虑多行格式化输出

3. 常见陷阱 ：

   • 在 __repr__ 中调用 str() 方法
   • 两个方法返回完全相同的内容
   • 忽略集合类对象的特殊表示需求

4. 性能优化技巧 ：

   • 对大对象使用惰性求值
   • 缓存频繁调用的字符串结果
   • 使用 __slots__ 减少内存开销

class OptimizedUser:
    __slots__ = ('name', 'user_id', '_str_cache')
    
    def __init__(self, name, user_id):
        self.name = name
        self.user_id = user_id
        self._str_cache = None
        
    def __str__(self):
        if self._str_cache is None:
            self._str_cache = f"User: {self.name} (ID: {self.user_id})"
        return self._str_cache
    
    def __repr__(self):
        return f"User({self.name!r}, {self.user_id!r})"

通过合理实现这两个魔术方法，可以显著提升代码的可维护性和调试效率。在实际项目中，建议结合具体场景选择适当的表示形式，并保持整个项目中的风格一致。