Overview

Best Practices in Python Package Development

This course by The Molecular Sciences Software Institute (MolSSI) teaches users MolSSI’s best practices in Python package development.

MolSSI’s best practices provide a starting point to learning software-development processes and protocols. Adhering to these protocols will ensure that your code is reliable and reproducible while decreasing long-term maintenance, increasing long-term viability, and allowing others to contribute to your code base. Before starting to learn the MolSSI’s best practices, you should first consider your project’s user and developer community. If your project is small with a limited number of potential contributors, certain topics from the best practices course may be more important to your work than others. However, for projects with a large user base, it is crucial to complete all components of the course.

This lesson is under continual development, please report issues to the workshop repository. If you see a subject you would like to contribute to, submit a pull request!

Prerequisites

This material is best suited for people who have experience scripting in Python and are ready to learn about how to make their scripts into a software package. You should have experience programming Python and in using the terminal (or shell)

You can see a tutorial on using the shell from Software Carpentry. or use our command line basics lesson.

Workshop Lessons

The workshop lessons listed in this table below are designed to be completed sequentially. In this workshop sequence, we first run the CookieCutter, then use the produced repository for the lesson on version control.

If you need a refresher on the command line, see our command line basics lesson. If you would like to do the git and GitHub lessons outside of the context of the CookieCutter, see our standalone lesson on git and standalone lesson on GitHub.

Set-Up

Lesson Title	Questions	Objectives
Computer Set-Up	How do I set up my environment? How do I set up git and GitHub? What text editor should I use?	Use conda to create an environment and install packages. Set up credentials for GitHub.
Python Package Set-Up	What is the layout of a Python package? How can I quickly create the structure of a Python package? What license should I choose for my project?	Explain Python package structure. Use the CMS CookieCutter to build a Python package.

git and GitHub

Lesson Title	Questions	Objectives
Introduction to Version Control using git	How do I use git to keep a record of my project?	Explain the purpose of version control. Introduce common git commands. Understand how to create a commit. Understand how to view diffs and see previous versions of files.
GitHub	How do I use GitHub to host my projects? How do I use git and GitHub together?	Explain reasons to use GitHub.
Code Collaboration	How can others contribute to my project on GitHub? How can I contribute to the projects of others?	Learn about collaboration models. Learn what a fork is on GitHub Learn how to open a pull request

Code Style and documentation

Lesson Title	Questions	Objectives
Python Coding Style	How can I write Python code that is readable?	Learn how to raise exceptions. Understand how to follow PEP8 style for Python. Understand what docstrings are and why they are important. Learn to write docstrings in numpy style.
Deciding Package Structure	How should I organize my code? How can I handle imports in my package?	Break code into modules and subpackages based on functionality. Understand how the __init__.py file affects your Python package.
Type Hinting in Python	What is type hinting? What does type hinting do for my software?	Learn about type hinting in Python. Learn the syntax to utilize type hinting in Python.
Package Documentation	How can we document our package?	Explain in-code documentation Explain documentation tools like Read The Docs

Continuous Integration, Testing, Distribution

Lesson Title	Questions	Objectives
Python Testing using pytest	How is a Python module tested?	Explain the overall structure of testing. Explain the reasons why testing is important. Understand how to write tests using the pytest framework.
Continuous Integration using GitHub Actions	How can we automate testing? How do we link a repository on GitHub to continuous integration services?	Explain the concept and benefits of continuous integration. Introduce the GitHub Marketplace as a one-stop shop for continuous integration services. Demonstrate how to setup continuous integration using GitHub Actions. Familiarize learners with YAML configuration files.
Distributing Packages	How can I get my project out there?	Discuss community strategies.