[HAI5016] Project Environment Setup

Let’s continue where we left off in the previous class and set up your project environment for Data Science using Visual Studio Code and UV.

What we will cover in this class:

• Setting up a Python project environment using UV
• Installing and configuring Visual Studio Code for Python development
• Exploring the project files created by UV
• Running your first Python script
• Pushing your code to GitHub

Disclaimer: This blog provides instructions and resources for the workshop part of my lectures. It is not a replacement for attending class; it may not include some critical steps and the foundational background of the techniques and methodologies used. The information may become outdated over time as I do not update the instructions after class.

1. Set Up Your (Python) Project Environment

1. Open your terminal.
2. Navigate to your Developer directory that we made earlier:

   cd ~/Developer
   

3. Use the ls command to list the contents of the Developer directory and confirm that the my-first-project directory exists:

   ls
   

4. You should see my-first-project listed among the contents. If you do, navigate into that directory:

   cd my-first-project
   

   If you do not see the my-first-project directory, ensure you are in the correct location and that the directory was created successfully in the previous class

5. Now, create a Python project environment using the uv tool. Run the following command:

   uv init --python 3.11
   

6. After the command completes, let’s see what is in our folder now:

   ls
   

   or use ls -a on macOS/Linux to see hidden files as well.

   You should see some new files in your project folder including .gitignore, main.py and README.md. Let’s explore these files later.

7. Let’s add some Python packages to our project. For this example, we will add ipykernel and pandas, which are commonly used for data manipulation and analysis. Run the following command:

   uv add pandas ipykernel
   

   This command will create a virtual environment for your project and install the specified packages within that environment.

8. During one of the steps above, UV should have automatically created a .venv directory that contains your virtual environment based on Python 3.11. To activate the virtual environment, run the following command:
   • for Windows:

     .venv\Scripts\activate
     

     If you encounter an error stating that you cannot activate the virtual environment because “running scripts is disabled on this system,” you may need to change your PowerShell execution policy. You can do this by running PowerShell as an administrator and executing the following command:

     Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser
     

     And then press your arrow up twice to find the previous command to activate the virtual environment again.

   • for macOS and Linux:

     source .venv/bin/activate
     

9. Once activated, your terminal prompt should change to indicate that you are now working within the virtual environment (you should see (my-first-project) or similar at the beginning of your prompt).
10. To verify that you are using the correct Python version within your virtual environment, run:

    python --version
    

    You should see Python 3.11.x (or the version you specified) as the output.

11. Run a Python script by executing the main.py script:

    uv run main.py
    

Congratulations! You have successfully set up a Python virtual environment for your project. Now, let’s open this project in Visual Studio Code and configure it for Python development.

---

2. Set up Visual Studio Code for Python Development

We installed Visual Studio Code (VS Code) in the previous class. Now, let’s set it up for Data Science and Python development.

• In your terminal, while still in the my-first-project directory, run:

  code .
  

Visual Studio Code should open with your project directory. When asked if you trust the authors of the files in this folder, click “Yes, I trust the authors”.

1. Make sure your project folder is opened in Visual Studio Code (see title my-first-project in the file explorer on the left).
2. Make sure you have the latest version of Visual Studio Code:
   • Click the gear icon in the lower-left corner and select “Check for Updates”.
3. Install the Python extension for Visual Studio Code:
   • Go to the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of the window.
   • Search for “Python” and install the extension published by Microsoft. This should also automatically install the Pylance and Python Environments extensions.
   • Also install the following recommended extensions for Data Science:
     • Jupyter - for working with Jupyter Notebooks
     • Prettier - Code formatting to keep your code neat
     • Data Wrangler - Interact with tabular data directly in VS Code.
     • GitHub CoPilot - AI-powered code completion, suggestions and coding agent.

     To use GitHub Copilot, you will need to sign in with your GitHub account

2.1 Explore the Visual Studio Code Interface

• Editor - The main area to edit your files. You can open as many editors as you like side by side vertically and horizontally.
• Primary Side Bar - Contains different views like the Explorer, Source control and Extensions to assist you while working on your project.
• Secondary Side Bar - Opposite the Primary Side Bar. By default, contains the Copilot Chat view. Drag and drop views from the Primary Side Bar to the Secondary Side Bar to move them.
• Status Bar - Information about the opened project and the files you edit, including the current Python interpreter, Git branch, errors, warnings, and more.
• Activity Bar - Located on the far left-hand side. Lets you switch between views and gives you additional context-specific indicators, like the number of outgoing changes when Git is enabled. You can change the position of the Activity Bar.
• Panel - An additional space for views below the editor region. By default, it contains output, debug information, errors and warnings, and an integrated terminal. The Panel can also be moved to the left or right for more vertical space.

More at VS Code: User interface

---

3. Discover the Project Files

