Python Package Best Practices: Setup

This setup tutorial will walk you through installing the software you will need for this workshop.

For this workshop, you will need to have Python installed. We recommend and assume you will have Python installed using Anaconda, and will be talking about package management using conda and Anaconda (see instructions below). You will also need to download workshop materials, and configure git.

We will cover the following topics. Click on a particular topic to skip to that section.

  1. Downloading workshop materials
  2. Downloading a text editor
  3. Installing Python using Anaconda
  4. Creating a Python environment using conda
  5. Installation of cookiecutter
  6. Creating a GitHub Account
  7. Installing and Configuring git

Workshop materials

In this workshop, we will be moving code from a Jupyter notebook into a Python package that we can install and import into other scripts.

Choosing a text editor

You will need an editor for Python files for this workshop. If you do not have a prefered text editor, we recommend atom or Visual Studio Code

Installing Python Using Anaconda

Python is a popular language for scientific computing, and great for general-purpose programming as well. Installing all of its scientific packages individually can be a bit difficult, however, so we recommend the all-in-one installer Anaconda.

Throughout the rest of this set-up, we will assume that you are using Anaconda and the conda package manager.

Please set up your python environment at least a day in advance of the workshop. If you encounter problems with the installation procedure, ask your workshop organizers via e-mail for assistance so you are ready to go as soon as the workshop begins.

Windows - Video tutorial

  1. Open https://www.anaconda.com/download with your web browser.

  2. Download the Python 3 installer for Windows.

  3. Double-click the executable and install Python 3 using MOST of the default settings. The only exception is to check the Make Anaconda the default Python option.

Alternatively, if you are running Windows 10, you can install the Windows Subsystem for Linux and follow the Linux tutorial.

Mac OS X - Video tutorial

  1. Open https://www.anaconda.com/download with your web browser.

  2. Download the Python 3 installer for OS X.

  3. Install Python 3 using all of the defaults for installation.

Linux

Note that the following installation steps require you to work from the shell. If you run into any difficulties, please request help before the workshop begins.

  1. Open https://www.anaconda.com/download with your web browser.

  2. Download the Python 3 installer for Linux.

  3. Install Python 3 using all of the defaults for installation.

    a. Open a terminal window.

    b. Navigate to the folder where you downloaded the installer

    c. Type

    $ bash Anaconda3-
    

    and press tab. The name of the file you just downloaded should appear.

    d. Press enter.

    e. Follow the text-only prompts. When the license agreement appears (a colon will be present at the bottom of the screen) hold the down arrow until the bottom of the text. Type yes and press enter to approve the license. Press enter again to approve the default location for the files. Type yes and press enter to prepend Anaconda to your PATH (this makes the Anaconda distribution the default Python).

Using Anaconda and conda

Use of Anaconda with its package manager, conda, greatly simplifies package installation and environment management.

conda is a general package manager, meaning that it can install dependencies and packages in languages besides Python, unlike pip (which is Python’s package manager). Both pip and conda can be used to install packages.

Python environments

A conda environment contains a specific collection of packages you have installed. This means that packages are isolated, and installed only for a specific environment – you can have several environments each with different installed packages, or different versions of installed packages in different environments.

It’s considered a best practice to create a new Python environment for each project you work on.

This section uses the command line interface (CLI) to create an environment using conda. If you are on Mac or Linux, you will type these commands into your terminal. If you are on Windows, you should use the Anaconda Navigator.

To create an environment for this project using conda,

$ conda create --name molssi_best_practices python=3.7

For other projects, you should replace molssi_best_practices with a descriptive name for your project. conda also allows you to specify the python version to use with the environment. Here, python=3.7 specifies that we want to use Python 3.7 in this environment. Executing this command will list the environment location and a list of Python packages to be installed. Choose y(es) when prompted.

Activate the environment using the command

$ conda activate molssi_best_practices

Once you’ve activated an environment, the name of the environment will be in parenthesis at the front of your command line prompt.

If you wanted to create an environment for testing your code in Python 3.5, for example, you could use the command (Do not execute this, it’s just an example.)

$ conda create --name molssi_35 python=3.5

When this environment is activated, Python 3.5 will be used instead of Python 3.7.

To see a list of all your environments

$ conda info --envs

To deactivate an environment, type

$ conda deactivate

Package installation using conda

Using conda, we can install packages to our environments. Note: Make sure you have activated the environment where you want to install packages.

$ conda activate molssi_best_practices

To list all the Python packages installed in an environment, first activate it, then type

$ conda list

Packages can be installed using the conda install package_name command. For example, to install NumPy,

$ conda install numpy

Further, the desired version of NumPy can be specified:

$ conda install numpy=1.15

For this workshop, you will need to install the following packages into your environment

You can install all of them in one line with

$ conda install numpy matplotlib jupyter

CookieCutter Installation

For this workshop, we will create the structure of our Python package using the CMS CookieCutter. Please have this package installed in your molssi_best_practices environment.

First, switch to your environment for this workshop if you are not in it.

$ conda activate molssi_best_practices

Install the general cookiecutter with the following commands.

$ conda config --add channels conda-forge
$ conda install cookiecutter

Installing and configuring git

Installation

Download and install git for your operating system.

Configuring Git

The first time you use Git on a particular computer, you need to configure some things.

First, you should set your identity. One of the most important things that version control like Git does is to keep track of who changes what. This helps repository maintainers coordinate the efforts of all the people who contribute to the project. Most importantly, it makes it easier to figure out who to blame when something goes wrong. You can provide git your name and contact information with the following commands:

$ git config --global user.name "<Firstname> <Lastname>"
$ git config --global user.email "<email address>"

Next, you might want to change the Git text editor. As we will see later, certain Git commands will open text files. When this happens, Git will use your environment’s default text editor, which might not be the editor you are most comfortable using. Using configuration commands, you can tell Git to use your favorite editor. To use Emacs as your text editor, you can do:

$ git config --global core.editor "emacs"

Alternatively, to use Vim as your text editor, do:

$ git config --global core.editor "vim"

A more complete list of possible editors is available here.

You can check the configuration commands that you have set using:

$ git config --list

Create GitHub Account

Create an account on github.com. Remember the user name and password. If you are making a GitHub account, please remember that your username should be recognizable and professional.

Conclusion

At the end of this set-up, you should have created a Python environment (molssi_best_practices) which has Python 3.7, numpy, matplotlib, jupyter, and cookiecutter installed. You should also have installed and created an account on GitHub and configured git.