MSL Developers Guide

This guide [1] shows you how to:

and describes one way to set up an environment to develop Python programs. The guide does not intend to imply that the following is the best way to develop programs in the Python language.

Install and set up Python, Git and PyCharm

This section uses the MSL-LoadLib repository as an example of a repository that one would like to clone and import into PyCharm.

The following instructions are written for a Windows x64 operating system. To install the same software on a Debian architecture, such as Ubuntu, run

sudo apt update
sudo apt install git snapd
sudo snap install pycharm-community --classic
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda*

and answer the questions that you are asked. After running these commands you can follow the appropriate steps below.

Attention

The screenshots below might not represent exactly what you see during the installation or configuration procedure as this depends on the version of the software that you are using.

  1. Download a 64-bit version of Miniconda.

  2. Install Miniconda. It is recommended to Register Anaconda but not to Add it to your PATH.

    _images/anaconda_setup.png
  3. Open the Anaconda Command Prompt

    _images/anaconda_prompt.png

    and then enter the following command to update all Miniconda packages:

    conda update --all
    
  4. It is usually best to create a new virtual environment for each Python project that you are working on to avoid possible conflicts between the packages that are required for each Python project or to test the code against different versions of Python (i.e., it solves the Project X depends on version 1.x but Project Y depends on version 4.x dilemma).

    In the Anaconda Command Prompt create a new py37 virtual environment (you can pick another name, py37 is just an example of a name) and install the Python 3.7 interpreter in this environment (NOTE: You can also create conda environment’s from within PyCharm if you are not comfortable with the command line, see Step 9)

    conda create --name py37 python=3.7
    

    You may also want to create another virtual environment so that you can run the code against another Python version. For example, here is an example of how to create a Python 2.7 virtual environment named py27:

    conda create --name py27 python=2.7
    
  5. Create a GitHub account (if you do not already have one).

  6. Download and install git (accept the default settings). This program is used as the version control system.

  7. Download and install the Community Edition of PyCharm to use as an IDE. This IDE is free to use and it provides a lot of the features that one expects from an IDE. When asked to Create associations check the .py checkbox and you can also create a shortcut on the desktop (you can accept the default settings for everything else that you are asked during the installation)

    _images/pycharm_installation1.png
  8. Run PyCharm and perform the following:

    1. Import settings from a previous version of PyCharm (if available)

      _images/pycharm_installation2.png
    2. Select the default editor theme (you can also change the theme later) and click Skip Remaining and Set Defaults

      _images/pycharm_installation3.png
    3. Select the Git option from Check out from Version Control

      _images/pycharm_github_checkout.png
    4. Click the Log in to Github… button

      _images/pycharm_github_login1.png

      and then enter your GitHub account information (see Step 5 above) and click Log In

      _images/pycharm_github_login2.png
    5. Clone the MSL-LoadLib repository. Specify the Directory where you want to clone the repository (NOTE: the MSL-LoadLib repository will only appear if you are part of the MSLNZ organisation on GitHub. A list of your own repositories will be available.)

      _images/pycharm_github_clone.png
    6. Open the MSL-LoadLib repository in PyCharm

      _images/pycharm_github_open.png
  9. Add the py37 virtual environment that was created in Step 4 as the Project Interpreter (NOTE: you can also create a new conda environment in Step 9d)

    1. Press CTRL+ALT+S to open the Settings window

    2. Go to Project Interpreter and click on the gear button in the top-right corner

      _images/pycharm_interpreter1.png
    3. Select Add

      _images/pycharm_interpreter2.png
    4. Select Conda Environment \(\rightarrow\) Existing environment and select the py37 virtual environment that was created in Step 4 and then click OK You can also create a new environment if you want

      _images/pycharm_interpreter3.png
    5. Click Apply then OK

    6. If you created a py27 virtual environment then repeat Steps 9b-9d to add the Python 2.7 environment

  10. The MSL-LoadLib project is now shown in the Project window and you can begin to modify the code.

Commit changes to a repository

The following is only a very basic example of how to upload changes to the source code to the MSL-LoadLib repository by using PyCharm. See this link for a much more detailed overview on how to use git.

Note

This section assumes that you followed the instructions from Install and set up Python, Git and PyCharm.

  1. Make sure that the git Branch you are working on is up to date by performing a Pull.

    1. Click on the blue, downward-arrow button in the top-right corner to update the project

      _images/pycharm_github_pull_1.png
    2. Select the options for how you want to update the project (the default options are usually okay) and click OK

      _images/pycharm_github_pull_2.png
  2. Make changes to the code.

  3. When you are happy with the changes that you have made you should Push the changes to the MSL-LoadLib repository.

    1. Click on the green, check-mark button in the top-right corner to commit the changes

      _images/pycharm_github_commit1.png
    2. Select the file(s) that you want to upload to the MSL-LoadLib repository, add a useful message for the commit and then select Commit and Push.

      _images/pycharm_github_commit2.png
    3. Finally, Push the changes to the MSL-LoadLib repository.

      _images/pycharm_github_commit3.png

Use the setup.py and condatests.py scripts

MSL packages come with two scripts to help make development easier: setup.py and condatests.py. See the “create” ReadMe page for an overview on how to use these scripts.

Edit source code using the style guide

Please adhere to the following style guides when contributing to MSL packages. With multiple people contributing to the code base it will be easier to understand if there is a coherent structure to how the code is written:

Note

This section assumes that you followed the instructions from Install and set up Python, Git and PyCharm.

  • Follow the PEP 8 style guide when possible (by default, PyCharm will notify you if you do not).

  • Docstrings must be provided for all public classes, methods and functions.

  • For the docstrings use the NumPy Style format.

    • Press CTRL+ALT+S to open the Settings window and navigate to Tools \(\rightarrow\) Python Integrated Tools to select the NumPy docstring format and then click Apply then OK.

      _images/pycharm_numpy_style.png
  • Do not use print() statements to notify the end-user of the status of a program. Use logging instead. This has the advantage that you can use different logging levels to decide what message types are displayed and which are filtered and you can also easily redirect all messages, for example, to a GUI widget or to a file. The django project has a nice overview on how to use Python’s builtin logging module.