python-ml-template: A Makefile repository from bellanich

Python ML Template

A starter kit for Python-based Machine Learning projects
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

About The Project
- Features
- Built With
Getting Started
- Prerequisites
- Installation
Usage
Contributing
License
Contact
Acknowledgments

About The Project

Launching a new project from scratch can be a challenge, especially with a personal commitment to high-quality work. This initial setup complexity got me thinking: "How few commands can I really get away with to kickstart a new machine learning (ML) project"?

Well, from putting together this Python ML Template project, my answer is three:

copier copy python-ml-template/ your-new-project
cd your-new-project/
make

This even automatically creates a remote repository on GitHub! Of course, this template is doing most of the heavy lifting. For more details on getting started, please Checkout this README's "Getting Started" section.

(back to top)

Features

So, what exactly did I choose to include in my essential starter kit for a Python-based Machine Learning project?

A simple continuous integration (CI) pipeline that blocks any pull requests (PRs) with failing Python tests
Dynamic template generation to encourage a "document as you go" approach rather than hastily throwing everything together
A base Python environment definition so that I'm not consistently reinstalling my favorite Python packages (e.g., black) over and over
Git and GitHub-focused templates to make version control and peer-to-peer collaboration as streamlined as possible

For a deeper dive of what's included in this project and why, please refer to the project documentation.

(back to top)

Built With

This project leverages the power of the following frameworks and libraries. Refer to the acknowledgments section for the other resources that I've employed

(back to top)

Getting Started

Want to get started with ML development as soon as possible? Then just follow the steps outlined below.

Prerequisites

Make sure you have the following dependencies installed:

Node.js (also known as node.js, node@21, nodejs, and npm) for commit linting and other Javascript based pre-commit hooks
Conda or miniconda for Python package management
Copier for dynamic Markdown file templating
GitHub CLI for automated project publishing and run gh auth login to setup

Installation

Getting started is simple. Here are the step-by-step instructions:

Clone this repository (git clone https://github.com/bellanich/python-ml-template)
Fill out your personal details in the relevant fields of the copier.yml file
Use copier to copy this template to a new directory and fill out the provided prompts (copier copy python-ml-template/ your-new-project/)
Execute the Makefile inside the newly created directory
```
cd your-new-project/
make
```

Activate your conda environment and you're ready to go

# By default, your conda env will have the same name as your project
CONDA_ENV_NAME=$(basename "$(pwd)")
conda activate $CONDA_ENV_NAME

(back to top)

Usage

In a more prototypical Python ML project, this section would use screenshots, code examples, and (possibly) demos to illustrate project use cases. However, in this case, this section simply serves as a reminder to demonstrate the practical application of your work. After all, the thrill of ML software development is only rivaled by your work in action.

(back to top)

Contributing

If you have a suggestion that would make this project better, please fork this repository and create a pull request. You can also simply open an issue with the tag "enhancement".

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE file for more information.

(back to top)

Contact

Bella Nicholson - @bella-nicholson - bellanich.software@gmail.com

Project Link: https://github.com/bellanich/python-ml-template

(back to top)

Acknowledgments

Rather than re-inventing the wheel, I've leveraged the following great resources in my template formulation:

(back to top)