파이썬 프로젝트

파이썬 프로젝트 생성기는 최신 Python 라이브러리나 애플리케이션을 생성하는 데 사용할 수 있으며, UV로 관리되는 단일 lockfile과 UV 워크스페이스 내의 가상 환경, 테스트 실행을 위한 pytest, 정적 분석을 위한 Ruff가 구성된 모범 사례가 적용되어 있습니다.

사용 방법

파이썬 프로젝트 생성

새 파이썬 프로젝트를 두 가지 방법으로 생성할 수 있습니다:

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - py#project
5. 필수 매개변수 입력
6. 클릭 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#project

yarn

yarn nx g @aws/nx-plugin:py#project

npm

npx nx g @aws/nx-plugin:py#project

bun

bunx nx g @aws/nx-plugin:py#project

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:py#project --dry-run

yarn

yarn nx g @aws/nx-plugin:py#project --dry-run

npm

npx nx g @aws/nx-plugin:py#project --dry-run

bun

bunx nx g @aws/nx-plugin:py#project --dry-run

옵션

매개변수	타입	기본값	설명
name 필수	string	-	The name of the Python project
directory	string	packages	Parent directory where the project is placed.
projectType 필수	string	application	Project type
moduleName	string	-	Python module name

생성기 출력 결과

생성기는 <directory>/<name> 디렉토리에 다음 프로젝트 구조를 생성합니다:

• 디렉터리<module-name>

  • __init__.py 모듈 초기화
  • hello.py 예제 파이썬 소스 파일
• 디렉터리tests

  • __init__.py 모듈 초기화
  • conftest.py 테스트 설정
  • test_hello.py 예제 테스트
• project.json 프로젝트 설정 및 빌드 타겟
• pyproject.toml UV용 패키징 설정 파일
• .python-version 프로젝트의 파이썬 버전 포함

워크스페이스 루트에 다음 파일들이 생성/업데이트되는 것도 확인할 수 있습니다:

• pyproject.toml UV용 워크스페이스 수준 패키징 설정
• .python-version 워크스페이스 파이썬 버전 포함
• uv.lock 파이썬 의존성 lockfile

파이썬 소스 코드 작성

파이썬 소스 코드는 <module-name> 디렉토리에 추가하세요.

다른 프로젝트에서 라이브러리 코드 임포트

add 타겟을 사용하여 파이썬 프로젝트에 의존성을 추가할 수 있습니다.

my_app과 my_lib 두 개의 파이썬 프로젝트를 생성했다고 가정합니다. 이 프로젝트들은 my_scope.my_app과 my_scope.my_lib의 완전한 프로젝트 이름을 가지며, 기본적으로 각각 my_scope_my_app과 my_scope_my_lib 모듈 이름을 가집니다.

my_app이 my_lib에 의존하도록 하려면 다음 명령을 실행합니다:

pnpm

pnpm nx run my_scope.my_app:add my_scope.my_lib

yarn

yarn nx run my_scope.my_app:add my_scope.my_lib

npm

npx nx run my_scope.my_app:add my_scope.my_lib

bun

bunx nx run my_scope.my_app:add my_scope.my_lib

참고

의존 대상과 의존 받는 대상 모두 완전한 프로젝트 이름을 사용합니다. 의존을 추가할 프로젝트에는 축약형 문법을 사용할 수 있지만, 의존할 프로젝트 이름은 완전히 지정해야 합니다.

이제 라이브러리 코드를 임포트할 수 있습니다:

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.hello import say_hello

위 예시에서 my_scope_my_lib은 라이브러리의 모듈 이름이며, hello는 hello.py 파이썬 소스 파일에 해당하고, say_hello는 hello.py에 정의된 메서드입니다.

의존성 관리

프로젝트에 의존성을 추가하려면 파이썬 프로젝트에서 add 타겟을 실행하세요:

pnpm

pnpm nx run my_scope.my_library:add some-pip-package

yarn

