Table of Contents

1. Contents
2. Course requirements
3. Getting ready for the course
   1. How to install Python 3
   2. Check your installation
   3. Setup the python environment for the course
      1. 0. Make sure you have Git installed.
      2. 1. Clone the course GitHub repository
      3. 2. Create a Python virtual environment
      4. 3. Setup the course
      5. 4. Deactivate your environment
4. Building the course site

In this workshop you will learn how to turn a couple of python scripts into a full blown Python package. You will see how you can develop and maintain this package independantly from your research projects and "pip install" to reuse it across them, using virtual environments. You will then learn the simple steps to make it possible for anyone to "pip install" your package, automatically installing the required dependencies.

Contents

• I Making a python package from a collection of python sripts
• II Reusing package(s) across research projects
• III Python virtual environments
• IV Sharing your package with the world
• V Overview of advanced topics

Course requirements

• A basic familiarity with Python 3
• Python 3, pip and Git installed.

Getting ready for the course

The course assumes that he following software is installed on your system:

• Python 3 (3.3 or above)
• The pip package manager to upload and download Python packages.
• The venv Python module to create Python virtual environments.

Not sure? Plese check your Python installation.

If you already have the above requirements satisfied, jump to Setup the python environment for the course. Otherwise, read on.

How to install Python 3

We recommend install Python via Anaconda. You can see Anaconda as a bundle including Python itself + useful utilities (such as the pip package manager) + several gigabytes worth of Python packages. An alternative to Anaconda is Miniconda, which is essentially a stripped version of Anaconda. It provides a lighter Python distribution consisting of just Python + a handful of core utility packages.

For the purpose of this course, it really doesn't matter if you install Miniconda or Anaconda. If you'd rather save some disk space and go for a shorter download, we recommend you go for Miniconda.

• Click here for instructions on how to install Miniconda/Anaconda.

If you'd rather install Python outside of Anaconda or Miniconda, check out our instructions on how to install Python 3 outside of Anaconda/Miniconda.

If you encounter issues whilst installing any of the above, feel free to get in touch by opening an issue on this repository.

Check your installation

First, check that you have Python 3 available with

python --version

If you find that python refers to Python 2, try with python3 instead.

Next, check that both pip and venv are available. They typically come along with Python itself.

python -m pip --version

python -m venv --help

If any of the three commands above results in an error, please refer to the installation instructions. If you get stuck, please open an issue this repository and we'll help you.

If not, congratulations! Python 3 is now installed and ready to go. One last step, let's setup the python environment for the course.

Setup the python environment for the course

0. Make sure you have Git installed.

The commands in this section are meant to be entered in a terminal (GNU/Linux or MacOS) or a command prompt (Windows).

$ git --version

If not, please install Git. On GNU/Linux Git is available via your package manager, for instance on Ubuntu:

$ sudo apt install git

On MacOS, you can use Homebrew once again:

$ brew install git

On Windows, we recommend that you use Git for Windows.

1. Clone the course GitHub repository

Open a terminal (on Windows you can use git-bash or the Anaconda prompt) and run the following command:

$ git clone https://github.com/OxfordRSE/python-packaging-course.git

2. Create a Python virtual environment

Next, let's move into the course directory and create a virtual environment. Once this virtual environment activated, you'll work in isolation from other Python versions installed on your machine, and you can install any packages you want without fear or breaking any dependencies for your other work.

Open a terminal (or the Anaconda prompt/command prompt if you're using Windows) and enter the following commands:

$ cd python-packaging-course/
$ python -m venv python-course-venv # just "python" for Anaconda/Miniconda
# The following is GNU/Linux and MacOS only
$ source python-course-venv/bin/activate # This activates the virtual environment

On windows use the following instead to activate the virtual environment.

python-course-venv\Scripts\activate.bat

Again, you might need to type python3 instead of python in order to use Python 3.

3. Setup the course

Now that your Python 3 virtual environment is activated, typing python at the command line will automatically call the Python 3 versions which was used to create the virtual environment (give python --version a try).

Let's get the latest version of the Python package manager and install the packages required to run the examples in the course.

$ python -m pip install --upgrade pip wheel setuptools
$ python -m pip install course_setup/

4. Deactivate your environment

That's all! You can deactivate your environment with the following command:

$ deactivate

See you at the workshop!

Building the course site

This is not required to participate in the course.

1. Install Hugo

2. Clone this repository

   $ git clone https://github.com/OxfordRSE/python-packaging-course.git
   

3. Install the Hugo Learn theme

   $ cd python-packaging-course/site/
   $ git clone git@github.com:matcornic/hugo-theme-learn.git themes/hugo-theme-learn
   

4. Build the site

   $ hugo server