@nxlv/python

@nxlv/python

@nxlv/python plugin is designed to extend the Nx features to work with Python projects based on Poetry.

Check this article for more details: https://lucasvieirasilva.medium.com/poetry-python-nx-monorepo-5750d8627024

What is Nx

🔎 Extensible Dev Tools for Monorepos.

What is @nxlv/python

🔎 An Nx Custom Plugin to generate Python projects using Poetry, Tox and a custom dependency tree plugin

Getting Started

Add to an existing Nx Workspace

Install the npm dependency

npm install @nxlv/python --save-dev

Usage

1. Update nx.json to add the property plugins with @nxlv/python value.

Example:

{
  ...
  "plugins": [
    "@nxlv/python"
  ]
  ...
}

Add a new Python Project

nx generate @nxlv/python:project myproject

Options

Option	Type	Description	Required	Default
--type	string	Project type application or library	true	application
--description	string	Project description	false
--directory	string	A directory where the project is placed	false
--packageName	string	Package name	true
--publishable	boolean	Speficies if the project is publishable or not	false	true
--customSource	boolean	Speficies if the project uses custom PyPi registry	false	false
--sourceName	string	Custom PyPi registry name	only if the --customSource is true
--sourceUrl	string	Custom PyPi registry url	only if the --customSource is true
--sourceSecondary	boolean	Custom PyPi registry secondary flag	only if the --customSource is true	true
--tags	string	Add tags to the project	false

Add a new dependency to a project

nx run {project}:add --name {projectName} --local

Add an external dependency to the project

To add a new dependency to the project use the nx run {project}:add command detailed below. This ensures that any dependent projects are updated.

nx run {project}:add --name {dependencyName}

Executors

sls-deploy

The @nxlv/python:sls-deploy executor handles npx sls deploy command for serverless framework projects.

This executor uses the @nxlv/python:build artifacts to generate a requirements.txt and to be used with serverless-python-requirements plugin.

Serverless YAML example:

service: myservice

plugins:
  - serverless-python-requirements

custom:
  pythonRequirements:
    usePoetry: false

The property usePoetry must be false, so, the serverless-python-requirements uses the requirements.txt file generated by this executor, this is required when the project has more than 2 levels of local dependencies.

Example:

- root:
  - sls-app
   - local-lib1
    - local-lib2

Using the native serverless-python-requirements plugin with poetry the 2 levels of local dependencies are not supported.

project.json example:

{
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "projectType": "application",
  "sourceRoot": "apps/myapp/lambda_functions",
  "targets": {
    "deploy": {
      "executor": "@nxlv/python:sls-deploy",
      "dependsOn": ["build"],
      "options": {}
    },
    "package": {
      "executor": "@nxlv/python:sls-package",
      "dependsOn": ["build"],
      "options": {}
    },
    ...
    "build": {
      "executor": "@nxlv/python:build",
      "outputs": ["apps/myapp/dist"],
      "options": {
        "outputPath": "apps/myapp/dist",
        "publish": false
      }
    },
  }
}

Options

Option	Type	Description	Required	Default
--stage	string	Serverless Framework stahe name	true
--verbose	boolean	Serverless Framework CLI verbose flag	false	true
--force	boolean	Serverless Framework CLI force flag	false	false

add

The @nxlv/python:add executor handles poetry add command to provide a level of abstraction and control in the monorepo projects.

Features

• Add new external dependencies
• Add local dependencies

Both features updates the local workspace dependency tree to keep the lock/venv updated.

Options

Option	Type	Description	Required	Default
--name	string	Dependency name (if local dependency use the Nx project name)	true
--args	string	Custom args to be used in the poetry add command	false
--local	boolean	Specifies if the dependency is local	false (only if the --name is a local dependency)

update

The @nxlv/python:update executor handles poetry update command to provide a level of abstraction and control in the monorepo projects.

Features

• Update external dependencies
• Update local dependencies

Both features updates the local workspace dependency tree to keep the lock/venv updated.

Options

Option	Type	Description	Required	Default
--name	string	Dependency name (if local dependency use the Nx project name)	false
--args	string	Custom args to be used in the poetry update command	false
--local	boolean	Specifies if the dependency is local	false (only if the --name is a local dependency)

remove

The @nxlv/python:remove executor handles poetry remove command to provide a level of abstraction and control in the monorepo projects.

Features

• Remove external dependencies
• Remove local dependencies

Both features updates the local workspace dependency tree to keep the lock/venv updated.

Options

Option	Type	Description	Required	Default
--name	string	Dependency name (if local dependency use the Nx project name)	true
--args	string	Custom args to be used in the poetry remove command	false
--local	boolean	Specifies if the dependency is local	false (only if the --name is a local dependency)

build

The @nxlv/python:build command handles the sdist and wheel build generation. When the project has local dependencies the executor copies the package/dependencies recursively.

Options

Option	Type	Description	Required	Default
--silent	boolean	Hide output text	false	false
--outputPath	string	Output path for the python tar/whl files	true
--keepBuildFolder	boolean	Keep build folder	false	false
--ignorePaths	array	Ignore folder/files on build process	false	[".venv", ".tox", "tests"]

flake8

The @nxlv/python:flake8 handles the flake8 linting tasks and reporting generator.

Options

Option	Type	Description	Required	Default
--silent	boolean	Hide output text	false	false
--outputFile	string	Output pylint file path	true

install

The @nxlv/python:install handles the poetry install command for a project.

Options

Option	Type	Description	Required	Default
--silent	boolean	Hide output text	false	false
--args	string	Custom arguments (e.g --group dev)	false
--cacheDir	string	Custom poetry install cache directory	false
--verbose	boolean	Use verbose mode in the install poetry install -vv	false	false
--debug	boolean	Use debug mode in the install poetry install -vvv	false	false

tox

The @nxlv/python:tox handles tox executions for a project.

Options

Option	Type	Description	Required	Default
--silent	boolean	Hide output text	false	false
--args	string	Custom arguments (e.g -e py38)	false

Shared Virtual Environment

By default, the @nxlv/python manages the projects individually, so, all the projects have their one set of dependencies and virtual environments.

However, In some cases, we want to use a shared virtual environment for the entire workspace to save some installation time in your local environment and CI tool, we use this mode when the workspace contains many projects with the same dependencies and versions that don't conflict in the workspace level.

To migrate to this mode, run the following command:

npx nx generate @nxlv/python:migrate-to-shared-venv

Options

Option	Type	Description	Required	Default
--moveDevDependencies	boolean	Specifies if migration moves the dev dependencies from the projects to the root pyproject.toml	true	true