Programming with Python

There are many ways to work with Python. Those learning Python for the first time often find it easiest to practice Python on the cloud using platforms like Google Colab or Dartmouth's JupyterHub. But, for researchers and students ready to build their own projects, it is often preferable to download and install Python on your own machine.

Working with Python on your own computer

There are various different options for installing and working with Python locally on your own computer. Some common approaches include:

1. Installing the Anaconda distribution package for Python. This allows you to install hundreds of packages at once. For more on this option scroll down.

2. One folder - one project - one environment approach: It is good practice to create a separate folder on your computer for each project. However, it is also good practice to set up separate "virtual environments" for each project. This allows you to only install the packages necessary for a project and to, thus, more easily share your project with others. We provide our suggested method to follow this approach next:

Visual Studio Code with Virtual Environments Option

While there are different options for installing and working with Python locally, the Dartmouth Library's Research Data Services team recommends the following option: working with Python within Visual Studio Code and setting up a unique virtual environment for each project. For more on what this means and how to do this, follow the instructions below:

Step 1: Setup

1. Download Python and install it on your computer. Select
2. Download and install Visual Studio Code.

Step 2: Getting a Project Started in Visual Studio Code

1. Open Visual Studio Code (VSC)
2. Open a project folder
   1. If you don't have a project folder already, create one on your hard drive
   2. Within VSC select File --> Open Folder
   3. You should see this folder and its contents appear in the Explore window on the left panel of VSC
3. Open a terminal in VSC - VSC allows a user to move back and forth between a terminal (also known as "The Command Line") and Python scripts and notebooks
   1. Select the Terminal tab --> New Terminal
   2. A terminal window will appear at the bottom of VSC.
   3. [explain diff types of terminals available]
   4. We will use the terminal to install Jupyter Notebooks
   5. In the terminal type:
      • Windows: pip install notebook
      • Macs: pip3 install notebook

Step 3: Setting Up a Virtual Environment in VSC

1. Setup a Virtual Environment in Visual Studio Code
   1. In the terminal, create a virtual environment called ".venv" by typing in the following commands:
      1. Windows:  python -m venv .venv
      2. Mac: python3 -m venv .venv
   2. In the Explorer window on the left you should now see a .venv folder for you virtual environment
2. Activate local virtual environment (.venv)
   1. Everytime you open your project folder you will want to make sure your virtual environment is activated by typing the following in the terminal:
      1. Windows: .venv\Scripts\activate
      2. Mac: source .venv/bin/activate
   2. You will know the virtual environment is activated if you see (.venv) at the start of each new line in the terminal.

Step 4: Getting Started with Python in VSC

1. Open a Jupyter Notebook in VSC
   1. File --> New File --> Jupyter Notebook
   2. Save the new notebook: File --> Save As
2. Setup Python Kernel
   1. click on Select Kernel in the top right of the notebook. Select Python Environments and .venv
3. Experiment with the new notebook
   1. Add new cells using ESC + B or clicking on + Code (to add a new code cell) or + Text (to add a new text cell).
   2. try typing in some text in the markdown / text cells
   3. try running some basic code in the code cells
      1. upon running your first code cell, VSC may ask you if you want to install the ipykernel package. Select Install.
   4. try importing a Python package in a code cell, such as pandas running import pandas as pd
      1. Note: you will receive a ModuleNotFoundError. This is because we need to install pandas into the local virtual environment before importing it. To do that we need to return to the terminal in VSC:
4. Install Python Packages to local virtual environment (.venv)
   1. to install packages into the virtual environment you will want to:
      1. check to see if the virtual environment is activated (you will see (.venv) at the start of each new line in the terminal.
      2. install a new package using pip. The syntax for installing packages in the terminal is:
         1. Windows: pip install [package-name]
         2. Macs: pip3 install [package-name]
   2. Install pandas, a popular package used for working with dataframes, by typing the following in the terminal:
      1. Windows: pip install pandas
      2. Macs: pip3 install pandas
   3. Return to your notebook and run the cell importing pandas again import pandas as pd. It should work now.
5. Create requirements.txt file for sharing package requirements
   1. After installing several packages into your virtual environment you can view what packages have been installed typing pip freeze (for Windows) or pip3 freeze (for Macs) in the terminal. Note: you will see far more than those packages you manually installed. This is because when you install a new package, pip automatically installs other packages that your requested package depends on.
   2. You can save the list of packages you have installed into a virtual environment by typing pip freeze > requirements.txt (for Windows) or pip3 freeze > requirements.txt (for Macs) into the terminal. You should see a new file called "requirements.txt" in the Explorer window on the left. Open the text file and review its contents. The requirements.txt will allow others to reproduce the exact same virtual environment on their computers and thus ensure they can run the same code as you.
      1. Note: the requirements.txt file does not automatically update when you install new packages. Run pip freeze > requirements.txt (for Windows) and pip3 freeze > requirements.txt (for Macs) as needed before sharing the requirements.txt file with a collaborators.
6. Recreating someone else's virtual environment.
   1. If you wish to recreate someone else's virtual environment or a virtual environment you used on another project, the requirements.txt file comes in handy.
   2. With the requirements.txt file moved into your project folder, type pip install -r requirements.txt (for Windows) or pip3 install -r requirements.txt (for Macs) into the terminal. This will install all packages (and their specific versions) listed in the .txt file.
7. Deactivate the virtual environment
   1. if you ever need to deactivate your virtual environment from within the terminal just run deactivate.
8. Customizing Visual Studio Code (VSC)
   1. Open the Extensions pane in the lefthand window of VSC
   2. Search for and install Jupyter and Python extensions

Other Options for using Python on your own computer

Besides the above method, there are other ways to install Python on your own computer. Perhaps the most popular alternative is to install the Anaconda distribution package. To do so:

1. Install the Anaconda distribution package for Python. This will install 1000s of the most popular Python packages and a dozen or so software tools for working with Python. You can then open Anaconda and experiment with coding in Python using Jupyter Notebooks, PyCharm, Spyder, or other included software.Additional instructions for installing Anacaonda can be found here.
2. To install packages with Anaconda, you will use conda instead of pip in a terminal. But keep in mind many of the packages you will most commonly used are already installed with anaconda. To see a full list of available packages with conda, type "conda list" in the Anaconda Powershell terminal.

Working with Python on the cloud (the no-installation option)

Teachers and students may choose to use Google Colab or Dartmouth's JupyterHub server. These are great options for instruction and training. However, neither resource allow you to save your work long-term, so are not recommended for research and project work.

For instructors and students using the JupyterHub, please see instructions below:

Instructions: Opening JupyterHub and Getting Started

1. Open jhub.dartmouth.edu in a browser.

2. Choose "Reproducible Research Workshops"

3. Select "Start My Server." It may take a few minutes to load. Once open, your JHub page should look something like this (if you've opened it before, however, you may already have a notebook or other files open):

4. Use the screenshot below to find the root folder of your JHub directory:

5. You should then navigate to your workshop folder. For the Text Analysis in Python series, for example, you will want to go to the following directory: RR-workshops/text-analysis/text-analysis-with-python to find workshop materials. To get started with the Week 1 ("Strings and Files") workbook you will want to also open the strings-and-files folder