Python Package Best Practices: Glossary

Key Points

Python Package Set-up
  • There is a common way to structure Python packages

  • You can use the CMS CookieCutter to quickly create the layout for a Python package

Intro to Version Control with Git
  • Git provides a way to track changes in your project.

  • Git is a software for version control, and is separate from GitHub.

Using GitHub
  • You can use GitHub to store your project online where you or others can access it from a central repository.

  • You can use GitHub to store your projects so you can work on them from multiple computers.

Python Coding Style
  • Your code should adhere to standards outlined in PEP8 so that it easily readable by others.

  • All functions and modules should be documented with docstrings.

Deciding Package Structure
  • Your package should be broken up into modules and subpackages depending on the amount of code and functionality.

Code Collaboration using GitHub
  • To contribute to someone else’s project, you should fork their repository.

  • All development work should be done on a new branch. Each branch should implement one feature.

  • Once you’ve implemented a new feature, push to your repository and create a pull request on the original repo.

Python Testing
  • A good set of tests covers individual functions/features and behavior of the software as a whole.

  • It’s better to write tests during development so you can check your progress along the way. The longer you wait to start the harder it is.

  • Try to test as much of your package as you can, but don’t go overboard, most packages don’t have 100% test coverage.

Continuous Integration
  • Continuous integration automates development steps, such as testing, coverage, and packaging.

  • Continuous integration also allows you to test your code on a variety of operative systems and platforms.

  • The CookieCutter includes (almost) ready-to-use configuration files for Travis CI and CodeCov.

  • Travis, Codecov, and many others are available for free for open-source projects in the GitHub Marketplace.

Documentation
  • Some documentation is better than no documentation

Deployment

Glossary

The glossary would go here, formatted as:

{:auto_ids}
key word 1
:   explanation 1

key word 2
:   explanation 2

({:auto_ids} is needed at the start so that Jekyll will automatically generate a unique ID for each item to allow other pages to hyperlink to specific glossary entries.) This renders as:

key word 1
explanation 1
key word 2
explanation 2