As we saw earlier, your project folder now contains several files. Let’s take a look at some of the important ones:

my-first-project/
├── .venv/
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock

• .venv/: This folder contains your python virtual environment, including all installed packages.
• .gitignore: This file specifies files and directories that should be ignored by Git version control.
• .python-version: This file specifies the Python version used in this project.
• main.py: This is the main entry point for your python project.
• pyproject.toml: This file contains metadata about your project and its dependencies.
• README.md: This file contains information about your project, including how to set it up and use it.
• uv.lock: This file locks the versions of the packages installed in your virtual environment to ensure consistency across different setups.

Filenames that start with a dot (.) are hidden files, which means you may not see them when using your standard file explorer. In MacOS, you can use the shortcut Cmd+Shift+. to toggle hidden files in Finder.

---

4. hello_world.py

1. In Visual Studio Code, click on the “New File” icon in the Explorer view or use the shortcut Cmd+N (macOS) or Ctrl+N (Windows/Linux).
2. Name the file hello_world.py and press Enter.
3. In the hello_world.py file, type the following code:

   print("Hello, World!")
   

4. Save the file by clicking on “File” > “Save” or using the shortcut Cmd+S (macOS) or Ctrl+S (Windows/Linux).
5. To run the hello_world.py file, you can use the integrated terminal in Visual Studio Code or click the “Run” button if available.
6. See the output in the terminal or output pane.
7. In the hello_world.py file, add the following code:

   # Simple math: calculate the sum of two numbers
   a = 5
   b = 7
   result = a + b
   print("The sum of", a, "and", b, "is", result)
   

---

5. Adding files to .gitignore

1. Create a new file named .env in the root of your project directory. This file will be used to store environment variables.
2. Open the .env file and add the following line to set an example environment variable:

     SECRET_KEY=your_secret_key_here
   

3. Save the .env file.
4. Check your source control view in Visual Studio Code. You should see that the .env file is listed as an untracked file.
5. Open the .gitignore file in Visual Studio Code.
6. Add the following lines to the file to ignore common files and directories that should not be tracked by Git:

     .env
   

7. Save the .gitignore file.

8. Go back to the Source Control view. You should see that the .env file is no longer listed as an untracked file.

   Always make sure that your .env file -and other files that contain sensitive information- is included in your .gitignore file to prevent sensitive information from being committed to your Git repository.

---

6. Pushing Your Code to GitHub

1. Make sure you are logged into GitHub in Visual Studio Code.
   • Click on the Accounts icon in the lower-left corner and sign in to GitHub if you haven’t already.
2. Open the Source Control view by clicking on the Source Control icon in the Activity Bar on the side of the window.
3. In the “Message” box at the top of the Source Control view, type a commit message, such as “Initial commit”.
4. Click the checkmark icon (✓) to commit your changes.
5. A “Publish Branch” button should appear at the top of the Source Control view. Click on it to push your code to GitHub.
   • You will be prompted to create new private or public repository on GitHub. Choose according to your preference, for this exercise select “public repository”.

Check your GitHub account to see your newly created repository with the code you just pushed!

If time allows

Write some Markdown in the README.md file to describe your project. You can use the following template:

# My First Project
A simple Python project to demonstrate setting up a project environment using UV and Visual Studio Code.

## Features
- Prints "Hello, World!" to the console.
- Performs a simple addition of two numbers and prints the result.

• Save the README.md file.
• Commit and push the changes to GitHub as described in step 6. As commit message, you can use “Added first text to README.md”.
• Check your GitHub repository to see the updated README.md file.

---

References

• More information about Python virtual environments in UV
• Why VS Code Struggles with Conda (And How UV Solves It)
• Status of Python versions
• What is .gitignore?

Super Kickstart

Missed the previous class? Quickly prepare a Windows 11 machine by running the condensed PowerShell commands below.

# Allow script execution in PowerShell (if needed)
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

# Install Git, UV and VS Code
winget install --id Git.Git -e --source winget --accept-source-agreements --accept-package-agreements
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
winget install --id Microsoft.VisualStudioCode --accept-source-agreements --accept-package-agreements
exit

Then, close and reopen your terminal and run the following commands: Before running: change the Git identity (user.name and user.email) to your own name and email so commits show the correct author.

# Set your Git identity (CHANGE THESE WITH YOUR OWN INFO BEFORE RUNNING)
git config --global user.name "Prof Pim"
git config --global user.email "prof.pim@class.skku.edu"

# Install the extensions we will use in VS Code
code --install-extension ms-python.python ms-python.vscode-python-envs ms-toolsai.jupyter ms-toolsai.datawrangler esbenp.prettier-vscode GitHub.copilot --force

# Create project folder
mkdir ~/Developer/my-first-project
cd ~/Developer/my-first-project
uv init --python 3.11
uv add pandas ipykernel
.venv\Scripts\activate
code .