AGENT SKILL

scaffold-decorator

Add or wire helpers/decorators, preferring ArchiPy's (ttl_cache, atomic UoW, trace_span, measure_duration, retry). Use for "cache this function", "add timing/tracing/retry", or "write a decorator".

License 许可
MIT
最近更新
2026-11-07
Stars
★ 3
Forks
1

01 前言 Front Matter

name
scaffold-decorator
description
Add or wire helpers/decorators, preferring ArchiPy's (ttl_cache, atomic UoW, trace_span, measure_duration, retry). Use for "cache this function", "add timing/tracing/retry", or "write a decorator".

03 SKILL.md 正文

Scaffold ArchiPy Decorator

Scope

Only helpers/decorators/. Do not create utils or interceptors here.

Read first

Read these plugin rules in full before generating files (paths relative to this skill directory; Claude Code: ${CLAUDE_SKILL_DIR}/../../rules/):

  • ../../rules/using-archipy-decorators.mdc

Before writing files

  1. Inspect existing decorators, call sites, and the installed ArchiPy version for a matching decorator.
  2. Infer sync/async style and project naming from the target call site.
  3. Ask only for unresolved behavior. Prefer an ArchiPy decorator whenever it fits.
  4. Preserve existing decorator modules; do not overwrite.

Prefer ArchiPy

Examples:

  • from archipy.helpers.decorators import ttl_cache
  • from archipy.adapters.base.sqlalchemy.atomic import postgres_sqlalchemy_atomic (detects async def)
  • trace_span / trace_root (+ async twins) from archipy.helpers.decorators.tracing
  • measure_duration / count_calls (+ async twins) from archipy.helpers.decorators.metrics
  • timeout, retry, singleton, timing, and grpc_rate_limit under archipy.helpers.decorators

Show correct usage on a sample function; do not reimplement. UoW decorators belong on logics, not services/repositories.

Custom decorator

Create helpers/decorators/<name>.py:

from __future__ import annotations

import functools
import inspect
import logging
import time
from collections.abc import Callable
from typing import ParamSpec, TypeVar

logger = logging.getLogger(__name__)

P = ParamSpec("P")
R = TypeVar("R")


def timed(func: Callable[P, R]) -> Callable[P, R]:
    """Log wall-clock duration of a sync call.

    Args:
        func: Callable to wrap.

    Returns:
        Wrapped callable that logs elapsed milliseconds.

    Raises:
        TypeError: If `func` is a coroutine function — use an async twin instead.

    Example:
        @timed
        def build_report(order_id: str) -> str:
            ...
    """
    if inspect.iscoroutinefunction(func):
        raise TypeError(f"{func.__qualname__} is async; use an async twin instead of timed()")

    @functools.wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        started = time.perf_counter()
        try:
            return func(*args, **kwargs)
        finally:
            elapsed_ms = (time.perf_counter() - started) * 1000
            logger.debug("%s took %.2f ms", func.__qualname__, elapsed_ms)

    return wrapper
  • Use functools.wraps
  • Preserve types where practical (ParamSpec / TypeVar)
  • Google-style docstring with Args/Returns and a usage example
  • No concrete adapter imports at module level
  • One decorator detects async def with inspect.iscoroutinefunction and returns a sync or async wrapper

Do not

  • Wrap an async def with a sync wrapper (it would return an un-awaited coroutine).

Verify

Run formatter/linter and focused tests for return values, exceptions, and metadata/signature preservation. Report the reused ArchiPy API or files created, plus commands run.

Docs

04 同仓库更多 Skills