Proyectos de Python

El generador de proyectos Python permite crear bibliotecas o aplicaciones modernas de Python configuradas con mejores prácticas, gestionadas 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 maneras:

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	-	The name of the Python project
directory	string	packages	Parent directory where the project is placed.
projectType Requerido	string	application	Project type
moduleName	string	-	Python module name

Salida del generador

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

• Directory<module-name>

  • __init__.py Inicialización del módulo
  • hello.py Archivo ejemplo de código Python
• Directorytests

  • __init__.py Inicialización del módulo
  • conftest.py Configuración de pruebas
  • test_hello.py Ejemplo de pruebas
• 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 observar estos archivos creados/actualizados en la raíz del workspace:

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

Escribiendo código Python

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

Importando código de tu biblioteca en otros proyectos

Usa 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, ejecutamos:

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

Nota

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

Luego podrás importar tu biblioteca:

packages/my_app/my_scope_my_app/main.py

from my_scope_my_lib.hello import say_hello

Aquí, my_scope_my_lib es el nombre del módulo de la biblioteca, hello corresponde al archivo fuente hello.py, y say_hello es un método definido en hello.py.

Dependencias

Para añadir dependencias a tu proyecto, ejecuta el objetivo add en tu proyecto Python:

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 runtime (por ejemplo como handler para una función AWS Lambda), necesitarás crear un paquete del código fuente y sus dependencias. Puedes lograrlo añadiendo un objetivo como este en tu 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-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 con:

pnpm

pnpm nx run <project-name>:build

yarn

yarn nx run <project-name>:build

npm

npx nx run <project-name>:build

bun

bunx nx run <project-name>:build

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

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

La salida de construcción se encuentra en la carpeta dist raíz de tu workspace, dentro de un directorio para tu paquete y objetivo, por ejemplo dist/packages/<my-library>/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 con prefijo test_, por ejemplo:

• Directorymy_library

  • hello.py
• Directorytest

  • test_hello.py Pruebas para hello.py

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

test/test_hello.py

from my_library.hello 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 ejecutan como parte del objetivo build, pero también puedes ejecutarlas por separado:

pnpm

pnpm nx run <project-name>:test

yarn

yarn nx run <project-name>:test

npm

npx nx run <project-name>:test

bun

bunx nx run <project-name>:test

Puedes ejecutar una prueba individual usando el flag -k:

pnpm

pnpm nx run <project-name>:test -k 'test_say_hello'

yarn

yarn nx run <project-name>:test -k 'test_say_hello'

npm

npx nx run <project-name>:test -k 'test_say_hello'

bun

bunx nx run <project-name>:test -k 'test_say_hello'

Linting

Los proyectos Python usan Ruff para linting.

Ejecutando el linter

Para invocar el linter y verificar tu proyecto:

pnpm

pnpm nx run <project-name>:lint

yarn

yarn nx run <project-name>:lint

npm

npx nx run <project-name>:lint

bun

bunx nx run <project-name>:lint

Corrigiendo problemas de linting

La mayoría de problemas se pueden corregir automáticamente. Ejecuta Ruff con --configuration=fix:

pnpm

pnpm nx run <project-name>:lint --configuration=fix

yarn

yarn nx run <project-name>:lint --configuration=fix

npm

npx nx run <project-name>:lint --configuration=fix

bun

bunx nx run <project-name>:lint --configuration=fix

Para corregir todos los problemas en todos los paquetes:

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