컨텐츠로 건너뛰기

파이썬 프로젝트

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

사용법

Python 프로젝트 생성

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

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

    옵션

    매개변수 타입 기본값 설명
    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 예제 Python 소스 파일
    • 디렉터리tests
      • __init__.py 모듈 초기화
      • conftest.py 테스트 구성
      • test_hello.py 예제 테스트
    • project.json 프로젝트 구성 및 빌드 타겟
    • pyproject.toml UV용 패키징 구성 파일
    • .python-version 프로젝트의 Python 버전 포함

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

    • pyproject.toml UV용 워크스페이스 수준 패키징 구성
    • .python-version 워크스페이스 Python 버전 포함
    • uv.lock Python 종속성 lockfile

    Python 소스 코드 작성

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

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

    UV 워크스페이스가 구성되어 있으므로, 워크스페이스 내 다른 Python 프로젝트에서 Python 프로젝트를 참조할 수 있습니다:

    packages/my_other_project/my_other_project/main.py
    from "my_library.hello" import say_hello

    위 예시에서 my_library는 모듈 이름, hello는 Python 소스 파일 hello.py에 해당하며, say_hellohello.py에 정의된 메서드입니다.

    종속성 관리

    프로젝트에 종속성을 추가하려면 Python 프로젝트에서 add 타겟을 실행할 수 있습니다:

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

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

    런타임 코드

    Python 프로젝트를 런타임 코드(예: 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 my_library -o dist/packages/my_library/bundle/requirements.txt",
    "uv pip install -n --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"]
    },
    },
    }

    빌드

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

    Terminal window
    pnpm nx run <project-name>:build

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

    build 타겟은 컴파일, 린트 및 테스트를 수행합니다.

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

    테스트

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

    테스트 작성

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

    • 디렉터리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 타겟을 별도로 실행할 수도 있습니다:

    Terminal window
    pnpm nx run <project-name>:test

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

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

    린팅

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

    린터 실행

    프로젝트 린트 검사를 수행하려면 lint 타겟을 실행하세요:

    Terminal window
    pnpm nx run <project-name>:lint

    린트 문제 수정

    대부분의 린트 또는 포맷팅 문제는 자동으로 수정할 수 있습니다. --configuration=fix 인자를 추가해 Ruff가 문제를 수정하도록 할 수 있습니다:

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

    워크스페이스 내 모든 패키지의 린트 문제를 한 번에 수정하려면 다음 명령을 실행하세요:

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