mcpField
P
python-skills

python-skills

github.com/llama-farm开发83668 次安装21 周前更新
代码仓库

关于 python-skills

面向 LlamaFarm monorepo Python 组件的实践指南与代码审查清单，涵盖常见架构、异步、测试和安全规范。

主要功能

  1. 01Python 编码规范
  2. 02架构模式参考
  3. 03异步与类型检查清单
  4. 04测试与错误处理建议
  5. 05安全审查要点

适用场景

  1. 01审查 LlamaFarm Python 代码
  2. 02统一不同组件的编码实践
  3. 03检查异步任务与异常处理
  4. 04排查输入处理和反序列化风险

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/llama-farm/llamafarm --skill python-skills

安装后在 Claude Code 中输入/python-skills确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

async.md
error-handling.md
patterns.md
security.md
testing.md
typing.md

详细介绍

LlamaFarm 的 Python 技能

适用于 LlamaFarm 单体仓库中所有 Python 组件的通用最佳实践和代码审查清单。

适用组件

组件路径Python主要依赖项
服务端server/3.12+FastAPI、Celery、Pydantic、structlog
RAGrag/3.11+LlamaIndex、ChromaDB、Celery
通用运行时runtimes/universal/3.11+PyTorch、transformers、FastAPI
配置config/3.11+Pydantic、JSONSchema
通用组件common/3.10+HuggingFace Hub

快速参考

主题文件要点
模式patterns.mdDataclass、Pydantic、推导式、导入
异步async.mdasync/await、asyncio、并发执行
类型typing.md类型提示、泛型、协议、Pydantic
测试testing.mdPytest 夹具、模拟、异步测试
错误error-handling.md自定义异常、日志记录、上下文管理器
安全security.md路径遍历、注入、密钥、反序列化

代码风格

LlamaFarm 使用 ruff，并在 ruff.toml 中共享配置：

line-length = 88
target-version = "py311"
select = ["E", "F", "I", "B", "UP", "SIM"]

主要规则：

  • E, F：核心 pyflakes 和 pycodestyle
  • I：导入排序（isort）
  • B：Bugbear（常见陷阱）
  • UP：将语法升级为现代 Python
  • SIM：简化代码模式

架构模式

使用 pydantic-settings 管理设置
from pydantic_settings import BaseSettings

class Settings(BaseSettings, env_file=".env"):
    LOG_LEVEL: str = "INFO"
    HOST: str = "0.0.0.0"
    PORT: int = 14345

settings = Settings()  # Singleton at module level
使用 structlog 进行结构化日志记录
from core.logging import FastAPIStructLogger  # Server
from core.logging import RAGStructLogger      # RAG
from core.logging import UniversalRuntimeLogger  # Runtime

logger = FastAPIStructLogger(__name__)
logger.info("Operation completed", extra={"count": 10, "duration_ms": 150})
使用抽象基类实现可扩展性
from abc import ABC, abstractmethod

class Component(ABC):
    def __init__(self, name: str, config: dict[str, Any] | None = None):
        self.name = name or self.__class__.__name__
        self.config = config or {}

    @abstractmethod
    def process(self, documents: list[Document]) -> ProcessingResult:
        pass
使用 Dataclass 存储内部数据
from dataclasses import dataclass, field

@dataclass
class Document:
    content: str
    metadata: dict[str, Any] = field(default_factory=dict)
    id: str = field(default_factory=lambda: str(uuid.uuid4()))
使用 Pydantic 模型定义 API 边界
from pydantic import BaseModel, Field, ConfigDict

class EmbeddingRequest(BaseModel):
    model: str
    input: str | list[str]
    encoding_format: Literal["float", "base64"] | None = "float"

    model_config = ConfigDict(str_strip_whitespace=True)

目录结构

每个 Python 组件都遵循以下结构：

component/
├── pyproject.toml     # UV-managed dependencies
├── core/              # Core functionality
│   ├── __init__.py
│   ├── settings.py    # Pydantic Settings
│   └── logging.py     # structlog setup
├── services/          # Business logic (server)
├── models/            # ML models (runtime)
├── tasks/             # Celery tasks (rag)
├── utils/             # Utility functions
└── tests/
    ├── conftest.py    # Shared fixtures
    └── test_*.py

审查清单摘要

审查 LlamaFarm 中的 Python 代码时：

  1. 模式（中优先级）

    • 使用现代 Python 语法（3.10+ 类型提示）
    • 适当使用 Dataclass 或 Pydantic
    • 不使用可变默认参数

  2. 异步（高优先级）

    • 异步函数中不进行阻塞调用
    • 正确使用 asyncio.Lock
    • 正确处理取消操作

  3. 类型（中优先级）

    • 完整的返回类型提示
    • 为泛型类型指定参数
    • 使用 Pydantic v2 模式

  4. 测试（中优先级）

    • 正确设置夹具作用域
    • 异步测试使用 pytest-asyncio
    • 清理模拟对象

  5. 错误（高优先级）

    • 自定义异常包含上下文
    • 使用 extra dict 进行结构化日志记录
    • 正确链接异常

  6. 安全（关键优先级）

    • 防止路径遍历
    • 清理输入
    • 安全反序列化

有关包含 grep 模式的详细清单，请参阅各主题文件。

评论

支持 Markdown