새 Python 프로젝트 생성

요약

새 Python 리포지터리를 생성할 때, 코드를 표준화하는 데 도움이 되는 몇 가지 가이드라인이 있습니다. pytest: 테스트를 작성하고 실행하기 위한 기본 테스트 프레임워크. pytest-cov: pytest용 테스트 커버리지 리포팅 플러그인.

새 Python 리포지터리를 생성할 때, 코드를 표준화하는 데 도움이 되는 몇 가지 가이드라인이 있습니다.

권장 라이브러리#

개발 및 테스트#

pytest: 테스트를 작성하고 실행하기 위한 기본 테스트 프레임워크.
pytest-cov: pytest용 테스트 커버리지 리포팅 플러그인.
black: 일관된 코드 스타일을 보장하는 독단적인 코드 포매터.
flake8: 스타일 준수를 위한 린터.
pylint: 오류 탐지 및 품질 강화를 위한 종합 린터.
mypy: 정적 타입 검사기.
isort: import 문을 정렬하는 유틸리티.

패키지 매니저 및 빌드 시스템#

poetry: 현대적인 패키징 및 의존성 관리 도구.

공통 유틸리티#

typer: CLI 애플리케이션 구축을 위한 라이브러리.
python-dotenv: 환경 변수 관리 도구.
pydantic: Python 타입 어노테이션을 사용한 데이터 유효성 검사 및 설정 관리.
fastapi: API 구축을 위한 현대적이고 고성능의 웹 프레임워크.
structlog: 구조화된 로깅 라이브러리.
httpx: 비동기적이고 성능이 뛰어난 HTTP 클라이언트.
rich: 리치 텍스트를 위한 터미널 포매팅 라이브러리.
sqlmodel: 직관적이고 견고한 ORM.
tqdm: CLI용 빠르고 확장 가능한 진행 바.

권장 폴더 구조#

프로젝트 유형(예: API 서비스, CLI 애플리케이션 또는 라이브러리)에 따라 폴더 구조가 달라질 수 있습니다. 다음은 표준 CLI 애플리케이션을 위한 구조입니다.

project_name/
├── .gitlab/                     # GitLab-specific configuration
│   ├── issue_templates/         # Issue templates
│   └── merge_request_templates/ # MR templates
├── .gitlab-ci.yml               # CI/CD configuration
├── project_name/                # Main package directory
│   ├── __init__.py              # Package initialization
│   ├── cli.py                   # Command-line interface entry points
│   ├── config.py                # Configuration handling
│   └── core/                    # Core functionality
│       └── __init__.py
├── tests/                       # Test directory
│   ├── __init__.py
│   ├── conftest.py              # pytest fixtures and configuration
│   └── test_*.py                # Test modules
├── docs/                        # Documentation
├── scripts/                     # Utility scripts
├── README.md                    # Project overview
├── CONTRIBUTING.md              # Contribution guidelines
├── LICENSE                      # License information
├── pyproject.toml               # Project metadata and dependencies (Poetry)

린터 구성#

가능한 한 모든 구성을 pyproject.toml에 통합하는 것을 권장합니다.

pyproject.toml#

[tool.black]
line-length = 120

[tool.isort]
profile = "black"

[tool.mypy]
python_version = 3.12
ignore_missing_imports = true

[tool.pylint.main]
jobs = 0
load-plugins = [
  # custom plugins
]

[tool.pylint.messages_control]
enable = [
  # custom plugins
]

[tool.pylint.reports]
score = "no"

setup.cfg#

[flake8]
extend-ignore = E203,E501
extend-exclude = **/__init__.py,.venv,tests
indent-size = 4
max-line-length = 120

Makefile 예시#

# Excerpt from project Makefile showing common targets

# lint
.PHONY: install-lint-deps
install-lint-deps:
    @echo "Installing lint dependencies..."
    @poetry install --only lint

.PHONY: format
format: black isort

.PHONY: black
black: install-lint-deps
    @echo "Running black format..."
    @poetry run black ${CI_PROJECT_DIR}

.PHONY: isort
isort: install-lint-deps
    @echo "Running isort format..."
    @poetry run isort ${CI_PROJECT_DIR}

.PHONY: lint
lint: flake8 check-black check-isort check-pylint check-mypy

.PHONY: flake8
flake8: install-lint-deps
    @echo "Running flake8..."
    @poetry run flake8 ${CI_PROJECT_DIR}

.PHONY: check-black
check-black: install-lint-deps
    @echo "Running black check..."
    @poetry run black --check ${CI_PROJECT_DIR}

.PHONY: check-isort
check-isort: install-lint-deps
    @echo "Running isort check..."
    @poetry run isort --check-only ${CI_PROJECT_DIR}

.PHONY: check-pylint
check-pylint: install-lint-deps install-test-deps
    @echo "Running pylint check..."
    @poetry run pylint ${CI_PROJECT_DIR}

.PHONY: check-mypy
check-mypy: install-lint-deps
    @echo "Running mypy check..."
    @poetry run mypy ${CI_PROJECT_DIR}

# test
.PHONY: test
test: install-test-deps
    @echo "Running tests..."
    @poetry run pytest

.PHONY: test-coverage
test-coverage: install-test-deps
    @echo "Running tests with coverage..."
    @poetry run pytest --cov=duo_workflow_service --cov=lints --cov-report term --cov-report html

GitLab CI 구성 예시#

# Excerpt from .gitlab-ci.yml showing linting and testing jobs

image: python:3.13

stages:
  - lint
  - test

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
  POETRY_CACHE_DIR: "$CI_PROJECT_DIR/.cache/poetry"
  POETRY_VERSION: "2.1.2"

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - $PIP_CACHE_DIR
    - $POETRY_CACHE_DIR
    - .venv/

# Base template for Python jobs
.poetry:
  before_script:
    - pip install poetry==${POETRY_VERSION}
    - poetry config virtualenvs.in-project true
    - poetry add --dev black isort flake8 pylint mypy pytest pytest-cov

# Linting jobs
black:
  extends: .poetry
  stage: lint
  script:
    - poetry run black --check ${CI_PROJECT_DIR}

isort:
  extends: .poetry
  stage: lint
  script:
    - poetry run isort --check-only ${CI_PROJECT_DIR}

flake8:
  extends: .poetry
  stage: lint
  script:
    - poetry run flake8 ${CI_PROJECT_DIR}

pylint:
  extends: .poetry
  stage: lint
  script:
    - poetry run pylint ${CI_PROJECT_DIR}

mypy:
  extends: .poetry
  stage: lint
  script:
    - poetry run mypy ${CI_PROJECT_DIR}

# Testing jobs
test:
  extends: .poetry
  stage: test
  script:
    - poetry run pytest --cov=duo_workflow_service --cov-report=term --cov-report=xml:coverage.xml --junitxml=junit.xml
  coverage: '/TOTAL.+?(\d+\%)/'
  artifacts:
    when: always
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml

리뷰어 룰렛 추가#

리뷰 작업 부하를 리뷰어와 메인테이너에게 분산하기 위해 리뷰어 룰렛을 사용하는 것을 권장합니다. 소규모 Python 프로젝트에서 사용할 수 있는 Python 리뷰어 풀이 있으며, 다음 단계를 따라 구성할 수 있습니다.

프로젝트 전용 리뷰어 풀을 생성하려면:

GitLab Dangerfiles 지침을 따라 프로젝트에 구성을 추가합니다.
GitLab CI 파이프라인에 Danger Reviewer 컴포넌트를 구현하여 룰렛을 자동으로 트리거합니다.