Back to Details

scaffold-module

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

scaffold-module

搭建模块

Generate new modules following pplx-sdk's layered architecture and conventions.
按照pplx-sdk的分层架构和约定生成新模块。

When to use

使用场景

Use this skill when creating a new transport backend, domain service, or shared utility for the SDK.
当你需要为SDK创建新的传输后端、领域服务或共享工具时，使用此技能。

Instructions

操作步骤

  1. Identify the target layer (core, shared, transport, domain, or client).
  2. Create the source file with proper imports, type annotations, and docstrings.
  3. Create the test file in 
    tests/test_<module>.py
    .
  4. Update 
    __init__.py
     exports in the target package.
  5. Verify with 
    pytest tests/test_<module>.py -v
    and 
    mypy pplx_sdk/
    .
  1. 确定目标层级（core、shared、transport、domain或client）。
  2. 创建源文件，包含正确的导入、类型注解和文档字符串。
  3. 创建测试文件，路径为
    tests/test_<module>.py
    。
  4. **更新
    __init__.py
    **中的目标包导出内容。
  5. 验证：运行
    pytest tests/test_<module>.py -v
    和
    mypy pplx_sdk/
    。

Layer Rules

层级规则

LayerDirectoryMay Import FromPurpose
Core
pplx_sdk/core/
NothingProtocols, types, exceptions
Shared
pplx_sdk/shared/
core/
Auth, logging, retry utilities
Transport
pplx_sdk/transport/
core/
, 
shared/
HTTP/SSE backends
Domain
pplx_sdk/domain/
core/
, 
shared/
, 
transport/
Business logic services
Client
pplx_sdk/client.py
All layersHigh-level API
层级目录可导入来源用途
Core
pplx_sdk/core/
无协议、类型、异常定义
Shared
pplx_sdk/shared/
core/
认证、日志、重试工具
Transport
pplx_sdk/transport/
core/
, 
shared/
HTTP/SSE后端
Domain
pplx_sdk/domain/
core/
, 
shared/
, 
transport/
业务逻辑服务
Client
pplx_sdk/client.py
所有层级高级API

Source File Template

源文件模板

python
"""Module description."""

from __future__ import annotations

from typing import Any, Dict, Optional

from pplx_sdk.core.exceptions import TransportError


class NewComponent:
    """Component description.

    Example:
        >>> component = NewComponent(base_url="https://api.example.com")
        >>> result = component.execute()
    """

    def __init__(
        self,
        base_url: str,
        auth_token: Optional[str] = None,
        timeout: float = 30.0,
    ) -> None:
        """Initialize component.

        Args:
            base_url: Base URL for API requests
            auth_token: Authentication token
            timeout: Request timeout in seconds
        """
        self.base_url = base_url
        self.auth_token = auth_token
        self.timeout = timeout
python
"""Module description."""

from __future__ import annotations

from typing import Any, Dict, Optional

from pplx_sdk.core.exceptions import TransportError


class NewComponent:
    """Component description.

    Example:
        >>> component = NewComponent(base_url="https://api.example.com")
        >>> result = component.execute()
    """

    def __init__(
        self,
        base_url: str,
        auth_token: Optional[str] = None,
        timeout: float = 30.0,
    ) -> None:
        """Initialize component.

        Args:
            base_url: Base URL for API requests
            auth_token: Authentication token
            timeout: Request timeout in seconds
        """
        self.base_url = base_url
        self.auth_token = auth_token
        self.timeout = timeout

Test File Template

测试文件模板

python
"""Tests for new_component module."""

import pytest
from pplx_sdk.core.exceptions import TransportError


def test_new_component_initialization():
    component = NewComponent(base_url="https://api.test.com")
    assert component.base_url == "https://api.test.com"
    assert component.timeout == 30.0


def test_new_component_error_handling():
    component = NewComponent(base_url="https://invalid.test")
    with pytest.raises(TransportError):
        component.execute()
python
"""Tests for new_component module."""

import pytest
from pplx_sdk.core.exceptions import TransportError


def test_new_component_initialization():
    component = NewComponent(base_url="https://api.test.com")
    assert component.base_url == "https://api.test.com"
    assert component.timeout == 30.0


def test_new_component_error_handling():
    component = NewComponent(base_url="https://invalid.test")
    with pytest.raises(TransportError):
        component.execute()

Checklist

检查清单

  • from __future__ import annotations
    at top
  • Complete type annotations on all functions
  • Google-style docstrings on public APIs
  • Custom exceptions from 
    pplx_sdk.core.exceptions
  • Tests with Arrange-Act-Assert pattern
  • __init__.py
    exports updated
  • 文件顶部包含
    from __future__ import annotations
  • 所有函数都有完整的类型注解
  • 公开API使用Google风格的文档字符串
  • 从
    pplx_sdk.core.exceptions
    引入自定义异常
  • 测试采用Arrange-Act-Assert模式
  • 更新了
    __init__.py
    的导出内容