用途
本技能用于在 Python 中确定性地管理资源。数据库连接、文件句柄和网络套接字等资源应被可靠释放,即使发生异常也不例外。资料列出的适用场景包括:管理数据库连接与连接池、处理文件句柄与 I/O、实现自定义上下文管理器、构建带状态的流式响应、处理嵌套资源清理、创建异步上下文管理器。
核心概念
- 上下文管理器:with 语句确保资源即使遇到异常也会自动释放。
- 协议方法:同步使用 enter/exit,异步使用 aenter/aexit 进行资源管理。
- 无条件清理:无论是否发生异常,exit 始终运行。
- 异常处理:从 exit 返回 True 表示抑制异常,返回 False 表示向上传播。
快速开始
使用 contextlib 的 @contextmanager 装饰器封装资源:
from contextlib import contextmanager
@contextmanager
def managed_resource():
resource = acquire_resource()
try:
yield resource
finally:
resource.cleanup()
with managed_resource() as r:
r.do_work()
基础模式
模式 1:类式上下文管理器
为复杂资源实现上下文管理器协议,例如带自动清理的数据库连接:
class DatabaseConnection:
"""Database connection with automatic cleanup."""
def __init__(self, dsn: str) -> None:
self._dsn = dsn
self._conn: Connection | None = None
def connect(self) -> None:
"""Establish database connection."""
self._conn = psycopg.connect(self._dsn)
def close(self) -> None:
"""Close connection if open."""
if self._conn is not None:
self._conn.close()
self._conn = None
def __enter__(self) -> "DatabaseConnection":
"""Enter context: connect and return self."""
self.connect()
return self
def __exit__(
self,
exc_type: type[BaseException] | None,
exc_val: BaseException | None,
exc_tb: TracebackType | None,
) -> None:
"""Exit context: always close connection."""
self.close()
# Usage with context manager (preferred)
with DatabaseConnection(dsn) as db:
result = db.execute(query)
# Manual management when needed
db = DatabaseConnection(dsn)
db.connect()
try:
result = db.execute(query)
finally:
db.close()
模式 2:异步上下文管理器
针对异步资源实现异步协议:
class AsyncDatabasePool:
"""Async database connection pool."""
def __init__(self, dsn: str, min_size: int = 1, max_size: int = 10) -> None:
self._dsn = dsn
self._min_size = min_size
self._max_size = max_size
self._pool: asyncpg.Pool | None = None
async def __aenter__(self) -> "AsyncDatabasePool":
"""Create connection pool."""
self._pool = await asyncpg.create_pool(
self._dsn,
min_size=self._min_size,
max_size=self._max_size,
)
return self
async def __aexit__(
self,
exc_type: type[BaseException] | None,
exc_val: BaseException | None,
exc_tb: TracebackType | None,
) -> None:
"""Close all connections in pool."""
if self._pool is not None:
await self._pool.close()
async def execute(self, query: str, *args) -> list[dict]:
"""Execute query using pooled connection."""
async with self._pool.acquire() as conn:
return await conn.fetch(query, *args)
# Usage
async with AsyncDatabasePool(dsn) as pool:
users = await pool.execute("SELECT * FROM users WHERE active = $1", True)
模式 3:使用 @contextmanager 装饰器
对于直接明了的场景,用装饰器简化上下文管理器:
from contextlib import contextmanager, asynccontextmanager
import time
import structlog
logger = structlog.get_logger()
@contextmanager
def timed_block(name: str):
"""Time a block of code."""
start = time.perf_counter()
try:
yield
finally:
elapsed = time.perf_counter() - start
logger.info(f"{name} completed", duration_seconds=round(elapsed, 3))
# Usage
with timed_block("data_processing"):
process_large_dataset()
@asynccontextmanager
async def database_transaction(conn: AsyncConnection):
"""Manage database transaction."""
await conn.execute("BEGIN")
try:
yield conn
await conn.execute("COMMIT")
except Exception:
await conn.execute("ROLLBACK")
raise
# Usage
async with database_transaction(conn) as tx:
await tx.execute("INSERT INTO users ...")
await tx.execute("INSERT INTO audit_log ...")
模式 4:无条件释放资源
无论是否发生异常,始终在 exit 中清理资源:
class FileProcessor:
"""Process file with guaranteed cleanup."""
def __init__(self, path: str) -> None:
self._path = path
self._file: IO | None = None
self._temp_files: list[Path] = []
def __enter__(self) -> "FileProcessor":
self._file = open(self._path, "r")
return self
def __exit__(
self,
exc_type: type[BaseException] | None,
exc_val: BaseException | None,
exc_tb: TracebackType | None,
) -> None:
"""Clean up all resources unconditionally."""
# Close main file
if self._file is not None:
self._file.close()
# Clean up any temporary files
for temp_file in self._temp_files:
try:
temp_file.unlink()
except OSError:
pass # Best effort cleanup
# Return None/False to propagate any exception
更详细的示例与模式
资料说明,从“Advanced Patterns”开始的详细章节位于 references/details.md。当上述导航摘要不足时,可阅读该文件。
最佳实践摘要
- 始终使用上下文管理器:适用于任何需要清理的资源。
- 无条件清理:exit 即使在异常时也会运行。
- 不要意外抑制异常:除非有意抑制,否则返回 False。
- 使用 @contextmanager:适用于简单的资源模式。
- 同时实现两种协议:支持 with 与手动管理。
- 使用 ExitStack:用于处理数量动态的资源。
- 高效累积:使用列表加 join,而非字符串拼接。
- 跟踪指标:对流式处理而言,首字节时延很重要。
- 记录行为:尤其是异常抑制行为。
- 测试清理路径:验证错误时资源确实被释放。
限制
资料未说明该技能的收费、价格、支持平台或安装方式,这些信息暂未提供。