Python 프로젝트

Python 프로젝트 생성기는 모범 사례로 구성된 최신 Python 라이브러리 또는 애플리케이션을 생성하는 데 사용할 수 있습니다. UV로 관리되며, UV 워크스페이스에서 단일 잠금 파일과 가상 환경을 사용하고, 테스트 실행을 위한 pytest, 정적 분석을 위한 Ruff, 타입 검사를 위한 ty가 구성되어 있습니다.

사용법

Python 프로젝트 생성

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

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

VSCode

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

옵션

매개변수	타입	기본값	설명
name 필수	string	-	Python 프로젝트의 이름
directory	string	packages	프로젝트가 배치될 상위 디렉토리
subDirectory	string	-	프로젝트가 배치되는 하위 디렉토리입니다. 기본값은 프로젝트 이름입니다.
type 필수	application | library	application	프로젝트가 애플리케이션인지 라이브러리인지 여부
moduleName	string	-	Python 모듈 이름
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

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

• 디렉터리<module-name>

  • __init__.py Module initialisation
• 디렉터리tests

  • __init__.py Module initialisation
  • conftest.py Test configuration
  • test_noop.py Placeholder test
• project.json Project configuration and build targets
• pyproject.toml Packaging configuration file used by UV
• .python-version Contains the project’s Python version

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

• pyproject.toml Workspace level packaging configuration for UV
• .python-version Contains the workspace Python version
• uv.lock Lockfile for Python dependencies

Python 소스 코드 작성

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

다른 프로젝트에서 라이브러리 코드 가져오기

add 타겟을 사용하여 Python 프로젝트에 의존성을 추가하세요.

my_app과 my_lib라는 두 개의 Python 프로젝트를 생성했다고 가정해 봅시다. 이들은 각각 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.my_module import my_function

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

의존성

프로젝트에 의존성을 추가하려면 Python 프로젝트에서 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이 업데이트됩니다.

런타임 코드

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 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-manylinux_2_28 --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에 정의됨)으로 구성되어 있으며, 다음을 통해 실행할 수 있습니다:

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

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

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

빌드 출력은 워크스페이스의 루트 dist 폴더에서 찾을 수 있으며, 패키지 및 타겟에 대한 디렉터리 내부에 있습니다. 예: dist/packages/<my-library>/build

워크스페이스의 모든 프로젝트를 빌드하려면 다음을 실행하세요:

pnpm

pnpm nx run-many --target build

yarn

yarn nx run-many --target build

npm

npx nx run-many --target build

bun

bunx nx run-many --target build

또는 단축 명령을 사용하세요:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

테스트

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

테스트 작성

테스트는 프로젝트 내의 test 디렉터리에 작성해야 하며, test_ 접두사가 붙은 Python 파일에 작성합니다. 예를 들어:

• 디렉터리my_library

  • my_module.py
• 디렉터리tests

  • test_my_module.py Tests for my_module.py

테스트는 test_로 시작하는 메서드이며 기대값을 검증하기 위해 단언문을 만듭니다. 예를 들어:

tests/test_my_module.py

from my_library.my_module import say_hello

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

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

테스트 실행

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

pnpm

pnpm nx test <project-name>

yarn

yarn nx test <project-name>

npm

npx nx test <project-name>

bun

bunx nx test <project-name>

-k 플래그를 사용하여 테스트 파일 또는 메서드의 이름을 지정하여 개별 테스트 또는 테스트 모음을 실행할 수 있습니다:

pnpm

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

yarn

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

npm

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

bun

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

타입 검사

Python 프로젝트는 타입 검사를 위해 ty를 사용합니다.

타입 검사기 실행

타입 검사는 프로젝트의 build 타겟의 일부로 실행되지만, typecheck 타겟을 통해 별도로 실행할 수도 있습니다:

pnpm

pnpm nx run <project-name>:typecheck

yarn

yarn nx run <project-name>:typecheck

npm

npx nx run <project-name>:typecheck

bun

bunx nx run <project-name>:typecheck

타입 오류 억제

단일 라인에 대한 특정 진단을 억제하려면 라인 끝에 # ty: ignore[<rule>] 주석을 추가하세요. 예를 들어:

value: int = "not an int"  # ty: ignore[invalid-assignment]

프로젝트 전체에서 타입 검사 동작을 구성하려면 프로젝트의 pyproject.toml에 [tool.ty] 섹션을 추가하세요. 사용 가능한 옵션은 ty 구성 참조를 참조하세요.

린트

Python 프로젝트는 린트를 위해 Ruff를 사용합니다.

린터 실행

프로젝트를 검사하기 위해 린터를 호출하려면 lint 타겟을 실행할 수 있습니다.

pnpm

pnpm nx lint <project-name>

yarn

yarn nx lint <project-name>

npm

npx nx lint <project-name>

bun

bunx nx lint <project-name>

린트 문제 수정

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

pnpm

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

yarn

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

npm

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

bun

bunx nx lint <project-name> --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

단축 명령

워크스페이스 루트에서 사용할 수 있는 단축 명령이 있습니다:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

린트 문제 건너뛰기

개발 중에 린트 문제로 인해 속도가 느려지는 것을 방지하려면(특히 프로젝트에 자동 수정할 수 없는 문제가 있는 경우), skip-lint 구성으로 빌드를 실행할 수 있습니다:

pnpm

pnpm nx run-many --target build --configuration=skip-lint

yarn

yarn nx run-many --target build --configuration=skip-lint

npm

npx nx run-many --target build --configuration=skip-lint

bun

bunx nx run-many --target build --configuration=skip-lint

이렇게 하면 빌드의 일부로 Ruff가 여전히 실행되지만, 린트 타겟은 항상 성공한 것으로 간주됩니다.

단축 명령

워크스페이스 루트에서 사용할 수 있는 단축 명령이 있습니다:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint