### Install Dependencies

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Handles the installation of project dependencies using either Poetry or Uv.

```APIDOC
## @nxlv/python:install

### Description
Installs project dependencies using Poetry or Uv.

### Method
N/A (Executor)

### Endpoint
N/A (Executor)

### Parameters
#### Query Parameters
- **silent** (boolean) - Optional - Hide output text. Default: `false`
- **args** (string) - Optional - Custom arguments (e.g `--group dev`).
- **cacheDir** (string) - Optional - Custom poetry install cache directory.
- **verbose** (boolean) - Optional - Use verbose mode in the install `poetry install -vv`. Default: `false`
- **debug** (boolean) - Optional - Use debug mode in the install `poetry install -vvv`. Default: `false`

### Request Example
```json
{
  "install": {
    "silent": false,
    "args": "--group dev",
    "cacheDir": "/path/to/cache",
    "verbose": false,
    "debug": false
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of installation.

#### Response Example
```json
{
  "message": "Dependencies installed successfully."
}
```
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

Run this command after cloning the repository to install all necessary project dependencies.

```bash
npm i
```

--------------------------------

### Poetry Build Configurations

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Examples of pyproject.toml configurations for Poetry within an Nx monorepo, demonstrating different build behaviors.

```APIDOC
## Poetry Build Example

### Description
This example shows a standard Poetry configuration where local dependencies are bundled.

### Method
N/A (Configuration File)

### Endpoint
N/A

### Request Body
N/A

### Request Example
```toml
# packages/proj1/pyproject.toml
[tool.poetry]
name = "pymonorepo-proj1"

  [[tool.poetry.packages]]
  include = "pymonorepo_proj1"

  [tool.poetry.dependencies]
  python = ">=3.8,<3.10"
  pendulum = "^2.1.2"

    [tool.poetry.dependencies.pymonorepo-lib1]
    path = "../lib1"
    develop = true
```

```toml
# packages/lib1/pyproject.toml
[tool.poetry]
name = "pymonorepo-lib1"
version = "1.0.0"

  [[tool.poetry.packages]]
  include = "pymonorepo_lib1"

  [tool.poetry.dependencies]
  python = ">=3.8,<3.10"
  numpy = "^1.24.1"
```

### Response
N/A

## Non-Locked Versions Build

### Description
When the `--lockedVersions=false` option is used, Poetry uses versions directly from `pyproject.toml` and bundles local dependencies.

### Method
N/A (Configuration File)

### Endpoint
N/A

### Request Body
N/A

### Request Example
```toml
# packages/proj1/dist/pymonorepo-proj1-1.0.0.tar.gz/pyproject.toml
[tool.poetry]
name = "pymonorepo-proj1"
version = "1.0.0"

  [[tool.poetry.packages]]
  include = "pymonorepo_proj1"

  [[tool.poetry.packages]]
  include = "pymonorepo_lib1"

  [tool.poetry.dependencies]
  python = ">=3.8,<3.10"
  numpy = "^1.24.1"
  pendulum = "^2.1.2"
```

### Response
N/A

## Non-Bundled Local Dependencies Build

### Description
Using `--bundleLocalDependencies=false` and `--lockedVersions=false` prevents bundling local dependencies, using versions from `pyproject.toml` instead. The executor checks if the local dependency is publishable.

### Method
N/A (Configuration File)

### Endpoint
N/A

### Request Body
N/A

### Request Example
```toml
# packages/proj1/dist/pymonorepo-proj1-1.0.0.tar.gz/pyproject.toml
[tool.poetry]
name = "pymonorepo-proj1"
version = "1.0.0"

  [[tool.poetry.packages]]
  include = "pymonorepo_proj1"

  [tool.poetry.dependencies]
  python = ">=3.8,<3.10"
  pendulum = "^2.1.2"
  pymonorepo-lib1 = "1.0.0"
```

### Response
N/A

## Custom Source Specification

### Description
Configures a custom PyPI source for a package using `customSourceName` and `customSourceUrl` in the build options.

### Method
N/A (Configuration File)

### Endpoint
N/A

### Request Body
N/A

### Request Example
```json
// project.json example
{
  "...": "...",
  "targets": {
    "...": "...",
    "build": {
      "executor": "@nxlv/python:build",
      "outputs": ["apps/myapp/dist"],
      "options": {
        "outputPath": "apps/myapp/dist",
        "publish": false,
        "customSourceName": "example",
        "customSourceUrl": "http://example.com/"
      }
    }
  }
}
```

### Response
N/A
```

--------------------------------

### Create a New Nx Workspace

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

Use this command to scaffold a new Nx workspace. Ensure you have pnpm installed.

```bash
pnpm create-nx-workspace@latest
```

--------------------------------

### Configure Poetry Project Dependencies

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Example pyproject.toml files for a project and a local library dependency.

```toml
[tool.poetry]
name = "pymonorepo-proj1"

  [[tool.poetry.packages]]
  include = "pymonorepo_proj1"

  [tool.poetry.dependencies]
  python = ">=3.8,<3.10"
  pendulum = "^2.1.2"

    [tool.poetry.dependencies.pymonorepo-lib1]
    path = "../lib1"
    develop = true
```

```toml
[tool.poetry]
name = "pymonorepo-lib1"
version = "1.0.0"

  [[tool.poetry.packages]]
  include = "pymonorepo_lib1"

  [tool.poetry.dependencies]
  python = ">=3.8,<3.10"
  numpy = "^1.24.1"
```

--------------------------------

### Install a Linked Package in Nx Workspace

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

Link a locally developed package into your Nx workspace. Ensure you are in the workspace root and use the correct package name.

```bash
npm link <package-name>
```

--------------------------------

### Key Generator Examples

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/PROJECT_ARCHITECTURE.md

Lists and briefly describes essential generators provided by the plugin, including those for scaffolding new Python projects with Poetry or uv, migrating virtual environments, and enabling Nx releases.

```typescript
poetry-project / uv-project — scaffold a Python project for the respective manager (templates under `files/`: `base`, `pytest`, `flake8`, `standard`, `src-dir`)
project — legacy combined generator.
migrate-to-shared-venv — convert isolated venvs to a single shared venv.
enable-releases (hidden) — wire a Python project into Nx release.
pkg-sync — keep `pyproject.toml` dependencies in sync.
```

--------------------------------

### Rollback Migration Script

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/data-migration/README.md

Initiate a rollback for migration scripts in a specified environment, starting from a given namespace and version. The `--from` option defines the rollback starting point.

```bash
npx nx run my-project:migrate-rollback --env {environment} --from {namespace}:{version}
```

--------------------------------

### Add Dependency with Custom Arguments (Poetry/uv)

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Provide custom arguments to the `add` command when using the `@nxlv/python:add` executor. This allows for more granular control over dependency installation.

```bash
npx nx add @nxlv/python:add --name=<dependency-name> --args=<custom-args>
```

--------------------------------

### Nx Project Configuration for Serverless Deploy

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Define deployment and packaging targets for a Serverless Framework application within your Nx `project.json`. This example shows how the `deploy` and `package` targets utilize the `@nxlv/python:sls-deploy` and `@nxlv/python:sls-package` executors, respectively, and depend on the `build` target.

```json
{
  "$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
      }
    },
  }
}
```

--------------------------------

### Migrate to Shared Virtual Environment

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Run this command to migrate your Nx workspace to use a shared virtual environment. This can save installation time and reduce workspace size by consolidating dependencies.

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

--------------------------------

### Migrate to Shared Virtual Environment

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Command to migrate Nx projects to use a shared virtual environment, consolidating dependencies and saving installation time.

```APIDOC
## Migrate to Shared Virtual Environment

### Description
Migrates your Nx workspace to use a shared virtual environment for all projects. This consolidates dependencies and can save installation time in local development and CI.

### Command
```bash
npx nx generate @nxlv/python:migrate-to-shared-venv
```

### Options

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
npx nx generate @nxlv/python:migrate-to-shared-venv --moveDevDependencies=true --autoActivate=true --packageManager=poetry
```

### Response
#### Success Response (200)
Workspace is migrated to use a shared virtual environment with a root `pyproject.toml`.

#### Response Example
None
```

--------------------------------

### Executor/Provider Test Structure with Vitest

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/UNIT_TEST.md

Example structure for testing Nx executors, demonstrating the use of Vitest mocks, in-memory filesystem (memfs), and spying on utility functions and child process calls.

```typescript
import { vi, MockInstance } from 'vitest';
import { vol } from 'memfs';
import '../../utils/mocks/cross-spawn.mock';
import '../../utils/mocks/fs.mock';
import * as poetryUtils from '../../provider/poetry/utils';
import { PoetryProvider } from '../../provider/poetry/provider';
import executor from './executor';
import spawn from 'cross-spawn';

describe('Add Executor', () => {
  afterEach(() => {
    vol.reset(); // wipe the in-memory FS
    vi.resetAllMocks();
  });

  describe('poetry', () => {
    beforeEach(() => {
      vi.spyOn(poetryUtils, 'checkPoetryExecutable').mockResolvedValue(undefined);
      vi.spyOn(poetryUtils, 'getPoetryVersion').mockResolvedValue('1.8.2');
      vi.spyOn(PoetryProvider.prototype, 'activateVenv').mockResolvedValue(undefined);
      vi.mocked(spawn.sync).mockReturnValue({ status: 0, output: [''], pid: 0, signal: null, stderr: null, stdout: null });
      vi.spyOn(process, 'chdir').mockReturnValue(undefined);
    });
    // ... it('should ...') assertions on result.success and on what spawn.sync was called with
  });
});
```

--------------------------------

### Rollback Multiple Migration Versions

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/data-migration/README.md

Rollback multiple migration versions by specifying the starting version in the `--from` option. This command will revert the specified migration and all subsequent migrations.

```bash
npx nx run my-project:migrate-rollback --env {environment} --from my-migration-namespace:202304052
```

--------------------------------

### Configure Release Lock Arguments in nx.json

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Customize the arguments passed to the `lock` command during versioning in Nx releases by adding the `lockArgs` option within the `release.version.generatorOptions` object in your `nx.json` file. This example sets the index strategy to `unsafe-best-match`.

```json
{
  ...
  "release": {
    ...
    "version": {
      "generatorOptions": {
        ...
        "lockArgs": "--index-strategy unsafe-best-match"
      }
    }
  }
}
```

--------------------------------

### Build All Projects

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CLAUDE.md

Command to build all projects within the monorepo.

```bash
pnpm nx run-many --target=build --all
```

--------------------------------

### Format Code with Nx

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

Run this command to format your code according to the project's style guidelines. This is a required step before submitting a PR.

```bash
nx format
```

--------------------------------

### Navigate to Package Build Directory

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

Change directory into the build output folder for a specific package. Replace `<project>` with the actual package name.

```bash
cd dist/packages/<project>
```

--------------------------------

### Build All Nx Packages

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

Execute this command to build all packages within the Nx monorepo.

```bash
pnpm nx run-many --target=build --all
```

--------------------------------

### Project Generation and Configuration

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Details on the available options for the @nxlv/python:poetry-project generator and how to configure global defaults in nx.json.

```APIDOC
## Configuration Options

### Parameters
- **codeCoverage** (boolean) - Optional - Enable Code Coverage Reports
- **codeCoverageHtmlReport** (boolean) - Optional - Enable Code Coverage HTML Reports
- **codeCoverageXmlReport** (boolean) - Optional - Enable Code Coverage XML Reports
- **codeCoverageThreshold** (number) - Optional - Minimum Code Coverage Threshold
- **projectNameAndRootFormat** (string) - Optional - Format for project name and root directory (as-provided or derived)

### Global Configuration Example
```json
{
  "generators": {
    "@nxlv/python:poetry-project": {
      "unitTestHtmlReport": false,
      "codeCoverageThreshold": 100,
      "devDependenciesProject": "shared-development"
    }
  }
}
```
```

--------------------------------

### UV Packaged Application/Library Configuration

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Recommended configuration for generating module source files within a `src` directory for packaged projects using uv.

```APIDOC
## UV Packaged Application/Library Configuration

### Description
Provide the `--srcDir` and `--buildSystem=uv` option to generate the module source files inside a `src` directory. This is the recommended approach for [packaged projects](https://docs.astral.sh/uv/concepts/projects/init/#packaged-applications).

### Method
N/A (Configuration options)

### Endpoint
N/A

### Parameters
#### Query Parameters
- **--srcDir** (boolean) - Optional - Whether to generate the module source files inside a `src` directory.
- **--buildSystem** (string) - Optional - Build system to use, set to `uv`.
```

--------------------------------

### Build System Configuration

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Option to specify the build system for the project.

```APIDOC
## Build System Configuration

### Description
Specifies the build system to be used for the project.

### Parameters
#### Query Parameters
- **--buildSystem** (string) - Optional - Build system to use (`hatch` or `uv`)
```

--------------------------------

### Project Generator Options

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Configuration options for initializing a new project using the Nx plugin.

```APIDOC
## Project Generator Options

### Description
These options are used to configure the project generation process, including directory structure, Python environment settings, and testing/linting tools.

### Parameters
#### Options
- **--directory** (string) - Optional - A directory where the project is placed
- **--tags** (string) - Optional - Add tags to the project
- **--projectType** (string) - Required - Project type `application` or `library` (Default: `application`)
- **--packageName** (string) - Optional - Poetry Package name (Default: `name` property)
- **--moduleName** (string) - Optional - Project Source Module (Default: `name` property using `_` instead of `-`)
- **--description** (string) - Optional - Project description
- **--pyprojectPythonDependency** (string) - Optional - Python version range used in the `pyproject.toml` (Default: `>=3.9,<3.11`)
- **--pyenvPythonVersion** (string) - Optional - `.python-version` pyenv file content (Default: `3.9.5`)
- **--publishable** (boolean) - Optional - Specifies if the project is publishable or not (Default: `true`)
- **--buildLockedVersions** (boolean) - Optional - Use locked versions for build dependencies (Default: `true`)
- **--buildBundleLocalDependencies** (boolean) - Optional - Bundle local dependencies (Default: `true`)
- **--linter** (string) - Optional - Linter framework (`flake8`, `ruff` or `none`) (Default: `flake8`)
- **--unitTestRunner** (string) - Optional - Unit Test Runner (`pytest` or `none`) (Default: `pytest`)
- **--unitTestHtmlReport** (boolean) - Optional - Enable HTML Pytest Reports (Default: `true`)
- **--unitTestJUnitReport** (boolean) - Optional - Enable JUnit Pytest Reports (Default: `true`)
```

--------------------------------

### Project Configuration Options

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Options for configuring project naming and source directory structure.

```APIDOC
## Project Configuration Options

### Description
Options for configuring project naming conventions and source directory structure.

### Parameters
#### Query Parameters
- **--projectNameAndRootFormat** (string) - Optional - Whether to generate the project name and root directory as provided (`as-provided`) or generate them composing their values and taking the configured layout into account (`derived`).
- **--srcDir** (boolean) - Optional - Whether to generate the module source files inside a `src` directory (uv recommended). NOTE: To keep backward compatibility with previous versions, the default value is `false`.
```

--------------------------------

### Generate Migration Script using Nx CLI (Interactive)

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/data-migration/README.md

Use the Nx CLI to generate a new migration script. You will be prompted for project, name, namespace, description, migration provider, lifecycle hook, parent version, stream addition, and baseline flag.

```bash
npx nx g @nxlv/data-migration:migration
```

--------------------------------

### Test a Single Project

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CLAUDE.md

Command to run tests for a specific project, such as nx-python.

```bash
pnpm nx test nx-python
```

--------------------------------

### Build a Specific Nx Project

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

Build a specific project within the Nx workspace. Replace `<project>` with the actual project name.

```bash
nx run <project>:build
```

--------------------------------

### Generate Migration Script using Nx CLI (with Options)

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/data-migration/README.md

Generate a migration script by providing all necessary options directly to the Nx CLI command. This bypasses interactive prompts.

```bash
npx nx g @nxlv/data-migration:migration \
  --project=my-project \
  --name=my-migration-name \
  --namespace=my-migration-namespace \
  --description="My migration description" \
  --migrationProvider=standard \
  --lifecycleHook=before:deploy \
  --parentVersion=202304051 \
  --addStream=true
  --baseline=true
```

--------------------------------

### Generate Uv Project

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Create a new project using the uv-project generator.

```shell
nx generate @nxlv/python:uv-project myproject
```

--------------------------------

### Generate a New Poetry Project

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Use the Nx CLI to generate a new Python project managed by Poetry.

```shell
nx generate @nxlv/python:poetry-project myproject
```

--------------------------------

### Scaffolding a Project with Tree and Snapshots

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/UNIT_TEST.md

This snippet demonstrates a typical unit test for an Nx generator. It uses `createTreeWithEmptyWorkspace` to set up an in-memory workspace, mocks necessary utilities, and then asserts the generated project configuration and files against snapshots.

```typescript
import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
import { Tree, readProjectConfiguration, readNxJson } from '@nx/devkit';
import generator from './generator';

let appTree: Tree;
beforeEach(() => {
  vi.resetAllMocks();
  appTree = createTreeWithEmptyWorkspace({ layout: 'apps-libs' });
  vi.spyOn(uvUtils, 'checkUvExecutable').mockResolvedValue(undefined);
  // spawn.sync stubbed to fake `python --version`, etc.
});

it('scaffolds the project', async () => {
  await generator(appTree, options);
  expect(readProjectConfiguration(appTree, 'test')).toMatchSnapshot();
  expect(appTree.read('test/pyproject.toml', 'utf-8')).toMatchSnapshot();
});
```

--------------------------------

### Workspace Directory Structure

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/WORKSPACE_STRUCTURE.md

Illustrates the top-level directory layout of the Nx monorepo, including packages, e2e tests, tools, and configuration files.

```bash
.
├── packages/                 # all publishable projects + libraries (libsDir)
│   ├── nx-python/            # @nxlv/python  — the main plugin
│   ├── data-migration/       # @nxlv/data-migration — DynamoDB-style data migration plugin
│   ├── util/                 # @nxlv/util — shared string utilities library
│   └── data-migration-example/  # non-published example app (excluded from TS project refs/typecheck)
├── e2e/                      # appsDir per nx.json workspaceLayout (end-to-end projects)
├── tools/                    # workspace tooling/scripts
├── tests/setup.ts            # global Vitest setup (registers aws-sdk-client-mock matchers)
├── types/                    # ambient type declarations
├── nx.json                   # Nx config: targetDefaults, plugins, release config
├── tsconfig.base.json        # shared compilerOptions + project references
├── eslint.config.mjs         # root ESLint flat config
├── vitest.workspace.ts       # Vitest workspace aggregator
└── release.base.config.js    # shared release config (sharedGlobals input)

```

--------------------------------

### Sync Dependencies

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Synchronizes locked dependencies with the Python virtual environment using Poetry or Uv.

```APIDOC
## @nxlv/python:sync

### Description
Synchronizes locked dependencies with the Python virtual environment.

### Method
N/A (Executor)

### Endpoint
N/A (Executor)

### Parameters
#### Query Parameters
- **silent** (boolean) - Optional - Hide output text. Default: `false`
- **args** (string) - Optional - Custom arguments (e.g `--check dev`).
- **cacheDir** (string) - Optional - Custom poetry install cache directory.
- **verbose** (boolean) - Optional - Use verbose mode in the install (e.g. `poetry install -vv`). Default: `false`
- **debug** (boolean) - Optional - Use debug mode in the install (e.g. `poetry install -vvv`). Default: `false`

### Request Example
```json
{
  "sync": {
    "silent": false,
    "args": "--check dev",
    "cacheDir": "/path/to/cache",
    "verbose": false,
    "debug": false
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of synchronization.

#### Response Example
```json
{
  "message": "Dependencies synchronized successfully."
}
```
```

--------------------------------

### Provider Abstraction Entry Point

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/PROJECT_ARCHITECTURE.md

The `getProvider` function is the central entry point for resolving the appropriate Python package manager provider (Poetry or uv) based on workspace configuration, lockfiles, or explicit options.

```typescript
getProvider(workspaceRoot, logger?, tree?, context?, options?)
```

--------------------------------

### Enable Dependency Inference and Global Sync

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Update nx.json to enable dependency inference and register the global package sync generator.

```json
{
  ...
  "sync": {
    "globalGenerators": ["@nxlv/python:pkg-sync"]
  },
  "plugins": [
    {
      "plugin": "@nxlv/python",
      "options": {
        ...
        "inferDependencies": true
      }
    },
    ...
  ]
  ...
}
```

--------------------------------

### High-level Layers Diagram

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/PROJECT_ARCHITECTURE.md

Illustrates the architectural layers of the `@nxlv/python` Nx plugin, showing the flow from Nx CLI to executors, generators, migrations, and the provider abstraction interacting with Poetry or uv.

```text
Nx (CLI / graph / release)
        │
        ▼
executors.json / generators.json / migrations.json   ← manifests (point at ./dist/...)
        │
        ▼
src/executors/*   src/generators/*   src/migrations/*   src/plugins/plugin.ts   src/release/*
        │
        └──────────────► src/provider (getProvider) ──────────► Poetry | uv implementations
```

--------------------------------

### Run Unit Tests for Nx Projects

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/UNIT_TEST.md

Commands to run Vitest tests for individual Nx projects or affected projects. Useful for local development and CI pipelines.

```bash
pnpm nx test nx-python            # one project
pnpm nx test util                 # another project
pnpm nx affected --target=test    # only what changed (used in CI)
```

--------------------------------

### Run Unit Tests for a Specific Package

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

To run unit tests for a particular package, specify the package name after the 'nx test' command.

```bash
nx test nx-python
```

--------------------------------

### Configure Auto-Activation for Poetry

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Enable automatic virtual environment activation for Poetry in your Nx workspace by setting `autoActivate` to `true` in the root `pyproject.toml` file. This is relevant when using the `@nxlv/python:run-commands` executor in a Shared virtual environment mode.

```toml
...
[tool.nx]
autoActivate = true

...
```

--------------------------------

### Custom Source Specification in project.json

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Configuring custom Pypi sources within the build options of a project.json file.

```json
{
  ...
  "targets": {
    ...
    "build": {
      "executor": "@nxlv/python:build",
      "outputs": ["apps/myapp/dist"],
      "options": {
        "outputPath": "apps/myapp/dist",
        "publish": false,
        "customSourceName": "example",
        "customSourceUrl": "http://example.com/"
      }
    },
  }
}
```

--------------------------------

### Manually Sync Local Python Package Dependencies

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Use the 'nx run <project>:add <local-package-name> --local' command to manually sync local packages to the pyproject.toml file when using the @nxlv/python plugin.

```shell
nx run <project>:add <local-package-name> --local
```

--------------------------------

### Project Generation Command

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Command to generate a new project using the uv package manager.

```APIDOC
## Generate UV Project

### Description
Generates a new Python project using the uv package manager.

### Command
`nx generate @nxlv/python:uv-project {projectName}`
```

--------------------------------

### Publish Project

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Handles the publishing of Python projects using Poetry or Uv, including building and managing local dependencies.

```APIDOC
## @nxlv/python:publish

### Description
Publishes Python project artifacts. This executor first builds the project and then publishes it, ensuring local dependencies are correctly handled.

### Method
N/A (Executor)

### Endpoint
N/A (Executor)

### Parameters
#### Query Parameters
- **silent** (boolean) - Optional - Hide output text. Default: `false`
- **buildTarget** (string) - Optional - Build Nx target (it needs to be a target that uses the `@nxlv/python:build` execution). Default: `build`
- **repository** (string) - Optional - The repository to publish to (Poetry only).

### Request Example
```json
{
  "publish": {
    "silent": false,
    "buildTarget": "build",
    "repository": "my-private-repo"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of successful publication.

#### Response Example
```json
{
  "message": "Project published successfully."
}
```
```

--------------------------------

### Serverless Framework YAML Configuration

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Configure your Serverless Framework `serverless.yml` to use the `serverless-python-requirements` plugin. Ensure `usePoetry` is set to `false` when the `@nxlv/python:sls-deploy` executor is used to generate `requirements.txt` for projects with complex local dependencies.

```yaml
service: myservice

plugins:
  - serverless-python-requirements

custom:
  pythonRequirements:
    usePoetry: false
```

--------------------------------

### Add Local Dependency

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Add a local project as a dependency to another project.

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

--------------------------------

### Add Local Dependency with Poetry

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Use the `@nxlv/python:add` executor with the `--local` flag to add a local Nx project as a dependency. This updates the local workspace dependency tree.

```bash
npx nx add @nxlv/python:add --name=<nx-project-name> --local
```

--------------------------------

### Create DynamoDB Table and Seed Data (v1)

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/data-migration/README.md

Use this migration to create a DynamoDB table named 'my-table-v1' and populate it with initial data. It utilizes dynamoose for DynamoDB interaction.

```typescript
import { MyTableModel } from '../somewhere';
import { Migration, DynamoDBMigrationBase, LifecycleHook } from '@nxlv/data-migration';
import { chunks } from '@nxlv/util';

@Migration({
  namespace: 'teststream',
  version: 202303311,
  name: 'create-v1-table',
  description: 'Create the v1 table',
  lifecycleHook: LifecycleHook.BEFORE_DEPLOY,
})
export default class extends DynamoDBMigrationBase {
  async up(): Promise<void> {
    await this.createTable({
      TableName: 'my-table-v1',
      KeySchema: [
        { AttributeName: 'clientId', KeyType: 'HASH' },
        { AttributeName: 'id', KeyType: 'RANGE' },
      ],
      AttributeDefinitions: [
        { AttributeName: 'clientId', AttributeType: 'S' },
        { AttributeName: 'id', AttributeType: 'S' },
      ],
      BillingMode: 'PAY_PER_REQUEST',
    });

    this.logger.info('Creating 100 records');
    for (const chunk of chunks(Array.from(Array(100).keys()), 25)) {
      await MyTableModel.batchPut(
        chunk.map((i) => ({
          clientId: 'test',
          id: `id-${i}`,
          name: `name-${i}`,
        })),
      );
    }

    this.logger.info('Done');
  }

  async down(): Promise<void> {
    await this.deleteTable('my-table-v1', true);
  }
}
```

--------------------------------

### Configure @nxlv/python Plugin in nx.json

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Add the @nxlv/python plugin to the 'plugins' array in your nx.json file to enable its functionality. For Nx 20.x and higher, use the object format.

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

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

--------------------------------

### Enable Nx Releases for Python Projects

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Activate the Nx releases feature for your project by running the `nx generate @nxlv/python:enable-releases` command. This command sets up the necessary configurations to manage project releases using Nx.

```bash
nx generate @nxlv/python:enable-releases
```

--------------------------------

### Format Code (Write)

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CLAUDE.md

Command to format all code in the monorepo according to Prettier rules.

```bash
pnpm nx format:write
```

--------------------------------

### Execute Migration Script

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/data-migration/README.md

Run migration scripts for a specific project and environment. The `--env` option specifies the target environment. By default, migrations run with the `before:deploy` lifecycle hook.

```bash
npx nx run my-project:migrate --env {environment}
```

--------------------------------

### Enable Automatic Sync Changes

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Set applyChanges to true in nx.json to automatically update pyproject.toml files during task execution.

```json
{
  ...
  "sync": {
    ...
    "applyChanges": true
  }
  ...
}
```

--------------------------------

### Configure Task-Level Sync Generators

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Add sync generators to specific project targets in project.json to run them before task execution.

```json
{
  ...
  "targets": {
    ...
    "build": {
      ...
      "syncGenerators": ["@nxlv/python:pkg-sync"]
    }
  }
}
```

--------------------------------

### Format Code (Check)

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CLAUDE.md

Command to check if all code in the monorepo is formatted correctly.

```bash
pnpm nx format:check
```

--------------------------------

### Update Dependencies with Custom Arguments (Poetry)

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Provide custom arguments to the `update` command when using the `@nxlv/python:update` executor with Poetry. This allows for specific update behaviors.

```bash
npx nx update @nxlv/python:update --name=<dependency-name> --args=<custom-args>
```

--------------------------------

### Define a Generic Migration Script

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/data-migration/README.md

Use the MigrationBase class to create a lightweight migration script with custom lifecycle hooks and conditions.

```typescript
import { Migration, MigrationBase, LifecycleHook } from '@nxlv/data-migration';

@Migration({
  namespace: 'my-migration-namespace',
  version: 202304051,
  name: 'my-migration-name',
  description: 'Migration description',
  lifecycleHook: LifecycleHook.BEFORE_DEPLOY,
})
export default class extends MigrationBase {
  async condition(): Promise<boolean> {
    return process.env.ENV === 'demo';
  }

  async up(): Promise<void> {
    this.logger.info('apply migration');
  }

  async down(): Promise<void> {
    this.logger.info('rollback migration');
  }
}
```

--------------------------------

### Link Local Package

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

Create a symbolic link for the current package in the global npm registry, allowing it to be linked into other projects.

```bash
npm link
```

--------------------------------

### Flake8 Linting

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Documentation for the `@nxlv/python:flake8` executor, which handles Flake8 linting tasks.

```APIDOC
## Flake8 Linting

### Description
The `@nxlv/python:flake8` executor handles `flake8` linting tasks and reporting.

### Method
N/A (Executor Configuration)

### Endpoint
N/A

### Parameters
#### Options
| Option         |   Type    | Description             |
| -------------- | :-------: | ----------------------- |
| `--silent`     | `boolean` | Hide output text        |
| `--outputFile` | `string`  | Output pylint file path |

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Commit with Conventional Commits

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CLAUDE.md

Command to initiate a commit using Commitizen for Conventional Commits.

```bash
pnpm commit
```

--------------------------------

### Execute Migration Script with Custom Lifecycle Hook

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/data-migration/README.md

Execute migration scripts using a specific lifecycle hook, such as `after:deploy`. This allows control over when migrations are applied relative to deployment.

```bash
npx nx run my-project:migrate --env {environment} --lifecycleHook=after:deploy
```

--------------------------------

### Shared TOML Utilities

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/PROJECT_ARCHITECTURE.md

Provides utility functions for reading and parsing TOML configuration files, specifically `pyproject.toml`, supporting both filesystem operations and Nx Tree operations.

```typescript
getPyprojectData (real FS)
readPyprojectToml (Tree-based)
```

--------------------------------

### Dependency Management Commands

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Commands to add local or external dependencies to an Nx Python project.

```APIDOC
## Add Dependency

### Description
Adds a new dependency to a project, ensuring dependent projects are updated.

### Command
`nx run {project}:add --name {dependencyName}`

### Examples
- Add local dependency: `nx run {project}:add --name {projectName} --local`
- Add external dependency: `nx run {project}:add --name {dependencyName}`
```

--------------------------------

### Test Affected Projects

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CLAUDE.md

Command to test projects affected by recent changes, including linting and building.

```bash
pnpm nx affected -t lint test build
```

--------------------------------

### Configure Uv Package Manager in nx.json

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

To use the 'uv' package manager without workspaces, explicitly set the 'packageManager' option to 'uv' within the plugin configuration in nx.json.

```json
{
  ...
  "plugins": [
    ...
    {
      "plugin": "@nxlv/python",
      "options": {
        "packageManager": "uv"
      }
    }
  ]
  ...
}
```

--------------------------------

### Execute Migration Script with Debug Log Level

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/data-migration/README.md

Increase the verbosity of migration script execution by setting the log level to `debug`. This is useful for troubleshooting.

```bash
npx nx run my-project:migrate --env {environment} --logLevel=debug
```

--------------------------------

### Run Affected Unit Tests

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/CONTRIBUTING.md

Use this command to run unit tests only for projects affected by your changes. This is a performance optimization.

```bash
nx affected --target=test
```

--------------------------------

### Update Local Dependencies with Poetry

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Use the `@nxlv/python:update` executor with the `--local` flag to update local Nx project dependencies. This keeps your project's internal dependencies synchronized.

```bash
npx nx update @nxlv/python:update --name=<nx-project-name> --local
```

--------------------------------

### Non-Bundled Local Dependencies Build Output

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

The pyproject.toml content when using --bundleLocalDependencies=false, referencing the local dependency by version.

```toml
[tool.poetry]
name = "pymonorepo-proj1"
version = "1.0.0"

  [[tool.poetry.packages]]
  include = "pymonorepo_proj1"

  [tool.poetry.dependencies]
  python = ">=3.8,<3.10"
  pendulum = "^2.1.2"
  pymonorepo-lib1 = "1.0.0"
```

--------------------------------

### Common Executor Body Pattern

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/PROJECT_ARCHITECTURE.md

Illustrates the typical structure of an Nx executor, involving changing the current directory, obtaining a package manager provider, executing a provider method, and handling errors.

```typescript
process.chdir(context.root)
getProvider(...)
call the matching provider method
catch errors and print with chalk
```

--------------------------------

### Update External Dependencies with Poetry

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Use the `@nxlv/python:update` executor to update external dependencies for your project using Poetry. This ensures your project uses the latest compatible versions.

```bash
npx nx update @nxlv/python:update --name=<dependency-name>
```

--------------------------------

### Lock Dependencies

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Handles the locking of project dependencies for Poetry or Uv.

```APIDOC
## @nxlv/python:lock

### Description
Locks project dependencies using Poetry or Uv.

### Method
N/A (Executor)

### Endpoint
N/A (Executor)

### Parameters
#### Query Parameters
- **silent** (boolean) - Optional - Hide output text. Default: `false`
- **args** (string) - Optional - Custom arguments (e.g `--check dev`).
- **cacheDir** (string) - Optional - Custom poetry install cache directory.
- **verbose** (boolean) - Optional - Use verbose mode in the install (e.g. `poetry lock -vv`). Default: `false`
- **debug** (boolean) - Optional - Use debug mode in the install (e.g. `poetry lock -vvv`). Default: `false`
- **update** (boolean) - Optional - Update dependencies versions. Default: `false`

### Request Example
```json
{
  "lock": {
    "silent": false,
    "args": "--check dev",
    "cacheDir": "/path/to/cache",
    "verbose": false,
    "debug": false,
    "update": true
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation of dependency lock.

#### Response Example
```json
{
  "message": "Dependencies locked successfully."
}
```
```

--------------------------------

### Migrate Nx Release Versioning Configuration

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Update project.json files to use the new 'versionActions' property for release versioning. This change is necessary for Nx release versioning compatibility.

```json
{
  "name": "app1",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "projectType": "application",
  "sourceRoot": "apps/app1/app1",
  "targets": {
    ...
  },
  "tags": [],
  "release": {
    "version": {
      "generator": "@nxlv/python:release-version"
    }
  }
}
```

```json
{
  "name": "app1",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "projectType": "application",
  "sourceRoot": "apps/app1/app1",
  "targets": {
    ...
  },
  "tags": [],
  "release": {
    "version": {
      "versionActions": "@nxlv/python/release/version-actions"
    }
  }
}
```

--------------------------------

### Import Reusable Mocks

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/docs/UNIT_TEST.md

Import mock modules for common Node.js APIs like the filesystem and cross-spawn. These mocks are essential for isolating tests and controlling external dependencies.

```typescript
import '../../utils/mocks/cross-spawn.mock';
import '../../utils/mocks/fs.mock';
```

--------------------------------

### Configure Global Generator Defaults

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Define default values for generator options in the nx.json file to apply them across all projects.

```json
{
  ...
  "generators": {
    "@nxlv/python:poetry-project": {
      "unitTestHtmlReport": false,
      "codeCoverageThreshold": 100,
      "devDependenciesProject": "shared-development"
    }
  }
  ...
}
```

--------------------------------

### Python Build Executor

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

The `@nxlv/python:build` executor generates `sdist` and `wheel` build artifacts for Python projects, with options for bundling local dependencies.

```APIDOC
## POST /api/python/build

### Description
Builds Python project artifacts (sdist or wheel).

### Method
POST

### Endpoint
/api/python/build

### Parameters
#### Query Parameters
- **silent** (boolean) - Optional - Hide output text. Default: `false`
- **outputPath** (string) - Required - Output path for the python tar/whl files
- **keepBuildFolder** (boolean) - Optional - Keep build folder. Default: `false`
- **lockedVersions** (boolean) - Optional - Build with locked versions. Default: `true`
- **bundleLocalDependencies** (boolean) - Optional - Bundle local dependencies. Default: `true`
- **ignorePaths** (array) - Optional - Ignore folder/files on build process. Default: `[".venv", ".tox", "tests"]`
- **format** (string) - Optional - Build format (allowed values `sdist` or `wheel`). Default: `wheel`

### Request Example
{
  "outputPath": "./dist",
  "format": "sdist",
  "lockedVersions": false
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of build completion.

#### Response Example
{
  "message": "Build completed successfully."
}
```

--------------------------------

### Add External Dependency with Poetry

Source: https://github.com/lucasvieirasilva/nx-plugins/blob/main/packages/nx-python/README.md

Use the `@nxlv/python:add` executor to add new external dependencies to your project using Poetry. This updates the local workspace dependency tree.

```bash
npx nx add @nxlv/python:add --name=<dependency-name>
```