Summary

This template repository is for anyone to use as a convenient starting point. It is intended to:

• show expected structure of Python code
• encourage code reuse, sharing and safe storage
• show how to use simple tools like pylint

This was originally for the Cyber Security Cooperative Research Centre:

• featured in a seminar on "Software Best Practices" on 2021-08-27
• video (watch)
• video (download)
• slides

Installation

This module can be installed directly from GitHub.

# No username or password needed.
pip install git+https://github.com/ma-al/example-python.git

# note: only been tested on MacOS

Subsequently, the module will be downloaded and installed into your Python environment.

If successful, you should see:

Successfully built example-python
Installing collected packages: example-python
Successfully installed example-python-1.1.0

Cloning

If you want to use this to start your own repo, simply clone it with below command:

git clone https://github.com/ma-al/example-python.git

Alternatively, use your favourite GUI Git tool, including:

• GitHub Desktop
• SourceTree

Once cloned, be sure to change the remote URL to your own repository somewhere else.

It's probably easier for new users to either:

• create a new repository from this template, or
• learn how to fork this repo

Running

If installed directly via pip:

# just run in any folder
python -m example_python show-example

If you've cloned it:

cd example-python # go to repo root
python -m example_python show-example

Tests

Researchers are encouraged to implement tests for their code. For more details, please see documentation in the tests folder

Code Style & Quality

Researchers should strive for code quality that matches industry and community standards. Doing so leads to better science outcomes and easier sharing of knowledge.

If commercialisation is a criteria, writing good code from the start leads to faster prototyping and outcomes.

cd example-python # go to repo root
pylint example_python

# if pylint is not found
pip install pylint

Above conducts a check locally on your machine, using the included pylintrc file.

Credits

List credits or references here, if applicable

People

For help, please contact:

• Kerrie Jackson
• Mahathir Almashor