Proyectos Python

El generador de proyectos Python se puede utilizar para crear una biblioteca o aplicación moderna de Python configurada con las mejores prácticas, gestionada con UV, un único archivo de bloqueo y entorno virtual en un espacio de trabajo UV, pytest para ejecutar pruebas, Ruff para análisis estático, y ty para verificación de tipos.

Uso

Generar un Proyecto Python

Puedes generar un nuevo proyecto Python de dos maneras:

Ejecute este generador@aws/nx-plugin:py#project

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

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - py#project
5. Complete los parámetros requeridos
6. Haga clic en Generate

Construya su comando6

nameRequerido

typeRequerido

applicationlibrary

directory

subDirectory

moduleName

preferInstallDependencies

true

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Opciones

Opciones del generador6 opciones

nameRequeridostring

El nombre del proyecto Python

typeRequeridoenumPredeterminado: application

Si el proyecto es una aplicación o una biblioteca

applicationlibrary

directorystringPredeterminado: packages

Directorio padre donde se coloca el proyecto.

subDirectorystring

El subdirectorio en el que se coloca el proyecto. Por defecto, este es el nombre del proyecto.

moduleNamestring

Nombre del módulo Python

preferInstallDependenciesbooleanPredeterminado: true

Si se prefiere instalar las dependencias después de que se ejecute el generador. Establece en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instala una vez al final.

Salida del Generador

El generador creará la siguiente estructura de proyecto en el directorio <directory>/<name>:

• Directorio<module-name>

  • __init__.py Module initialisation
• Directoriotests

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

También puedes notar los siguientes archivos creados/actualizados en la raíz de tu espacio de trabajo:

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

Escribir Código Fuente Python

Agrega tu código fuente Python en el directorio <module-name>.

Importar tu Código de Biblioteca en Otros Proyectos

Usa el objetivo add para agregar una dependencia a un proyecto Python.

Supongamos que hemos creado dos proyectos python, my_app y my_lib. Estos tendrán nombres de proyecto completamente calificados de my_scope.my_app y my_scope.my_lib, y por defecto cada uno tendrá nombres de módulo de my_scope_my_app y my_scope_my_lib.

Para que my_app dependa de my_lib, podemos ejecutar el siguiente comando:

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

Nombres Completamente Calificados

Usamos el nombre de proyecto completamente calificado tanto para el dependiente como para el dependido. Podemos usar la sintaxis abreviada para el proyecto al que queremos agregar la dependencia, pero debemos calificar completamente el nombre del proyecto del que dependerá.

Luego puedes importar tu código de biblioteca:

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.my_module import my_function

Arriba, my_scope_my_lib es el nombre del módulo para la biblioteca, my_module corresponde a un archivo fuente Python my_module.py, y my_function es un método definido en ese archivo.

Dependencias

Para agregar dependencias a tu proyecto, puedes ejecutar el objetivo add en tu proyecto Python, por ejemplo:

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

Esto agregará la dependencia al archivo pyproject.toml de tu proyecto, y actualizará el uv.lock raíz.

Código de Tiempo de Ejecución

Cuando uses tu proyecto Python como código de tiempo de ejecución (por ejemplo, como el controlador para una función lambda de AWS), necesitarás crear un paquete del código fuente y todas sus dependencias. Los generadores py#lambda-function, py#api y py#mcp-server agregan esto por ti. Para agregar uno manualmente, agrega objetivos como los siguientes a tu archivo project.json, coincidiendo con la forma que esos generadores proporcionan:

project.json

