Jupyter Notebook中Python字符串输出的美化与截断处理

一、长文本输出的核心痛点与机制差异

在Jupyter环境中，很多初学者容易混淆直接在代码单元格最后输入变量名与调用 print() 的输出机制。直接输出变量名触发的是Python对象的 __repr__ 表达，Jupyter通过交互显示通道呈现结果，换行符 \n 会被直接显示为转义字面量；而 print() 触发对象的 __str__ 表达，将解析后的纯文本流重定向至 stdout。

当输出内容超过常规单元格高度时，Jupyter前端会默认将其截断或在单元格左侧添加点击可切换的滚动区域。然而，纯文本输出缺乏自适应边界能力，如果单行字符数达到数千字符且没有空格分词，浏览器不仅渲染迟缓，还会产生巨大的横向滚动条。

二、标准库原生方案：折行、格式化与截断

在不引入复杂第三方依赖的前提下，Python自带的标准库提供了极其稳定的格式化与截断工具，能够快速解决绝大部分常见排版问题。

1. 使用 textwrap 模块控制单行宽度

针对没有自然换行的长句子或自然语言文本，textwrap.fill() 能够按照指定的每行最大字符数自动折行，避免横向长条的出现：

import textwrap

long_text = "Jupyter Notebook是一个基于Web的交互式计算笔记本环境。当我们在单元格中输出极为冗长的字符串时，默认的展示方式往往会横向拉得很长，降低排版美感与代码可读性。"

# 限制单行最大宽度为36个字符自动折行
wrapped_text = textwrap.fill(long_text, width=36)
print(wrapped_text)

2. 使用 textwrap.shorten 优雅截断

如果只想查看长文本的开头摘要并保证整体长度不超出限制，切忌直接使用硬切片 text[:100]。硬切片容易将英文单词或中文词组在中间生硬截断。textwrap.shorten() 会尽量以空格和单词为边界截断，并在末尾追加占位符：

import textwrap

log_line = "2026-10-20 18:42:10 ERROR Database connection pool exhausted: timeout waiting for idle connection from host 10.0.4.12"

# 截断到最大50个字符，超出部分以 [...] 替代
short_log = textwrap.shorten(log_line, width=50, placeholder=" [...]")
print(short_log)
# 示例输出：2026-10-20 18:42:10 ERROR Database connection [...]

3. 结构化字符串的美化：pprint 与 json.dumps

针对包含字典或嵌套对象的字符串，直接 print() 会难以辨别层级。可以使用 json.dumps() 配合缩进参数，或者使用标准库 pprint：

import json

raw_json_str = '{"status":"success","code":200,"data":{"user_id":10086,"profile":{"name":"Alex","tags":["python","data-science","ml"],"history":[{"action":"login","timestamp":1729420000}]}}}'

# 解析并重新美化输出
parsed = json.loads(raw_json_str)
pretty_str = json.dumps(parsed, indent=2, ensure_ascii=False)
print(pretty_str)

三、借助 IPython.display 打造富文本美化输出

在Jupyter环境中，最高效的美化手段是利用内核原生的 IPython.display 模块。通过将字符串转换为HTML或Markdown对象，我们可以彻底突破标准终端输出的样式限制。

1. Markdown 格式化渲染

对于需要呈现标题、粗体、代码块或引用段落的说明性文本，将其包裹为 Markdown 对象输出能大幅改善排版质感：

from IPython.display import display, Markdown

report = """
### 数据清洗流水线报告
- **处理状态**: 完成
- **异常行数**: 12 行已自动过滤
> **核心提示**: 下游任务请在调用前先验证空值填充率。
"""

display(Markdown(report))

2. 构建带独立滚动条的固定高度容器

当面临成千上万行的调试日志或未分块的巨型字符串时，既不想破坏整体排版，又希望能自由上下滚动查阅，最佳方式是构建一个带有局部内联CSS样式的 <pre> 容器：

import html
from IPython.display import display, HTML

def display_scrollable_text(text: str, max_height: int = 240):
    """
    在Jupyter中生成一个限制最大高度且支持垂直滚动的纯文本容器。
    """
    # 必须执行HTML转义，防止文本内部的特殊字符破坏DOM
    escaped_text = html.escape(text)
    
    html_template = f"""
    <pre style="
        max-height: {max_height}px;
        overflow-y: auto;
        background-color: #1e1e1e;
        color: #d4d4d4;
        padding: 12px 16px;
        border-radius: 6px;
        font-family: 'Consolas', 'Menlo', monospace;
        font-size: 13px;
        line-height: 1.5;
        white-space: pre-wrap;
        word-break: break-all;
        border: 1px solid #333;
    ">{escaped_text}</pre>
    """
    display(HTML(html_template))

# 模拟超长日志字符串
dummy_logs = "\n".join([f"Log Line [{i:04d}]: Processing item token #{i*137}..." for i in range(150)])
display_scrollable_text(dummy_logs, max_height=200)

四、双向保留的高级截断算法

在很多算法日志和模型调试场景中，字符串的最前部分（如请求头、版本号、初始参数）和最后部分（如执行结果状态码、耗时总结）是最重要的，而中间的重复循环体或长载荷可以被省略。

针对这种情况，设计一个“两端保留、中间省略”的双向截断函数是极其便利的解法：

def truncate_middle(content: str, max_chars: int = 120, separator: str = " ... [中间已省略 %d 字符] ... ") -> str:
    """
    两端保留的对称截断函数：当字符数超标时，保留前段与后段，折叠中间内容。
    """
    if len(content) <= max_chars:
        return content
    
    # 预留占位符的空间评估
    rough_sep_len = len(separator % 0)
    if max_chars <= rough_sep_len + 4:
        # 预算太小时回退为普通单侧截断
        return content[:max_chars]
    
    keep_len = (max_chars - rough_sep_len) // 2
    omitted_count = len(content) - (keep_len * 2)
    actual_separator = separator % omitted_count
    
    return content[:keep_len] + actual_separator + content[-keep_len:]

# 验证效果
sample_token = "ey" + "x"*600 + "signature_part_end"
print(truncate_middle(sample_token, max_chars=80))
# 示例输出：eyxxxxxxxxxxxxxxxxxxxxxxxxxxx ... [中间已省略 549 字符] ... xxxxxxxxxsignature_part_end

五、方案选型矩阵与核心注意事项

根据应用场景的侧重点不同，开发者应灵活组合使用不同技术方案。下表汇总了常见处理方案的适用场景与开销特征：