Saltearse al contenido
@aws/nx-plugin
Blog

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 crear un nuevo proyecto Python de dos formas:

  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
    • Haga clic en Generate

    Opciones

    Parámetro Tipo Predeterminado Descripción
    name Requerido string - Project name.
    directory string packages Parent directory where the project is placed.
    projectType Requerido string application Project type
    moduleName string - Python module name

    Resultado del generador

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

    • Directory<nombre-del-módulo>
      • __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 build
    • pyproject.toml Archivo de configuración de empaquetado usado por UV
    • .python-version Contiene la versión de Python del proyecto

    También notarás estos 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 Python

    Añade tu código fuente Python en el directorio <nombre-del-módulo>.

    Importando tu biblioteca en otros proyectos

    Gracias a la configuración de espacios de trabajo UV, puedes referenciar tu proyecto Python desde cualquier otro proyecto en tu espacio de trabajo:

    packages/my_other_project/my_other_project/main.py
    from "my_library.hello" import say_hello

    Aquí, my_library es el nombre del módulo, 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:

    Terminal window
    pnpm 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 producción

    Cuando uses tu proyecto Python como código en producción (por ejemplo como handler de una función AWS Lambda), necesitarás crear un paquete con el 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 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"]
        },
      },
    }

    Compilación

    Tu proyecto Python incluye un objetivo build (definido en project.json) que puedes ejecutar con:

    Terminal window
    pnpm nx run <project-name>:build

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

    El objetivo build compilará, verificará estilo y ejecutará pruebas del proyecto.

    La salida del build 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/<mi-biblioteca>/build

    Pruebas

    El proyecto está configurado con pytest para ejecutar pruebas.

    Escribiendo pruebas

    Las pruebas deben escribirse en el directorio test 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 realizan aserciones para verificar expectativas:

    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 separadamente con:

    Terminal window
    pnpm nx run <project-name>:test

    Puedes ejecutar una prueba individual usando el flag -k con el nombre del archivo o método:

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

    Verificación de estilo

    Los proyectos Python usan Ruff para verificación de estilo.

    Ejecutando el linter

    Para ejecutar el linter y verificar tu proyecto:

    Terminal window
    pnpm nx run <project-name>:lint

    Corrigiendo problemas

    La mayoría de problemas de estilo pueden corregirse automáticamente. Ejecuta Ruff con el argumento --configuration=fix:

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

    Para corregir problemas en todos los paquetes de tu espacio de trabajo:

    Terminal window
    pnpm nx run-many --target lint --all --configuration=fix