{
  "targets": {
    "bundle": {
      "dependsOn": ["bundle-x86"]
    },
    "bundle-x86": {
      "cache": true,
      "inputs": ["production", "^production"],
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle-x86"],
      "options": {
        "commands": [
          "uv export --frozen --no-dev --no-editable --project {projectRoot} --package my_scope.my_library -o dist/{projectRoot}/bundle-x86/requirements.txt",
          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux_2_28 --python-version 3.14 --target dist/{projectRoot}/bundle-x86 -r dist/{projectRoot}/bundle-x86/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    }
  }
}

Instalación

Instala las dependencias de Python con el siguiente comando:

uv sync

Construcción

Tu proyecto Python está configurado con un objetivo build (definido en project.json), que puedes ejecutar mediante:

pnpm

pnpm nx build <project-name>

yarn

yarn nx build <project-name>

npm

npx nx build <project-name>

bun

bunx nx build <project-name>

Donde <project-name> es el nombre completamente calificado de tu proyecto.

El objetivo build compilará, analizará, probará y verificará los tipos de tu proyecto.

La salida de la construcción se puede encontrar en la carpeta dist raíz en tu espacio de trabajo, dentro de un directorio para tu paquete y objetivo, por ejemplo dist/packages/<my-library>/build

Para construir todos los proyectos en tu espacio de trabajo, ejecuta:

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

O usa el comando abreviado:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Ensamblaje

Tu proyecto también tiene un objetivo assemble, que produce lo que tu proyecto contribuye a un despliegue (por ejemplo, su salida compilada o empaquetada), sin ejecutar las compuertas de análisis, pruebas o verificación de tipos.

pnpm

pnpm nx assemble <project-name>

yarn

yarn nx assemble <project-name>

npm

npx nx assemble <project-name>

bun

bunx nx assemble <project-name>

Los objetivos de despliegue dependen de assemble, por lo que el despliegue construye solo lo que está a punto de desplegar.

Usa build en tu pipeline

assemble se usa para una iteración más rápida durante el desarrollo. Ejecuta build en tu pipeline de CI para asegurar que tu proyecto pase las compuertas de calidad antes de un despliegue a producción.

Pruebas

pytest está configurado para probar tu proyecto.

Escribir Pruebas

Las pruebas deben escribirse en el directorio tests dentro de tu proyecto, en archivos python con el prefijo test_, por ejemplo:

• Directoriomy_library

  • my_module.py
• Directoriotests

  • test_my_module.py Tests for my_module.py

Las pruebas son métodos que comienzan con test_ y hacen aserciones para verificar expectativas, por ejemplo:

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

Para más detalles sobre cómo escribir pruebas, consulta la documentación de pytest.

Ejecutar Pruebas

Las pruebas se ejecutarán como parte del objetivo build para tu proyecto, pero también puedes ejecutarlas por separado ejecutando el objetivo 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>

Puedes ejecutar una prueba individual o un conjunto de pruebas usando la bandera -k, especificando el nombre del archivo de prueba o del método:

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'

Archivos de Prueba y Caché

El directorio tests de tu proyecto se excluye de la entrada nombrada production en nx.json.

Los objetivos cuya salida no puede contener un archivo de prueba - como compile y cualquier objetivo de empaquetado - leen production en lugar de default, por lo que editar una prueba no los invalida ni a ninguna tarea en un proyecto que dependa del tuyo.

La exclusión está deliberadamente limitada al directorio tests. Un archivo test_*.py dentro del directorio de tu paquete se trata como código de producción, ya que se empaqueta en tu distribución construida, y por lo tanto aún invalida la construcción.

Los objetivos test, lint, format y typecheck leen default y por lo tanto se vuelven a ejecutar cuando editas una prueba. Ten en cuenta que typecheck también verifica los tipos de tus pruebas, por lo que un error de tipo en una prueba aún se reporta.

Verificación de Tipos

Los proyectos Python usan ty para la verificación de tipos.

Ejecutar el Verificador de Tipos

La verificación de tipos se ejecuta como parte del objetivo build para tu proyecto, pero también puedes ejecutarla por separado mediante el objetivo 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

Suprimir Errores de Tipo

Para suprimir un diagnóstico específico para una sola línea, agrega un comentario # ty: ignore[<rule>] al final de la línea, por ejemplo:

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

Para configurar el comportamiento de la verificación de tipos en tu proyecto, agrega una sección [tool.ty] al pyproject.toml de tu proyecto. Consulta la referencia de configuración de ty para las opciones disponibles.

Análisis

Los proyectos Python usan Ruff para el análisis.

Ejecutar el Analizador

Para invocar el analizador para verificar tu proyecto, puedes ejecutar el objetivo 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>

Corregir Problemas de Análisis

La mayoría de los problemas de análisis o formato se pueden corregir automáticamente. Puedes indicarle a Ruff que corrija problemas de análisis ejecutando con el argumento --configuration=fix.

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

De manera similar, si deseas corregir todos los problemas de análisis en todos los paquetes de tu espacio de trabajo, puedes ejecutar:

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

Comando Abreviado

Este tiene un comando abreviado desde la raíz de tu espacio de trabajo:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Omitir Problemas de Análisis

Para evitar que los problemas de análisis te ralenticen durante el desarrollo (particularmente si tienes problemas no corregibles automáticamente en tu proyecto), puedes ejecutar una construcción con la configuración 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

Esto seguirá ejecutando Ruff como parte de la construcción, pero el objetivo lint siempre se considerará exitoso.

Comando Abreviado

Este tiene un comando abreviado desde la raíz de tu espacio de trabajo:

pnpm

pnpm build:skip-lint

yarn

yarn build:skip-lint

npm

npm run build:skip-lint

bun

bun build:skip-lint