gittogethers / codespaces-teaching-template-py

Codespaces template for teaching Python

Python Codespace Template

• Who is this for? Educators of all levels.
• How much experience do students need? Zero. This template is built with basic elements complete with comments so it can be used in beginner to advanced lessons.
• Prerequisites: None. This template will provide a working Jupyter Notebook with Pandas using a dataset so that you can immediately start analyzing data.

Create or extend a ready-to-use repository for teaching Python in minutes

With this template repository you can quickly create a normalized environment to teach or learn Python. Make your students focus on learning rather than setting up their environment. This template uses Codespaces, a development environment that's hosted in the cloud with Visual Studio Code, a powerful text editor.

🤔 Curious? Watch the following video where we explain all the details:

🎥 Watch the video tutorial to learn more about Codespaces

🚀 Codespaces features:

• Repeatable cloud environment offering a push-button experience.
• Can be configured and customized.
• Integrates with your repositories on GitHub and VSCode

As a teacher that means that you can create an environment, in the cloud, for your class that all students can use with zero or next to zero configuration regardless of what operating system they are using.

🧑‍🏫 What is GitHub Codespace and how can I use it in my teaching?

A Codespace is a development environment that's hosted in the cloud that you can configure. The Codespaces Education benefit gives Global Campus teachers a free monthly allowance of GitHub Codespaces hours to use in GitHub Classroom. Learn more here about Using GitHub Codespaces with GitHub Classroom.

If you are not already a Global Campus teacher, apply here or for more information, see Apply to GitHub Global Campus as a teacher.

Customization

Customize your project for GitHub Codespaces by committing configuration files to your repository (often known as Configuration-as-Code), which creates a repeatable codespace configuration for all users of your project.

You can configure things like:

• Extensions, you can specify what extensions should be preinstalled.
• Dotfiles and settings.
• Operating system libraries and dependencies

💡 Learn more about customization and configuration in the official documentation

Codespaces template

This repo is a GitHub template. It contains the following:

• example-notebook.ipynb: A Jupyter notebook using the Pandas library to teach basic operations with a small CSV (Comma Separated Value file) dataset
• .devcontainer/Dockerfile: Configuration file used by Codespaces to determine operating system and other details.
• .devcontainer/devcontainer.json, A configuration file used by Codespaces to configure Visual Studio Code settings, such as the enabling of additional extensions.
• README.md. This file describes this repository and what's in it.

🧐 Try it out

Try out this template repository using Codespaces following these steps:

1. Create a repository from this template. Use this create repo link. You can make the repository private or public, up to you.
2. Navigate to the main page of the newly created repository.
3. Under the repository name, use the Code drop-down menu, and in the Codespaces tab, select "Create codespace on main".
4. Wait as Github initializes the codespace:

Inspect your codespaces environment

What you have at this point is a pre-configured environment where all the runtimes and libraries you need are already installed - a zero config experience.

You also have a Jupyter Notebook that you can start using without any configuration.

This environment will run the same regardless of whether your students are on Windows, macOS or Linux.

Open up your Jupyter Notebook file example-notebook.ipynb and note how you can add code and run it.

Customize the Codespace

Let's make changes to your environment. We'll cover two different challenges that you are likely to want to do:

1. Change the Python version installed
2. Add an extension

Step 1: Change the Python environment

Let's say you want to change what version of Python is installed. This is something you can control.

Open .devcontainer/devcontainer.json and replace the following section:

"VARIANT": "3.8-bullseye"

with the following instruction:

"VARIANT": "3.9-bullseye"

This change instructs Codespaces to use Python 3.9 instead of 3.8.

If you make any configuration change in devcontainer.json, a box will appear after saving.

Click on rebuild. Wait for your Codespace to rebuild the VS Code environment.

Step 2: Add an extension

Your environment comes with pre-installed extensions. You can change which extensions your Codespaces environment starts with. Here's how:

1. Open file .devcontainer/devcontainer.json and locate the following JSON element extensions:

   "extensions": [
    "ms-python.python",
    "ms-python.vscode-pylance"
   ]

2. Add "ms-python.black-formatter" to the list of extensions. It should end up looking like the following:

   "extensions": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-python.black-formatter"
   ]

   That string is the unique identifier of Black Formatter, a popular extension for formatting Python code according to best practices. Adding the "ms-python.black-formatter" identifier to the list lets Codespaces know that this extension should be pre-installed upon startup.

   Remainder: When you change any configuration on the json, a box will appear after saving.

   

   Click on rebuild. Wait for your codespace to rebuild the VS Code environment.

To find the unique identifier of an extension:

• Navigate to the extension's web page, for example https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter
• Locate the Unique Identifier field under More info section on your right side.

Learn more

• GitHub Codespaces docs overview
• GitHub Codespaces docs quickstart
• Using GitHub Codespaces with GitHub Classroom

🔎 Found an issue or have an idea for improvement?

Help us make this template repository better by letting us know and opening an issue!.