yarn nx run my_scope.my_library:add some-pip-package

npm

npx nx run my_scope.my_library:add some-pip-package

bun

bunx nx run my_scope.my_library:add some-pip-package

이 명령은 프로젝트의 pyproject.toml 파일에 의존성을 추가하고 루트 uv.lock을 업데이트합니다.

런타임 코드

파이썬 프로젝트를 런타임 코드(예: AWS 람다 함수 핸들러)로 사용할 경우, 소스 코드와 모든 의존성을 번들로 만들어야 합니다. project.json 파일에 다음 타겟을 추가하여 이를 구현할 수 있습니다:

project.json

{
  ...
  "targets": {
    ...
    "bundle": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/packages/my_library/bundle"],
      "options": {
        "commands": [
          "uv export --frozen --no-dev --no-editable --project packages/my_library --package my_scope.my_library -o dist/packages/my_library/bundle/requirements.txt",
          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux2014 --python `uv python pin` --target dist/packages/my_library/bundle -r dist/packages/my_library/bundle/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    },
  },
}

빌드

파이썬 프로젝트는 build 타겟(project.json에 정의)으로 구성되며 다음 명령으로 실행할 수 있습니다:

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx nx run <project-name>:build

여기서 <project-name>은 프로젝트의 완전한 이름입니다.

build 타겟은 프로젝트를 컴파일, 린트, 테스트합니다.

빌드 결과물은 워크스페이스 루트의 dist 폴더 내 패키지 및 타겟별 디렉토리(예: dist/packages/<my-library>/build)에서 확인할 수 있습니다.

테스트

pytest가 프로젝트 테스트를 위해 구성되어 있습니다.

테스트 작성

테스트는 프로젝트 내 test 디렉토리의 test_ 접두사가 붙은 파이썬 파일에 작성해야 합니다:

• 디렉터리my_library

  • hello.py
• 디렉터리test

  • test_hello.py hello.py 테스트

테스트는 test_로 시작하는 메서드로 작성하며, 예상 결과를 검증하기 위해 assertion을 사용합니다:

test/test_hello.py

from my_library.hello import say_hello

def test_say_hello():
  assert say_hello("Darth Vader") == "Hello, Darth Vader!"

테스트 작성 방법에 대한 자세한 내용은 pytest 문서를 참조하세요.

테스트 실행

테스트는 프로젝트의 build 타겟 실행 시 함께 실행되지만, 별도로 test 타겟을 실행할 수도 있습니다:

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

-k 플래그를 사용하여 특정 테스트 파일이나 메서드를 지정해 개별 테스트를 실행할 수 있습니다:

pnpm

pnpm nx run <project-name>:test -k 'test_say_hello'

yarn

yarn nx run <project-name>:test -k 'test_say_hello'

npm

npx nx run <project-name>:test -k 'test_say_hello'

bun

bunx nx run <project-name>:test -k 'test_say_hello'

린팅

파이썬 프로젝트는 Ruff를 사용해 린팅을 수행합니다.

린터 실행

프로젝트 린트 검사를 위해 lint 타겟을 실행할 수 있습니다:

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

린트 이슈 수정

대부분의 린트 또는 포맷팅 이슈는 자동으로 수정 가능합니다. --configuration=fix 인자와 함께 Ruff를 실행해 수정하세요:

pnpm

pnpm nx run <project-name>:lint --configuration=fix

yarn

yarn nx run <project-name>:lint --configuration=fix

npm

npx nx run <project-name>:lint --configuration=fix

bun

bunx nx run <project-name>:lint --configuration=fix

워크스페이스 전체 패키지의 린트 이슈를 한 번에 수정하려면 다음 명령을 실행합니다:

pnpm

pnpm nx run-many --target lint --all --configuration=fix

yarn

yarn nx run-many --target lint --all --configuration=fix

npm

npx nx run-many --target lint --all --configuration=fix

bun

bunx nx run-many --target lint --all --configuration=fix