Configuración de un proyecto de Python para GitHub Codespaces

Introducción

En esta guía se muestra cómo configurar un proyecto de Python en en Codespaces mediante la aplicación de escritorio Visual Studio Code o el cliente web VS Code. Te mostrará un ejemplo de cómo abrir tu proyecto en un codespace y cómo agregar y modificar una configuración de contenedor de dev predeterminada..

Prerrequisitos

Debes tener un proyecto existente de Python en un repositorio de GitHub.com. Si no tiene un proyecto, puede probar este tutorial con el ejemplo siguiente: https://github.com/2percentsilk/python-quickstart.
Debes tener GitHub Codespaces habilitado en tu organización.

Paso 1: Abre tu proyecto en un codespace

Debajo del nombre del repositorio, usa el menú desplegable Código de y, en la pestaña Codespaces, haz clic en el signo más ().

Cuando creas un codespace, tu proyecto se crea en una MV remota dedicada a ti. Predeterminadamente, el contenedor para tu codespace tiene muchos lenguajes y tiempos de ejecución, incluyendo a Node.js, JavaScript, TypeScript, nvm, npm y yarn. También incluye un conjunto de herramientas comunes como git, wget, rsync, openssh y nano.

You can customize your codespace by adjusting the amount of vCPUs and RAM, adding dotfiles to personalize your environment, or by modifying the tools and scripts installed. For more information, see "Customizing your codespace."

GitHub Codespaces uses a file called devcontainer.json to configure the development container that you use when you work in a codespace. Each repository can contain one or more devcontainer.json files, to give you exactly the development environment you need to work on your code in a codespace.

On launch, GitHub Codespaces uses a devcontainer.json file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "Introduction to dev containers."

Paso 2: agregar una configuración de contenedor de desarrollo al repositorio desde una plantilla

El contenedor de desarrollo predeterminado, o "contenedor de desarrollo", para GitHub Codespaces viene con la versión más reciente de Python, los administradores de paquetes (pip, Miniconda) y otras herramientas comunes preinstaladas. Sin embargo, recomendamos que configures tu propio contenedor de desarrollo para incluir todas las herramientas y scripts que necesita el proyecto. Esto garantizará un entorno totalmente reproducible para todos los usuarios de GitHub Codespaces en el repositorio.

Para configurar el repositorio a fin de usar un contenedor de desarrollo personalizado, deberás crear uno o varios archivos devcontainer.json. Puedes agregarlos desde una plantilla de configuración predefinida, en Visual Studio Code, o bien puedes escribir los tuyos propios. Para obtener más información sobre las configuraciones de los contenedores de desarrollo, consulta "Introducción a los contenedores de desarrollo".

Accede a Visual Studio Code Command Palette (Mayús+Comando+P (Mac) / Ctrl+Mayús+P (Windows/Linux)) y, luego, empieza a escribir "dev container". Seleccione Codespaces: Agregar archivos de configuración de contenedor de desarrollo... .
Para este ejemplo, haga clic en Python 3. Si necesitas características adicionales, puedes seleccionar cualquier contenedor que sea específico para Python o una combinación de herramientas tales como Python 3 y PostgreSQL.
Haz clic en la versión recomendada de Python.
Acepta la opción predeterminada para agregar a Node.js a tu personalización. 1. Accede a VS Code Command Palette (Comando+Shift+P (Mac) / Ctrl+Shift+P (Windows/Linux)) y, a continuación, empieza a escribir "recompilar". Seleccione Codespaces: Rebuild Container.

Consejo: En ocasiones, es posible que quieras realizar una recompilación completa para borrar la memoria caché y recompilar el contenedor con imágenes nuevas. Para más información, consulta "Realización de una recompilación completa de un contenedor".

Anatomía de tu contenedor dev

Al agregar la plantilla de contenedor de desarrollo de Python, se agrega un directorio .devcontainer a la raíz del repositorio del proyecto con los archivos siguientes:

devcontainer.json
Dockerfile

En el archivo devcontainer.json recién agregado se definen varias propiedades que se describen después del ejemplo.

devcontainer.json

{
    "name": "Python 3",
    "build": {
        "dockerfile": "Dockerfile",
        "context": "..",
        "args": {
            // Update 'VARIANT' to pick a Python version: 3, 3.6, 3.7, 3.8, 3.9
            "VARIANT": "3",
            // Options
            "INSTALL_NODE": "true",
            "NODE_VERSION": "lts/*"
        }
    },

    // Set *default* container specific settings.json values on container create.
    "settings": {
        "terminal.integrated.shell.linux": "/bin/bash",
        "python.pythonPath": "/usr/local/bin/python",
        "python.linting.enabled": true,
        "python.linting.pylintEnabled": true,
        "python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8",
        "python.formatting.blackPath": "/usr/local/py-utils/bin/black",
        "python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf",
        "python.linting.banditPath": "/usr/local/py-utils/bin/bandit",
        "python.linting.flake8Path": "/usr/local/py-utils/bin/flake8",
        "python.linting.mypyPath": "/usr/local/py-utils/bin/mypy",
        "python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle",
        "python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle",
        "python.linting.pylintPath": "/usr/local/py-utils/bin/pylint"
    },

    // Add the IDs of extensions you want installed when the container is created.
    "extensions": [
        "ms-python.python"
    ],

    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    // "forwardPorts": [],

    // Use 'postCreateCommand' to run commands after the container is created.
    // "postCreateCommand": "pip3 install --user -r requirements.txt",

    // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
    "remoteUser": "vscode"
}

