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
- Inspect existing decorators, call sites, and the installed ArchiPy version for a matching decorator.
- Infer sync/async style and project naming from the target call site.
- Ask only for unresolved behavior. Prefer an ArchiPy decorator whenever it fits.
- Preserve existing decorator modules; do not overwrite.
Prefer ArchiPy
Examples:
from archipy.helpers.decorators import ttl_cachefrom archipy.adapters.base.sqlalchemy.atomic import postgres_sqlalchemy_atomic(detectsasync def)trace_span/trace_root(+ async twins) fromarchipy.helpers.decorators.tracingmeasure_duration/count_calls(+ async twins) fromarchipy.helpers.decorators.metricstimeout,retry,singleton,timing, andgrpc_rate_limitunderarchipy.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 defwithinspect.iscoroutinefunctionand returns a sync or async wrapper
Do not
- Wrap an
async defwith 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
- https://syntaxarc.github.io/ArchiPy/tutorials/helpers/
- Bundled skill reference:
../archipy-docs/reference/helpers.md(Decorators section), resolved relative to thisSKILL.md's directory in the plugin installation — not the app workspace.
04 同仓库更多 Skills
scaffold-utils
Add or wire pure helpers/utils, preferring ArchiPy utils (datetime, JWT, password, file, string). Use for "add a helper/util function", "format dates", "hash passwords", or "generate tokens".
scaffold-service
Scaffold a thin FastAPI router or gRPC servicer under services/{domain}/v{n}/ with AppUtils bootstrap. Use for "add an endpoint/route/API", "expose via REST/gRPC", or "new API version".
scaffold-observability
Configure ArchiPy 5.x OpenTelemetry traces, metrics, logs, and instrumentation. Use for "add tracing/metrics/OTel", "Prometheus/Pushgateway", or migrating off Sentry, Elastic APM, or old Prometheus.
scaffold-models
Scaffold ArchiPy models under models/: domain/repository DTOs, errors, optional entities and types. Use for "add DTO/schema/request/response model", "new error type", or "SQLAlchemy entity".
scaffold-logic
Scaffold an ArchiPy logic (use case) under logics/{domain}/ with a unit-of-work decorator and DTO I/O. Use for "add business logic", "new use case", "transactional operation", or "service layer method".
scaffold-interceptor
Add or wire cross-cutting FastAPI/gRPC interceptors or middleware, preferring ArchiPy's. Use for "add middleware", "request ID/logging/auth interceptor", or "gRPC interceptor".