Python Projects

The Python project generator can be used to create a modern Python library or application configured with best practices, managed with UV, a single lockfile and virtual environment in an UV workspace, pytest for running tests, Ruff for static analysis, and ty for type checking.

Usage

Generate a Python Project

You can generate a new Python project in two ways:

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

You can also perform a dry-run to see what files would be changed

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. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - py#project
5. Fill in the required parameters
6. Click Generate

Options

Parameter	Type	Default	Description
name Required	string	-	The name of the Python project
directory	string	packages	Parent directory where the project is placed.
subDirectory	string	-	The sub directory the project is placed in. By default this is the project name.
type Required	application | library	application	Whether the project is an application or library
moduleName	string	-	Python module name
preferInstallDependencies	boolean	true	Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator will create the following project structure in the <directory>/<name> directory:

• Directory<module-name>

  • __init__.py Module initialisation
• Directorytests

  • __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

You may also notice the following files created/updated in the root of your workspace:

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

Writing Python Source Code

Add your Python source code in the <module-name> directory.

Importing your Library Code in Other Projects

Use the add target to add a dependency to a Python project.

Suppose we have created two python projects, my_app and my_lib. These will have fully qualified project names of my_scope.my_app and my_scope.my_lib, and by default will each have module names of my_scope_my_app and my_scope_my_lib.

For my_app to depend on my_lib, we can run the following command:

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

Fully Qualified Names

We use the fully qualified project name for both the dependant and dependee. We can use the shorthand syntax for the project we want to add the dependency to, but must fully qualify the name of the project to depend on.

You can then import your library code:

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.my_module import my_function

Above, my_scope_my_lib is the module name for the lib, my_module corresponds to a Python source file my_module.py, and my_function is a method defined in that file.

Dependencies

To add dependencies to your project, you can run the add target in your Python project, for example:

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

This will add the dependency to your project’s pyproject.toml file, and update the root uv.lock.

Runtime Code

When you use your Python project as runtime code (for example as the handler for an AWS lambda function), you will need to create a bundle of the source code and all its dependencies. You can achieve this by adding a target such as the following to your project.json file:

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"]
    },
  },
}

Building

Your Python project is configured with a build target (defined in project.json), which you can run via:

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Where <project-name> is the fully qualified name of your project.

The build target will compile, lint, test and type check your project.

Build output can be found in the root dist folder in your workspace, inside a directory for your package and target, for example dist/packages/<my-library>/build

To build all of the projects in your workspace, run:

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

Or use the shorthand command:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Testing

pytest is configured for testing your project.

Writing Tests

Tests should be written in the test directory within your project, in python files prefixed with test_, for example:

• Directorymy_library

  • my_module.py
• Directorytests

  • test_my_module.py Tests for my_module.py

Tests are methods which begin with test_ and make assertions to verify expectations, for example:

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!"

For more details about how to write tests, please refer to the pytest documentation.

Running Tests

Tests will run as part of the build target for your project, but you can also run them separately by running the test target:

pnpm

pnpm nx test <project-name>

yarn

yarn nx test <project-name>

npm

npx nx test <project-name>

bun

bunx nx test <project-name>

You can run an individual test or suite of tests using the -k flag, specifying either the name of the test file or method:

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'

Type Checking

Python projects use ty for type checking.

Running the Type Checker

Type checking runs as part of the build target for your project, but you can also run it separately via the typecheck target:

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

Suppressing Type Errors

To suppress a specific diagnostic for a single line, add a # ty: ignore[<rule>] comment at the end of the line, for example:

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

To configure type checking behaviour across your project, add a [tool.ty] section to your project’s pyproject.toml. Refer to the ty configuration reference for available options.

Linting

Python projects use Ruff for linting.

Running the Linter

To invoke the linter to check your project, you can run the lint target.

pnpm

pnpm nx lint <project-name>

yarn

yarn nx lint <project-name>

npm

npx nx lint <project-name>

bun

bunx nx lint <project-name>

Fixing Lint Issues

The majority of linting or formatting issues can be fixed automatically. You can tell Ruff to fix lint issues by running with the --configuration=fix argument.

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

Similarly if you would like to fix all lint issues in all packages in your workspace, you can run:

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

Shorthand Command

This has a shorthand command from the root of your workspace:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Skipping Lint Issues

To avoid linting issues slowing you down during development (particularly if you have non auto-fixable issues in your project), you can run a build with the skip-lint configuration:

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

This will still run Ruff as part of the build, but the lint target will always be considered successful.

Shorthand Command

This has a shorthand command from the root of your workspace:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint