Proyectos de Python

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

Uso

Generar un proyecto Python

Puedes generar un nuevo proyecto Python de dos formas:

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

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

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

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	El nombre del proyecto Python
directory	string	packages	Directorio padre donde se coloca el proyecto.
subDirectory	string	-	El subdirectorio en el que se coloca el proyecto. Por defecto, este es el nombre del proyecto.
projectType Requerido	string	application	Si el proyecto es una aplicación o una biblioteca
moduleName	string	-	Nombre del módulo Python

Salida del generador

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

• Directorio<module-name>

  • __init__.py Inicialización del módulo
• Directoriotests

  • __init__.py Inicialización del módulo
  • conftest.py Configuración de pruebas
  • test_noop.py Prueba de marcador de posición
• project.json Configuración del proyecto y objetivos de construcción
• pyproject.toml Archivo de configuración de empaquetado usado por UV
• .python-version Contiene la versión de Python del proyecto

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

• pyproject.toml Configuración de empaquetado a nivel de espacio de trabajo para UV
• .python-version Contiene la versión de Python del espacio de trabajo
• uv.lock Archivo de bloqueo de dependencias Python

Escribiendo código fuente Python

Añade tu código fuente Python en el directorio <module-name>.

Importando código de tu biblioteca en otros proyectos

Utiliza el objetivo add para añadir una dependencia a un proyecto Python.

Supongamos que hemos creado dos proyectos Python, my_app y my_lib. Estos tendrán nombres completos de proyecto my_scope.my_app y my_scope.my_lib, y por defecto tendrán nombres de módulo 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 cualificados

Usamos el nombre completo del proyecto tanto para el dependiente como para el dependido. Podemos usar sintaxis abreviada para el proyecto al que queremos añadir la dependencia, pero debemos calificar completamente el nombre del proyecto del que dependemos.

Luego podrás importar el código de tu 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 añadir 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 añadirá la dependencia al archivo pyproject.toml de tu proyecto y actualizará el uv.lock raíz.

Código en tiempo de ejecución

Cuando uses tu proyecto Python como código de tiempo de ejecución (por ejemplo como manejador de una función AWS Lambda), necesitarás crear un paquete del código fuente y todas sus dependencias. Puedes lograrlo añadiendo un objetivo como el siguiente a tu archivo 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-manylinux2014 --python `uv python pin` --target dist/packages/my_library/bundle -r dist/packages/my_library/bundle/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    },
  },
}

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 completo de tu proyecto.

El objetivo build compilará, verificará y probará tu proyecto.

La salida de construcción se encontrará en la carpeta dist raíz de 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

Pruebas

pytest está configurado para probar tu proyecto.

Escribiendo pruebas

Las pruebas deben escribirse en el directorio test dentro de tu proyecto, en archivos Python prefijados con test_, por ejemplo:

• Directoriomy_library

  • my_module.py
• Directoriotests

  • test_my_module.py Pruebas para 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.

Ejecutando pruebas

Las pruebas se ejecutarán como parte del objetivo build de tu proyecto, pero también puedes ejecutarlas por separado usando 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 el flag -k, especificando el nombre del archivo de prueba o 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'

Verificación de código

Los proyectos Python usan Ruff para verificación de código.

Ejecutando el verificador

Para invocar el verificador y revisar 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>

Corrigiendo problemas de verificación

La mayoría de los problemas de verificación o formato pueden corregirse automáticamente. Puedes indicar a Ruff que corrija problemas 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 forma similar, si deseas corregir todos los problemas de verificación 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

Esto 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

Omitiendo problemas de verificación

Para evitar que los problemas de verificación 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

Esto 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