pytemplate-uv
PyPI
Python
CI
License: MIT
몇 초 만에 프로덕션 레디(production-ready)한 Python 프로젝트를 생성합니다. 프로필, 조합 가능한 컴포넌트, 템플릿 팩을 갖춘 결정론적 애플리케이션 팩토리입니다.
uv-native Python 프로젝트를 생성하는 현대적인 애플리케이션 팩토리입니다. 내장된 템플릿 덕분에 모든 프로젝트는 첫 커밋부터 linting, formatting, type-checking, 테스트를 통과합니다. 프로필(CLI가 있는 타입 패키지 또는 FastAPI 서비스)을 선택하고, 컴포넌트(데이터베이스, 인증, 백그라운드 작업)를 추가하여 바로 배포할 준비가 된 프로젝트를 얻으세요.
- ✅ 결정론적 (Deterministic): 동일한 요청은 바이트 단위로 동일한 프로젝트를 생성합니다.
- ✅ 검증됨 (Checked): 모든 내장 컴포넌트 조합이 CI에서 엄격한 품질 게이트를 통과합니다.
- ✅ uv-native: 생성된 프로젝트는
uv와 uvx만 필요하며, pip, virtualenv 활성화 또는 make가 필요 없습니다.
- ✅ 확장 가능 (Extensible): 템플릿 팩을 사용하여 포크(forking) 없이 사용자 정의할 수 있습니다.
- ✅ 타입 안전 (Type-safe): 생성된 코드는 엄격한 mypy를 사용하며, 무언가를 작성하기 전에 요청이 검증됩니다.
얻게 되는 것들
프로필 (택일)
python — Typer CLI가 있는 타입 패키지; 도구에 적합합니다.
library — CLI나 콘솔 스크립트가 없는 타입 패키지; 다른 곳에서 가져다 쓸 코드(import)에 적합합니다.
fastapi — 구조화된 로깅, 헬스 체크, 보안 및 체계적인 아키텍처를 갖춘 계층형 REST API 서비스
컴포넌트 (혼합 및 매칭)
| 컴포넌트 | 목적 | 사용 시점 |
|---|
database | SQLAlchemy 2.x ORM + Alembic migrations | 영구적인 데이터가 필요할 때 |
| ... | | |
| 컴포넌트를 자유롭게 조합하세요 — 생성기가 조합을 검증하고 필요한 종속성을 추가합니다. | | |
첫날부터의 품질 보장
내장된 템플릿으로 생성되는 모든 프로젝트는 다음을 통과합니다:
- ✅
ruff check 및 ruff format --check (코드 품질 및 스타일)
- ✅ 엄격한
mypy (타입 안전성)
- ✅
pytest (테스트 포함)
모든 커밋에서 묶인 28가지 컴포넌트 조합 전체에 걸쳐 검증됩니다. 사용자가 직접 만든 템플릿 팩의 프로젝트는 이 검사 범위에 포함되지 않습니다. 해당 팩도 동일한 방식으로 테스트해야 합니다.
팀을 위해 구축됨 (Built for teams)
- 검사 가능(Inspectable):
plan은 아무것도 작성하지 않고 파일과 종속성을 보여줍니다.
- 재현 가능(Reproducible):
.pytemplate.toml은 각 파일의 정확한 버전과 체크섬을 기록합니다.
- 스크립트화 가능(Scriptable): CI/CD 통합을 위해
--json 출력 및 안정적인 종료 코드를 제공합니다.
- 확장성(Extensible): 템플릿 팩을 통해 자체 프로필과 컴포넌트를 가져올 수 있습니다.
pytemplate-uv를 사용하는 이유?
해결하는 문제점:
- 보일러플레이트(Boilerplate) 코드는 취약합니다—인증 누락, 잘못된 설정, 구식 패턴, 통합 테스트 격차 등이 있습니다.
- 모든 팀이 인증(auth), 로깅, 데이터베이스 연결, 컨테이너 설정을 재구현해야 합니다.
- 생성된 코드는 대개 지저분하고, 검사가 누락되어 있으며, 정리할 필요가 있습니다.
해결책:
- 검토된 패턴에서 시작합니다: 계층형 아키텍처(layered architecture), 헬스 체크(health checks), 구조화된 로그(structured logs), 주체 및 범위 기반 인증(auth behind a principal and scopes).
- 모든 묶인 컴포넌트 조합은 CI에서 생성되고 검사됩니다 (Linux 및 Windows에서 28가지 조합).
- 스크립트로 처리합니다: 동일한 요청은 항상 동일한 프로젝트를 생성합니다.
적합한 경우:
- FastAPI 서비스 또는 타입이 지정된 CLI 도구를 시작하는 팀.
- 하나의 검토된 템플릿에서 많은 유사한 앱을 생성하는 플랫폼.
- 스크립트화되고 검증된 초기화 단계가 필요한 CI 파이프라인 및 AI 에이전트.
설치 (Install)
사용해 보기 위해 설치 불필요:
pytemplate 명령어 설치 방법:
uv tool install pytemplate-uv
Python 3.11–3.15가 필요합니다. Linux, macOS 및 Windows에서 실행됩니다. 또한 pip install pytemplate-uv를 통해 사용할 수 있습니다.
프로젝트 생성 (Create a project)
30초 퀵스타트
uvx pytemplate-uv create my-api -p fastapi -c database -c auth-oidc -y
cd my-api
uv sync
...
(만약 pytemplate 명령어를 설치했다면, pytemplate create ...를 작성하세요.) 완료되면, create가 다음 단계: cd 및 프로필 자체의 라이프사이클 명령을 출력합니다.
이것으로 끝입니다. 데이터베이스, OIDC 인증(OIDC authentication), 테스트, GitHub Actions 워크플로우, 구조화된 로깅(structured logging), 그리고 헬스 체크(health checks)가 포함된 계층형 FastAPI 서비스입니다.
추가 예시
pytemplate create my-tool -p python -y
...
create-project는 pytemplate create와 동일한 인자 및 옵션을 가진 선택적 단축 명령어입니다. (uvx pytemplate-uv create NAME은 단축 명령어가 필요 없습니다.):
uvx --from pytemplate-uv create-project pricing-api -p fastapi -y
명령어
| 명령어 | 기능 |
|---|
create NAME | 프로젝트 생성 |
| ... | |
팁:
schema(이미 JSON을 출력함)와 skill을 제외한 모든 명령어는 --json을 허용합니다.
- 자체 템플릿 패키지에서 렌더링하려면
--template을 사용하세요.
plan과 validate는 아무것도 작성하지 않습니다.
종료 코드:
0: 성공.
1: 유효하지 않은 요청입니다. 아무것도 작성되지 않습니다. --json을 사용하면 오류가 {"ok": false, "error": {...}} 형식으로 출력됩니다.
2: 렌더링 또는 쓰기 과정에서 실패한 유효한 요청입니다.
create 옵션
--profile, -p: 프로필 식별자입니다 (기본값: python).
--component, -c: 컴포넌트를 추가합니다; 필요에 따라 반복 사용하십시오. 프로필 기본값은 항상 포함되며, 필수 컴포넌트는 자동으로 추가됩니다. --output-dir, -o: 기존 상위 디렉터리입니다 (기본값: .).
--data, -d KEY=VALUE: 템플릿 질문에 답변합니다; 필요에 따라 반복 사용하십시오. 입력 값으로는 package_name, description, author, email, python_version(3.11–3.15), 그리고license (SPDX 표현식)가 있습니다. --template, -t SOURCE 및 --template-ref REF: 템플릿 패크에서 렌더링합니다 (아래 참조).
--yes, -y: 프롬프트 대신 템플릿 기본값을 수락합니다. 이것이 없으면 create가 프롬프트를 표시하고, 아래의 피커는 선택적 컴포넌트를 요청합니다. 표준 입력(standard input)이 터미널이 아닐 경우, 렌더링 전에 종료 코드 1을 반환하며 -y를 요청합니다. --json은 -y를 의미합니다. --no-input도 여전히 작동하지만 사용 중단 예정입니다: stderr에 경고 메시지를 출력하며 4.0 버전에서 제거될 예정입니다. --git: 렌더링 후, git init을 실행하고 모든 것을 "Initial commit from pytemplate-uv"로 커밋합니다. --lock: 먼저 uv lock을 실행하여 커밋에 uv.lock이 포함되도록 합니다. 둘 다 기본값이 아니며, --dry-run과 함께 실행되지 않습니다. 단계 중 하나가 실패하면 프로젝트는 유지되며, 무엇이 생성되었고 무엇이 실패했는지 메시지와 함께 종료 코드 2를 반환합니다.
--dry-run: 쓰기 작업 없이 대상을 검증하고 보여줍니다. --force, -f: 기존 디렉터리를 교체합니다. 프로젝트는 스테이징(staging) 디렉터리에 렌더링된 후 성공적으로 렌더링되었을 때만 스왑되므로 오래된 파일(stale files)이 남지 않습니다.
--json`: 결과를 JSON 형식으로 출력합니다.
컴포넌트 피커, 자동 완성 및 상태
- 터미널에서
-y, --json, 또는 -c 옵션 없이 create를 실행하면, 해당 프로필의 선택적 구성 요소들이 다중 선택 목록으로 제공됩니다. 필수 구성 요소는 여전히 추가되며, 충돌이 발생할 경우 여전히 거부됩니다.
--profile 및 --component는 셸에서 (번들된 카탈로그용) pytemplate --install-completion을 실행하면 자동 완성 기능을 사용할 수 있습니다.
pytemplate status [PATH]는 생성된 프로젝트를 .pytemplate.toml에 있는 SHA-256 인벤토리와 비교하여 변경, 삭제 또는 추가된 파일을 나열합니다. 이 명령어는 .git/, .venv/, 캐시, uv.lock, 그리고 매니페스트 파일은 무시하며, 절대 쓰기 작업을 수행하지 않고, --json 옵션을 허용하지 않으며, PATH에 유효한 매니페스트가 없을 경우 1을 반환합니다.
- 오류 및 경고는 표준 에러 스트림(stderr)으로 전송되며,
--json 출력과 결과만 표준 출력 스트림(stdout)으로 전송됩니다. 오타가 있는 프로필, 구성 요소, 스키마 또는 --data 키의 경우 "Did you mean" (다음 의도하셨나요?) 제안을 받게 됩니다.
재현 가능한 렌더 요청 (Reproducible render requests)
project_name = "pricing-api"
profile = "fastapi"
...
pytemplate validate pricing-api.toml
pytemplate plan pricing-api.toml --json
pytemplate create-from-config pricing-api.toml
각 프로젝트는 어떻게 생성되었는지 기록하며, 이 두 파일 중 어느 것도 비밀 정보나 환경 변수 값을 저장하지 않습니다:
.pytemplate.toml은 생성기(generator), 템플릿 소스, 프로필 및 구성 요소 버전 (각 구성 요소가 존재하는 이유와 함께), 답변 내용, 그리고 모든 생성된 파일에 대한 SHA-256 해시 및 소유자를 기록합니다;
.copier-answers.yml은 Copier의 답변과 템플릿 소스를 기록합니다.
pytemplate schema manifest는 형식을 설명합니다.
템플릿 팩 (Template packs)
템플릿 팩은 사용자 정의 프로필과 구성 요소를 포함하는 디렉터리 또는 Git 저장소입니다. 이는 번들된 템플릿과 동일한 레이아웃을 가집니다:
my-pack/
pytemplate-pack.toml # contract = 1, id, name, description, version
copier.yml # _subdirectory: "{{ profile }}/template"; --- !include questions.yml
...
pytemplate list-profiles --template ./my-pack
pytemplate create my-tool -p tool --template gh:org/my-pack --template-ref v1.2.0 -y
- 팩(Packs)은 각 요청에 대해 명시적으로 선택되며, 어떠한 것도 발견되거나 설치되지 않습니다.
- 이들은 번들링된 템플릿과 동일한 규칙을 따릅니다:
- Copier의 `unsafe=False`로 렌더링됩니다;
- `_tasks`, `_migrations`, `_jinja_extensions`, `_external_data`, 그리고 심볼릭 링크(symlinks)는 거부되며, 이는 팩의 `copier.yml`이 포함하는 파일에도 해당합니다.
- 팩으로 생성된 프로젝트는 해당 팩의 소스 및 태그를 기록합니다.
- git 팩에서 가져온 프로젝트 역시 렌더링된 커밋(commit)과 다이제스트(digest)를 기록합니다. 변경된 팩을 거부하려면 다음과 같이 고정(pin)하십시오:
```bash
pytemplate create my-tool -p tool --template gh:org/my-pack --template-ref v1.2.0 \
--template-commit <commit> --template-digest <digest> -y
--template-ref는 전체 커밋 해시(full commit hash)도 허용합니다. 커밋과 다이제스트 모두에 고정된 팩은 사용자 캐시 디렉터리(user cache directory)에 캐싱되며, 사용할 때마다 해당 다이제스트와 비교됩니다. --no-cache를 전달하거나 (PYTEMPLATE_NO_CACHE=1 설정), PYTEMPLATE_CACHE_DIR을 변경하여 다시 가져올 수 있습니다. Git은 절대로 자격 증명(credentials)을 요청하지 않으며, 클론은 120초(PYTEMPLATE_GIT_TIMEOUT) 후에 중단됩니다.
AI 코딩 에이전트를 위해 구축됨 (Built for AI coding agents)
생성된 모든 프로젝트에는 AGENTS.md가 포함됩니다: 이는 해당 포맷을 읽는 모든 에이전트(agent)를 위한 명령어, 레이아웃, 규칙 및 안전 규정을 담고 있습니다. CLAUDE.md는 이를 한 줄로 가져오는 방식이므로, Claude Code도 동일한 텍스트를 읽습니다.
에이전트가 호출할 수 있는 무언가를 구축하려면, python 프로젝트에 mcp를 추가하십시오:
pytemplate create pricing-tools --profile python --component mcp -y
cd pricing-tools && uv sync && uv run pytest
공식 SDK에서는 Model Context Protocol 서버, pricing-tools-mcp 명령어, 해당 서버를 통해 도구를 호출하는 테스트, 그리고 저장소 내에서 작동하는 에이전트를 위해 이를 등록하는 .mcp.json 파일을 얻게 됩니다. 렌더링 시 모델을 호출하지 않으며 API 키가 필요 없습니다.
pytemplate-uv는 에이전트 스킬(SKILL.md)을 제공하며, 이 스킬은 에이전트에게 다음 작업을 수행하도록 가르칩니다:
- 프로필 및 컴포넌트를 검색하고(discover);
- 렌더 요청을 작성하고
plan으로 확인합니다;
- 사용자의 확인을 기다립니다;
- 프로젝트를 생성하고 검사를 실행합니다.
uvx pytemplate-uv skill install
uvx pytemplate-uv skill install --project
uvx pytemplate-uv skill install --agent agents
그런 다음 예를 들어, "데이터베이스와 OIDC 로그인이 포함된 pricing-api라는 FastAPI 서비스를 생성해 줘"라고 요청하십시오. 다른 AI 도구의 경우, uvx pytemplate-uv skill show에서 지침을 제공하면 됩니다.
Python 또는 기타 도구에서의 사용
Python에서:
from pathlib import Path
from pytemplate import api
...
스크립트, CI/CD 또는 다른 언어에서:
pytemplate plan --name my-api -p fastapi -c database --json | jq .
...
생성된 FastAPI 레이아웃
pricing-api/
AGENTS.md CLAUDE.md README.md pyproject.toml .env.example .copier-answers.yml .pytemplate.toml
pricing_api/
...
기여하기
시작하기:
uv sync
uv run pytest
PYTEMPLATE_SMOKE=1 uv run pytest
...