name: puedes asignar el nombre que quieras al contenedor de desarrollo, este es solo el nombre predeterminado.
build: las propiedades de compilación.
- dockerfile: en el objeto build, dockerfile contiene la ruta de acceso al Dockerfile que también se ha agregado desde la plantilla.
- args
  - variant: este archivo solo contiene un argumento de compilación, que es la variante del nodo que queremos usar que se pasa al Dockerfile.
settings: la configuración de Visual Studio Code.
- terminal.integrated.shell.linux: aunque aquí bash sea el shell de terminal predeterminado, puedes modificarlo y usar otros.
extensions: las extensiones incluidas de forma predeterminada.
- ms-python.python: la extensión de Python de Microsoft te proporciona una compatibilidad enriquecida para el lenguaje Python (para todas las versiones compatibles del lenguaje: >=3.6), incluidas las características tales como IntelliSense, linting, depuración, navegación de código, formato de código, refactorización, explorador de variables, explorador de pruebas y mucho más.
forwardPorts: cualquier puerto que se incluya aquí se reenviará de forma automática. Para más información, vea "Reenvío de puertos en el codespace".
postCreateCommand: después de crear el codespace, usa esta opción para ejecutar comandos que no están definidos en el Dockerfile, como pip3 install -r requirements.
remoteUser: de manera predeterminada, la ejecución se realiza como el usuario vscode, pero opcionalmente se puede establecer en root.

Dockerfile

# [Choice] Python version: 3, 3.9, 3.8, 3.7, 3.6
ARG VARIANT="3"
FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT}

# [Option] Install Node.js
ARG INSTALL_NODE="true"
ARG NODE_VERSION="lts/*"
RUN if [ "${INSTALL_NODE}" = "true" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi

# [Optional] If your pip requirements rarely change, uncomment this section to add them to the image.
# COPY requirements.txt /tmp/pip-tmp/
# RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
#    && rm -rf /tmp/pip-tmp

# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
#     && apt-get -y install --no-install-recommends <your-package-list-here>

# [Optional] Uncomment this line to install global node packages.
# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1

Puedes utilizar este Dockerfile para agregar capas de contenedor adicionales y especificar paquetes de SO, versiones de nodo o paquetes globales que queremos incluir en nuestro contenedor.

Paso 3: Modifica tu archivo devcontainer.json

Con la configuración del contenedor de desarrollo agregada y un conocimiento básico de lo que hace cada elemento, ya puedes realizar cambios para personalizar aún más el entorno. En este ejemplo, agregarás porpiedades para instalar extensiones y tus dependencias de pryecto cuando se lance tu codespace.

En el Explorador, expanda la carpeta .devcontainer y seleccione el archivo devcontainer.json del árbol para abrirlo.

Actualice la lista extensions del archivo devcontainer.json para agregar algunas extensiones que son útiles al trabajar con el proyecto.

JSON

"extensions": [
        "ms-python.python",
        "cstrap.flask-snippets",
        "streetsidesoftware.code-spell-checker"
    ],

Quite la marca de comentario de postCreateCommand para instalar automáticamente los requisitos como parte del proceso de instalación de los codespaces.
JSON
```
// Use 'postCreateCommand' to run commands after the container is created.
"postCreateCommand": "pip3 install --user -r requirements.txt",
```
Accede a VS Code Command Palette (Comando+Shift+P (Mac) / Ctrl+Shift+P (Windows/Linux)) y, a continuación, empieza a escribir "recompilar". Seleccione Codespaces: Rebuild Container.

Consejo: En ocasiones, es posible que quieras realizar una recompilación completa para borrar la memoria caché y recompilar el contenedor con imágenes nuevas. Para más información, consulta "Realización de una recompilación completa de un contenedor".

Reconstruir dentro de tu codespace garantiza que tus cambios funcionan como se espera antes de que los confirmes los en el repositorio. Si algo falla, se te colocará en un codespace con un contenedor de recuperación desde el cual puedes volver a compilar para seguir ajustando tu contenedor.
Verifica tus cambios en donde se aplicaron con éxito verificando que se hayan instalado las extensiones "Code Spell Checker" y "Flask Snippet".

Paso 4: Ejecución de la aplicación

En la sección anterior, ha usado postCreateCommand para instalar un conjunto de paquetes mediante pip3. Ahora que instalaste tus dependencias, puedes ejecutar tu aplicación.

Para ejecutar la aplicación, presione F5 o escriba python -m flask run en el terminal del codespace.
Cuando se inicie el proyecto, deberías ver un mensaje de notificación del sistema en la esquina inferior derecha de VS Code, que contendrá un mensaje para conectarse al puerto que usa el proyecto.

Paso 5: Confirma tus cambios

Una vez que hayas hecho cambios a tu codespace, ya sea de código nuevo o de cambios de configuración, necesitarás confirmar tus cambios. El confirmar los cambios en tu repositorio garantiza que cualquiera que cree un codespace desde este repositorio tendrá la misma configuración. Esto también significa que cualquier personalización que hagas, tal como agregar extensiones de VS Code, aparecerá para todos los usuarios.

Para obtener información, vea "Uso del control de código fuente en codespace".

Pasos siguientes

Ahora ya deberías poder empezar a desarrollar tu proyecto de Python en GitHub Codespaces. Aquí tienes algunos recursos adicionales para situaciones más avanzadas.