create-python-lib

A standardized template for Urban Machine Python3.10+ projects.

Why Use This Template?

This template helps streamline development by ensuring that every new Python project starts with the same setup, tools, and best practices. By using cruft, we link the project to the template, allowing us to apply template updates as our standards evolve, without disrupting existing codebases. It’s a fast, reliable way to maintain high-quality, secure, and consistent Python projects across the organization.

Features

• Python 3.10+ Compatibility: Pre-configured environment for modern Python projects.
• Automated Code Formatting: Uses black and isort to keep code style consistent.
• Comprehensive Linting: ruff enforces style, security, and quality rules from multiple sources.
• Static Type Checking: mypy in strict mode to catch type errors early.
• Testing and Code Coverage: pytest and pytest-cov for testing with coverage tracking.
• Security Scanning: bandit checks for common security vulnerabilities.
• Dependency Management: poetry handles dependencies and virtual environments.
• Template Sync with Cruft: Stay up-to-date with template improvements across all projects.
• CI/CD Ready: GitHub Actions workflows for linting, testing, and optional Codecov integration.

Quick Start Guide

Adding the Template to an Existing Project

If you have an existing git repository and you want it to follow this template, use these instructions, start from Step 1. If you are starting a new project, start from Step 3.

1. Create a template branch:

   git checkout --orphan template 

2. Clear files in this branch

   git reset --hard 

3. Install Cruft (if not already installed):

   This tool allows you to create projects from 'cookiecutter' repositories, such as this one.

   pip install cruft

4. Initialize the template. This will create a new directory where the project files will be dumped.

   Fill in the form with the appropriate values for your project. The values in the parameters are the default values that will be used if you don't fill in your own.

   cruft create https://github.com/UrbanMachine/create-python-lib.git

5. Add the generated files into the project directory and commit them to git.

6. Check that everything is synced with the template repository

   cruft check

7. Merge template into your main branch:

   You may need to use:

   git merge --allow-unrelated-histories template main

8. Delete the template branch

Updating a Template on an Existing Project

To pull in the latest template changes: 1.Run the following:

cruft update --allow-untracked-files

2. Follow the prompts and resolve any merge conflicts that arise.

Post Set-Up Guide

Lock the pyproject.toml File

After adding the template to your project, you should lock the pyproject.toml file to ensure that all developers use the same dependencies. This file is generated by Poetry and should be committed to the repository. To lock the file, run:

poetry lock

Then commit the pyproject.lock file to the repository.

Fixing the lint Github Action

This template automatically runs CI via github actions on every pull request.

The CI uses cruft to check if there's been upstream changes on the template repository. Depending on how you clone the repository, you might get the following error:

╭─ Error ──────────────────────────────────────────────────────────────────────╮
│ Unable to initialize the cookiecutter using                                  │
│ [email protected]:UrbanMachine/create-ros-app.git! Failed to clone the repo.    │
│ stderr: 'Cloning into '/tmp/tmpavykj68r'...                                  │
│ [email protected]: Permission denied (publickey).                               │
│ fatal: Could not read from remote repository.                                │
│                                                                              │
│ Please make sure you have the correct access rights                          │
│ and the repository exists.                                                   │
│ '                                                                            │
╰──────────────────────────────────────────────────────────────────────────────╯

If you do, it's because github actions is trying to use SSH to clone the template repo, and failing. To fix this, edit your .cruft.json template key so it points to the repository using https://...your-url...git

1. Generate an SSH Key

   ssh-keygen

2. Add the private key (id_rsa) to your Github repository's sectrets under the name SSH_KEY. Settings can be found under: https://github.com/GITHUB_ORG/PROJECT_NAME/settings/secrets/actions

3. Add a public key (id_rsa.pub) to your repository's deploy keys on github. Settings can be found under: https://github.com/GITHUB_ORG/PROJECT_NAME/settings/keys

Optional: Adding Codecov Support

Codecov let's your project report on test coverage on every pull request. This process requires being an Admin on the github org this project lives in.

1. Sign in to Codecov with your Github account.
2. Under your repository in Codecov, select "Activate".
3. Get a codecov API token. Settings can be found under: https://app.codecov.io/gh/GITHUB_ORG/PROJECT_NAME/
4. Add a secret named CODECOV_TOKEN to your Github repositories secrets. Settings can be found under: https://github.com/GITHUB_ORG/PROJECT_NAME/settings/secrets/actions
5. You should now be able to see code coverage under codecov!