
Create a Python package using best practices, from build systems and documentation to testing and version control, guided by cookie cutter templates for easy packaging with Pip and Conga.
You will learn a few useful commands for the Linux terminal command line. You will be able to show files and folders, move between directories, and create new directories.
You will install the Anaconda dependency manager in your terminal. Conda will allow you to create isolated environments for your development work to avoid dependency conflicts.
Utilize the conda package manager to create an environment and install the cookiecutter software.
Run the cookiecutter using the MolSSI template to create an initial python package with a number of software best practices initialized for the project.
A brief look at the files output by the cookiecutter template. We will go over each of them in more detail in subsequent lessons.
Project level documentation informs users and developers about a software package at a high level and includes READMEs, license files, code of conducts, and any other information about the maintainers or developers of a software package.
The cookiecutter template provides a basic python package with a single starting module. The initial module contains a function along with example docstrings in the numpy format. The package provides an starting point for further python package development.
The cookiecutter template initializes a number of python build system settings, stored in MANIFEST.in and pyproject.toml. Each of these files is filled in by the cookiecutter with initial settings along with a description of the settings, instructions for customizing some settings, and relevant links to setting documentation.
Version control is used by developers to manage a history of changes in their software package. The cookiecutter template initializes a git repository in the file structure. With git you can save versions of your package, view or load older versions, and isolate feature development on separate branches.
Remote hosting services for git repositories, such as GitHub, provide multiple benefits to a developer. They act as remote storage for the repository, allow for synchronization across multiple development environments, and provide tools for collaboration between developers. The cookiecutter created all the files needed for the python package to be hosted on GitHub, all it requires is uploading it.
Testing is an important part of the software development process. Including tests provides confidence that changes made to the software either do not break any functionality or aid in finding the portions of the code that break. The cookiecutter has setup an initial test file to provide a starting point for testing.
Continuous integration (CI) is the practice of frequently merging changes back into the codebase. CI usually integrates automated tools to reduce developer busy work. The cookiecutter provides a GitHub Actions workflow to perform automated testing whenever changes are made to the GitHub repository.
Sphinx is used to generate documentation. It uses your code and a set of text files to generate pages that can be hosted on a website.
When working with python, many developers often start with scripts to achieve specific goals. As they continue to develop, they often begin to see a potential benefit to the wider software community to share their efforts. Turning your code into a python package will enable you to deploy and share your code through package management tools, such as pip and conda, allowing other users to easily obtain and work with your code.
Creating a python package can come with a number of additional difficulties, such as understanding the python build system and including proper documentation. As code bases develop, they often become more complicated or gain additional developers. Including some software best practices: testing, version control, or continuous integration; will improve your development process. However, getting the best practices put in place and setting up the python packaging files can be a tedious experience.
To solve this problem, you can use a software called Cookiecutter, which is an open source tool to create projects from project templates. Cookiecutter uses a template to prompt you with a few questions about your project, and uses your answers to produce a set of files and folders in your filesystem. MolSSI has developed a template to support the development of python packages that implements a number of best practices in software design to give a developer a head start on creating a python package.
Through these lessons, you will obtain the Cookiecutter software, run it with the MolSSI Cookiecutter Template, and learn about the files that the Cookiecutter has produced. We will give a brief overview of why we think the included best practices are important. We hope you gain a further interest in expanding your software development skills and look into utilizing all the best practices the Cookiecutter has put in place for you.