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.
Download a 64-bit version of Miniconda.
Install Miniconda. It is recommended to Register Anaconda but not to Add it to your PATH.
Open the Anaconda Command Prompt
and then enter the following command to update all Miniconda packages:
conda update --all
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
Create a GitHub account (if you do not already have one).
Download and install git (accept the default settings). This program is used as the version control system.
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)
Run PyCharm and perform the following:
Import settings from a previous version of PyCharm (if available)
Select the default editor theme (you can also change the theme later) and click Skip Remaining and Set Defaults
Select the Git option from Check out from Version Control
Click the Log in to Github… button
and then enter your GitHub account information (see Step 5 above) and click Log In
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.)
Open the MSL-LoadLib repository in PyCharm
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)Press
CTRL+ALT+S
to open the Settings windowGo to Project Interpreter and click on the gear button in the top-right corner
Select Add
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 wantClick Apply then OK
If you created a
py27
virtual environment then repeat Steps 9b-9d to add the Python 2.7 environment
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.
Make sure that the git Branch you are working on is up to date by performing a Pull.
Click on the blue, downward-arrow button in the top-right corner to update the project
Select the options for how you want to update the project (the default options are usually okay) and click OK
Make changes to the code.
When you are happy with the changes that you have made you should Push the changes to the MSL-LoadLib repository.
Click on the green, check-mark button in the top-right corner to commit the changes
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.
Finally, Push the changes to the MSL-LoadLib repository.
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.
Do not use
print()
statements to notify the end-user of the status of a program. Uselogging
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.